チャット：ストリーミングターンを開始

POST /v1/chat/stream

Agent のターンを開始し、session id を直ちに返します。ターンはバックグラウンドで実行されます。LLM デルタ、ツール呼び出し、ツール結果、最終アシスタントメッセージは、/v1/stream の多重化 WebSocket を通じて配信されます。channel は chat、key は返された session_id です。再接続時はセッションごとのシーケンスバッファーから再開します。

リクエスト本文

{ "message": "analyze BTC momentum", "session_id": "chat_...", "attachments": [ { "key": "file_ab12", "filename": "chart.png", "media_type": "image/png", "size": 48213, "kind": "image" } ], "model": "claude-sonnet-4-5", "reasoning_effort": "high" }

レスポンス本文

{ "session_id": "chat_...", "kind": "chat", "is_new": true }

注記

message 以外のフィールドはすべて任意です。完了済みのプロバイダー接続障害ターンを resume: true で継続する場合、または機能の設定後に capability_continuation でタスクを継続する場合は、message を省略できます。session_id は既存の会話を継続します。省略すると新しいセッションが開始され、その場合は session_kind がサーフェスを選択します（既定値は "chat"）。retry: true は重複するターンを追加せず、セッションの最新ターンを置き換えます。resume: true には既存の session_id が必要です。完了済みのツール結果を保持し、最後の永続化済み境界から処理を継続し、表示されるユーザーメッセージ行は追加しません。

メッセージ識別子と単発のスキル：client_message_id はクライアントが生成する空白以外を含む文字列（最大 200 文字）で、ユーザーメッセージとともに保存されます。retry: true では元の client_message_id を retry_target に指定します。従来のメッセージには u-<row id> も使えます。最新の永続化済みユーザーターンが対象と一致する場合だけ、そのターンを取り消します。未保存または後続のメッセージで置き換えられた対象は既存の履歴を削除しません。retry_target を省略すると、最新ターンを置き換える従来の動作を維持します。turn_skill_overrides: { include: string[], exclude: string[] } は今回のメッセージだけに適用し、メタデータの skill_overrides に保存します。セッションの既定値は変更しません。同じスキルで再試行する場合は元の設定を再送します。次の通常メッセージには引き継がれません。

capability_continuation: { "tool_call_id": "..." } には、既存の session_id と、直近の終了済みターンのツール結果に含まれる再開可能な機能設定要求が必要です。機能はインストール済みで、要求されたサービスを使用できる状態である必要があります。継続時は会話履歴とツール結果を保持し、表示されるユーザーメッセージ行を追加しません。重複したコールバック、新しいタスクで置き換えられたコールバック、未完了の設定には 409 を返します。retry: true や resume: true と併用しないでください。 継続時には元の Plan/Deep モードも保持され、中断されたタスクにも 409 を返します。parent_session_id や Plan 承認の継続と併用できません。connector_continuation は旧クライアント向けの別名で、同じ機能チェックを実行します。継続フィールドはどちらか一つだけ指定してください。

添付ファイル：まず POST /v1/files（multipart）でファイルをアップロードして key を取得し、このリクエストで参照します。各項目は { key, filename, media_type, size, kind } です。kind は "image" | "pdf" | "spreadsheet" | "text" | "office" に対応し、汎用の "file" は拒否します。1 ターンにつき最大 8 件、画像は各 5 MiB、その他のファイルは各 20 MiB までです。音声入力では voice_input_key に元の録音の FileStore key を指定します（POST /v1/voice/transcribe?persist でアップロード）。履歴で音声を再生でき、文字起こしは message に入ります。

ターン単位のモデル指定：model はこのターンのモデルのみを変更します。デプロイの既定値（PUT /v1/llm/default-model）や他のクライアントには影響しません。指定するモデルは現在接続中のプロバイダーが提供する必要があります。GET /v1/llm/available-models を参照してください。接続の切り替えが必要なモデルは 400 で拒否します。reasoning_effort はこのターンの推論レベルを上書きし、有効なモデルが対応する値に限ります。不正な値はターン開始前に 400 を返します。

ターン途中の誘導イベント：POST /v1/chat/interject でキューに入れたメッセージが実行中のターンへ注入されると、user_interjection イベント（{ "message": "...", "ts_ms": 1747000000000 }）が発行されます。最終 done イベントのデータには任意の 2 フィールドがあります。POST /v1/chat/interrupt でターンを停止した場合の interrupted: true と、注入には遅すぎたメッセージを列挙する pending_interjections: string[] です。クライアントは後者を通常のメッセージとして再送します。ヘッドレス呼び出しでは、任意の本文フィールド surface（"web" | "cli"、既定値 "web"）と prompt_mode（"full" | "minimal"、既定値 "full"）でシステムプロンプトを調整できます。cli はカスタム URI ワイヤープロトコルを省略し、minimal はリーンな骨格（アイデンティティ、スキル/ツール機構、基本 Markdown）をマウントして、スキルカタログ、日付、作業ディレクトリを保ったまま注入コンテキストから個人化を除去します。

WebSocket の channel、購読、シーケンス番号、再生、制御フレームは多重化 WebSocketを参照してください。