自律タスク実行の Agentic Loops

Agentic loop はすべての自律 Claude システムの実行の心拍である。Claude Certified Architect — Foundations（CCA-F）試験のタスクステートメント 1.1「自律タスク実行のための agentic loops を設計し実装する」が Domain 1（27% の比重）の中心に位置しているのには理由がある：試験に出てくる他のすべてのオーケストレーションパターン——コーディネーター・サブエージェントのファンアウトからセッションのフォーキング、マルチステップハンドオフまで——は、正しく設計された agentic loop の上に積み上げられる構造的な装飾にすぎない。ループのプリミティブを誤読すれば、Domain 1 の残り全体を誤読することになる。

本学習ノートは、CCA-F 受験者がアーキテクチャレベルで設計を求められる agentic loop の全領域を解説する。知覚・推論・行動・観察サイクル、stop_reason フィールドの正確なセマンティクス、認識を求められる四つの stop_reason の値、無限ループを防ぐ安全な終了条件、tool_result の注入形状、メッセージ履歴の増大管理、逐次 vs 並列ツール呼び出し、三つの Agent SDK ループエントリーポイント（run・stream・process）、ループ内のエラー処理分岐、そして本番環境品質の可観測性。最後のトラップセクションと六問の FAQ は、agentic loops を最も多く扱う四つの試験シナリオ——customer-support-resolution-agent・code-generation-with-claude-code・developer-productivity-with-claude・multi-agent-research-system——にすべての抽象的な概念を結びつける。

Agentic Loop とは何か：知覚・推論・行動・観察

Agentic loop とは、Claude が tool_use の提案と tool_result としての観察の受け取りを交互に繰り返し、終了条件が発火するまでイテレートする、制御されたマルチターンパターンである。ループがなければ Claude はテキスト補完であり、あれば Claude はエージェントになる。

ループは明示的である——あなたのコードが Claude を駆動する while ループを実行する。これは各応答の後に会話が終了するチャットボットとは根本的に異なる。ループは Claude が end_turn を発するか、あなたのガードレールがそれを遮断するか、ハードリミットが作動するまで実行し続ける。

CCA-F が Agentic Loops を最初に置く理由

試験ガイドがタスク 1.1 を Domain 1 の基盤として挙げているのは、後続のすべてのタスクステートメント（1.2 コーディネーター・サブエージェント、1.3 生成、1.4 ハンドオフ、1.5 hooks、1.6 タスク分解、1.7 セッション状態）が、tool_use と end_turn の間で Claude が何をしているかをすでに理解していることを前提としているからだ。コミュニティの合格報告は繰り返し、「stop_reason シグナルを無視する」ことを上位五つのミスの一つとして挙げている——試験当日に二〜三問のスコア付き問題を暗黙のうちに失う種類のミスだ。

Agentic Loop vs 単一ターン推論 — それぞれのアーキテクチャを選ぶ時

すべての Claude 呼び出しにループが必要なわけではない。本番での Claude 利用の大部分は依然として単一ターンだ：このテキストを分類する・このドキュメントを要約する・このメールの下書きを作成する。単一呼び出しで十分なときにループを選ぶと、メリットなしにレイテンシ・コスト・失敗モードが増加する。ループが必要なときに単一呼び出しを選ぶと、作業が不完全に終わることを保証する。

単一ターン推論

一発の prompt → 一発のレスポンス。タスクがすでに prompt の情報で完了でき、クエリするべき外部状態がなく、既知の形状（散文・JSON・ラベル）の出力を生成する場合に使用する。

Agentic Loop

タスクに認識論的不確実性がある場合——Claude がメッセージ時点では完全な答えを知ることができず、進捗するために情報を取得またはアクションを取る必要がある——は常に必要だ。ループはファイルの読み取り・データベースのクエリ・API の呼び出し、そしてステップ数を事前に予測できないオープンエンドのタスク（「このバグを修正する」「このチケットを解決する」）に適合する。

判断の経験則

ツールを削除しても Claude がタスクを完了できるなら、ループは必要ない。削除するとタスクが不可能になるなら、必要だ。

stop_reason フィールド — tool_use と end_turn の識別

すべての Claude レスポンスの stop_reason フィールドはループを駆動するシグナルである。Agentic loop はアーキテクチャ的に stop_reason のスイッチ文だ。このフィールドを誤読することは、CCA-F コミュニティプールで Domain 1 の最も高頻度のトラップとして繰り返し識別されている。

スイッチ文の思考モデル

while true:
    response = claude.messages.create(messages=history, tools=tools, ...)
    history.append(response)

    if response.stop_reason == "tool_use":
        tool_results = execute_tools(response.content)
        history.append({"role": "user", "content": tool_results})
        continue   # イテレート
    elif response.stop_reason == "end_turn":
        break      # Claude が完了と言っている
    elif response.stop_reason == "max_tokens":
        handle_truncation(response)
        break      # または後続のフォローアップで続行することを決定
    elif response.stop_reason == "stop_sequence":
        break      # 設定されたシーケンスが一致した；終了として扱う

このスケルトンは暗記する価値がある。実際の CCA-F agentic loop 設問のほとんどは、与えられた stop_reason の値に対して正しいブランチ動作を選択する能力をテストする。

tool_use — ループを続行する

stop_reason == "tool_use" の場合、Claude のコンテンツは一つ以上の tool_use ブロック（それぞれ name・id・input を持つ）を含む。それぞれを実行し、出力を一致する tool_use_id を持つ tool_result ブロックとしてパッケージ化し、新しいuser メッセージとして追加し、API を再度呼び出す。tool_use は続行を義務付ける唯一の値だ。

end_turn — ループを終了する

stop_reason == "end_turn" の場合、Claude は完了した——最後のアシスタントメッセージがユーザー向けの答えを含む。これがハッピーパスの終了だ。

stop_reason 値のカタログ — tool_use・end_turn・max_tokens・stop_sequence

CCA-F では四つの stop_reason の値を認識し、それぞれに対して正しいループの応答を知ることを求められる。

tool_use

Claude が一つ以上の tool_use ブロックを生成した。一致する tool_result ブロックを追加し、ループを続行する。

end_turn

Claude が完了と判断した。ループを終了する；最後のアシスタントメッセージが答えだ。

max_tokens

Claude がレスポンスの途中で設定された max_tokens の上限に達した——文の途中または tool_use ブロックの途中かもしれない。通常の完了ではない：出力バジェットが小さすぎる。max_tokens を増やして再試行するか、「続けて」というユーザーメッセージを追加するか、失敗として扱いエスカレーションするかのいずれかだ。

stop_sequence

Claude の生成が stop_sequences の文字列と一致した。ほとんどは既知のデリミタに Claude を事前にコミットする構造化出力ワークフローで一般的だ。その構造化ステップの終了として扱う——ただし、上位レベルの agentic loop は続行できる。

ループ終了条件 — 無限ループを避けるための安全な終了基準の設計

end_turn は Claude の自己申告の終了シグナルだが、本番の agentic loop は Claude の判断にのみ依存してはならない。多層防御としてガード条件を設計する。

すべての本番ループが実装すべき五つの終了ガード

1. イテレーションキャップ — ループのターン数のハードな最大値（例：20）。これなしのループは時折永遠に実行される。
2. 実経過時間タイムアウト — ループ全体の最大経過時間。
3. トークンバジェット — すべてのターンにわたる累積の入力＋出力トークンをビジネス定義の上限でキャップする。
4. 繰り返し状態の検出 — Claude が三回連続して同一の input で同じ tool_use を発した場合、ループはスタックしている；中止する。
5. ヒューマンエスカレーショントリガー — ループが自発的に人間に制御を返す条件（低信頼度・機密アクション・スコープ外のリクエスト）。

安全な終了が重要な理由

Claude は役立つように永続的に訓練されている。あいまいなタスクや役に立たないツールエラーでは、無限に再試行する可能性がある——CI/CD でキャップのないループは一晩中 API バジェット全体を消費することがあり、またはトークンが尽きるまで二つの同等のツール呼び出しの間を振動することがある。

Tool Result の注入 — tool_result メッセージとして観察をフィードバックする

すべてのループイテレーションの観察フェーズは、コンテンツが tool_result ブロックの配列である新しいuser メッセージを追加することとして機械的に実装される。このメッセージの形状を間違えることは、よくある実装レベルの試験トラップだ。

tool_result ブロックの形状

各 tool_result ブロックは以下を含む：

• type: "tool_result"
• tool_use_id — 前のアシスタントメッセージの対応する tool_use ブロックの id。
• content — ツールの出力を表す文字列またはコンテンツブロックの配列（テキスト・画像）。
• is_error — オプションのブール値；true はツール呼び出しが Claude が反応すべき方法で失敗したことを示す。

一つの user メッセージ、多くの tool_result ブロック

Claude が単一のアシスタントメッセージで複数の tool_use ブロックを発した場合（並列ツール呼び出し）、次の user メッセージは一つのメッセージ内にすべての一致する tool_result ブロックを含まなければならない——未処理の tool_use_id ごとに一つのブロック。一つずつ送ったり、新しいユーザーテキストと混在させると、API のコントラクトが壊れる。

構造化シグナルとしてのエラー

ツールが失敗した場合、is_error: true と content に簡潔で実行可能なエラー文字列を返す。これにより Claude はツール呼び出しが成功しなかったことを知り、再試行するか、代替ツールに切り替えるか、エスカレーションするかを決定するのに十分なコンテキストを得る。構造化エラーレスポンス（コンテンツ内に明示的な errorCategory と isRetryable フィールドを含む）は Domain 2 のパターンだが、その使用は agentic loop 内で行われる。

メッセージ履歴の増大 — ループイテレーション間の累積コンテキストの管理

すべてのループイテレーションは会話履歴に少なくとも二つのメッセージを追加する（アシスタントターンと user tool_result ターン）。長い agentic loop は大量のコンテキストを蓄積できる——中程度のツール出力を持つ 30 イテレーションのループは容易に数万トークンを埋める。

増大する履歴が生む三つの圧力

1. コスト — 後続のすべての API 呼び出しは、新しい生成に加えて入力トークンとして完全な履歴に対して支払う。
2. レイテンシ — 入力処理時間はコンテキストの長さとともにスケールする。
3. アテンション劣化 — 一定のスケールを超えると、Claude はコンテキストの中間にある情報が開始・終了コンテンツより重みを低くされる「中間で迷子」効果を示す。

ループ内の緩和戦略

• 詳細なツール出力のトリミング — ツールが 50,000 トークンのドキュメントを返す場合、結果を履歴に保存する前に要約または抽出する。
• 追い越された tool_result のクリア — 新しい tool_result は古いものを包含することが多い；コンテキスト編集機能（Claude 4 ではベータ）は廃止されたものをドロップできる。
• subagents の使用 — 高トークンのサブタスクを、独自の分離されたコンテキストを持つ subagent に委任する（タスク 1.2 / 1.3 で解説）。
• コンパクション / ハンドオフ — チェックポイントで、これまでのループを構造化された状態ブロブに要約し、新しいセッションを開始する。

これらの技法は Context Management の章節（Domain 5）で詳しく解説されているが、agentic loop のアーキテクトはそれらの存在と呼び出すタイミングを知っている必要がある。

ループ内の並列性 — 逐次ツール呼び出し vs 並列ファンアウト実行

Claude が単一のアシスタントメッセージで複数の tool_use ブロックを発した場合、二つの実行選択肢がある。

逐次 vs 並列

逐次——各ツール呼び出しを前のものが終了した後に実行する。ツール A の出力がツール B の入力を供給する場合に必要だ。

並列——すべての呼び出しを同時に実行する。呼び出しが独立している場合（異なるファイル・異なる DB クエリ・異なる検索語）は高速で安全だ。

アーキテクチャ的含意

ループは「ターンごとに一つのツール」ではない。単一のアシスタントターンは N 個の tool_use ブロックを運ぶ場合があり、一致する user ターンは N 個の tool_result ブロックを保持しなければならない。現代の Claude モデルは独立性を検出すると積極的に並列化するため、並列呼び出しを N 個の別々のターンにシリアライズするアプリはレイテンシ節約を無駄にする。

Agent SDK ループプリミティブ — run()・stream()・process() エントリーポイント

Claude Agent SDK（旧 Claude Code SDK）はあなたが毎回スイッチ文を手書きしなくて済むよう自動化された agentic loop を提供する。CCA-F では三つのエントリーポイントの認識と各使用時期を求められる。

run() — ブロッキング完全ループ実行

ループをスタートからフィニッシュまで実行し最終結果を返す。同期的な「答えを返して」という形状。スクリプト化されたタスク・バッチジョブ・短命な統合に最適。

stream() — インクリメンタルイベントストリーム

ループの進行に伴いイベントを生成する——アシスタントテキストのチャンク・tool_use の提案・tool_result の追加・イテレーション境界。人間が見ている場合に使用する：チャット UI・ミドループでの計測された判断・リアルタイム UI 更新。

process() — 低レベルのプログラム的制御

ターンごとの hooks、任意の状態遷移、カスタムループ形状（例：外部承認のために一時停止するループ）。run() と stream() では設計を表現できない場合にのみ使用する。

自動 vs 手動

SDK の自動ループはスイッチ文・tool_result の構築・終了ガードを処理する。そのためにターンごとの可視性とエキゾチックアーキテクチャの柔軟性を失う。ほとんどの本番システムは run() または stream() に住んでいる；Messages API に対する手動ループは SDK が公開する以上の細かい制御が必要な場合にのみ適切——通常はカスタムマルチエージェントオーケストレーターの内部だ。

ループ内のエラー処理 — ツール失敗時の再試行・スキップ・中止

本番ではツール呼び出しは常に失敗する：ネットワーク障害・レートリミット・期限切れの認証情報・ツール入力の論理エラー。よく設計された agentic loop はすべてのツール失敗に対して三つの応答オプションを持つ。

再試行

is_error: true とエラーが一時的であることを示すメッセージ（例：「ネットワークタイムアウト——1 秒後に再試行してください」）を含む tool_result を返す。Claude は通常、同じまたはわずかに変更された tool_use を再発する。再試行は基礎となる条件が自然に解消されると予想される場合に適切だ。

スキップ

is_error: true と特定のリクエストは履行できないが代替が機能するかもしれないことを示すメッセージを含む tool_result を返す。Claude は別のアプローチを試みる。スキップは特定のリソースへの権限エラー・特定のクエリへの不正入力・スコープ外のアイテムに適切だ。

中止

アプリケーション側からループを終了する。回復不可能なエラー（認証が完全に無効・ツールバックエンドが完全に停止・重大なガード条件のトリップ）に適切だ。

構造化エラーの分類

すべての is_error: true レスポンスをカテゴリ（transient・business・permission・internal）と isRetryable ブール値と組み合わせる。これは正式には Domain 2 のパターンだが、その使用は agentic loop のエラー処理分岐内に存在する。汎用的なエラー文字列は Claude を長い再試行ストームに誘発する；構造化エラーは Claude が正しいルーティング判断を下せるようにする。

ループの可観測性 — デバッグのための tool_use と tool_result のログ記録

Agentic loop は計装なしにデバッグするのが特に困難だ。すべての CCA-F 受験者は本番ループの最小の可観測性サーフェスを知っている必要がある。

各イテレーションでログに記録すべき内容

• イテレーションインデックス — ループの何番目のターンか。
• stop_reason — スイッチ文を駆動するシグナル。
• すべての tool_use ブロック — ツール名・入力引数・tool_use_id。
• すべての tool_result ブロック — tool_use_id・is_error・コンテンツのプレビューを切り捨てたもの・レイテンシ。
• トークン数 — ターンごとの入力・出力トークン；累積合計。
• タイミング — ターンごとの実経過時間；累積実経過時間。

これらすべてが重要な理由

エージェントが本番で誤動作した場合、最初の診断は「各ステップで Claude は何を決定したか」だ。tool_use ストリームがその物語を語る。tool_result ストリームは環境が協力したかどうかを明らかにする。トークンとタイミングの数は経済的・レイテンシのパソロジーを明らかにする。このデータなしに、すべてのデバッグセッションはゼロから始まる。

PostToolUse と PreToolUse の Hooks

Agent SDK は毎回のツール実行の前後に実行される PreToolUse と PostToolUse の hooks を公開している。これらはログ記録・メトリクス・ポリシーチェックを接続するクリーンな場所だ。Hook はフォーマルにはタスク 1.5 の章節だが、その存在は agentic loop の可観測性サーフェスの一部だ。

やさしい解説: — Agentic Loop の三つの類比

抽象的なループ機構は、ほとんどの受験者がすでに知っている物理的なシステムに固定すると直感的になる。三つの全く異なる類比が agentic loop の全領域を解説する。

類比 1: 厨房の調理場 — 知覚・推論・行動・観察

サービス中のシェフが調理場で働いている様子を想像してほしい。オーダーが入る（知覚——「12 番テーブルがローズマリーポテト添えのミディアムレアステーキを注文」）。シェフは何が必要かを考える（推論——「ステーキにはグリル、ポテトにはオーブン、コールドステーションからガーニッシュが必要」）。シェフは各ステーションにコマンドを発する（行動——tool_use ブロック）。しばらくして各ステーションが皿・タイマー・ステータス更新を返す（観察——tool_result ブロック）。シェフは何が返ってきたかを見て、料理が完成しているか次のステップが必要かを判断する。サービスシフト全体が agentic loop だ。tool_use はシェフが「ステーキを火にかけろ！」と叫ぶことだ。end_turn はシェフがエクスポのベルを叩いて「ピックアップ」と言うことだ。max_tokens は途中でキッチンが皿切れになってストップするようなことだ。stop_sequence はシェフのマネージャーが入ってきて「夜 10 時ぴったりにキッチンを閉める」と言うことだ。シェフは最初から完全な計画を書き出すことはしない——各ステーションから何が返ってくるかを観察しながら、一枚一枚のオーダーをイテレートする。これがまさに agentic loop の形状だ。

類比 2: 刑事の捜査 — 認識論的不確実性がループを駆動する

事件を担当している刑事は、限られた情報から始まる——被害者・場所・タイムライン。何を知らないかを知らないため、一発で事件を解決することはできない。手がかりを追う（証人へのインタビュー・電話記録の入手・現場への訪問）、何が返ってきたかを観察する、仮説を更新し、次の手がかりを追う。時に手がかりは行き詰まり（is_error: true）、別の角度を試みる（スキップ）。時に電話が初回で繋がらず（一時的な失敗）、再度かけ直す（再試行）。捜査が終わるのは刑事が答えに自信を持ったとき（end_turn）か、上司が残業予算がなくなったとして捜査を打ち切るとき（イテレーションキャップ）だ。刑事はすべてのステップを事前に計画しない；観察に反応する。Agentic loop は刑事が Claude・ツールが捜査アクション・あなたのアプリケーションが予算とルールを提供する警察署である刑事捜査だ。

類比 3: カーナビのループ — 単一ターンでは不十分な場合

カーナビゲーションシステムは、世界が変化できるときに agentic loop が単一ターン推論を凌駕する理由を示している。紙の地図（単一ターン推論）は出発時にルートを提供し、ドライブ中に何も変わらないと仮定する。ライブ GPS（agentic loop）は各ステップで再計算する：現在位置を観察し（知覚）、次の曲がり角を判断し（推論）、曲がるよう指示し（行動）、実際に曲がったかどうかを待つ（観察）。渋滞が出現すれば、ルートを変更する。出口を通り過ぎれば、調整する。目的地に到着すれば、「目的地に着きました」と言う（end_turn）。ガス欠になれば（max_tokens）、どれほど良い地図でもナビゲートを続けられない。紙の地図は不確実性のない一回限りのクエリに有効だ。ライブ GPS——agentic loop——はステップの間に現実が驚かせる可能性があるときに有効だ。驚きを含む CCA-F シナリオはほぼ常に単一ターン呼び出しではなくループを必要とする。

どの類比がどの試験問題に適合するか

• 四フェーズサイクルに関する設問 → 厨房の調理場の類比。
• なぜループが必要かに関する設問 → 刑事捜査の類比。
• agentic loop vs 単一ターンに関する設問 → カーナビの類比。

一般的な試験トラップ

CCA-F Domain 1 は agentic loops に関して五つの繰り返しトラップパターンを一貫して利用する。すべての五つはコミュニティの合格報告に記録されており、もっともらしい誤答の選択肢として偽装されて登場する。

トラップ 1: end_turn をエラーとして扱う

end_turn はagentic loop の正しい、成功した終了だ——Claude がタスクが完了したと判断し、これ以上することはないことを意味する。誤答の選択肢は end_turn を「モデルがあきらめた」または「ループが失敗した」とフレームする。両方のフレームが誤りだ。end_turn はハッピーパスだ。

トラップ 2: max_tokens を通常の完了として扱う

ループ中の max_tokens は切り捨てシグナルであり、正常な終了ではない。出力バジェットが使い果たされたためレスポンスが切り捨てられた。max_tokens を end_turn であるかのように扱う——例えば切り捨てられたコンテンツを最終的な答えとしてユーザーに返す——と壊れた出力が生成される。正しい処理はバジェットを増やして再試行するか、Claude に続けるよう求めるか、明示的なエラーで中止することだ。

トラップ 3: tool_result の tool_use_id が欠けている

すべての tool_result ブロックは元の tool_use ブロックに一致する tool_use_id を持たなければならない。ID フィールドなしに tool_result の注入を説明する答えは誤りだ。ID がなければ API がメッセージを拒否するか、Claude が最後のものが返されたことを確認できず同一のツール呼び出しを再発する。

トラップ 4: 本番ループにイテレーションキャップがない

end_turn にのみ基づいて終了するループは、暴走動作に対する防御がない。エージェントは時折、トークンが尽きるか請求が爆発するまで二つのツール呼び出しの間を振動し、繰り返し状態サイクルにはまることがある。すべての本番 agentic loop は明示的なイテレーションキャップと理想的には実経過時間タイムアウトを持たなければならない。キャップを省略した答えは安全ではない。

トラップ 5: run() で十分なときに process() を選ぶ

CCA-F は過剰エンジニアリングをペナルティにする。バッチモード抽出エージェントは process() ではなく run() を使用すべきだ。部分的な出力をレンダリングするチャット UI は process() ではなく stream() を使用すべきだ。process() は他の二つが表現できないアーキテクチャのためにある——カスタムの一時停止と再開・外部承認ゲート・新しいマルチエージェント形状。デフォルトで最も低レベルのプリミティブを選ぶことは設計の悪臭だ。

練習アンカー

Agentic loop の概念は CCA-F の六つのシナリオのうちの二つで最も多く登場する。以下をシナリオクラスター設問のアーキテクチャの背骨として扱うこと。

Customer-Support-Resolution-Agent シナリオ

このシナリオでは、カスタマーサポートエージェントが受信チケットを取得し、ナレッジベース検索ツール・CRM クエリツール・アカウントステータスツールを呼び出して調査し、チケットを自律的に解決するかヒューマンエスカレーションするかのいずれかを行う。Agentic loop は基幹だ：各ツール呼び出しは異なるシステムを観察し、呼び出しの順序は各検索が返すものに依存するため事前に計画できない。stop_reason を正しく分岐するか・到達できないバックエンドを is_error: true でマークするか・イテレーションキャップとヒューマンエスカレーショントリガーを実装するかをテストする設問を期待すること。

Developer-Productivity-With-Claude シナリオ

このシナリオでは、開発者が SDK 駆動エージェントを使用して大規模なコードベースにわたって自律タスクを実行する——バグ調査・複数ファイルのリファクタリング・テスト作成。エージェントは Read・Grep・Glob・Edit・Bash ツールを、数十イテレーションに及ぶことのある長いループで呼び出す。Tool_result 注入形状・メッセージ履歴管理（いつコンパクションするか、いつ subagent を生成するか）・並列ツール呼び出し処理（Claude はファイル読み取りを頻繁にファンアウトする）・正しい SDK エントリーポイント（スクリプト化バッチには run()、IDE UI には stream()）をテストする設問を期待すること。Multi-agent-research-system シナリオも agentic loops を扱うが、一次比重はタスク 1.2（コーディネーター・サブエージェントオーケストレーション）にシフトする。

FAQ — Agentic Loops 上位 6 問

Claude の文脈で agentic loop とは正確に何か

Agentic loop とは、Claude Messages API を繰り返し呼び出し、ツール実行結果を tool_result メッセージとしてフィードバックし、Claude が stop_reason: "end_turn" を返す（自然な終了）かガード条件が発火する（イテレーションキャップ・タイムアウト・トークンバジェット）まで続ける制御されたイテレーティブプロセスだ。ループは単一ターンチャットボットと自律エージェントの構造的な違いだ。CCA-F Domain 1 はほぼ全体がこのループを正しく設計することについてであり、後続のすべての Domain 1 パターン（マルチエージェントオーケストレーション・subagent の生成・ハンドオフ）はその上の装飾だ。

stop_reason の値としての tool_use と end_turn の違いは何か

tool_use は Claude が一つ以上のツール呼び出しを提案しており、アプリケーション（またはプラットフォーム）がそれらを実行して tool_result ブロックを返すことを待っていることを意味する；ループを続行しなければならない。end_turn は Claude がタスクが完了したと判断し、これ以上のアクションを取らないことを意味する；ループが終了し、最後のアシスタントメッセージが答えだ。これら二つの値を混同することは CCA-F Domain 1 で最も多く引用されるミスだ。正しいループは機械的に、tool_use で続行し end_turn で終了する stop_reason のスイッチ文だ。

ループ中の max_tokens という stop_reason はどう処理するか

max_tokens は Claude のレスポンスが出力バジェットに達したため切り捨てられたことを意味する。これは通常の完了ではない。三つの応答オプション：（1）max_tokens を増やして最後の呼び出しを再試行する；（2）短い「続けて」というユーザーメッセージを追加し Claude が次のターンで完了できるようにする；（3）ビジネスロジックが切り捨てを許容できない場合は明示的なエラーでループを中止する。max_tokens を end_turn であるかのように扱う——最終的な答えとして切り捨てられたコンテンツをユーザーに返す——ことは一般的なアーキテクチャ上のバグであり、CCA-F で直接テストされる。

Agent SDK の run() を stream() または process() の代わりにいつ使用するか

バッチ・非インタラクティブ・スクリプト化されたエージェント実行で単一の「最終結果を返して」という戻り値が欲しい場合は run() を使用する。人間が待っておりインクリメンタル出力を表示する必要がある場合——チャット UI・ライブダッシュボード・IDE 統合——は stream() を使用する。他の二つがループ形状を表現できない場合にのみ process() を使用する——カスタムの一時停止と再開パターン・ループ中の外部承認ゲート・エキゾチックなマルチエージェントオーケストレーション。試験は最もシンプルなプリミティブを選ぶことを報いる；柔軟性を求めてデフォルトで process() を選ぶことは設計の悪臭だ。

Agentic loop が永遠に実行されないようにするにはどうすればよいか

少なくとも二つのガードを実装する：（1）ループを stop_reason に関わらず終了させるハードなイテレーションキャップ（典型値は 15〜30 ターン）；（2）実経過時間タイムアウト・累積トークンバジェット・繰り返し状態の検出・ヒューマンエスカレーショントリガーのリストから追加のガード一つ。end_turn にのみ依存することは Claude が時折同等のツール呼び出しの間を振動する可能性があるため不十分だ。CCA-F は「イテレーションキャップを追加する」をベースラインの安全要件として扱う；それを省略したシナリオの答えは、設計の残りが適切であっても不正解だ。

Agentic loop 内でツールエラーを Claude にどうフィードバックするか

元の tool_use に一致する tool_use_id を持つ tool_result ブロック、is_error: true、そして content に簡潔で実行可能なエラーメッセージを返す。理想的にはエラーメッセージに構造化カテゴリ（transient・business・permission・internal）と isRetryable ヒントを含め、Claude が再試行するか、代替アプローチを試みるか、エスカレーションするかを決定できるようにする。is_error: true なしにツール失敗を非エラー文字列として返すことは最悪のアンチパターンだ——Claude はコンテンツを正当な観察データとして扱い、捏造された事実に基づいてさらなるアクションを計画するかもしれない。

参考資料

• Claude のツール使用 — 概要と agentic loop: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
• Agent SDK 概要: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview
• ツール呼び出しの処理 — tool_result フォーマット: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/handle-tool-calls
• 効果的なエージェントの構築 — agentic loop リファレンス: https://docs.anthropic.com/en/docs/build-with-claude/agentic-loop
• Writing tools for agents — Anthropic Engineering Blog: https://www.anthropic.com/engineering/writing-tools-for-agents

関連 ExamLab 章節: コーディネーター・サブエージェントパターンによるマルチエージェントオーケストレーション, タスク分解戦略, セッション状態・再開・フォーキング, Agent SDK Hooks によるツール呼び出し傍受.