メインコンテンツへスキップ

​
Session オブジェクト

Session を作成、取得、一覧表示、更新、アーカイブするエンドポイントは、このオブジェクトを返します。 
{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "客服助手",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "客户支持会话",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "credits": 12.5
  },
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T11:00:00Z"
}
フィールド型必須返却説明
idstringはいsess_\ プレフィックス付きの Session ID。
typestringはい固定値\ "session"。
identity_idstringはいForward Identity ID。この Session が属するエンドユーザーの Identity を表します。
templateobjectはいForward Template の概要。フィールドは Template 概要 を参照してください。
source_typestringはいSession の発生元:api、im\ または\ schedule。
statusstringはいSession の実行状態:idle、running、rescheduling、canceling\ または\ terminated。アーカイブ状態は\ archived_at\ で表現されます。
titlestringはいSession のタイトル。
incremental_streaming_enabledbooleanはいこの Session で増分ストリーミングイベントを有効にするかどうか。作成時に省略した場合は\ false\ となり、作成後は変更できません。
metadataobjectいいえ呼び出し側の業務メタデータ。
configobjectいいえSession の設定。指定しない場合は省略されることがあります。
config.environment_variablesobjectいいえセッションレベルの環境変数。key-value 形式。
statsobjectいいえSession の統計情報。フィールドは Session stats を参照してください。
usageobjectいいえ使用量情報。関連する課金モジュールが有効でない場合は省略されることがあります。
usage.creditsnumberいいえCredit の消費量。
archived_atstring | nullはいアーカイブ日時。アーカイブされていない場合は\ null。
created_atstringはい作成日時。RFC 3339 形式。
updated_atstringはい最終更新日時。RFC 3339 形式。

​
Template 概要

フィールド型必須返却説明
idstringはいForward Template ID。
typestringはい固定値\ "template"。
namestringはいTemplate 名。
modelstringはいTemplate が使用するモデルのティアまたはモデル識別子。
versionintegerはいTemplate のバージョン番号。

​
Session stats

フィールド型必須返却説明
active_secondsintegerいいえアクティブな処理時間(秒)。新しい Session では通常\ 0。
duration_secondsintegerいいえSession の継続時間(秒)。新しい Session では通常\ 0。

​
Event オブジェクト

エンドポイントが返す Event は type によって変化する JSON オブジェクトです。返却されるすべての Event は共通フィールドを含み、イベントタイプによって異なる payload フィールドを持ちます。 
{
  "id": "evt_xxx",
  "type": "agent.message",
  "session_id": "sess_xxx",
  "content": [
    {
      "type": "text",
      "text": "这是分析结果。"
    }
  ],
  "processed_at": "2026-06-22T11:00:03Z"
}
フィールド型必須返却説明
idstringはいevt_\ プレフィックス付きの Event ID。
typestringはいEvent のタイプ。
session_idstringはいEvent が属する Session ID。
processed_atstringいいえイベントが処理された日時。RFC 3339 形式。一部の agent 生成イベントや増分イベントには含まれない場合があります。
イベントタイプごとに出現が許可される payload フィールドは以下のとおりです。表では共通フィールド id、type、session_id、processed_at は繰り返し記載していません。
Event タイプ許可されるフィールド
user.messagecontent
user.interruptなし
user.tool_confirmationtool_use_id、result、deny_message
user.tool_resulttool_use_id、content、is_error
user.custom_tool_resultcustom_tool_use_id、content、is_error
user.define_outcomedescription、rubric、outcome_id、max_iterations
system.messagecontent
agent.messagecontent
agent.thinkingなし
agent.message_startmessage_id、message
agent.content_block_startmessage_id、index、content_block
agent.content_block_deltamessage_id、index、delta
agent.content_block_stopmessage_id、index
agent.message_deltamessage_id、delta、usage
agent.message_stopmessage_id
agent.tool_usename、input、evaluated_permission
agent.tool_resulttool_use_id、content、is_error
agent.custom_tool_usename、input
agent.mcp_tool_usemcp_server_name、name、input、evaluated_permission
agent.mcp_tool_resultmcp_tool_use_id、content、is_error
agent.artifact_deliveredfile_id、original_filename、size、content_type
session.status_runningなし
session.status_idlestop_reason
session.status_terminatedなし
session.errorerror
session.updatedagent、metadata、title

​
クライアントが送信できるイベントタイプ

POST /api/v1/forward/sessions/{session_id}/events は以下のイベントタイプのみを受け付けます。
タイプ必須フィールド説明
user.messagecontentユーザーメッセージ。content\ は空でない content block の配列である必要があり、text、image、document\ などのブロックタイプをサポートします。
user.interruptなし現在の処理の中断を要求します。
user.tool_confirmationtool_use_id、resultツール呼び出しの確認。result\ は\ allow\ または\ deny。拒否時は\ deny_message\ を渡せます。
user.tool_resulttool_use_id組み込みツールの結果を返します。content\ と\ is_error\ は任意です。
user.custom_tool_resultcustom_tool_use_idクライアント定義のカスタムツールの結果を返します。content\ と\ is_error\ は任意です。
user.define_outcomedescription、rubric期待する結果と評価基準を定義します。max_iterations\ は任意です。
system.message は公開 Event タイプですが、Forward クライアントの書き込みイベントとしては公開されていません。

​
公開イベントタイプ

履歴の照会や SSE イベントストリームの購読時には、以下の公開イベントタイプを受け取る可能性があります: user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result、user.define_outcome、system.message、agent.message、agent.thinking、agent.message_start、agent.content_block_start、agent.content_block_delta、agent.content_block_stop、agent.message_delta、agent.message_stop、agent.tool_use、agent.tool_result、agent.custom_tool_use、agent.mcp_tool_use、agent.mcp_tool_result、agent.artifact_delivered、session.status_running、session.status_idle、session.status_terminated、session.error、session.updated。

​
増分ストリーミングイベント

増分ストリーミングイベントを公開するかどうかは、Session 作成時の incremental_streaming_enabled フィールドで制御され、履歴照会や SSE 購読のリクエストパラメータでは制御されません:
  • true:イベントストリームは最終的な完全な agent.message の前に assistant の出力フラグメントを返します。履歴照会でも同じ増分イベント群が返されます。
  • false または省略:通常モードを維持し、完全な公開イベントのみを返し、増分イベントは返しません。
増分ストリーミングを有効にしても、最終的な完全な agent.message は引き続き返されます。クライアントは増分イベントを即時表示に使用し、最終的な agent.message を永続化または表示の校正結果として使用できます。 トップレベルの増分イベントタイプは以下の 6 種類のみです:
イベントタイプ主要フィールド説明
agent.message_startmessage_id、messageassistant message を開始します。
agent.content_block_startmessage_id、index、content_blocktext、thinking、tool use などの content block を開始します。
agent.content_block_deltamessage_id、index、deltaindex\ に対応する content block の増分フラグメントを保持します。
agent.content_block_stopmessage_id、indexindex\ に対応する content block を終了します。
agent.message_deltamessage_id、delta、usagestop_reason、stop_sequence\ や使用量情報など、message レベルの増分を保持します。
agent.message_stopmessage_idassistant message を終了します。
text_delta、thinking_delta、signature_delta、input_json_delta、tool_output_delta はトップレベルの Event タイプではなく、agent.content_block_delta.delta.type としてのみ出現します。
delta.typeフィールド説明
text_deltatextテキスト出力フラグメント。クライアントは\ delta.text\ を追記してテキストを再構築できます。
thinking_deltathinkingモデルまたは provider が thinking を出力する際の思考フラグメント。
signature_deltasignaturethinking block の署名フラグメント。存在する場合に透過して返されます。
input_json_deltapartial_jsonツール入力パラメータの JSON フラグメント。
tool_output_deltavaries将来のツール出力ストリーミング用に予約されています。現時点では完全な\ agent.tool_result\ が優先されます。
agent.content_block_delta の例: 
1{2  "id": "evt_delta_xxx",3  "type": "agent.content_block_delta",4  "session_id": "sess_xxx",5  "message_id": "msg_xxx",6  "index": 0,7  "delta": {8    "type": "text_delta",9    "text": "这是"10  },11  "processed_at": "2026-06-22T11:00:01Z"12}
増分イベントの解析規約:
  • SSE event: と JSON data.type はどちらも公開 Event タイプを使用します。
  • agent.content_block_delta.index は複数の content block を区別するために使用します。
  • processed_at は増分イベントでは欠落する場合があります。クライアントは任意フィールドとして扱う必要があります。
  • ネットワーク中断後は、Last-Event-ID に最後に受信した Event ID を持たせて再接続できます。
  • include_thinking=false の場合、thinking_delta、signature_delta、および識別可能な thinking content block の start/stop イベントがフィルタリングされます。
  • include_tool_calls=false の場合、input_json_delta、tool_output_delta、および識別可能な tool content block の start/stop イベントがフィルタリングされます。