Qoder CN シリーズ:セッションとイベントのデータ構造

Session オブジェクト

Create、Get、List、Update、および Archive Session エンドポイントはすべて、このオブジェクトを返します。

{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Customer support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Customer support conversation",
  "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"
}

テンプレートの概要

セッション統計

イベントオブジェクト

API によって返されるイベントは JSON オブジェクトで、ペイロードは type によって異なります。すべてのイベントには同じ共通フィールドのセットに加え、タイプ固有のペイロードフィールドが含まれます。

{
  "id": "evt_xxx",
  "type": "agent.message",
  "session_id": "sess_xxx",
  "content": [
    {
      "type": "text",
      "text": "Here is the analysis result."
    }
  ],
  "processed_at": "2026-06-22T11:00:03Z"
}

各イベントタイプで使用できるペイロードフィールドは、以下のとおりです。共通フィールドの id、type、session_id、および processed_at は、繰り返しになるため表には記載していません。

クライアント書き込み可能なイベントタイプ

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

system.message はパブリックイベントタイプですが、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 。

インクリメンタルストリーミングイベント

インクリメンタルストリーミングイベントを公開するかどうかは、会話の作成時に設定する incremental_streaming_enabled フィールドによって制御され、履歴クエリや SSE サブスクリプションのリクエストパラメータには依存しません。

• true ：イベントストリームは、最終的な agent.message の前にアシスタントの部分的な出力を返します。履歴クエリも同じインクリメンタルイベントを返します。

• false または省略：標準モード。完全な公開イベントのみが返され、インクリメンタルイベントは発行されません。

インクリメンタルストリーミングが有効な場合でも、最終的な完全な agent.message は返されます。クライアントは、即時レンダリングのためにインクリメンタルイベントを使用し、永続化や表示の調整における信頼できる唯一の情報源として、最終的な agent.message に依存できます。

以下の 6 つのトップレベルイベントタイプのみがインクリメンタルです。

text_delta 、 thinking_delta 、 signature_delta 、 input_json_delta 、および tool_output_delta はトップレベルのイベントタイプではありません。これらは agent.content_block_delta.delta.type の値としてのみ現れます。

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": "Here"
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

インクリメンタルイベントを解析するためのルール：

• SSE の event: 行と JSON の data.type は、両方とも公開イベントタイプを使用します。

• agent.content_block_delta.index は、複数のコンテンツブロックを区別します。

• processed_at はインクリメンタルイベントに存在しない場合があります。クライアントはこれを任意として扱う必要があります。

• ネットワークが中断した後は、最後に受信したイベント ID を含む Last-Event-ID ヘッダーを使用して再開します。

• include_thinking=false を設定すると、thinking_delta 、 signature_delta 、および認識可能な思考コンテンツブロックの開始/停止イベントが除外されます。

• include_tool_calls=false を設定すると、input_json_delta 、 tool_output_delta 、および認識可能なツールコンテンツブロックの開始/停止イベントが除外されます。