--print
と組み合わせることで --output-format
オプションにより複数の出力フォーマットを提供する。プログラムからの利用に適した構造化フォーマット(json
、stream-json
)に加え、人間が進捗を読み取りやすい簡易テキストフォーマットを用意している。
デフォルトの
--output-format
は stream-json
。このオプションが有効になるのは、出力を表示する場合(--print
)か、表示モードが推定される場合(TTY でない stdout、またはパイプされた stdin)に限られる。JSON 形式
json
出力形式は、実行が正常に完了すると単一の JSON オブジェクト(末尾に改行)を出力する。デルタやツールイベントは出力されず、テキストは最終結果に集約される。
失敗時は、プロセスは非ゼロの終了コードで終了し、エラーメッセージを stderr に書き出す。失敗時には、正しく構成された JSON オブジェクトは出力されない。
成功時のレスポンス
Field | Description |
---|---|
type | ターミナル結果では常に "result" |
subtype | 成功した完了時は常に "success" |
is_error | 成功したレスポンスでは常に false |
duration_ms | 実行時間の合計(ミリ秒) |
duration_api_ms | API リクエスト時間(ミリ秒、現在は duration_ms と同一) |
result | アシスタントの応答全文(すべてのテキストデルタを連結したもの) |
session_id | 一意のセッション識別子 |
request_id | 任意のリクエスト識別子(省略される場合あり) |
Stream JSON フォーマット
stream-json
の出力フォーマットは、改行区切り JSON(NDJSON)を出力する。各行には、実行中のリアルタイムイベントを表す単一の JSON オブジェクトが含まれる。
ストリームは、成功時には終端の result
イベントで終了する。失敗時には、プロセスは非ゼロの終了コードで終了し、終端イベントなしに早期に終了する場合がある。エラーメッセージは stderr に出力される。
イベントタイプ
システム初期化
将来的に、このイベントに
tools
や mcp_servers
といったフィールドが追加される可能性がある。ユーザーメッセージ
Assistant text delta
完全なアシスタントの返答を再構成するには、順番どおりにすべての
message.content[].text
の値を連結してね。ツール呼び出しイベント
ツール呼び出しの種類
- 開始:
tool_call.readToolCall.args
に{ "path": "file.txt" }
が含まれる - 完了:
tool_call.readToolCall.result.success
にファイルのメタデータと内容が含まれる
- 開始:
tool_call.writeToolCall.args
に{ "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
が含まれる - 完了:
tool_call.writeToolCall.result.success
に{ "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
が含まれる
{ "name": "tool_name", "arguments": "..." }
を持つtool_call.function
構造を使用する場合がある
ターミナル結果
例のシーケンス
テキスト形式
text
出力形式は、エージェントの動作を人間が読みやすいシンプルなストリームで提供する。詳細な JSON イベントではなく、エージェントがリアルタイムで何をしているかを簡潔なテキストで記述して出力する。
この形式は、構造化データのパースによるオーバーヘッドなしでエージェントの進捗を監視できるため、ログ記録、デバッグ、シンプルな進捗トラッキングに最適。
出力例
実装メモ
- 各イベントは
\n
で終端される単一行として出力される thinking
イベントはプリントモードでは抑止され、いずれの出力形式にも含まれない- フィールドの追加は後方互換性を保つ形で段階的に行われる可能性がある(コンシューマは未知のフィールドを無視すること)
- ストリーム形式はリアルタイムに更新を提供し、JSON 形式は完了まで待機してから結果を出力する
- 完全なレスポンスを再構成するには、すべての
assistant
メッセージのデルタを連結する - ツール呼び出し ID は開始/完了イベントの相関付けに使用できる
- セッション ID は単一のエージェント実行全体を通して一貫して維持される