# エージェントループ：モデル呼び出しとツール使用の反復 > コーディングエージェント Claude Code の中心にある「モデルを呼ぶ → ツールを実行する → 結果を返す」の反復を、公開ドキュメントの記述から状態遷移の模型として定式化し、メッセージ列の不変条件、ターン上限による停止、入力トークンの 2 次の増加、予算の超過幅を証明する。 > https://rikai.mugen-giken.com/computer-science/claude-code-internals/agent-loop ## 0. この記事の要点 Claude Code に「失敗しているテストを直して」と頼むと、ファイルを読み、コマンドを動かし、結果を見てまた次の手を打つ、という動きをします。この動きの裏には、AI の答えを受け取って道具を動かし、その結果をまた AI に見せる、という単純な繰り返しがあります。この記事では、その繰り返しを小さな数式の模型で表し、途中で止まるのか、どれだけ文章が膨らむのか、いくらまで使うのかを、はっきり言える形で調べます。読み終えると、エージェントが「なぜ止まるのか」「なぜ長い作業ほど重くなるのか」を、理由つきで説明できるようになります。 - Claude Code の中心は、**モデルを呼ぶ → 応答に[ツール呼び出し](/computer-science/claude-code-internals/tools-and-permissions#def-tool-call)があれば実行する → 結果をメッセージ列の末尾に足してもう一度モデルを呼ぶ**、という反復です。公式ドキュメントはこれを agentic loop と呼び、モデルの周りでツールを提供し文脈を管理する層を agentic harness（ハーネス。モデルを動かす外側のプログラムのこと）と呼んでいます。 - この記事では、公開されている仕様（Messages API のツール使用の書式、Agent SDK のループの説明）を**状態遷移の模型**として置き、その模型の中で性質を証明します。模型はモデルの中身を何も仮定しません（任意の写像として扱います）。 - 模型のループは、「ツール呼び出しのある assistant メッセージの直後に、同じ id の結果がちょうど 1 つずつ先頭に並ぶ」という不変条件（処理のあいだ、ずっと成り立つ条件）を保ちます。これは API が要求する書式そのもので、ツールの実行が拒否された場合にも保たれます。 - ツール使用ターンの上限 $T$ を置くと、モデルの呼び出しは高々 $T + 1$ 回で止まります。上限を置かないループの停止は、モデルの振る舞いに依存し、ハーネスの側からは保証できません。 - 圧縮をしなければ、$k$ 回目の呼び出しの入力は $k$ について 1 次で増え、入力の合計は 2 次で増えます。[コンテキストウィンドウ](/computer-science/claude-code-internals/context-window-and-prompt-caching#def-context-window)（モデルが一度に読める量の上限）$W$ のもとで続けられる呼び出しの回数には上界があります。 - 支出の上限を「応答を受け取ったあとで比べる」規則では、最終の支出は上限を 1 応答ぶん未満だけ超えうる、という公式ドキュメントの注意が、判定の時点から導けます。 この記事の事実の記述は、2026-10-10 に確認した公式ドキュメントに基づきます。コマンド名・既定値・モデル名は版と時期で変わるので、各節の末尾の出典で最新の記述を確かめてください。 ## 1. 動機 言語モデルは、与えられたトークン列の続きを 1 トークンずつ生成する関数です（[推論：自己回帰生成・KV キャッシュ・サンプリング・量子化](/computer-science/llm-architecture/inference-and-sampling)）。それだけでは、ファイルを読むことも、テストを実行することもできません。コーディングエージェントが「失敗しているテストを直す」ことができるのは、モデルの外側に、モデルの出力を読んで実際にコマンドを実行し、その結果を次の入力に入れる**ふつうのプログラム**があるからです。 したがって、エージェントの振る舞いを理解するには、2 つを分けて考えるのが有効です。 1. **モデル**が何を出力するか。これは学習で決まり、確率的で、外から保証できることはわずかです。 2. **ハーネス**（モデルの周りのプログラム）が、その出力をどう扱うか。これは決定的なコードで、不変条件や停止性を証明できます。 [LLM とプログラミング](/computer-science/ai-era/llm-and-programming) では、仕事を任せるかどうかの判断を、委譲コスト（）と検証器（）で扱いました。この記事は、その先、**任せたときに何が動いているか**を扱います。モデルがなぜそのツールを選ぶのかは説明しません。公開資料に書かれていないからです。説明するのは 2 のほう、ハーネスが守る規則と、そこから導ける性質です。 このテーマの以降の章は、すべてこの記事のループへの操作として書かれます。[ツールと権限](/computer-science/claude-code-internals/tools-and-permissions) はループの「ツールを実行する」直前の関門を、[コンテキストウィンドウとプロンプトキャッシュ](/computer-science/claude-code-internals/context-window-and-prompt-caching) は「モデルに渡すメッセージ列」の大きさと料金を扱います。 ## 2. メッセージ・ブロック・ツール：公開されている書式 まず、公開されている API の書式を定義として整理します。ここでの「環境」は、ファイルの内容のように、ツールが読み書きする外側の状態のことです。また、ツールの入力の形を書き表す JSON Schema は、「どんな名前の項目がどんな型で入るか」を決める記法です。この節の定義は、Claude API のドキュメントの記述を、後の証明で使う範囲に絞って抽象化したものです。 $\mathrm{Id}$ を識別子の集合、$\mathrm{Name}$ をツール名の集合、$\mathrm{In}$ をツールの入力（JSON の値）の集合、$\mathrm{Str}$ を文字列の集合とする。**内容ブロック**は次の 3 種類のいずれかである。 - **text ブロック** $\mathsf{text}(s)$（$s \in \mathrm{Str}$）。 - **tool_use ブロック** $\mathsf{use}(u, n, x)$（$u \in \mathrm{Id}$、$n \in \mathrm{Name}$、$x \in \mathrm{In}$）。モデルが「ツール $n$ を入力 $x$ で呼びたい」と表明したもの。 - **tool_result ブロック** $\mathsf{res}(u, y, \epsilon)$（$u \in \mathrm{Id}$、$y \in \mathrm{Str}$、$\epsilon \in \{0, 1\}$）。id が $u$ の呼び出しの結果 $y$。$\epsilon = 1$ は実行が失敗したこと（`is_error`）を表す。 **メッセージ**は、役割 $\rho \in \{\mathtt{user}, \mathtt{assistant}\}$ と内容ブロックの有限列の組 $(\rho, (b_1, \ldots, b_\ell))$ である。メッセージ $m$ に現れる tool_use ブロックの id を、現れる順に並べた列を $U(m)$ と書く。 API の実物では、ブロックには画像や文書などの種類もあり、tool_result の内容は文字列のほかブロックの列でもかまいません。ここでは 3 種類に絞ります。役割についての注意が 1 つあります。Claude API には `tool` や `function` といった役割はなく、ツール呼び出しは assistant メッセージの中のブロック、結果は user メッセージの中のブロックとして表されます。「user メッセージ」は、人間が書いた文章とは限りません。 **ツールの定義**は、名前 `name`、説明 `description`、入力の形を JSON Schema で書いた `input_schema` の 3 つ組である。モデルには定義が渡され、モデルは説明を読んで呼ぶかどうかを決める。 **環境**の状態の集合を $E$ とする（ファイルシステムの内容、外部のサービスの状態など）。名前 $n$ のツールの**実行**を、写像 $$ \mathrm{exec}_n : \mathrm{In} \times E \to (\mathrm{Str} \times \{0, 1\}) \times E $$ として置く。$\mathrm{exec}_n(x, e) = ((y, \epsilon), e')$ は、「状態 $e$ で入力 $x$ を与えると、結果 $y$ と失敗の印 $\epsilon$ を返し、環境が $e'$ に変わる」ことを表す。 ツールは、実行される場所で 2 種類に分かれます。**クライアント側のツール**（client tools）は、API を呼ぶアプリケーションの側で実行されます。モデルの応答は tool_use ブロックを含んで止まり、アプリケーションが実行して結果を送り返します。**サーバ側のツール**（server tools。ウェブ検索、コード実行など）は API の提供者の基盤で実行され、アプリケーションは実行を扱いません。Claude Code の組み込みツール（ファイルの読み書き、シェルコマンドの実行など）は、利用者の機械の上で動くので、前者の形です。この記事の模型はクライアント側のツールだけを扱います。 API の応答は、生成が止まった理由 `stop_reason` を持つ。2026-10 時点の公式ドキュメントが挙げる値は次の 7 つである。 | 値 | 止まった理由 | |---|---| | `end_turn` | モデルが応答を自然に終えた | | `tool_use` | モデルが（クライアント側の）ツールを呼ぼうとしている | | `max_tokens` | 出力が要求の `max_tokens` の上限に達した | | `stop_sequence` | 指定した停止文字列が出力された | | `pause_turn` | サーバ側のツールの反復が、その回数の上限に達した | | `refusal` | モデルが応答を断った | | `model_context_window_exceeded` | 出力の途中でコンテキストウィンドウの上限に達した | ループを書くうえで本質的なのは `tool_use` とそれ以外の区別です。`pause_turn` はサーバ側のツールを使うときにだけ現れ、公式ドキュメントは、その反復の上限の既定を「1 回の要求あたり 10 回」と述べ、応答をそのまま送り返して続きを求めるよう指示しています。この記事の模型には入れません。 モデルの周りで、(i) ツールの定義をモデルに渡し、(ii) モデルが出力した tool_use ブロックを読んでツールを実行し、(iii) モデルに渡すメッセージ列（文脈）を組み立てて管理するプログラムを、**ハーネス**という。 公式ドキュメントは、ループを動かすものを「推論するモデル」と「行為するツール」の 2 つとし、Claude Code を「ツールを提供し、モデルが見る文脈を管理する、モデルの周りの層」と説明して、これを agentic harness と呼んでいます。 はその説明を定義の形にしたものです。同じドキュメントは、組み込みツールを、ファイル操作・検索・実行・ウェブ・コード解析の 5 つに分類し、このほかにサブエージェントの起動や利用者への質問などの調整用のツールがあると述べています。 書式には、後で不変条件として証明する規則があります。**tool_result ブロックは、対応する tool_use ブロックを含む assistant メッセージの直後のメッセージに置き、あいだに別のメッセージを挟めません。その user メッセージの中では tool_result ブロックを先頭に並べ、文章はそのあとに置きます。** 公式ドキュメントは、文章を先に置いた例を「400 エラーになる」例として示しています。 出典（確認日 2026-10-10）: [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)、[Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls)、[Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons)、[How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)。 ## 3. ループの模型と不変条件 ### 3.1. 模型 Agent SDK のドキュメントは、ループを 5 段階で説明しています。(1) プロンプトを受け取る。(2) モデルが評価して、文章・ツール呼び出しの要求・その両方のいずれかで応答する。(3) ハーネスが要求されたツールを実行し、結果をモデルに返す。(4) 2 と 3 を繰り返す。(5) ツール呼び出しのない応答が出たら、それを最終の結果として返す。これを状態遷移系として書きます。次の定義は、ループを「これまでのメッセージ列・環境・済んだターン数」という 3 つ組が 1 段ごとに更新されていく仕組みとして書いたものです。1 段では、モデルを 1 回呼び、ツール呼び出しが無ければ終わり、あれば実行して結果を足します。4 に出てくる $e^{(j)}$ は、$j$ 番目の呼び出しを実行した直後の環境です。 次のものが与えられているとする。 - **モデル** $M$: メッセージの有限列を受け取り、assistant メッセージを 1 つ返す写像。内容は text ブロックと tool_use ブロックだけからなり、1 つのメッセージの中の tool_use ブロックの id は互いに異なるとする。それ以外の性質は何も仮定しない。 - 各ツール名 $n$ に対する実行 $\mathrm{exec}_n$（）。 - **関門** $g : \mathrm{Name} \times \mathrm{In} \to \{\mathrm{run}, \mathrm{refuse}\}$。呼び出しを実行するか拒否するかを決める写像。 - 拒否を伝える文字列 $y_{\mathrm{ref}} \in \mathrm{Str}$。 - ツール使用ターンの上限 $T \in \{0, 1, 2, \ldots\} \cup \{\infty\}$。 **状態**は、メッセージ列 $h$、環境 $e \in E$、済んだツール使用ターンの数 $t$ の組 $(h, e, t)$ である。**初期状態**は、利用者のプロンプト $p$ と環境 $e_0$ に対して $((\mathtt{user}, (\mathsf{text}(p))),\ e_0,\ 0)$ とする。状態 $(h, e, t)$ からの **1 段**を次のように定める。 1. $a = M(h)$ を求める（モデルの呼び出し 1 回）。 2. $U(a)$ が空なら、**完了**として停止する。最終のメッセージ列は $h \cdot a$ である。 3. $U(a)$ が空でなく $t = T$ なら、**ターン上限**として停止する。$a$ のツール呼び出しは実行せず、メッセージ列は $h$ のままとする。 4. それ以外のとき、$a$ の tool_use ブロックを現れる順に $\mathsf{use}(u_1, n_1, x_1), \ldots, \mathsf{use}(u_q, n_q, x_q)$ とし、$e^{(0)} = e$ から順に、$j = 1, \ldots, q$ について - $g(n_j, x_j) = \mathrm{run}$ なら $((y_j, \epsilon_j), e^{(j)}) = \mathrm{exec}_{n_j}(x_j, e^{(j-1)})$、 - $g(n_j, x_j) = \mathrm{refuse}$ なら $(y_j, \epsilon_j) = (y_{\mathrm{ref}}, 1)$、$e^{(j)} = e^{(j-1)}$ と定める。user メッセージ $b = (\mathtt{user}, (\mathsf{res}(u_1, y_1, \epsilon_1), \ldots, \mathsf{res}(u_q, y_q, \epsilon_q), c_1, \ldots, c_r))$ を作る。ここで $c_1, \ldots, c_r$ は 0 個以上の text ブロック（実行中に利用者が送った追加の指示など）である。次の状態は $(h \cdot a \cdot b,\ e^{(q)},\ t + 1)$ である。 4 の 1 回を **1 ターン**（ツール使用ターン）という。 この模型は、公式ドキュメントが述べる仕様を定式化したもので、Claude Code の実装そのものではありません。模型に入れた仮定を挙げます。 - モデルの呼び出しとツールの実行は、必ず値を返して終わると仮定しています（写像として置いたため）。実物では通信の失敗や利用者による中断があり、Agent SDK はそれを結果の種別 `error_during_execution` で表します。 - 1 つの応答の中のツール呼び出しを順に実行するとしています。実物が並行に実行する場合については で扱います。 - 1 つのメッセージの中の tool_use の id が互いに異なることは、モデルの出力についての仮定です。API のドキュメントは id を「この tool_use ブロックの一意な識別子」と説明しています。 - 文脈の圧縮、サブエージェント、フックは入れていません。圧縮とサブエージェントは [文脈を保つ・減らす・分ける](/computer-science/claude-code-internals/compaction-memory-subagents) で、フックは [拡張の仕組み](/computer-science/claude-code-internals/extension-mechanisms) で扱います。
メッセージ列 h （末尾に足すだけ） モデル M a = M(h) a に tool_use はあるか 関門 g → 実行 （拒否も結果にする） 結果 b を作る h ← h · a · b 完了 ターン上限 （t = T） 無い ある（t が T 未満）
### 3.2. 書式の不変条件 メッセージ列 $h = (m_1, \ldots, m_N)$ が次の 3 条件を満たすとき、$h$ は**対応の不変条件** $\mathrm{Inv}$ を満たすという。 - (P1) $m_1$ の役割は $\mathtt{user}$ で、$m_N$ の役割も $\mathtt{user}$ である。 - (P2) 役割が $\mathtt{assistant}$ で $U(m_i) = (u_1, \ldots, u_q)$ が空でないすべての $i$ について、$i \lt N$ であり、$m_{i+1}$ は役割 $\mathtt{user}$ のメッセージで、その内容の最初の $q$ 個のブロックは、この順に id が $u_1, \ldots, u_q$ の tool_result ブロックである。 - (P3) (P2) の $m_{i+1}$ の $q + 1$ 個目以降のブロックに tool_result ブロックは無い。また、tool_result ブロックは (P2) の形で現れるものに限る。 (P2) と (P3) を合わせると、「assistant メッセージの各 tool_use の id に対し、直後の user メッセージに同じ id の tool_result がちょうど 1 つあり、それらが内容の先頭に並ぶ」となります。前節の末尾で見た API の書式の規則です。(P1) の後半は、モデルに渡すメッセージ列が user メッセージで終わることを言っています。 の模型で、モデル $M$・ツールの実行・関門 $g$・上限 $T$ が何であっても、初期状態から到達できるすべての状態 $(h, e, t)$ で、$h$ は $\mathrm{Inv}$ を満たす。特に、モデルの呼び出し $M(h)$ に渡されるメッセージ列は、つねに $\mathrm{Inv}$ を満たす。 次の証明のねらいは、「最初に成り立ち、1 段ごとに保たれる条件は、いつまでも成り立つ」ことを、帰納法の形で確かめることです。確かめるのは、新しく足す 2 つのメッセージ $a$ と $b$ が、(P1)〜(P3) を壊さないことだけです。 ループを、表現が状態 $(h, e, t)$、初期状態の集合が $\mathrm{Init} = \{((\mathtt{user}, (\mathsf{text}(p))), e_0, 0)\}$、公開操作が「1 段」だけのデータ型（）とみます。状態を変えるのは 1 段の 4 だけなので、実行は表現を漏らしません。表現不変条件を「$h$ が $\mathrm{Inv}$ を満たす」と置き、 の 2 つの仮定（成立・保存）を確かめます。 **成立。** 初期状態の $h$ は 1 つの user メッセージ $(\mathtt{user}, (\mathsf{text}(p)))$ です。(P1) は $N = 1$ で成り立ちます。assistant メッセージも tool_result ブロックも無いので、(P2) と (P3) は空虚に成り立ちます。 **保存。** $h = (m_1, \ldots, m_N)$ が $\mathrm{Inv}$ を満たすとし、1 段が 4 に進んで $h' = h \cdot a \cdot b$ になったとします（2 と 3 は停止で、状態を変えません）。$U(a) = (u_1, \ldots, u_q)$、$q \ge 1$ です。 (P1): $h'$ の先頭は $m_1$ で役割は $\mathtt{user}$、末尾は $b$ で役割は $\mathtt{user}$ です。 (P2): $h'$ の中の、tool_use を持つ assistant メッセージは、$h$ の中のものか $a$ です。$h$ の中の $m_i$ については、仮定の (P1) から $m_N$ は user メッセージなので $i \lt N$ で、直後のメッセージ $m_{i+1}$ は $h'$ でも同じです。したがって仮定の (P2) がそのまま成り立ちます。$a$ については、直後のメッセージは $b$ で、定義から $b$ の最初の $q$ 個のブロックは $\mathsf{res}(u_1, y_1, \epsilon_1), \ldots, \mathsf{res}(u_q, y_q, \epsilon_q)$ です。$j$ 番目の結果が実行によるものか拒否によるものかに関係なく、id は $u_j$ です。 (P3): $b$ の $q + 1$ 個目以降は text ブロック $c_1, \ldots, c_r$ だけです。$a$ は text と tool_use だけからなるので tool_result を含みません。したがって $h'$ の tool_result ブロックは、$h$ にあったものと $b$ の最初の $q$ 個だけで、どれも (P2) の形です。 以上で成立と保存が確かめられたので、 により、到達できるすべての状態で $h$ は $\mathrm{Inv}$ を満たします。 この命題で大事なのは、**モデルについて何も仮定していない**ことです（1 メッセージの中の id が異なることだけを使い、それも (P2) の「ちょうど 1 つ」を言うためだけです）。モデルがどんな順序で何個のツールを呼ぼうと、ハーネスが定義どおりに結果を並べる限り、次の要求は書式の規則を満たします。逆に、ハーネスが結果を 1 つ落としたり、結果の前に文章を置いたりすれば、次の要求は API に拒否されます。公式ドキュメントは、そのときのエラーメッセージの例として「tool_use の id に対して、直後に tool_result ブロックが見つからない」という趣旨の文を挙げています。 の 1 段の 4 で、ある $j$ について $g(n_j, x_j) = \mathrm{refuse}$ だったとする。このとき次が成り立つ。 1. $j$ 番目の呼び出しは環境を変えない（$e^{(j)} = e^{(j-1)}$）。 2. 次の状態のメッセージ列 $h \cdot a \cdot b$ は $\mathrm{Inv}$ を満たし、ループは停止せずに次の段へ進める。 3. 一方、拒否された呼び出しの tool_result ブロックを $b$ から省く方式では、$h \cdot a \cdot b$ は (P2) を満たさない。 (1) 定義の 4 の $\mathrm{refuse}$ の場合の式 $e^{(j)} = e^{(j-1)}$ そのものです。$\mathrm{exec}_{n_j}$ は適用されません。 (2) は任意の関門 $g$ について成り立つので、$h \cdot a \cdot b$ は $\mathrm{Inv}$ を満たします。次の状態 $(h \cdot a \cdot b, e^{(q)}, t + 1)$ は停止の状態ではなく、次の段の 1 で $M(h \cdot a \cdot b)$ が計算されます。そのメッセージ列には $\mathsf{res}(u_j, y_{\mathrm{ref}}, 1)$ が含まれるので、モデルは拒否されたことを入力として受け取ります。 (3) $b$ から $\mathsf{res}(u_j, \cdot, \cdot)$ を省くと、$a$ の直後のメッセージの最初の $q$ 個のブロックの中に id が $u_j$ の tool_result がありません（残りの tool_result の id は $u_j$ と異なり、省いたあとの $b$ に tool_result は $q - 1$ 個しかありません）。これは (P2) に反します。 Agent SDK のドキュメントは、ツールが拒否されたとき、モデルは拒否のメッセージをツール結果として受け取り、ふつうは別の方法を試すか、進められなかったことを報告する、と述べています。 は、その設計が書式の規則と両立する唯一の素直な形であることを示しています。拒否は「何も返さない」のではなく、「失敗という結果を返す」ことで表されます。関門 $g$ の中身（どの呼び出しを拒否するか）は次章で定義します。 出典（確認日 2026-10-10）: [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop)、[Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls)。 ## 4. 停止性：ターンの上限 公式ドキュメントの説明では、ループは「モデルがツール呼び出しのない応答を出すまで」続きます。これは**モデルの振る舞いについての条件**です。ハーネスの側から停止を保証するには、別の仕掛けが要ります。 Agent SDK は 2 つの上限を用意しています。`max_turns`（TypeScript では `maxTurns`）は、ドキュメントの言葉で「ツール使用ターンだけを数える」上限、`max_budget_usd`（`maxBudgetUsd`）は見積もりの支出の上限です。2026-10 時点の公式ドキュメントでは、既定はどちらも「上限なし」です。上限に達すると、結果を表すメッセージの種別が `error_max_turns` または `error_max_budget_usd` になります。 の模型について次が成り立つ。 1. $T$ が有限のとき、モデル $M$・ツールの実行・関門 $g$ が何であっても、ループはモデルの呼び出しが高々 $T + 1$ 回、ツール使用ターンが高々 $T$ 回で停止する。 2. 1 の上界は最良である。すなわち、モデルの呼び出しがちょうど $T + 1$ 回になるモデルが存在する。 3. $T = \infty$ のとき、停止しないモデルが存在する。 証明の方針は、残りのターン数 $v = T - t$ に注目することです。$v$ は 0 以上の整数で、ツールを使う段のたびにちょうど 1 減るので、いつかは使い切ります。$T = \infty$ のときは $v$ が使えず、止まらない例が作れます。 (1) 状態 $(h, e, t)$ に対して $v = T - t$ と置きます。まず、到達できるすべての状態で $0 \le t \le T$ であることを、段の数についての帰納法（）で示します。初期状態では $t = 0$ です。状態 $(h, e, t)$ で $0 \le t \le T$ とし、1 段が停止しなかったとすると、それは定義の 4 に進んだ場合で、4 に進むのは 3 の条件 $t = T$ が成り立たないとき、つまり $t \lt T$ のときだけです。次の状態の値は $t + 1 \le T$ です。 したがって $v$ は到達できる状態でつねに $0$ 以上の整数で、停止しない段のたびにちょうど $1$ 減ります。これは $v$ が の 2 条件（下に有界・真に減る）を、不変条件 $0 \le t \le T$ のもとで満たすことを意味します（各段の中のモデルの呼び出しとツールの実行は、写像として置いたので必ず終わります）。$v$ の初期値は $T$ なので、停止しない段は高々 $T$ 回です。これは (1) の停止の議論と同じ型で、ここでは回数まで数えています。 停止しない段が $k$ 回続いたあとの状態では $t = k$ です。$k \le T$ なので、ツール使用ターンは高々 $T$ 回です。モデルの呼び出しは各段にちょうど 1 回なので、停止しない段 $k$ 回と停止する段 1 回で、合計 $k + 1 \le T + 1$ 回です。あとは、停止しない段が $T$ 回続いたあとの段が必ず停止することを確かめます。そのときの状態は $t = T$ で、$a = M(h)$ について $U(a)$ が空なら 2 で停止し、空でなければ 3 の条件 $t = T$ が成り立つので停止します。 (2) $M_\infty$ を、どんなメッセージ列に対しても tool_use ブロックをちょうど 1 つ含む assistant メッセージを返すモデルとします。このモデルでは 2 による停止は起こりません。3 による停止は $t = T$ のときだけ起こり、それまでの各段は 4 に進んで $t$ を $1$ 増やします。したがって停止しない段がちょうど $T$ 回、停止する段が 1 回で、呼び出しは $T + 1$ 回です。 (3) $T = \infty$ のとき、3 の条件 $t = T$ はどの有限の $t$ でも成り立ちません。$M_\infty$ では 2 の条件も成り立たないので、どの段も 4 に進みます。段の数についての帰納法で、すべての $k$ について $k$ 段後の状態は停止の状態でないことが分かります。 の 3 は、「実物のモデルが止まらない」と言っているのではありません。「上限のないループの停止は、ハーネスのコードだけからは証明できない」と言っています。停止するかどうかは $M$ の性質で、$M$ は学習で得られた関数です。実物では、利用者がいつでも割り込めること（公式ドキュメントによれば、Esc キーで実行中のツール呼び出しを取り消して止められます）と、次章以降で扱う関門や文脈の上限が、別の経路で歯止めになっています。Anthropic のブログ記事 "Building effective agents" も、エージェントには制御を保つための停止条件（反復回数の上限など）を入れるのが一般的だと述べています。 課題「失敗しているテストを直して」に対するループを、メッセージ列の形で書き下します。内容は説明のために作ったもので、実際のモデルの応答の再現ではありません。ツール名は Claude Code の組み込みツールの名前（`Bash`・`Read`・`Edit`）を借りています。 | 番号 | 役割 | 内容ブロック | |---|---|---| | 1 | user | text「失敗しているテストを直して」 | | 2 | assistant | text「まずテストを実行します」、tool_use（id `u1`、`Bash`、テストの実行） | | 3 | user | tool_result（`u1`、失敗 1 件の出力） | | 4 | assistant | tool_use（`u2`、`Read`、実装のファイル）、tool_use（`u3`、`Read`、テストのファイル） | | 5 | user | tool_result（`u2`、ファイルの内容）、tool_result（`u3`、ファイルの内容） | | 6 | assistant | tool_use（`u4`、`Edit`、実装の修正）、tool_use（`u5`、`Bash`、テストの再実行） | | 7 | user | tool_result（`u4`、成功）、tool_result（`u5`、全件成功の出力） | | 8 | assistant | text「原因は境界の判定で、修正後は全件通りました」 | ツール使用ターンは 3 回（2–3、4–5、6–7）、モデルの呼び出しは 4 回（2・4・6・8 を生成）です。(P2) は、2 と 3、4 と 5、6 と 7 の組で確かめられます。 $T = 2$ と置くと、3 回目の呼び出しが返した 6 番のメッセージで $t = 2 = T$ となり、ループは**ターン上限**で止まります。6 番の `Edit` は実行されず、ファイルは変わりません。呼び出しは $3 = T + 1$ 回で、 の上界に一致します。公式ドキュメントも、同じ形の例で上限を 2 にすると編集の手前で止まると説明しています。 出典（確認日 2026-10-10）: [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop)、[How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)、[Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)（2024-12-19 公開）。 ## 5. 文脈の成長と予算 ### 5.1. 入力トークン数は 1 次で、合計は 2 次で増える ループは、過去のメッセージを消さずに末尾へ足していきます。公式ドキュメントも、コンテキストウィンドウはセッションの中でターンをまたいでリセットされず、システムプロンプト・ツール定義・会話の履歴・ツールの入力と出力がすべて積み上がる、と述べています。その帰結を数えます。 各メッセージ $m$ にトークン数 $\tau(m) \in \{1, 2, \ldots\}$ が定まり、メッセージ列のトークン数は各メッセージのトークン数の和であるとする。メッセージ列の外にある固定の部分（システムプロンプトとツール定義）のトークン数を $s_0 \ge 0$ とする。$k$ 回目のモデルの呼び出しの**入力トークン数** $n_k$ を、$s_0$ とそのとき渡すメッセージ列のトークン数の和と定める。$s = s_0 + \tau(m_1)$（$m_1$ は最初の user メッセージ）、$a_i = \tau(i\text{ 回目の応答})$、$r_i = \tau(i\text{ 回目の応答に対する結果のメッセージ})$ と書く。 トークン数がメッセージごとの和になるという仮定は、区切りのトークンなどの細部を無視した近似です。モデルが文章をトークン列に分ける仕組みは [トークン化](/computer-science/llm-architecture/tokenization-bpe) を参照してください。 の模型（圧縮なし）と の勘定のもとで、次が成り立つ。 1. $k$ 回目の呼び出しの入力トークン数は $n_k = s + \sum_{i=1}^{k-1} (a_i + r_i)$ である。 2. ある $c \gt 0$ があってすべての $i$ で $a_i + r_i \ge c$ ならば、$K$ 回の呼び出しの入力トークン数の合計は $$ \sum_{k=1}^{K} n_k \ \ge\ K s + \frac{c\,K(K-1)}{2} $$ を満たし、$K$ の関数として $\Omega(K^2)$ である。 3. 2 の仮定のもとで、各呼び出しの入力がコンテキストウィンドウの大きさ $W$ 以下でなければならないとすると、呼び出しの回数 $K$ は $K \le \dfrac{W - s}{c} + 1$ を満たす。 (1) $k$ についての帰納法で示します。$k = 1$ のとき、渡すメッセージ列は $(m_1)$ で、$n_1 = s_0 + \tau(m_1) = s$ です。和は空なので等式が成り立ちます。$k$ 回目の呼び出しに渡すメッセージ列を $h$ とし、$n_k = s + \sum_{i=1}^{k-1}(a_i + r_i)$ と仮定します。$k + 1$ 回目の呼び出しがあるのは、$k$ 回目の段が定義の 4 に進んだときで、渡すメッセージ列は $h \cdot a \cdot b$ です。$\tau(a) = a_k$、$\tau(b) = r_k$ なので、 $$ n_{k+1} = n_k + a_k + r_k = s + \sum_{i=1}^{k} (a_i + r_i) $$ です。 (2) 1 と仮定から $n_k \ge s + (k-1)c$ です。$k = 1, \ldots, K$ について足すと $$ \sum_{k=1}^{K} n_k \ \ge\ \sum_{k=1}^{K} \bigl(s + (k-1)c\bigr) = Ks + c \sum_{j=0}^{K-1} j = Ks + \frac{c\,K(K-1)}{2} $$ です。$K \ge 2$ のとき $K - 1 \ge K/2$ なので、右辺は $\frac{c}{4} K^2$ 以上です。したがって の意味で $\Omega(K^2)$ です。 (3) $K$ 回目の呼び出しについて $n_K \le W$ が必要です。2 の最初の不等式から $s + (K-1)c \le n_K \le W$ なので、$K - 1 \le (W - s)/c$ です。 2 次で増えるのは**合計**であることに注意してください。1 回の入力は 1 次でしか増えませんが、同じ履歴を毎回送り直すので、合計は三角数になります。この「送り直し」の料金と遅延を下げる仕組みがプロンプトキャッシュで、ウィンドウの上限 $W$ そのものへの対処が[圧縮](/computer-science/claude-code-internals/compaction-memory-subagents#def-compaction)とサブエージェントです。前者は [次々章](/computer-science/claude-code-internals/context-window-and-prompt-caching)、後者は [その次の章](/computer-science/claude-code-internals/compaction-memory-subagents) で扱います。
1 2 3 4 5 6 7 8 9 10 5,000 23,000 呼び出しの番号 k 入力トークン数 n_k
$s = 5{,}000$、すべての $i$ で $a_i + r_i = 2{,}000$ と**仮に**置きます（実測値ではなく、式の形を見るための数です）。 の 1 から $n_k = 5{,}000 + 2{,}000(k - 1)$ で、$n_1 = 5{,}000$、$n_2 = 7{,}000$、$n_{10} = 23{,}000$ です。10 回の合計は $10 \times 5{,}000 + 2{,}000 \times 45 = 140{,}000$ で、最後の 1 回の入力の約 6 倍です。ウィンドウを仮に $W = 200{,}000$ とすると、3 から $K \le 195{,}000 / 2{,}000 + 1 = 98.5$、つまり 98 回までです。ファイルを丸ごと読むツール結果が 1 回で数千トークンになることを考えると、長い作業で上限に達するのは不自然ではありません。 ### 5.2. 予算の上限と超過幅 の模型に、支出の上限 $B \gt 0$ を次の規則で加える。$i$ 回目のモデルの応答のコストを $c_i \ge 0$、累計を $S_k = \sum_{i=1}^{k} c_i$ とし、$k$ 回目の応答を受け取ったあとで $S_k \ge B$ ならば、ツールを実行せずに**予算上限**として停止する（サブエージェントは無いとする）。すべての $i$ で $c_i \le c_{\max}$ とする。このとき次が成り立つ。 1. ループが $k^\ast$ 回目の応答のあとに予算上限で停止したならば、$B \le S_{k^\ast} \lt B + c_{k^\ast} \le B + c_{\max}$ である。 2. どの時点で停止しても（完了・ターン上限を含めて）、最終の累計は $B + c_{\max}$ 未満である。 3. さらに、ある $c_{\min} \gt 0$ があってすべての $i$ で $c_i \ge c_{\min}$ ならば、モデルの呼び出しは高々 $\lceil B / c_{\min} \rceil$ 回である。 次の証明では、$k^\ast$ は予算上限で止まった回の番号、$K$ は最後に行われた呼び出しの番号です。3 つの主張はどれも、「$k$ 回目の呼び出しが行われるなら、その直前までの累計は $B$ 未満」という 1 つの事実から出ます。1 はその事実を予算上限で止まった回に使い、2 は止まった理由によらず最後の回に使い、3 は回数を数えるのに使います。 $k$ 回目の呼び出しが行われるのは、$k = 1$ であるか、$k - 1$ 回目の応答のあとで停止しなかったときです。後者では、予算の判定を通過しているので $S_{k-1} \lt B$ です。$S_0 = 0 \lt B$ と合わせて、$k$ 回目の呼び出しが行われるならば $S_{k-1} \lt B$ です。 (1) 予算上限で停止したので $S_{k^\ast} \ge B$ です。$k^\ast$ 回目の呼び出しが行われたので $S_{k^\ast - 1} \lt B$ で、$S_{k^\ast} = S_{k^\ast - 1} + c_{k^\ast} \lt B + c_{k^\ast} \le B + c_{\max}$ です。 (2) 最後の呼び出しを $K$ 回目とします。$S_{K-1} \lt B$ なので、停止の理由が何であっても $S_K = S_{K-1} + c_K \lt B + c_{\max}$ です。 (3) $K$ 回目の呼び出しが行われるならば $S_{K-1} \lt B$ で、$S_{K-1} \ge (K-1)c_{\min}$ なので $K - 1 \lt B / c_{\min}$ です。$K - 1$ は整数なので $K - 1 \le \lceil B / c_{\min} \rceil - 1$、すなわち $K \le \lceil B / c_{\min} \rceil$ です。 上限を超えうる理由は、判定の**時点**にあります。応答のコストは、API が応答と一緒に返すトークン使用量から決まるので、応答が届く前には比べられません。公式ドキュメントは、上限に達した応答は完了して合計に入るので、支出は「その 1 応答のコスト」と、その時点で動いているサブエージェントが止まるまでに使う分だけ上限を超えうる、と述べ、上限には余裕を持たせるよう勧めています。 の 1 は、その前半を模型の上で導いたものです。3 は、ターンの上限が無くても、1 回の応答に正の最小コストがあれば予算の上限が停止を保証することを言っています。 出典（確認日 2026-10-10）: [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop)（"Turns and budget"・"Budget headroom"・"The context window" の節）。 ## 6. 並行実行：読み取りは可換 1 つの応答に複数のツール呼び出しがあるとき、公式ドキュメントによれば、読み取り専用のツール（`Read`・`Glob`・`Grep`、読み取り専用と印の付いた MCP ツール）は並行に実行でき、状態を変えるツール（`Edit`・`Write`・`Bash`）は衝突を避けるために順に実行されます。なぜこの区別で足りるのかを、模型で確かめます。 ツール呼び出し $(n, x)$ が**読み取り専用**であるとは、すべての $e \in E$ について $\mathrm{exec}_n(x, e)$ の第 2 成分が $e$ であることをいう。このとき $\mathrm{exec}_n(x, e) = (\rho_{n,x}(e), e)$ と書ける。 読み取り専用の呼び出しの結果は環境の状態だけで決まり、呼び出しは環境に跡を残しません。これは、式の値がその式の部分式の値だけで決まるという参照透過性（）の、環境つきの版です。 $(n_1, x_1), \ldots, (n_q, x_q)$ を読み取り専用の呼び出しとし、$\pi$ を $\{1, \ldots, q\}$ の置換とする。環境 $e$ から、$\pi(1), \pi(2), \ldots, \pi(q)$ の順に 1 つずつ実行すると、$j$ 番目の呼び出しの結果は $\pi$ に依らず $\rho_{n_j, x_j}(e)$ で、最終の環境は $e$ である。 $i$ 個の呼び出しを実行したあとの環境を $e^{(i)}$ とします。$e^{(i)} = e$ を $i$ についての帰納法で示します。$e^{(0)} = e$ です。$e^{(i-1)} = e$ とすると、$i$ 番目に実行する呼び出し $(n_{\pi(i)}, x_{\pi(i)})$ は読み取り専用なので、$\mathrm{exec}_{n_{\pi(i)}}(x_{\pi(i)}, e) = (\rho_{n_{\pi(i)}, x_{\pi(i)}}(e), e)$ で、$e^{(i)} = e$ です。同じ式から、この呼び出しの結果は $\rho_{n_{\pi(i)}, x_{\pi(i)}}(e)$ です。$j = \pi(i)$ と書けば、$j$ 番目の呼び出しの結果は $\rho_{n_j, x_j}(e)$ で、$\pi$ に依りません。 並行な実行を「個々の呼び出しが不可分に、ある順序で起こる」ものとみなせるなら、どの順序でも結果の組と環境が同じなので、並行に実行しても逐次に実行した場合と区別がつきません。ハーネスは、結果を $u_1, \ldots, u_q$ の順に並べ直して (P2) を保つだけで済みます。 環境をファイル `a.txt` の内容とし、いまの内容を「`x = 1`」とします。次の 2 つの呼び出しを考えます。どちらも「置換前の文字列がファイルに無ければ、何も変えずに失敗を返す」とします。 - 編集 A: 文字列 `x = 1` を `x = 2` に置き換える。 - 編集 B: 文字列 `x = 1` を `x = 3` に置き換える。 A、B の順に実行すると、A は成功して内容は「`x = 2`」になり、B は置換前の文字列が無いので失敗します。B、A の順では、B が成功して内容は「`x = 3`」になり、A が失敗します。結果の組（成功・失敗の並び）も最終の環境も、順序で変わります。 の仮定（読み取り専用）を落とすと結論が壊れる例です。状態を変えるツールを、モデルが応答に書いた順に 1 つずつ実行するのは、実行の結果を「応答の順」という 1 つの順序に固定するためです。 出典（確認日 2026-10-10）: [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop)（"Parallel tool execution" の節）。 ## 7. ワークフローとエージェント Anthropic のブログ記事 "Building effective agents"（2024-12-19 公開）は、LLM を使う系を 2 つに分けています。**ワークフロー**は、LLM とツールが、あらかじめ決めたコードの経路で編成される系です。**エージェント**は、LLM が自分の手順とツールの使い方を動的に決める系です。同じ記事は、ワークフローの型として、プロンプトの連鎖（prompt chaining）、振り分け（routing）、並列化（parallelization）、指揮者と作業者（orchestrator-workers）、評価者と最適化者（evaluator-optimizer）を挙げ、エージェントを、環境からのフィードバックに基づいてループの中でツールを使う LLM と説明しています。この区別を、呼び出し回数の言葉で定式化します。次の定義の節点は、流れ図の中の「モデルを呼ぶ箱」のことです。ワークフローは、その箱を戻らずにつないだ経路で、たとえば「要約してから翻訳する」なら節点が 2 つで、それぞれを 1 回ずつ通ります。エージェントは、同じ箱の輪を何度でも回ります。 **ワークフロー**を、有限個のモデル呼び出しの箇所（節点）$V$ を持ち、どの入力とどのモデルに対しても、1 回の実行で各節点を高々 1 回しか通らないプログラムと定める。どの節点を通るかは、入力やモデルの出力に依ってよい。**エージェント**を、 のループと定める。 この定義では、連鎖・振り分け・並列化は、節点が有限個で後戻りのない経路なのでワークフローです。評価者と最適化者のように繰り返しを含む型は、繰り返しの回数をコードで固定した場合（繰り返しを展開して有限個の節点にできる場合）に限りワークフローです。これは、ブログ記事の「あらかじめ決めた経路」を数えられる形にした、この記事の模型です。 1. 節点の集合が $V$ のワークフローの、1 回の実行でのモデルの呼び出し回数は、入力にもモデルにも依らず $|V|$ 以下である。 2. 上限のない（$T = \infty$）エージェントでは、任意の $K \ge 1$ に対して、モデルの呼び出しがちょうど $K$ 回になるモデルが存在する。したがって、呼び出し回数を入力にもモデルにも依らずに抑える定数は存在しない。 3. 上限 $T$ が有限のエージェントの呼び出し回数は $T + 1$ 以下で、モデルをわたる上限はちょうど $T + 1$ である。 (1) 定義から、1 回の実行は各節点を高々 1 回しか通らず、モデルの呼び出しは節点を通るときにだけ起こります。したがって呼び出し回数は $|V|$ 以下です。 (2) $M_K$ を、渡されたメッセージ列の中の assistant メッセージの数が $K - 1$ 未満なら tool_use ブロックを 1 つ含むメッセージを返し、$K - 1$ 以上なら text ブロックだけのメッセージを返すモデルとします。$j$ 回目の呼び出しに渡されるメッセージ列は、assistant メッセージをちょうど $j - 1$ 個含みます（各段の 4 が assistant メッセージを 1 つずつ足すので）。したがって $j \le K - 1$ の呼び出しは tool_use を返して 4 に進み（$T = \infty$ なので 3 では止まりません）、$K$ 回目の呼び出しは text だけを返して 2 で完了します。呼び出しはちょうど $K$ 回です。$K$ は任意なので、どんな定数 $C$ に対しても $M_{C+1}$ が $C$ を超える呼び出しをします。 (3) の 1 と 2 です。 2 は、エージェントが悪いと言っているのではありません。回数が入力とモデルの出力で決まることは、やってみるまで手順の数が分からない課題（どのファイルに原因があるか、テストが何回目で通るか）に対応できる、という利点の裏面です。その代わり、コストと時間の上界は、ループの外から上限として与えるしかありません。ワークフローは、上界がコードの形から読める代わりに、あらかじめ決めた経路に収まる課題にしか使えません。 出典（確認日 2026-10-10）: [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)。 ## 8. 模型に入れなかった公式の説明 ここまでの命題は模型の上のものです。公式ドキュメントには、模型に入れなかった、しかしループを使ううえで知っておくべき説明があります。定理にはせず、事実として整理します（2026-10 時点の公式ドキュメントによる）。 **3 つの段階。** 公式ドキュメントは、課題を受けたモデルが「文脈を集める」「行為する」「結果を確かめる」の 3 つの段階を進むと説明し、段階は混ざり合い、全体を通してツールを使うと述べています。これはループの中でモデルが何をしているかの**説明**で、ハーネスが段階を切り替えているわけではありません。模型の上では、どの段階も「tool_use を含む応答 → 実行 → 結果」という同じ 1 ターンです。「確かめる」が入っている点は、生成と検証を組にするという考え方（）と対応します。 **割り込み。** 利用者はいつでもループに割り込めます。Esc キーは実行中のツール呼び出しを取り消して止め、文章を入力して Enter を押すと、止めずに訂正を待ち行列に入れられます。待ち行列のメッセージは、実行中のツール呼び出しが終わりしだい、同じターンの中でモデルに読まれます。模型では、4 の $c_1, \ldots, c_r$（結果のあとに置く text ブロック）がこれに当たります。 **セッションの保存・再開・分岐。** 会話はローカルに保存されます（各メッセージ・ツール使用・結果が `~/.claude/projects/` 以下の JSONL ファイルに書かれます）。セッションは互いに独立で、新しいセッションは新しいコンテキストウィンドウで始まります。再開（`--continue`・`--resume`）は同じセッション ID に追記し、分岐（`--fork-session`・`/branch`）は履歴を新しい ID に複製して元を変えません。模型の言葉では、再開は保存した $h$ から段を続けること、分岐は $h$ の複製から別の列を伸ばすことです。 **checkpoint が戻せるもの。** ファイルを編集する前に、その内容のスナップショットが取られ、あとで巻き戻せます。ただし対象はファイルの変更だけで、データベース・API・デプロイのような外部への作用は戻せない、と明記されています。模型の言葉では、環境 $E$ のうち「ローカルのファイル」の成分だけが復元でき、ほかの成分への $\mathrm{exec}$ の作用は取り消せません。取り消せない作用を持つツールほど、実行の前の関門（次章）が重要になります。 **メッセージの型と結果の種別。** Agent SDK は、ループの進行をメッセージの列として返します。中心になる型は、セッションの出来事を表す `SystemMessage`（開始時の `init`、圧縮のあとの `compact_boundary` など）、モデルの応答を表す `AssistantMessage`、ツール結果を表す `UserMessage`、部分的な出力を表す `StreamEvent`、ループの終わりを表す `ResultMessage` の 5 つです。`ResultMessage` の種別（`subtype`）は次のとおりで、模型の 3 通りの停止に、実行中のエラーなどが加わります。 | 種別 | 意味 | 模型での対応 | |---|---|---| | `success` | 課題を通常どおり終えた | 2 の完了 | | `error_max_turns` | ターンの上限に達した | 3 のターン上限 | | `error_max_budget_usd` | 支出の上限に達した | の予算上限 | | `error_during_execution` | エラーがループを中断した | 模型に無い（） | | `error_max_structured_output_retries` | 構造化出力の再試行の上限に達した | 模型に無い | 出典（確認日 2026-10-10）: [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)、[How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop)（"Message types"・"Handle the result" の節）。 ## 9. コード ### 9.1. 模型のシミュレーション（実行済み） をそのまま Python で書き、モデルを「台本どおりに応答する関数」で置き換えて実行します。API は呼びません。これは仕組みを確かめるための模型で、Claude Code の実装の再現ではありません。 ```python # Python 3.9（標準ライブラリのみ）。エージェントループの模型。API は呼ばない。 def use(u, name, x): return {"type": "tool_use", "id": u, "name": name, "input": x} def text(s): return {"type": "text", "text": s} def run_loop(model, tools, gate, prompt, env, T=None, B=None, cost=lambda a: 0): h = [{"role": "user", "content": [text(prompt)]}] turns = calls = 0 spent = 0 while True: a = model(h); calls += 1; spent += cost(a) uses = [b for b in a["content"] if b["type"] == "tool_use"] if not uses: return "success", h + [a], env, calls, turns, spent if B is not None and spent >= B: return "error_max_budget", h, env, calls, turns, spent if T is not None and turns == T: return "error_max_turns", h, env, calls, turns, spent results = [] for b in uses: # 応答に現れた順に実行する if gate(b["name"], b["input"]): y, err, env = tools[b["name"]](b["input"], env) else: y, err = "denied by permission rule", True results.append({"type": "tool_result", "tool_use_id": b["id"], "content": y, "is_error": err}) h = h + [a, {"role": "user", "content": results}] turns += 1 def invariant(h): for i, m in enumerate(h): ids = [b["id"] for b in m["content"] if b["type"] == "tool_use"] if m["role"] == "assistant" and ids: if i + 1 >= len(h) or h[i + 1]["role"] != "user": return False nxt = h[i + 1]["content"] got = [b["tool_use_id"] for b in nxt if b["type"] == "tool_result"] head = [b["type"] for b in nxt[:len(ids)]] if got != ids or head != ["tool_result"] * len(ids): return False return h[0]["role"] == "user" def read(x, env): return env.get(x["path"], "(no such file)"), x["path"] not in env, env def write(x, env): return "ok", False, {**env, x["path"]: x["text"]} TOOLS = {"read": read, "write": write} def scripted(h): # 3 回ツールを使って終わるモデル k = sum(1 for m in h if m["role"] == "assistant") plan = [[use("u1", "read", {"path": "a.py"}), use("u2", "read", {"path": "t.py"})], [use("u3", "write", {"path": "a.py", "text": "fixed"})], [use("u4", "write", {"path": "/etc/x", "text": "!"})]] return {"role": "assistant", "content": plan[k] if k < 3 else [text("done")]} def forever(h): # 常にツールを呼ぶモデル k = sum(1 for m in h if m["role"] == "assistant") return {"role": "assistant", "content": [use("v%d" % k, "read", {"path": "a.py"})]} gate = lambda name, x: not x["path"].startswith("/etc/") env0 = {"a.py": "bug", "t.py": "test"} for label, model, T in [("scripted, T=None", scripted, None), ("scripted, T=2", scripted, 2), ("forever, T=2", forever, 2), ("forever, T=5", forever, 5)]: status, h, env, calls, turns, _ = run_loop(model, TOOLS, gate, "fix", dict(env0), T=T) print("%-17s %-15s calls=%d turns=%d len(h)=%d inv=%s a.py=%s" % (label, status, calls, turns, len(h), invariant(h), env["a.py"])) status, h, env, calls, turns, _ = run_loop(scripted, TOOLS, gate, "fix", dict(env0)) print("denied result:", h[6]["content"][0]["content"], "| /etc/x in env:", "/etc/x" in env) status, h, env, calls, turns, spent = run_loop(forever, TOOLS, gate, "fix", dict(env0), B=10, cost=lambda a: 3) print("budget B=10, cost 3/call:", status, "calls=%d spent=%d" % (calls, spent)) s, c = 5000, 2000 n = [s + c * (k - 1) for k in range(1, 11)] print("n_k:", n[0], n[1], n[2], "...", n[9], "| sum_{k<=10} =", sum(n), "| max k for W=200000:", (200000 - s) // c + 1) ``` 実行結果（Python 3.9.6、2026-10-10）: ```text scripted, T=None success calls=4 turns=3 len(h)=8 inv=True a.py=fixed scripted, T=2 error_max_turns calls=3 turns=2 len(h)=5 inv=True a.py=fixed forever, T=2 error_max_turns calls=3 turns=2 len(h)=5 inv=True a.py=bug forever, T=5 error_max_turns calls=6 turns=5 len(h)=11 inv=True a.py=bug denied result: denied by permission rule | /etc/x in env: False budget B=10, cost 3/call: error_max_budget calls=4 spent=12 n_k: 5000 7000 9000 ... 23000 | sum_{k<=10} = 140000 | max k for W=200000: 98 ``` 読み方を確かめます。常にツールを呼ぶモデル `forever` は、$T = 2$ で 3 回、$T = 5$ で 6 回の呼び出しで止まり、 の $T + 1$ に一致します。どの実行でも `inv=True` で、 のとおりです。3 ターン目の `/etc/x` への書き込みは関門に拒否され、結果は失敗として返り、環境は変わっていません（）。予算 $B = 10$、1 応答のコスト $3$ では、4 回目の応答のあとで累計が $12$ になって止まり、$10 \le 12 \lt 10 + 3$ です（）。最後の行は の数値です。 ### 9.2. Messages API で書く最小のループ（未実行） 同じループを、Claude API の Python SDK（`anthropic` パッケージ）で書くと次の形になります。**このコードは執筆時に実行していません**（API を呼んでいないので、出力は載せません）。ツール使用の書式は 2 節の出典のページの例に従っています。API キーは環境変数 `ANTHROPIC_API_KEY` から SDK が読みます。モデル名は環境変数で与え、既定値は 2026-10 時点の公式ドキュメントの例に現れる値です（執筆時点の例で、変わりえます）。 ```python # 未実行。pip install anthropic が必要。API キーは環境変数 ANTHROPIC_API_KEY から読まれる。 import os import anthropic client = anthropic.Anthropic() MODEL = os.environ.get("ANTHROPIC_MODEL", "claude-opus-5-5") # 執筆時点の公式の例の値 MAX_TURNS = 5 # ターンの上限 T を必ず置く TOOLS = [{ "name": "list_files", "description": "List the file names in a directory. Read-only.", "input_schema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}, }] def list_files(path): # 副作用のないツール try: return "\n".join(sorted(os.listdir(path))), False except OSError as error: return str(error), True # 失敗は is_error で返す messages = [{"role": "user", "content": "このディレクトリにある Python ファイルを数えて。"}] turns = 0 while True: response = client.messages.create(model=MODEL, max_tokens=1024, tools=TOOLS, messages=messages) if response.stop_reason != "tool_use": # ツール呼び出しが無ければ完了 print(response.stop_reason, [b.text for b in response.content if b.type == "text"]) break if turns == MAX_TURNS: # 実行せずに止まる print("turn limit reached") break results = [] for block in response.content: if block.type == "tool_use": # 各 tool_use に結果をちょうど 1 つ content, is_error = list_files(block.input.get("path", ".")) results.append({"type": "tool_result", "tool_use_id": block.id, "content": content, "is_error": is_error}) messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": results}) # 結果だけを先頭に並べる turns += 1 ``` `while` の本体は の 1 段と 1 対 1 に対応します。`messages` には足すだけで、過去の要素を書き換えません。 ### 9.3. Agent SDK で書く（未実行） Agent SDK の `query()` は、上のループ（と、権限・文脈の管理）を内側で実行し、進行をメッセージの列として返します。**このコードも執筆時に実行していません。** 形は公式ドキュメントの例に従っています。 ```python # 未実行。pip install claude-agent-sdk が必要。認証は SDK の手順に従う（キーの値はコードに書かない）。 import asyncio from claude_agent_sdk import (query, ClaudeAgentOptions, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock) async def main(): options = ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"], # 読み取りだけを自動承認 max_turns=5) # ターンの上限 try: async for message in query(prompt="このディレクトリにある Python ファイルを数えて。", options=options): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): print("tool call:", block.name) elif isinstance(block, TextBlock): print("text:", block.text) if isinstance(message, ResultMessage): print("result subtype:", message.subtype, "turns:", message.num_turns) except Exception as error: # 公式ドキュメントによれば、上限などで終わると結果のあとに例外が出る print("ended with an error:", error) asyncio.run(main()) ``` モデルの応答は実行のたびに変わるので、どちらのコードも、呼ばれるツールの順序や回数は実行ごとに違いえます。変わらないのは、9.1 で確かめた性質（書式の不変条件、上限による停止）のほうです。 出典（確認日 2026-10-10）: [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)、[How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop)（"Handle messages"・"Put it all together" の節の例）。 ## 10. 演習 の模型で $T = 0$ と置く。モデルの呼び出しは何回行われるか。ツールは実行されるか。最終のメッセージ列はどうなるか。 の 1 から、呼び出しは高々 $0 + 1 = 1$ 回で、ループは最初の段で必ず 1 回呼ぶので、ちょうど 1 回です。その応答 $a$ に tool_use が無ければ完了で、最終のメッセージ列は $(m_1, a)$ です。tool_use があれば $t = 0 = T$ なのでターン上限で止まり、ツールは 1 つも実行されず、メッセージ列は $(m_1)$ のままです。$T = 0$ は「ツールを使わせない 1 回の問い合わせ」に当たります。 ハーネスの実装を誤って、1 段の 4 で作る user メッセージを $b' = (\mathtt{user}, (c_1, \mathsf{res}(u_1, y_1, \epsilon_1), \ldots, \mathsf{res}(u_q, y_q, \epsilon_q)))$（text ブロック $c_1$ を先頭に置く）としたとする。$h \cdot a \cdot b'$ が $\mathrm{Inv}$ のどの条件に反するかを示せ。 の証明のどこが通らなくなるか。 $U(a) = (u_1, \ldots, u_q)$、$q \ge 1$ です。(P2) は「$b'$ の最初の $q$ 個のブロックが、この順に id が $u_1, \ldots, u_q$ の tool_result である」ことを求めますが、$b'$ の 1 個目のブロックは text ブロック $c_1$ なので成り立ちません。証明では、保存の (P2) の「定義から $b$ の最初の $q$ 個のブロックは $\mathsf{res}(u_1, \ldots), \ldots, \mathsf{res}(u_q, \ldots)$ です」という 1 文が偽になります。2 節で見たとおり、API はこの形の要求を 400 エラーで拒否します。不変条件は、API の規則をハーネスの側の言葉に言い換えたものです。 $s = 8{,}000$ とし、各ターンで $a_i + r_i = 1{,}500$ だが、3 ターン目だけ大きなファイルを読んで $a_3 + r_3 = 40{,}000$ だったとする。(1) $n_3$、$n_4$、$n_{10}$ を求めよ。(2) 10 回の呼び出しの入力の合計を求め、3 ターン目も $1{,}500$ だった場合の合計と比べよ。 (1) の 1 から、$n_3 = 8{,}000 + 2 \times 1{,}500 = 11{,}000$、$n_4 = 8{,}000 + 1{,}500 + 1{,}500 + 40{,}000 = 51{,}000$、$n_{10} = 8{,}000 + 8 \times 1{,}500 + 40{,}000 = 60{,}000$ です。 (2) 3 ターン目も $1{,}500$ の場合、$n_k = 8{,}000 + 1{,}500(k-1)$ で、合計は $10 \times 8{,}000 + 1{,}500 \times 45 = 147{,}500$ です。実際には、$k \ge 4$ の 7 回の呼び出しのそれぞれで入力が $40{,}000 - 1{,}500 = 38{,}500$ 多いので、合計は $147{,}500 + 7 \times 38{,}500 = 417{,}000$ です。1 回の大きな読み取りの $38{,}500$ トークンは、そのあとの呼び出しの回数だけ繰り返し数えられます。早い時点で大きな結果を文脈に入れるほど、合計への寄与が大きくなります。 の 1 の上界 $S_{k^\ast} \lt B + c_{\max}$ が改良できないことを示せ。すなわち、任意の $B \gt 0$、$c_{\max} \gt 0$、$0 \lt \delta \lt \min(B, c_{\max})$ に対して、すべての $c_i \le c_{\max}$ で、予算上限で停止したときの累計が $B + c_{\max} - \delta$ になるコストの列を作れ。 $c_1 = B - \delta$、$c_2 = c_{\max}$ と置きます。$0 \lt \delta \lt B$ なので $c_1 \gt 0$ です。$c_1 \le c_{\max}$ が必要なので、$B - \delta \gt c_{\max}$ の場合は $c_1$ を、和が $B - \delta$ になる $c_{\max}$ 以下の正の数いくつかに分けます（$B - \delta = \ell c_{\max} + \theta$、$0 \le \theta \lt c_{\max}$ と書き、$c_{\max}$ を $\ell$ 個と、$\theta \gt 0$ なら $\theta$ を 1 個並べます）。この前半の応答はすべてツールを呼ぶとし、前半の途中と終わりの累計は高々 $B - \delta \lt B$ なので、予算の判定を通過します。次の応答のコストを $c_{\max}$ とし、ツールを呼ぶとすると、累計は $B - \delta + c_{\max} \ge B$（$\delta \lt c_{\max}$ より）となって予算上限で停止します。そのときの累計は $B + c_{\max} - \delta$ です。$\delta$ はいくらでも小さく取れるので、上界 $B + c_{\max}$ にいくらでも近づけます。 ## 参考文献 - Anthropic, [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works), Claude Code ドキュメント — agentic loop、ハーネス、ツールの分類、セッション、checkpoint（確認日 2026-10-10）。 - Anthropic, [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop), Claude Agent SDK ドキュメント — ループの手順、ターンと予算の上限、メッセージの型、並行実行（確認日 2026-10-10）。 - Anthropic, [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) および [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls), Claude API ドキュメント — ツールの定義、tool_use と tool_result の書式（確認日 2026-10-10）。 - Anthropic, [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons), Claude API ドキュメント — stop_reason の値（確認日 2026-10-10）。 - Erik S., Barry Zhang, [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents), Anthropic Engineering, 2024-12-19 — ワークフローとエージェントの区別。 - C. A. R. Hoare, "An Axiomatic Basis for Computer Programming", *Communications of the ACM* 12 (1969), 576–580. [doi:10.1145/363235.363259](https://doi.org/10.1145/363235.363259) — 不変条件と停止性の証明の型。