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

​
Session オブジェクト

create、get、list、update、archive の各エンドポイントが返します。
フィールド型説明
idstringsess_ プレフィックス付きの Session ID
typestring常に "session"
agentobjectこの Session が使用する Agent スナップショット。フィールドの形については Session 埋め込み agent を参照してください
environment_idstringこの Session が使用する Environment ID
statusstringSession のライフサイクル状態: rescheduling、running、idle、canceling、terminated。canceling は Cancel エンドポイントの確認応答が返す一時的な状態です。最終状態を確認するには Session をポーリングするか、ステータスイベントを監視してください
titlestring | nullSession のタイトル
metadataobjectSession のメタデータ
environment_variablesobjectagent ランタイムにエクスポートされる Session レベルの環境変数。JSON オブジェクト（{"NAME":"value"}）として返されます。空の Session では {} を返します。リクエスト形式は単一の文字列です（Session の作成 を参照）
incremental_streaming_enabledbooleanこの Session が増分ストリーミングイベントを公開するかどうか。作成時に省略した場合のデフォルトは false
resourcesSession resource の配列Session にアタッチされた file、GitHub repository、または Memory Store リソース
vault_idsstring の配列Session にアタッチされた Vault ID
deployment_idstring | nullSession が Deployment によって作成された場合の Deployment ID。それ以外は null
outcome_evaluationsarrayOutcome 評価結果。新しい Session では [] を返します
statsSession statsSession の統計情報
archived_atstring | nullアーカイブ時刻。アーカイブされていない場合は null
created_atstring作成時刻
updated_atstring最終更新時刻
Session レスポンスには agent_id、turn_status、memory_store_ids、usage などのレガシーフィールドは含まれなくなりました。

​
Agent 参照

create リクエストの agent は、文字列の Agent ID か、次のオブジェクトのいずれかを指定できます。
フィールド型必須説明
idstringはいagent_ プレフィックス付きの Agent ID
typestringはい（オブジェクト形式のみ)リテラル "agent" でなければなりません。オブジェクト形式を使う場合、欠落や他の値は 400 を返します。素の文字列形式（Agent ID を直接渡す)ではこのチェックはスキップされます
versionintegerいいえスナップショットする Agent バージョン。省略するか 0 を渡すと最新のアクティブバージョンを使用します

​
Session 埋め込み agent

Session オブジェクト 内に返される agent は、Session に固定された Agent スナップショットですが、公開される前にいくつかの Agent フィールドが取り除かれます。
  • created_at、updated_at — 埋め込み Agent には決して含まれません。
  • archived、archived_at — 含まれません。元の Agent のアーカイブ状態にかかわらず、Session はスナップショットへのアクセスを維持します。
  • metadata — Agent レベルのメタデータは取り除かれます。公開されるのは Session レベルの metadata のみです。
  • instructions — system に置き換えられます。
coordinator のマルチ Agent 構成では、agent.multiagent.agents[] がスタブの {type, id, version} 参照からサーバー側で完全な Agent 定義に展開されます（Multiagent ロスター要素 を参照）。Session Thread オブジェクト 内では、agent フィールドはさらに multiagent ブロックを取り除きます。coordinator のスレッドは agent ごとのスナップショットのみを保持します。

​
agent.model.effective_context_window

Session は agent.model 内に、レスポンス専用の追加フィールド effective_context_window（int64、トークン単位）を返します。これは、この Agent に対して Session が使用する、ランタイムで解決された（Environment レベルのオーバーライド適用後の)コンテキストウィンドウです。値がない場合や非正の場合は省略されます。クライアントはこのフィールドを参考情報として扱ってください。

​
Session resource

resources[] は type で区別される共用体です。

​
File resource

フィールド型必須説明
idstringレスポンスのみResource ID
typestringはい"file"
file_idstringはいfile_ プレフィックス付きの File ID。ファイルは ready である必要があります
mount_pathstringいいえコンテナ内のマウントパス。省略時のデフォルトは /mnt/session/uploads/<file_id>
created_atstringレスポンスのみリソースの作成時刻
updated_atstringレスポンスのみリソースの更新時刻

​
GitHub repository resource

フィールド型必須説明
idstringレスポンスのみResource ID
typestringはい"github_repository"
urlstringはいリポジトリ URL
authorization_tokenstringはい（書き込みのみ)リポジトリへのアクセスに使う GitHub トークン。レスポンスには返されません
mount_pathstringいいえコンテナ内の clone 先パス。省略時はリポジトリ名から既定値が設定されます
checkoutobjectいいえGit の checkout ターゲット。例: {"type":"branch","name":"main"}
created_atstringレスポンスのみリソースの作成時刻
updated_atstringレスポンスのみリソースの更新時刻

​
Memory Store resource

フィールド型必須説明
typestringはい"memory_store"
memory_store_idstringはいmemstore_ プレフィックス付きの Memory Store ID
accessstring | nullいいえ任意のアクセスモード。許可される値: "read_write"、"read_only"。空文字列または省略はデフォルト（オーバーライドなし)を意味します
instructionsstring | nullいいえSession リソースに保存される任意の指示。最大 4096 文字
namestring | nullレスポンスのみ取得可能な場合の現在の Memory Store 名
descriptionstringレスポンスのみ取得可能な場合の現在の Memory Store の説明
mount_pathstring | nullレスポンスのみ現在の実装では、既存のリソーススナップショットに値が含まれていない限り null を返します
Memory Store resource には id、created_at、updated_at フィールドは含まれません。

​
Session stats

フィールド型説明
active_secondsnumberアクティブな処理時間（秒)。新しい Session は 0 から始まります
duration_secondsnumberSession の継続時間（秒)。新しい Session は 0 から始まります

​
Multiagent ロスター要素

埋め込み Agent が multiagent.type = "coordinator" を宣言している場合、Session エンドポイントが返す agent.multiagent.agents[] の各エントリは、元のスタブ参照から完全な Agent 定義に展開されます（Session 埋め込み agent と同じフィールド除去ルールが適用され、さらに自身の multiagent フィールドも除かれます）。
フィールド型説明
typestring兄弟 Agent 参照の場合は "agent"、coordinator 自身の場合は "self"
idstringAgent ID。type = "agent" の場合に存在します。type = "self" の場合は coordinator 自身の ID をミラーします
versioninteger固定された Agent バージョン。type = "agent" の場合に存在します
namestring展開された Agent 名
descriptionstring | null展開された Agent の説明
systemstring展開された Agent のシステムプロンプト（instructions を置き換えます)
modelstring | object埋め込み Agent と同じ形。設定されている場合は effective_context_window を含みます
その他の Agent フィールド各種tools、MCP servers、skills、その他の Agent フィールド。埋め込み Agent と同じフィールド除去ルールが適用されます
解決に失敗したスタブ参照（例: 参照先の Agent バージョンがすでに存在しない)はそのまま返されます。

​
Event オブジェクト

send、list、stream の各エンドポイントが返すイベントは、イベントタイプごとに異なる JSON オブジェクトです。公開イベントレスポンスは、各イベントタイプの Claude 互換フィールドのみを公開します。
フィールド型説明
idstringevt_ プレフィックス付きの Event ID
typestringイベントタイプ
processed_atstringイベントが処理済みの場合に存在します。多くの agent 生成イベントはこのフィールドを省略します。
type に応じて、イベントには content、input、name、tool_use_id、mcp_tool_use_id、custom_tool_use_id、result、deny_message、rubric、outcome_id、session_thread_id、stop_reason、error、usage などのフィールドが追加で含まれることがあります。

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

増分ストリーミングは Session 作成時のフィールド incremental_streaming_enabled によって制御され、stream リクエストのパラメータでは選択しません。フラグが false または省略されている場合、list および stream エンドポイントは既存の完全な公開イベントのみを公開し続けます。フラグが true の場合、同じエンドポイントは次の増分イベントタイプも公開できます。 agent.message_start、agent.content_block_start、agent.content_block_delta、agent.content_block_stop、agent.message_delta、agent.message_stop。 これらがトップレベルの増分イベントタイプのすべてです。text_delta、thinking_delta、input_json_delta、tool_output_delta などの名前はイベントの type 値ではありません。これらは agent.content_block_delta 内の delta.type としてのみ現れます。
イベントタイプ主なフィールド説明
agent.message_startmessage_id, messageアシスタントメッセージを開始します。message はプロバイダーの raw stream message 形に従い、初期状態では content が空です
agent.content_block_startmessage_id, index, content_blocktext、thinking、redacted thinking、tool use などの 1 つの content block を開始します
agent.content_block_deltamessage_id, index, deltaindex の content block の delta を伝えます
agent.content_block_stopmessage_id, indexindex の content block を終了します
agent.message_deltamessage_id, delta, usagestop_reason、stop_sequence、任意の usage、任意のコンテキスト管理など、メッセージレベルの delta を伝えます
agent.message_stopmessage_idアシスタントメッセージを終了します
増分イベントには、利用可能な場合 session_id、session_thread_id、turn_id、parent_tool_use_id、processed_at も含まれることがあります。 サポートされる agent.content_block_delta.delta.type の値:
delta.typeフィールド備考
text_deltatextテキスト出力のチャンク
thinking_deltathinkingモデル/プロバイダーが出力する場合の thinking チャンク
signature_deltasignature利用可能な場合の thinking ブロックの署名チャンク
input_json_deltapartial_jsonツール入力 JSON のチャンク。これは製品レベルのツール入力 delta 概念のワイヤー形です
tool_output_delta各種将来のツール出力ストリーミング向けに予約されています。現在の実装では、完全なツール結果を代わりに agent.tool_result で返します
agent.content_block_delta の例: 
{
  "id": "evt_019efd3b90007c9b88be2a4e6d8c52a0",
  "type": "agent.content_block_delta",
  "session_id": "sess_019efd3b89d57bd18be423420cf5683f",
  "session_thread_id": "sthr_019efd3b89ff7ba19ddef9174cedba52",
  "turn_id": "turn_019efd3b8a117ca3a7f6b8bfbb4a4bb1",
  "message_id": "msg_019efd3b8c0d7d48a970f01dd6117d11",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Hello"
  },
  "processed_at": "2026-06-25T05:23:31.123Z"
}

​
クライアントイベントリクエストタイプ

POST /api/v1/cloud/sessions/{session_id}/events は、以下のクライアント送信イベントタイプのみを受け付けます。
タイプ必須フィールド備考
user.messagecontentcontent は空でない content block の配列でなければなりません
user.interruptなしsession_thread_id は任意で、省略時はレスポンスで null としてエコーされます
user.tool_confirmationtool_use_id、resultresult は allow または deny でなければなりません。deny_message は任意です
user.tool_resulttool_use_id組み込みツールの結果を返すために使用します。content と is_error は任意です
user.custom_tool_resultcustom_tool_use_idcontent と is_error は任意です
user.define_outcomedescription、rubricrubric は {"type":"text","content":"..."} や {"type":"file","file_id":"file_..."} などのオブジェクトです。max_iterations は任意です
system.messagecontentcontent は空でない text content block の配列でなければなりません。イベントは user/tool result イベントの後に続く必要があります

​
公開イベントタイプ

list および stream エンドポイントは、以下のイベントタイプを公開できます。 user.message、user.interrupt、user.tool_confirmation、user.custom_tool_result、user.define_outcome、user.tool_result、system.message、agent.custom_tool_use、agent.mcp_tool_result、agent.mcp_tool_use、agent.message、agent.message_start、agent.content_block_start、agent.content_block_delta、agent.content_block_stop、agent.message_delta、agent.message_stop、agent.thinking、agent.thread_context_compacted、agent.thread_message_received、agent.thread_message_sent、agent.tool_result、agent.tool_use、session.deleted、session.error、session.status_idle、session.status_rescheduled、session.status_running、session.status_terminated、session.thread_created、session.thread_status_idle、session.thread_status_rescheduled、session.thread_status_running、session.thread_status_terminated、session.updated、span.model_request_start、span.model_request_end、span.outcome_evaluation_start、span.outcome_evaluation_ongoing、span.outcome_evaluation_end。

​
Session Thread オブジェクト

managed-agent シナリオでは、Session 内の各 thread はこの構造で表現されます。
フィールド型説明
idstringsthr_ プレフィックス付きの Thread ID
typestring常に "session_thread"
session_idstring所属する Session ID
parent_thread_idstring | null親スレッド ID。coordinator スレッドの場合は null
agentobjectこの thread が使用する Agent スナップショット。Session 埋め込み agent と同じ形で、さらに multiagent ブロックが除かれます
statusstringスレッドのライフサイクル状態: running、idle、rescheduling、terminated
statsobject | nullスレッドの統計情報。現在の実装では null を返します
archived_atstring | nullアーカイブ時刻。アーカイブされていない場合は null
created_atstring作成時刻
updated_atstring最終更新時刻
Thread レスポンスには agent_id、agent_version、name、role、stop_reason、created_by_tool_use_id、usage などのレガシーフィールドは含まれなくなりました。

​
関連項目

Session の開始

Agent を環境に対してステートフルな会話として実行します。