> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # Session と Event のデータ構造 > Forward Session API で使用する 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": "客户支持会话", "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" } ``` | フィールド | 型 | 必須返却 | 説明 | | ------------------------------- | -------------- | ---- | -------------------------------------------------------------------------------------------------------------- | | `id` | string | はい | `sess_`\ プレフィックス付きの Session ID。 | | `type` | string | はい | 固定値\ `"session"`。 | | `identity_id` | string | はい | Forward Identity ID。この Session が属するエンドユーザーの Identity を表します。 | | `template` | object | はい | Forward Template の概要。フィールドは [Template 概要](#template-概要) を参照してください。 | | `source_type` | string | はい | Session の発生元:`api`、`im`\ または\ `schedule`。 | | `status` | string | はい | Session の実行状態:`idle`、`running`、`rescheduling`、`canceling`\ または\ `terminated`。アーカイブ状態は\ `archived_at`\ で表現されます。 | | `title` | string | はい | Session のタイトル。 | | `incremental_streaming_enabled` | boolean | はい | この Session で増分ストリーミングイベントを有効にするかどうか。作成時に省略した場合は\ `false`\ となり、作成後は変更できません。 | | `metadata` | object | いいえ | 呼び出し側の業務メタデータ。 | | `config` | object | いいえ | Session の設定。指定しない場合は省略されることがあります。 | | `config.environment_variables` | object | いいえ | セッションレベルの環境変数。key-value 形式。 | | `stats` | object | いいえ | Session の統計情報。フィールドは [Session stats](#session-stats) を参照してください。 | | `usage` | object | いいえ | 使用量情報。関連する課金モジュールが有効でない場合は省略されることがあります。 | | `usage.credits` | number | いいえ | Credit の消費量。 | | `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 stats | フィールド | 型 | 必須返却 | 説明 | | ------------------ | ------- | ---- | --------------------------------------- | | `active_seconds` | integer | いいえ | アクティブな処理時間(秒)。新しい Session では通常\ `0`。 | | `duration_seconds` | integer | いいえ | 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" } ``` | フィールド | 型 | 必須返却 | 説明 | | -------------- | ------ | ---- | --------------------------------------------------------------- | | `id` | string | はい | `evt_`\ プレフィックス付きの Event ID。 | | `type` | string | はい | Event のタイプ。 | | `session_id` | string | はい | Event が属する Session ID。 | | `processed_at` | string | いいえ | イベントが処理された日時。RFC 3339 形式。一部の agent 生成イベントや増分イベントには含まれない場合があります。 | イベントタイプごとに出現が許可される payload フィールドは以下のとおりです。表では共通フィールド `id`、`type`、`session_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` | | `system.message` | `content` | | `agent.message` | `content` | | `agent.thinking` | なし | | `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` | | `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.error` | `error` | | `session.updated` | `agent`、`metadata`、`title` | ## クライアントが送信できるイベントタイプ `POST /api/v1/forward/sessions/{session_id}/events` は以下のイベントタイプのみを受け付けます。 | タイプ | 必須フィールド | 説明 | | ------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------- | | `user.message` | `content` | ユーザーメッセージ。`content`\ は空でない content block の配列である必要があり、`text`、`image`、`document`\ などのブロックタイプをサポートします。 | | `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`\ は任意です。 | `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_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` の例: ``` 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 イベントがフィルタリングされます。