動いているエージェントに追加で指示を送る方法

公開 更新 著者 永上裕之マルチエージェント
宇宙船のコックピットで、小さなロボットが管制官に次々と指示のメモを送り、途中で止める赤いボタンに手をかけているイメージ

この記事の要点

  • チャットのように会話を続けるアプリは「ストリーミング入力」、1回の処理で終わる用途は「単発の呼び出し」を選ぶ
  • 各メッセージの応答は、結果メッセージ(result)で終わる。前の応答の結果を待ってから次を送ると、応答が1つずつ分かれる
  • interrupt() で応答を途中で止めても、セッションは閉じない。止めた応答は error_during_execution で終わり、続けて次のメッセージを送れる

活用例:社内のチャット画面から、動いているAIエージェントに追加の指示や画像を送る

部署
開発・情報システム
使うもの
Claude Agent SDK のストリーミング入力
AIに任せる
追加指示を受けた作業の続行・画像の読み取り
人が決める
どこで応答を止めるか・次に何を指示するか

AIエージェントを動かしたあとで、「やっぱりこの方向で」「この画像も見て」と足したくなることはありませんか。Claude Agent SDKには、1つのセッションを開いたまま、何度もメッセージを送れる仕組みがあります。

この記事は、公式ドキュメント「Send messages to a running agent」(2026年11月19日確認)にもとづいて、よくある疑問をQ&A形式でまとめます。SDKの全体像は Claude Agent SDKの記事 を、応答を逐次表示する出力側は ストリーミングの記事 をご覧ください。

Q1. 「ストリーミング入力」と「単発」は何が違う?

結論:会話を続けるならストリーミング入力、1つの用事で終わるなら単発です。

方式中身向く用途
ストリーミング入力セッションを開いたまま、複数のメッセージを送るチャット画面のような会話型のアプリ
単発query() にプロンプトの文字列を1つ渡す。Claudeが答えると呼び出しが終わるサーバーレス関数のような単一の作業

ストリーミング入力なら、画像の添付、応答の中断、実行中のモデルや権限モードの切り替えもできます。単発のあとに続きをしたいときは、セッションを再開する新しい呼び出しを始めます。再開の方法は セッションの記事 にあります。

なお、このページが扱うのは「こちらから送るメッセージ」です。Claudeの返答を生成中に画面へ出す方法は別のページ(ストリーミング出力)です。

Q2. どうやって複数のメッセージを送る?

言語によって形が違います。

Claudeに1通ずつ別々に答えさせたいなら、前の応答の結果メッセージを待ってから次を送ります。 TypeScriptでは、ジェネレーターに約束(Promise)を待たせ、query() のループで結果メッセージが来たらそれを解決します。Pythonでは、receive_response() のループが終わってから、次の client.query() を呼びます。

Q3. 作業中にメッセージを送るとどうなる?

ツール呼び出しが終わったあとで、Claudeに届きます。 Claudeは、その新しいメッセージと、前のメッセージを、1つの応答でまとめて答えます。そのターンが先に終わっていたときは、新しいターンが始まります。ターンと予算の細かい挙動は エージェントループの記事 で解説しています。

チャット画面に組み込むときの形は次のとおりです(TypeScript)。

応答の途中に積まれたメッセージは、1つの応答にまとまることがあります。いつ読ませるかを選びたいときは、メッセージの priority フィールドを使います。

Q4. 画像も送れる?

送れます。公式の例は、まずテキストで質問し、最初の応答が終わったあとで、テキストと画像を1つのメッセージに入れて送る流れです。画像は base64 に変換し、メディアの種類(PNG など)を添えます。

実行すると、「Response 1 finished: success」と「Response 2 finished: success」の2行が出ます。Claudeが画像を見ていないように見えるときは、公式のトラブルシューティングにある「画像を処理できなかった」の項目を確認します。

Q5. 応答が終わったことは、どこで分かる?

Claudeは、応答の最後に必ず結果メッセージを返します。 結果メッセージの subtype を見れば、成功(success)か、実行中のエラー(error_during_execution)かなど、終わり方が分かります。

最後の応答がエラーだった場合の違いに注意します。

言語挙動
TypeScriptそのエラーの結果を返したあと、例外を投げる。try と catch で包む。続けるなら、セッションを再開する新しい query() を始める
Pythonreceive_response() がエラーの結果をそのまま返し、例外は投げない

TypeScriptでも、ジェネレーターにまだ送るメッセージが残っている間は、前の応答のエラーで例外は出ません。結果の種類ごとの意味は、公式の「結果の扱い」の項目にあります。

Q6. 応答を途中で止めたい

interrupt() を呼びます。セッションは開いたままです。 呼ぶ場所は言語で違います。

中断された応答は、error_during_execution の結果で終わります。 中断の前に送っていて、まだ読まれていなかったメッセージは、中断した応答が終わったあとでClaudeに届きます。

公式の例は、長い作文を頼み、3秒後に中断し、そのあと同じセッションに「素数とは何か」を1文で聞く流れです。1回目は error_during_execution、2回目は success で終わります。

設計の前に確認したい3点

  1. 応答を1つずつ分けたいか、まとめてよいか(前の結果を待つかどうか)
  2. 最後の応答がエラーでも、会話を続けるか(TypeScriptは例外の処理が要る)
  3. 画面から「止める」ボタンを出すか(interrupt() の置き場所)

承認や確認の質問を扱うなら、ユーザー入力の記事 もあわせてご覧ください。

まとめ

  1. 会話型はストリーミング入力、単発の作業は query() に文字列を1つ渡す
  2. 応答は結果メッセージで終わる。次を送る前に、前の結果を待つと応答が分かれる
  3. 画像は、テキストと同じメッセージに base64 で入れる
  4. interrupt() で止めても、セッションは続く。止めた応答は error_during_execution で終わる

出典:Send messages to a running agent(公式ドキュメント)

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事