マルチエージェントAgent SDK の動く仕組み｜ターンと結果の見方
この記事の要点
- Agent SDK は「考える → 道具を使う → 結果を見る」を、道具を使わない返事が出るまで繰り返す。この1周がターン
- 回数（maxTurns）と金額（maxBudgetUsd）の上限は、どちらも既定では無し。本番では金額の上限を入れておくのが公式のすすめ
- 終わったら結果の subtype を見る。success 以外の時は result が入っていない
AI エージェントに作業を頼むと、「いま何をしているのか」「いつ終わるのか」「なぜ途中で止まったのか」 が分からなくなることがあります。Claude Agent SDK の中で何が繰り返されているかを知っておくと、止め方・見張り方・費用の抑え方が決めやすくなります。
この記事では、公式ドキュメント「How the agent loop works」（2026年11月12日確認）にもとづいて、エージェントループの仕組みを整理します。SDK の全体像は Claude Agent SDK とは で解説しています。
結論：「道具を使わない返事」が出るまで回り続ける
Agent SDK は、Claude Code と同じ仕組みで動きます。 頼んだ文を受け取ると、Claude が状況を見て道具（ファイルを読む・コマンドを実行するなど）を使うかを決め、その結果を見てまた次を決めます。これを、道具を1つも使わない返事が出るまで 繰り返します。
この1周を ターン と呼びます。ターンの間はあなたのコードに制御が戻らず、SDK が自動で結果を Claude に渡し続けます。
ターンの数え方の例
公式ドキュメントでは、「auth.ts のテストの失敗を直して」という依頼で、次の4ターンの例が示されています。
- テストを実行して、3件の失敗を見つける
- 対象のファイルとテストのファイルを読む
- ファイルを直して、テストをもう一度実行する（全部通る）
- 道具を使わずに「直しました。3件とも通ります」と返す
道具を使った3ターンに、最後の返事の1ターンを足して4ターン です。回数の上限（maxTurns）を決める時は、この最後の1ターンを忘れないようにします。足りないと、最後の返事が出ないまま止まります。
流れてくるメッセージは5種類
ループが回る間、SDK からはメッセージが順に届きます。
| 種類 | 中身 | 使いどころ |
|---|---|---|
| SystemMessage | 始まり（init）・要約した印・お知らせなど | 使える道具やスキルの確認 |
| AssistantMessage | Claude の返事や道具の呼び出し（1つずつ） | 進み具合の表示 |
| UserMessage | 道具の結果 | 何が返ったかの記録 |
| StreamEvent | 文字が出てくる途中経過（設定した時だけ） | 画面にリアルタイムで出す |
| ResultMessage | 最後の答え・使った量・費用・会話の ID | 結果と費用の保存 |
結果だけが欲しいなら ResultMessage だけを見れば足ります。 ただし、結果のあとに小さなお知らせが届くことがあるので、結果が来た時点で読むのをやめず、最後まで受け取るのが公式のすすめです。途中経過を画面に出す方法は Agent SDK のストリーミング で解説しています。
回数と金額に上限をかける
上限は、どちらも既定では「無し」です。 範囲がはっきりした依頼なら困りませんが、「このコードを良くして」のような終わりのない依頼では長く回り続けることがあります。
| 上限 | 指定 | 届いた時の結果 |
|---|---|---|
| 回数 | maxTurns（Python は max_turns） | error_max_turns |
| 金額 | maxBudgetUsd（Python は max_budget_usd） | error_max_budget_usd |
公式は、本番で動かすエージェントには金額の上限を入れておくのがよい としています。金額の上限には、サブエージェントが使った分も入ります。上限に届くと、新しいサブエージェントは起動できず、裏で動いていたものも止まります。
気をつけたいのは、金額は返事が届いてから計算される 点です。上限に届いた返事そのものは最後まで処理されるので、実際の費用はその1回分だけ上限を超えることがあります。上限には少し余裕を持たせます。費用の数え方は Agent SDK の費用の追い方 にまとめています。
考える深さと、確認の要り方も選べる
effort で、Claude がどれだけ深く考えるかを選べます。 深いほど丁寧ですが、時間と費用がかかります。
- low：ファイルを探す・一覧を出すなどの軽い作業
- medium：いつもの修正
- high：大きな直し・原因の調査
- xhigh・max：何段階もある難しい問題
道具を使う前に確認を取るかは、権限のモード（permissionMode）で決めます。対話のアプリなら default と承認の仕組み、作業用のフォルダで編集を任せるなら acceptEdits、確認なしで動かすのは隔離した環境だけ、というのが公式の目安です。くわしくは Agent SDK の権限設定 を見てください。
長い作業で文脈をむだにしない
会話の文脈（コンテキスト）は、ターンをまたいで積み上がっていきます。 大きなファイルを読んだり、長い出力のコマンドを実行したりすると、1回で大きく増えます。上限に近づくと SDK が古いやりとりを自動で要約しますが、初めのほうの細かい指示は残らないことがあります。
公式がすすめる工夫は次の4つです。
- 細かい作業はサブエージェントに任せる：戻ってくるのは最後の返事だけなので、本体の文脈がふくらまない
- 道具を絞る：道具の説明も文脈を使う
- ずっと守らせたい決まりは CLAUDE.md に書く：要約されても毎回読み直される
- 軽い作業は effort を low にする
終わったら結果の subtype を見る
| subtype | 意味 | 答え（result）はあるか |
|---|---|---|
| success | ふつうに終わった | ある |
| error_max_turns | 回数の上限に届いた | ない |
| error_max_budget_usd | 金額の上限に届いた | ない |
| error_during_execution | 途中でエラーが起きた | ない |
| error_max_structured_output_retries | 決めた形の出力が作れなかった | ない |
答えが入っているのは success の時だけ なので、必ず subtype を先に確かめます。どの場合も、費用・使った量・ターン数・会話の ID は入っているので、止まった会話を続きから再開できます。再開の方法は Agent SDK のセッション管理 で解説しています。
よくある質問
maxTurns を 0 にすると、すぐ止まりますか？
止まりません。0 は「上限なし」と同じ扱い です。一方、金額の上限に 0 を入れると、起動の時点で不正な値として断られます。
途中で何を待っているのか分かりません
AssistantMessage を受け取って、呼び出された道具の名前を画面やログに出すと、どこで時間がかかっているかが分かります。記録をまとめて残したい時は Agent SDK の見える化 も使えます。
まとめ
- Agent SDK は 道具を使わない返事が出るまで ターンを繰り返す
- 回数と金額の上限は既定で無し。本番では金額の上限を、余裕を持たせて入れる
- 終わったら subtype を見てから 答えを読む
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
