マルチエージェントAgent SDK のストリーミング｜返事を少しずつ表示する
この記事の要点
- 既定では、文章や道具の呼び出しが1かたまり書き終わってから届く。設定を1つ足すと、書いている途中から少しずつ届く
- 届くのは API の生の出来事。文章のかけらは自分でつなぎ合わせる
- サブエージェントの途中経過は流れてこない。途中で切れた時も、最後の合図だけは必ず届く
社内向けに AI のチャット画面を作ると、「返事が出るまで何も表示されず、止まっているように見える」 という声がよく出ます。長い返事ほど、待っている間の不安は大きくなります。
この記事では、公式ドキュメント「Stream responses in real-time」（2026年11月10日確認）にもとづいて、Claude Agent SDK で返事を書いている途中から少しずつ表示する方法を整理します。SDK の全体像は Claude Agent SDK とは で解説しています。
結論：設定を1つ足すと「書いている途中」から届く
既定の SDK は、文章や道具の呼び出しを「1かたまり書き終わってから」まとめて届けます。 途中から届けてほしいときは、オプションの includePartialMessages（Python では include_partial_messages）を true にします。
すると、いつものまとまったメッセージに加えて、書いている途中の出来事（ストリームの出来事） が次々に届くようになります。
届く出来事の種類
届くのは Claude API の生の出来事です。文章がつなぎ合わさった形ではなく、かけらで届く ので、表示する側でつなぎ合わせます。
| 出来事 | 意味 |
|---|---|
| message_start | 新しい返事が始まった |
| content_block_start | 文章か道具の呼び出しのかたまりが始まった |
| content_block_delta | かたまりの中身の続きが届いた |
| content_block_stop | かたまりが終わった |
| message_delta | 止まった理由や使った量などの更新 |
| message_stop | 返事が終わった |
文章を表示したいときは、content_block_delta のうち、中身の種類が text_delta のもの を拾って、順につなげて表示します。
道具を使っている様子も見せられる
道具の呼び出しも、少しずつ流れてきます。「いま何をしているか」を画面に出すと、待ち時間の不安が減ります。
- content_block_start で、どの道具を使い始めたかが分かる
- content_block_delta（中身は input_json_delta）で、道具に渡す内容が少しずつ届く
- content_block_stop で、呼び出しの組み立てが終わる
公式の例では、道具を使っている間だけ「[Read を使用中…]」のような表示を出し、終わったら「完了」と出す画面の作り方が紹介されています。
知っておきたい3つの注意
サブエージェントの途中経過は流れてこない
ストリームの出来事は、親の会話の分だけ です。サブエージェントの文章は、少しずつは届きません。どのサブエージェントの出力かを見分けたいときは、まとまったメッセージの側にある情報を使います。サブエージェントの使い方は Agent SDK のサブエージェント で解説しています。
途中で切れても「終わりの合図」は届く
通信が切れた、途中で止めた、などで返事が途中で切れることがあります。その場合も、message_stop は必ず届きます。 ただし、その手前の content_block_stop や message_delta は届かないことがあります。道具の呼び出しのかたまりが閉じないまま終わった時は、その呼び出しの中身は未完成として扱います。
古い版では、切れた時に終わりの合図が届かず、画面が「作成中」のまま残ることがありました（Claude Code 2.1.290 で改善。TypeScript 版 SDK 0.3.290 以降、Python 版 0.2.164 以降に同梱）。
決まった形の出力は、最後の結果を使う
決まった形（JSON）で答えさせる機能と一緒に使うと、途中のかけらは確認前の下書きとして流れてきます。確かめ終わった正しい結果は、最後の結果メッセージにだけ入ります。 形の決め方は Agent SDK の構造化出力 で解説しています。
仕事で使うときの考え方
少しずつ表示するかどうかは、「人が画面を見て待つかどうか」で決めます。
| 使い方 | おすすめ |
|---|---|
| 社内のチャット画面で人が待つ | 少しずつ表示する（待ち時間の不安が減る） |
| 夜間にまとめて処理する | 既定のまま（最後の結果だけ使えば十分） |
| 結果を表やデータとして使う | 既定のまま＋構造化出力 |
使った量（料金）を見たいときは、最後の結果メッセージの数字を使います。料金の見方は Agent SDK の料金の把握 を参照してください。
まとめ
- includePartialMessages を true にすると、書いている途中から届く
- 届くのは 生のかけら。文章は text_delta をつなげて表示する
- サブエージェントの途中は流れない。切れても message_stop は届く
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
