Session と Event のデータ構造

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": "客户支持会话",
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "resources": [
    {
      "id": "sesr_xxx",
      "type": "file",
      "file_id": "file_xxx",
      "mount_path": "/data/workspace/spec.md",
      "created_at": "2026-06-23T05:53:19Z",
      "updated_at": "2026-06-23T05:53:38Z"
    }
  ],
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "model_credits": 10.5,
    "sandbox_runtime_credits": 2,
    "total_credits": 12.5
  },
  "outcome_evaluations": [
    {
      "type": "outcome_evaluation",
      "outcome_id": "outc_xxx",
      "description": "Resolve the customer issue",
      "iteration": 1,
      "result": "satisfied",
      "explanation": "The issue was resolved.",
      "completed_at": "2026-06-22T10:30:00Z"
    }
  ],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T11:00:00Z"
}

フィールド	型	必須返却	説明
`id`	string	はい	`sess_` プレフィックス付きの Session ID。
`type`	string	はい	固定値 `"session"`。
`identity_id`	string	はい	Forward Identity ID。この Session が属するエンドユーザーの Identity を表します。
`template`	object	はい	Forward Template の概要。フィールドは Template 概要を参照してください。
`source_type`	string	はい	Session の発生元：`api`、`im`、`schedule`、または `batch`。
`status`	string	はい	Session の実行状態:`idle`、`running`、`rescheduling`、`canceling` または `terminated`。アーカイブ状態は `archived_at` で表現されます。
`title`	string	はい	Session のタイトル。
`metadata`	object	いいえ	呼び出し側の業務メタデータ。
`config`	object	いいえ	Session の設定。指定しない場合は省略されることがあります。
`config.environment_variables`	object	いいえ	セッションレベルの環境変数。key-value 形式。Template と Identity Config のコンパイル結果に追加マージされ、同じ名前の変数は Session レベルの値でベースレイヤーの値を上書きします。
`resources`	array	No	Session にマウントされたリソース。現在はSession リソースを追加で追加した `file` のみを含み、ない場合は空配列。
`stats`	object	いいえ	Session の統計情報。フィールドは Session stats を参照してください。
`usage`	object	いいえ	使用量情報。利用可能なデータがない場合は省略されます。
`usage.model_credits`	number	いいえ	モデルが消費した Credit。
`usage.sandbox_runtime_credits`	number	いいえ	Sandbox ランタイムが消費した Credit。
`usage.total_credits`	number	いいえ	CAS が返す累積 Credit 消費量。
`outcome_evaluations`	array	はい	Outcome の現在の評価状態。Outcome がない場合は空配列。
`archived_at`	string \| null	はい	アーカイブ日時。アーカイブされていない場合は `null`。
`created_at`	string	はい	作成日時。RFC 3339 形式。
`updated_at`	string	はい	最終更新日時。RFC 3339 形式。

Template 概要

フィールド	型	必須返却	説明
`id`	string	はい	Forward Template ID。
`type`	string	はい	固定値 `"template"`。
`name`	string	はい	Template 名。
`model`	string	はい	Template が使用するモデルのティアまたはモデル識別子。
`version`	integer	はい	Template のバージョン番号。

Session resource

フィールド	型	必須	説明
`id`	string	Yes	`sesr_` で始まる Session リソース ID。
`type`	string	Yes	リソース種別。現在は `file`。
`file_id`	string	Yes	マウントした File ID。
`mount_path`	string	Yes	Agent コンテナ内の実際のパス。
`created_at`	string	Yes	RFC 3339 形式の作成日時。
`updated_at`	string	Yes	RFC 3339 形式の更新日時。

Session stats

stats が返される場合、以下のフィールドが含まれます。時間は整数秒で、CAS が小数を返した場合は小数部分を切り捨てます。

フィールド	型	必須返却	説明
`active_seconds`	integer	はい（`stats` 返却時）	アクティブな処理時間(秒)。新しい Session では通常 `0`。
`duration_seconds`	integer	はい（`stats` 返却時）	Session の継続時間(秒)。新しい Session では通常 `0`。

usage 内の各フィールドはそれぞれ任意です。データソースが返さない場合は対応するフィールドが省略され、明示的なゼロ値は 0 として返されます。

Outcome evaluation

outcome_evaluations の各項目には以下のフィールドが含まれます:

フィールド	型	null 可	説明
`type`	string	いいえ	評価タイプ。
`outcome_id`	string	いいえ	Outcome ID。
`description`	string	いいえ	Outcome の説明。
`iteration`	number	いいえ	現在の評価イテレーション。
`result`	string	いいえ	評価結果。
`explanation`	string	はい	結果の説明。
`completed_at`	string	はい	完了日時。

戻り値には grader turn、評価基準、単一イテレーションの使用量などの内部フィールドは含まれません。

Thread オブジェクト

Thread は Session ランタイム内の実行ブランチです。Thread の一覧、取得、アーカイブの各エンドポイントはこのオブジェクトを返します。

{
  "id": "sthr_child_xxx",
  "type": "session_thread",
  "session_id": "sess_xxx",
  "parent_thread_id": "sthr_coordinator_xxx",
  "template_id": "tmpl_worker",
  "name": "research",
  "role": "child",
  "status": "idle",
  "stop_reason": { "type": "end_turn" },
  "created_by_tool_use_id": "toolu_xxx",
  "stats": {
    "active_seconds": 20,
    "duration_seconds": 300,
    "startup_seconds": 2
  },
  "usage": {
    "total_credits": 1.25
  },
  "created_at": "2026-06-22T11:00:00Z",
  "updated_at": "2026-06-22T11:05:00Z"
}

フィールド	型	必須返却	説明
`id`	string	はい	`sthr_` プレフィックス付きの Thread ID。
`type`	string	はい	固定値 `"session_thread"`。
`session_id`	string	はい	Thread が属する Session ID。
`parent_thread_id`	string	いいえ	親 Thread ID。coordinator Thread では返されません。
`template_id`	string	いいえ	ランタイム Agent を親 Session の Forward Template に確実に対応付けられる場合に返されます。
`name`	string	いいえ	Thread の公開名。
`role`	string	はい	Thread のロール：`coordinator` または `child`。
`status`	string	はい	未アーカイブ時は `idle`、`running`、`rescheduling`、`terminated` などの実行状態。`archived_at` が設定されている場合は `archived` に正規化されます。
`stop_reason`	object	いいえ	Thread の停止理由。
`created_by_tool_use_id`	string	いいえ	child Thread を作成した tool use ID。
`stats`	object	いいえ	Thread のランタイム統計。
`stats.active_seconds`	integer	はい（`stats` 返却時）	アクティブな処理時間(秒)。
`stats.duration_seconds`	integer	はい（`stats` 返却時）	Thread の継続時間(秒)。
`stats.startup_seconds`	integer	いいえ	Thread の起動時間(秒)。
`usage`	object	いいえ	Thread の使用量情報。
`usage.total_credits`	number	いいえ	Thread の累積 Credit 消費量。
`archived_at`	string	いいえ	RFC 3339 形式のアーカイブ日時。未アーカイブ時は省略されます。
`created_at`	string	いいえ	RFC 3339 形式の作成日時。
`updated_at`	string	いいえ	RFC 3339 形式の最終更新日時。

Thread の時間は整数秒で、小数部分は切り捨てられます。startup_seconds と total_credits は欠落している場合に省略され、明示的なゼロ値は保持されます。Thread は credits、model_credits、sandbox_runtime_credits を返しません。 Thread レスポンスでは、CAS Agent ID、Agent オブジェクト、Agent Version、Template Version は公開されません。

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"
}

フィールド	型	必須返却	説明
`id`	string	はい	`evt_` プレフィックス付きの Event ID。
`type`	string	はい	Event のタイプ。
`session_id`	string	はい	Event が属する Session ID。
`session_thread_id`	string	いいえ	Thread ライフサイクル Event が示す Thread ID。
`processed_at`	string	いいえ	イベントが処理された日時。RFC 3339 形式。一部の agent 生成イベントや増分イベントには含まれない場合があります。

イベントタイプごとに出現が許可される payload フィールドは以下のとおりです。表では共通フィールド id、type、session_id、session_thread_id、processed_at は繰り返し記載していません。

Event タイプ	許可されるフィールド
`user.message`	`content`
`user.interrupt`	なし
`user.tool_confirmation`	`tool_use_id`、`result`、`deny_message`
`user.tool_result`	`tool_use_id`、`content`、`is_error`
`user.custom_tool_result`	`custom_tool_use_id`、`content`、`is_error`
`user.define_outcome`	`description`、`rubric`、`outcome_id`、`max_iterations`
`agent.message`	`content`
`agent.thinking`	`thinking`、`text`
`agent.message_start`	`message_id`、`message`
`agent.content_block_start`	`message_id`、`index`、`content_block`
`agent.content_block_delta`	`message_id`、`index`、`delta`
`agent.content_block_stop`	`message_id`、`index`
`agent.message_delta`	`message_id`、`delta`、`usage`
`agent.message_stop`	`message_id`
`event_start`	`event`
`event_delta`	`event_id`、`delta`
`agent.tool_use`	`name`、`input`、`evaluated_permission`
`agent.tool_result`	`tool_use_id`、`content`、`is_error`
`agent.custom_tool_use`	`name`、`input`
`agent.mcp_tool_use`	`mcp_server_name`、`name`、`input`、`evaluated_permission`
`agent.mcp_tool_result`	`mcp_tool_use_id`、`content`、`is_error`
`agent.artifact_delivered`	`file_id`、`original_filename`、`size`、`content_type`
`session.status_running`	なし
`session.status_idle`	`stop_reason`
`session.status_terminated`	なし
`session.thread_created`	`session_thread_id`
`session.thread_status_running`	`session_thread_id`
`session.thread_status_idle`	`session_thread_id`
`session.thread_status_rescheduled`	`session_thread_id`
`session.thread_status_terminated`	`session_thread_id`
`session.error`	`error`
`session.updated`	`agent`、`metadata`、`title`
`span.model_request_end`	`is_error`、`model_request_start_id`、`model_usage`
`span.outcome_evaluation_start`	`iteration`、`outcome_id`
`span.outcome_evaluation_ongoing`	`iteration`、`outcome_id`
`span.outcome_evaluation_end`	`explanation`、`iteration`、`outcome_evaluation_start_id`、`outcome_id`、`result`、`usage`

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

POST /api/v1/forward/sessions/{session_id}/events は以下のイベントタイプのみを受け付けます。

タイプ	必須フィールド	説明
`user.message`	`content`	ユーザーメッセージ。`content` は空でない content block の配列である必要があり、`text` と `image` タイプのみをサポートします。
`user.interrupt`	なし	現在の処理の中断を要求します。
`user.tool_confirmation`	`tool_use_id`、`result`	ツール呼び出しの確認。`result` は `allow` または `deny`。拒否時は `deny_message` を渡せます。
`user.tool_result`	`tool_use_id`	組み込みツールの結果を返します。`content` と `is_error` は任意です。
`user.custom_tool_result`	`custom_tool_use_id`	クライアント定義のカスタムツールの結果を返します。`content` と `is_error` は任意です。
`user.define_outcome`	`description`、`rubric`	期待する結果と評価基準を定義します。`max_iterations` は任意です。

公開イベントタイプ

履歴の照会や SSE イベントストリームの購読時には、以下の公開イベントタイプを受け取る可能性があります: user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result、user.define_outcome、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、event_start、event_delta、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.thread_created、session.thread_status_running、session.thread_status_idle、session.thread_status_rescheduled、session.thread_status_terminated、session.error、session.updated、span.model_request_end、span.outcome_evaluation_start、span.outcome_evaluation_ongoing、span.outcome_evaluation_end。

モデル使用量イベント

モデル呼び出しが完了すると、イベントストリームはその呼び出しの使用量を含む span.model_request_end イベントを出力します。

{
  "id": "evt_xxx",
  "type": "span.model_request_end",
  "is_error": false,
  "model_request_start_id": "evt_yyy",
  "model_usage": {
    "credits": 0.42
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

フィールド	型	説明
`is_error`	boolean	モデルリクエストがエラーまたはキャンセルで終了したかどうか。
`model_request_start_id`	string	対応するモデルリクエスト開始イベントの Event ID。
`model_usage`	object	このモデル呼び出しの使用量オブジェクト。
`model_usage.credits`	number	このモデル呼び出しで消費した Credits。

model_usage.credits は 1 回の呼び出しに対する増分使用量であり、Session の累積値ではありません。コンシューマーは Event ID で重複排除してから Session のモデル使用量記録に加算できます。イベントストリームは Session の累積使用量を返しません。Get Session から usage.total_credits を読み取り、イベントから累積した値の照合に使用してください。 event_start と event_delta は event_deltas[] で SSE を購読した場合のみ返されます。

Outcome evaluation イベント

Outcome の評価プロセスでは以下の公開イベントが返されます:

Event タイプ	payload フィールド
`span.outcome_evaluation_start`	`iteration`、`outcome_id`
`span.outcome_evaluation_ongoing`	`iteration`、`outcome_id`
`span.outcome_evaluation_end`	`explanation`、`iteration`、`outcome_evaluation_start_id`、`outcome_id`、`result`、`usage`

その他の評価プロセスの内部フィールドは返されません。

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

Session イベントストリームの購読時に event_deltas[] クエリパラメータを渡すことで event delta streaming を有効化します。繰り返しパラメータをサポートし、許可される値は以下のとおりです:

`event_deltas[]` の値	説明
`agent.message`	アシスタントテキストメッセージの増分コンテンツを購読します。
`agent.thinking`	thinking の増分コンテンツを購読します。この購読は Beta 機能であり、`X-Qoder-Beta: thinking-event-stream-delta-2026-07-20` リクエストヘッダーが必要です。詳細は Session Event Stream の購読を参照してください。

有効化されると、SSE ストリームは追加で 2 つのトップレベル Event タイプを返す場合があります:

イベントタイプ	主要フィールド	説明
`event_start`	`event`	パブリックイベントの生成開始を示します。`event` は `id`、`type`、`name`、`mcp_server_name` のみを保持します。
`event_delta`	`event_id`、`delta`	パブリックイベントの増分フラグメント。`event_id` は対応するイベントを参照します。

event_start.event のフィールド:

フィールド	型	説明
`id`	string	対応するイベントの Event ID。
`type`	string	パブリック Event タイプ。現在は `agent.message` または `agent.thinking`。
`name`	string	予約フィールド。現在の `event_deltas[]` セレクタでは通常返されません。
`mcp_server_name`	string	予約フィールド。現在の `event_deltas[]` セレクタでは通常返されません。

event_delta.delta のフィールド:

フィールド	型	説明
`type`	string	Delta タイプ。例: `content_delta`。
`index`	integer	Content block のインデックス。
`content`	object	増分コンテンツ。現在は `type` と `text` のみを公開します。
`content.type`	string	コンテンツタイプ。例: `text` または `thinking`。
`content.text`	string	増分テキストフラグメント。

event_start の例:

{
  "id": "evt_xxx",
  "type": "event_start",
  "session_id": "sess_xxx",
  "event": {
    "id": "evt_xxx",
    "type": "agent.message"
  }
}

event_delta の例:

{
  "id": "evt_xxx",
  "type": "event_delta",
  "session_id": "sess_xxx",
  "event_id": "evt_xxx",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "这是"
    }
  }
}

Event delta streaming の規約:

event_start / event_delta は event_deltas[] で SSE を購読した場合のみ返されます。履歴クエリではこれらのイベントは返されません。
最終的な完全なパブリックイベントは引き続き返されます。クライアントは event delta フレームを即時表示に使用し、最終的な完全イベントを永続化または表示の校正結果として使用できます。
include_thinking=false は agent.thinking の event start シグナルと delta.content.type=thinking フラグメントをフィルタリングします。
include_tool_calls=false は event_deltas[] で現在サポートされているタイプ（agent.message と agent.thinking）には影響しませんが、標準のツール使用イベントとレガシーのツール input/output delta はフィルタリングします。

レガシー増分ストリーミングのデータ構造

既存クライアントとの後方互換性のため、イベントストリームと履歴クエリは引き続きレガシー増分イベントを返すことがあります。これらのイベントは Session 作成時の incremental_streaming_enabled フィールドで制御されます。新規統合ではこれらのイベントに依存しないでください。最終的な完全な agent.message は引き続き返されます。レガシーのトップレベル増分イベントタイプは次のとおりです:

イベントタイプ	主要フィールド	説明
`agent.message_start`	`message_id`、`message`	assistant message を開始します。
`agent.content_block_start`	`message_id`、`index`、`content_block`	text、thinking、tool use などの content block を開始します。
`agent.content_block_delta`	`message_id`、`index`、`delta`	`index` に対応する content block の増分フラグメントを保持します。
`agent.content_block_stop`	`message_id`、`index`	`index` に対応する content block を終了します。
`agent.message_delta`	`message_id`、`delta`、`usage`	`stop_reason`、`stop_sequence` や使用量情報など、message レベルの増分を保持します。
`agent.message_stop`	`message_id`	assistant message を終了します。

text_delta、thinking_delta、signature_delta、input_json_delta、tool_output_delta はトップレベルの Event タイプではなく、agent.content_block_delta.delta.type としてのみ出現します。

`delta.type`	フィールド	説明
`text_delta`	`text`	テキスト出力フラグメント。クライアントは `delta.text` を追記してテキストを再構築できます。
`thinking_delta`	`thinking`	モデルまたは provider が thinking を出力する際の思考フラグメント。
`signature_delta`	`signature`	thinking block の署名フラグメント。存在する場合に透過して返されます。
`input_json_delta`	`partial_json`	ツール入力パラメータの JSON フラグメント。
`tool_output_delta`	varies	将来のツール出力ストリーミング用に予約されています。現時点では完全な `agent.tool_result` が優先されます。

agent.content_block_delta の例:

{
  "id": "evt_delta_xxx",
  "type": "agent.content_block_delta",
  "session_id": "sess_xxx",
  "message_id": "msg_xxx",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "这是"
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

レガシー増分イベントの解析規約:

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 イベントがフィルタリングされます。

​Session オブジェクト

​Template 概要

​Session resource

​Session stats

​Outcome evaluation

​Thread オブジェクト

​Event オブジェクト

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

​公開イベントタイプ

​モデル使用量イベント

​Outcome evaluation イベント

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

​レガシー増分ストリーミングのデータ構造