Skip to main content
Sessions

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": "客户支持会话",
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "total_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、または batch。
statusstringはいSession の実行状態:idle、running、rescheduling、canceling\ または\ terminated。アーカイブ状態は\ archived_at\ で表現されます。
titlestringはいSession のタイトル。
metadataobjectいいえ呼び出し側の業務メタデータ。
configobjectいいえSession の設定。指定しない場合は省略されることがあります。
config.environment_variablesobjectいいえセッションレベルの環境変数。key-value 形式。Template と Identity Config のコンパイル結果に追加マージされ、同じ名前の変数は Session レベルの値でベースレイヤーの値を上書きします。
statsobjectいいえSession の統計情報。フィールドは Session stats を参照してください。
usageobjectいいえ使用量情報。関連する課金モジュールが有効でない場合は省略されることがあります。
usage.total_creditsnumberいいえ累積 Credit 消費量であり、推奨される使用量フィールド。新しく作成された Session にのみ返され、過去の Session では省略される場合があります。
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。

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",
  "created_at": "2026-06-22T11:00:00Z",
  "updated_at": "2026-06-22T11:05:00Z"
}
フィールド型必須返却説明
idstringはいsthr_ プレフィックス付きの Thread ID。
typestringはい固定値 "session_thread"。
session_idstringはいThread が属する Session ID。
parent_thread_idstringいいえ親 Thread ID。coordinator Thread では返されません。
template_idstringいいえランタイム Agent を親 Session の Forward Template に確実に対応付けられる場合に返されます。
namestringいいえThread の公開名。
rolestringはいThread のロール：coordinator または child。
statusstringはい未アーカイブ時は idle、running、rescheduling、terminated などの実行状態。archived_at が設定されている場合は archived に正規化されます。
stop_reasonobjectいいえThread の停止理由。
created_by_tool_use_idstringいいえchild Thread を作成した tool use ID。
archived_atstringいいえRFC 3339 形式のアーカイブ日時。未アーカイブ時は省略されます。
created_atstringいいえRFC 3339 形式の作成日時。
updated_atstringいいえRFC 3339 形式の最終更新日時。
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"
}
フィールド型必須返却説明
idstringはいevt_\ プレフィックス付きの Event ID。
typestringはいEvent のタイプ。
session_idstringはいEvent が属する Session ID。
session_thread_idstringいいえThread ライフサイクル Event が示す Thread ID。
processed_atstringいいえイベントが処理された日時。RFC 3339 形式。一部の agent 生成イベントや増分イベントには含まれない場合があります。
イベントタイプごとに出現が許可される payload フィールドは以下のとおりです。表では共通フィールド id、type、session_id、session_thread_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
agent.messagecontent
agent.thinkingthinking、text
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
event_startevent
event_deltaevent_id、delta
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.thread_createdsession_thread_id
session.thread_status_runningsession_thread_id
session.thread_status_idlesession_thread_id
session.thread_status_rescheduledsession_thread_id
session.thread_status_terminatedsession_thread_id
session.errorerror
session.updatedagent、metadata、title
span.model_request_endis_error、model_request_start_id、model_usage

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

POST /api/v1/forward/sessions/{session_id}/events は以下のイベントタイプのみを受け付けます。
タイプ必須フィールド説明
user.messagecontentユーザーメッセージ。content は空でない content block の配列である必要があり、text と image タイプのみをサポートします。
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\ は任意です。

公開イベントタイプ

履歴の照会や 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.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_errorbooleanモデルリクエストがエラーまたはキャンセルで終了したかどうか。
model_request_start_idstring対応するモデルリクエスト開始イベントの Event ID。
model_usageobjectこのモデル呼び出しの使用量オブジェクト。
model_usage.creditsnumberこのモデル呼び出しで消費した Credits。
model_usage.credits は 1 回の呼び出しに対する増分使用量であり、Session の累積値ではありません。コンシューマーは Event ID で重複排除してから Session のモデル使用量記録に加算できます。イベントストリームは Session の累積使用量を返しません。Get Session から usage.total_credits を読み取り、イベントから累積した値の照合に使用してください。 event_start と event_delta は event_deltas[] で SSE を購読した場合のみ返されます。

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

Session イベントストリームの購読時に event_deltas[] クエリパラメータを渡すことで event delta streaming を有効化します。繰り返しパラメータをサポートし、許可される値は以下のとおりです:
event_deltas[] の値説明
agent.messageアシスタントテキストメッセージの増分コンテンツを購読します。
agent.thinkingthinking の増分コンテンツを購読します。
有効化されると、SSE ストリームは追加で 2 つのトップレベル Event タイプを返す場合があります:
イベントタイプ主要フィールド説明
event_starteventパブリックイベントの生成開始を示します。event は id、type、name、mcp_server_name のみを保持します。
event_deltaevent_id、deltaパブリックイベントの増分フラグメント。event_id は対応するイベントを参照します。
event_start.event のフィールド:
フィールド型説明
idstring対応するイベントの Event ID。
typestringパブリック Event タイプ。現在は agent.message または agent.thinking。
namestring予約フィールド。現在の event_deltas[] セレクタでは通常返されません。
mcp_server_namestring予約フィールド。現在の event_deltas[] セレクタでは通常返されません。
event_delta.delta のフィールド:
フィールド型説明
typestringDelta タイプ。例: content_delta。
indexintegerContent block のインデックス。
contentobject増分コンテンツ。現在は type と text のみを公開します。
content.typestringコンテンツタイプ。例: text または thinking。
content.textstring増分テキストフラグメント。
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_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 の例: 
{
  "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 イベントがフィルタリングされます。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス