Skip to main content
デフォルトでは、Agent SDK は Claude がレスポンスの生成を完了した後に、完全な AssistantMessage オブジェクトを返します。テキストとツール呼び出しが生成されるときにインクリメンタルな更新を受け取るには、部分的なメッセージストリーミングを有効にします。
このページは出力ストリーミング(リアルタイムでトークンを受け取ること)について説明しています。入力モード(メッセージの送信方法)については、エージェントにメッセージを送信するを参照してください。また、CLI 経由で Agent SDK を使用してレスポンスをストリーミングすることもできます。

ストリーミング出力を有効にする

ストリーミングを有効にするには、オプションで include_partial_messages(Python)または includePartialMessages(TypeScript)を true に設定します。これにより、SDK は到着した生の API イベントを含む StreamEvent メッセージを返すようになり、通常の AssistantMessage と ResultMessage に加えて返されます。 コードは以下の処理を実行する必要があります:
  1. 各メッセージのタイプをチェックして、StreamEvent を他のメッセージタイプから区別する
  2. StreamEvent の場合、event フィールドを抽出してそのタイプをチェックする
  3. delta.type が text_delta である content_block_delta イベントを探す。これには実際のテキストチャンクが含まれます
以下の例はストリーミングを有効にし、テキストチャンクが到着するときに出力します。ネストされたタイプチェックに注意してください:最初に StreamEvent、次に content_block_delta、その後 text_delta です:

StreamEvent リファレンス

部分的なメッセージが有効な場合、生の Claude API ストリーミングイベントがオブジェクトでラップされて返されます。タイプは各 SDK で異なる名前を持ちます: どちらも生の Claude API イベントを含み、蓄積されたテキストではありません。テキストデルタを自分で抽出して蓄積する必要があります。 parent_tool_use_id フィールドは Python では常に None、TypeScript では null です。ストリームイベントはメインセッションのみに対して発行されます。サブエージェントからのトークンレベルのデルタは転送されません。出力をサブエージェントに属性付けするには、parent_tool_use_id を含む完全なメッセージを使用してください。サブエージェント呼び出しの検出を参照してください。 Claude Code は、ターンの最初の非 ping ストリームイベントで user_message_uuid を設定し、ターンが応答しているメッセージが変わるときに再度設定します。これは user_message_uuid の条件下で行われます。Python の StreamEvent はこのフィールドを公開していません。 event フィールドには、Claude API からの生のストリーミングイベントが含まれます。一般的なイベントタイプは以下の通りです:

メッセージフロー

Claude Code は、空でない各コンテンツブロックが完了するたびに AssistantMessage を発行します。そのため、テキストブロックとツール呼び出しを含むレスポンスは 2 つの AssistantMessage オブジェクトを生成します。各メッセージは独自のコンテンツブロックのみを含み、両方とも同じメッセージ ID を共有します。これは TypeScript では message.message.id として、Python では message.message_id として読み取ります。部分メッセージが有効な場合、各 AssistantMessage はそのブロックの content_block_stop イベントの前に到着し、メッセージは以下の順序で受け取ります。
部分メッセージが有効でない場合、StreamEvent を除くすべてのメッセージタイプを受け取ります。一般的なタイプには SystemMessage(セッション初期化)、AssistantMessage(完全なコンテンツブロック)、ResultMessage(最終結果)、および会話履歴がコンパクト化されたときを示すコンパクト境界メッセージ(TypeScript では SDKCompactBoundaryMessage、Python では subtype "compact_boundary" の SystemMessage)が含まれます。

途中で切断されたストリームを処理する

ターンを中断した場合や接続が切れた場合など、ストリームがメッセージの途中で切断された場合でも、ターンが終了する前にそのメッセージの message_stop を受け取ります。切断されたテキストブロックまたは思考ブロックには content_block_stop も送られます。切断されたツール呼び出しには送られないため、ツール呼び出しのブロックがまだ開いている間に message_stop が到着した場合は、その呼び出しの入力を不完全なものとして扱ってください。 Claude Code v2.1.290 より前では、切断されたストリームが message_stop なしでターンを終了することがあり、ストリームイベントからレンダリングした応答が進行中のまま表示され続ける可能性がありました。TypeScript Agent SDK は v0.3.290 以降、Python Agent SDK は v0.2.164 以降で Claude Code v2.1.290 以降をバンドルしています。ターンの終了後も応答が進行中のまま表示される場合は、SDK を更新してください。

ツール呼び出しをストリーミングする

ツール呼び出しもインクリメンタルにストリーミングされます。ツールが開始されるときを追跡し、生成されるときに入力を受け取り、完了するときを確認できます。以下の例は、現在呼び出されているツールを追跡し、ストリーミングされるときに JSON 入力を蓄積します。3 つのイベントタイプを使用します:
  • content_block_start: ツール開始
  • content_block_delta with input_json_delta: 入力チャンク到着
  • content_block_stop: ツール呼び出し完了

ストリーミング UI を構築する

この例は、テキストとツールストリーミングを統合された UI に組み合わせます。エージェントが現在ツールを実行しているかどうかを追跡します(in_tool フラグを使用)。ツールの実行中に [Using Read...] のようなステータスインジケータを表示します。ツールが実行されていないときはテキストが通常にストリーミングされ、ツール完了は「完了」メッセージをトリガーします。このパターンは、マルチステップエージェントタスク中に進捗を表示する必要があるチャットインターフェースに役立ちます。

既知の制限事項

  • 構造化出力: 部分メッセージが有効な場合、JSON はツール呼び出しの未検証の input_json_delta チャンクとしてストリーミングされ、検証済みの結果のみが最終的な ResultMessage.structured_output に到達します。詳細は構造化出力を参照してください。

次のステップ

テキストとツール呼び出しをリアルタイムでストリーミングできるようになったので、これらの関連トピックを探索してください: