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

この記事の要点
- チャットのように会話を続けるアプリは「ストリーミング入力」、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. どうやって複数のメッセージを送る?
言語によって形が違います。
- TypeScript:SDKUserMessage を yield する非同期ジェネレーターを作り、query() の prompt に渡す。ユーザーの次のメッセージが来るまで、ジェネレーターを待たせる
- Python:ClaudeSDKClient を開き、メッセージごとに client.query() に渡す。文字列ならテキスト、画像を付けるなら、ユーザーメッセージを yield する非同期ジェネレーターを渡す
Claudeに1通ずつ別々に答えさせたいなら、前の応答の結果メッセージを待ってから次を送ります。 TypeScriptでは、ジェネレーターに約束(Promise)を待たせ、query() のループで結果メッセージが来たらそれを解決します。Pythonでは、receive_response() のループが終わってから、次の client.query() を呼びます。
Q3. 作業中にメッセージを送るとどうなる?
ツール呼び出しが終わったあとで、Claudeに届きます。 Claudeは、その新しいメッセージと、前のメッセージを、1つの応答でまとめて答えます。そのターンが先に終わっていたときは、新しいターンが始まります。ターンと予算の細かい挙動は エージェントループの記事 で解説しています。
チャット画面に組み込むときの形は次のとおりです(TypeScript)。
- pushMessage():画面の入力処理が、ユーザーの送信のたびに呼ぶ
- closeInput():ユーザーがチャットを閉じたときに呼ぶ
- userMessages():query() の prompt に渡すジェネレーター。配列が空なら、メッセージが来るか閉じられるまで待つ
応答の途中に積まれたメッセージは、1つの応答にまとまることがあります。いつ読ませるかを選びたいときは、メッセージの priority フィールドを使います。
Q4. 画像も送れる?
送れます。公式の例は、まずテキストで質問し、最初の応答が終わったあとで、テキストと画像を1つのメッセージに入れて送る流れです。画像は base64 に変換し、メディアの種類(PNG など)を添えます。
実行すると、「Response 1 finished: success」と「Response 2 finished: success」の2行が出ます。Claudeが画像を見ていないように見えるときは、公式のトラブルシューティングにある「画像を処理できなかった」の項目を確認します。
Q5. 応答が終わったことは、どこで分かる?
Claudeは、応答の最後に必ず結果メッセージを返します。 結果メッセージの subtype を見れば、成功(success)か、実行中のエラー(error_during_execution)かなど、終わり方が分かります。
- TypeScript:query() の for await のループが、各応答のメッセージを順に返す。ループは、最後の応答の結果メッセージのあと、ジェネレーターが終了した時点で止まる。メッセージに uuid を付けておくと、結果の user_message_uuids で、どのメッセージへの答えか対応づけられる
- Python:応答ごとに receive_response() のループを回す。各ループは、次の ResultMessage で止まる。会話の文脈は、メッセージをまたいでクライアントが保つ
最後の応答がエラーだった場合の違いに注意します。
| 言語 | 挙動 |
|---|---|
| TypeScript | そのエラーの結果を返したあと、例外を投げる。try と catch で包む。続けるなら、セッションを再開する新しい query() を始める |
| Python | receive_response() がエラーの結果をそのまま返し、例外は投げない |
TypeScriptでも、ジェネレーターにまだ送るメッセージが残っている間は、前の応答のエラーで例外は出ません。結果の種類ごとの意味は、公式の「結果の扱い」の項目にあります。
Q6. 応答を途中で止めたい
interrupt() を呼びます。セッションは開いたままです。 呼ぶ場所は言語で違います。
- TypeScript:prompt にジェネレーターを渡し、query() が返す Query オブジェクトを保存して、その interrupt() を呼ぶ
- Python:ClaudeSDKClient の interrupt() を呼ぶ。receive_response() のループが応答を読んでいれば、中断された応答の ResultMessage でループが終わる。次のメッセージは、その結果が来てから送る
中断された応答は、error_during_execution の結果で終わります。 中断の前に送っていて、まだ読まれていなかったメッセージは、中断した応答が終わったあとでClaudeに届きます。
公式の例は、長い作文を頼み、3秒後に中断し、そのあと同じセッションに「素数とは何か」を1文で聞く流れです。1回目は error_during_execution、2回目は success で終わります。
設計の前に確認したい3点
- 応答を1つずつ分けたいか、まとめてよいか(前の結果を待つかどうか)
- 最後の応答がエラーでも、会話を続けるか(TypeScriptは例外の処理が要る)
- 画面から「止める」ボタンを出すか(interrupt() の置き場所)
承認や確認の質問を扱うなら、ユーザー入力の記事 もあわせてご覧ください。
まとめ
- 会話型はストリーミング入力、単発の作業は query() に文字列を1つ渡す
- 応答は結果メッセージで終わる。次を送る前に、前の結果を待つと応答が分かれる
- 画像は、テキストと同じメッセージに base64 で入れる
- interrupt() で止めても、セッションは続く。止めた応答は error_during_execution で終わる
出典:Send messages to a running agent(公式ドキュメント)
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。


