Claude Codeの仕組み講座（講師のためのエンジニア水準）

区分1 AIの動き方の芯★★★

No.02 エージェントの繰り返しと道具の呼び出し

Claude Code が、1回の返事の裏で何をしているかの単元です。ここが分かると、受講生の「なぜ今こう動いた？」の大半に答えられます。区分1の中でもいちばん大事なので、この単元はしっかりやります。
目次
  1. 第0章 前提知識
  2. 第1章 道具を呼ぶ往復
  3. 第2章 あなたは輪の中にいる
  4. 第3章 講義で使える図のたとえ
  5. 確認問題

第0章 前提知識

① ツール呼び出し　：モデルが「この道具を使って」と依頼する仕組み

前の単元で、モデルは「次のトークンを当てる」存在だと学びました。 では、ファイルを読んだりコマンドを動かしたりは、どうやっているのでしょうか。

実は、モデル自身は何も実行しません。 モデルがするのは、「この道具を、この内容で使ってください」という依頼文を出すことだけです。実行は、外側の仕組みがやります。

事務所にたとえると、モデルは「指示を出す人」、Claude Code は「実際に動いて報告する事務員」です。 公式のAPI（自分のプログラムから Claude を呼び出す窓口）の説明にも、モデルは自分では何も実行せず、構造化された依頼を出して、実行はアプリケーション側が行うと書かれています。

② 似た言葉との違い

何のことか
モデル 考えて、道具の使い方を依頼する頭
道具 手足（ファイルを読む・書く、コマンドを動かす、検索する）。公式では「ツール」
ハーネス モデルを包んで動かす外側の仕組み。Claude Code のこと。公式の用語集は Claude Code を「ハーネス」とも呼びます
往復（ターン） 依頼→実行→結果を返す、の1周分

「ターン」という言葉は、資料によって指す範囲が違います（補足を参照）。

第1章 道具を呼ぶ往復

① 1回の往復の中身 必ず覚える

道具を使う時、次の順番で進みます。

① Claude Code：会話の全部と、使える道具の説明をモデルに送る
        ↓
② モデル：道具を呼ぶ依頼（tool_use）を返す　例「Read を、この引数で」
        ↓
③ Claude Code：許可を確かめて、道具を実行する
        ↓
④ Claude Code：結果（tool_result）を会話に足して、モデルに送り直す
        ↓
⑤ モデルが次を考える　→ また道具を呼ぶなら②へ戻る
        　　　　　　　　 → 道具を呼ばず文章で答えたら終わり

言葉を先に説明します。

依頼が出る時、API の返事には「止まった理由」として tool_use が入っています。 「道具を呼びたいから、いったん止まっています」という合図です。道具を呼ばずに答えを出し終えた時は、止まった理由が end_turn（「この番の答えは終わり」という意味）になります。公式のAPI説明では、tool_use の間は繰り返し、それ以外の理由で止まったら終わり、と書かれています。

では実際に、「README.md を読んで」と頼んだ時の往復を見てみましょう。 下の形は JSON（項目名と値を { } で並べる、データの書き方）です。見やすいように簡略にした例で、実際の記録にはもう少し項目があります。

あなた：          README.md を読んで

モデルが返す依頼：  { "type": "tool_use", "id": "toolu_01…", "name": "Read",
                    "input": { "file_path": "/…/README.md" } }

Claude Code が実行して返す結果：
                  { "type": "tool_result", "tool_use_id": "toolu_01…",
                    "content": "（README.md の中身）" }

モデルの答え：     「README.md には〜と書かれています」（道具を呼ばず、文章で答える）

モデルが出すのは、Read という道具の名前と、読むファイルの場所（引数）だけです。 実際にファイルを開くのは Claude Code で、中身が tool_result として会話に足されて、モデルに戻ります。依頼の id と結果の tool_use_id が同じなので、「どの依頼への結果か」が分かります。

大事なのは、結果が会話に足されて、モデルに戻ることです。モデルは、その結果を見て次の一手を決めます。

② 1回の返事の裏で、何往復もしている 必ず覚える

あなたが一言頼むと、画面では1回の返事に見えます。 でも裏では、この往復が何回も回っています。

公式の例（テストを直す依頼）では、次のように進みます。

  1. テストを実行する → 3つ失敗と分かる
  2. 該当のファイルを読む
  3. ファイルを直して、もう一度テストを実行する → 全部通る
  4. 道具を呼ばず、「直りました」と文章で答える

これで4周です。大きな作業なら、数十回の道具の呼び出しがつながります。

もう1つ、説明に使えることがあります。 1回の返事の中で、モデルが道具を複数同時に依頼することがあります。公式のSDK説明（SDK＝自分のプログラムの中で Claude Code と同じ動きを使うための部品集。No.16で扱います）によると、読むだけの道具は同時に動かせます。たとえば Read、Glob（ファイル名のパターンで探す道具）、Grep（ファイルの中身の文字列で探す道具）です。 一方、書き換える道具（Edit・Write・Bash）は、衝突を避けるため1つずつ順番に動きます。

手元の実物で確かめてみましょう。 会話の記録は、~/.claude/projects/ の下に、作業場ごとのフォルダに分けて入っています。1会話が1つの .jsonl ファイルです（.jsonl は、1行に1つの記録を JSON で書き並べた形式のファイルです）。

その中で、道具の呼び出しが何回あったかは、ターミナル（Mac の「ターミナル」アプリ。文字でコマンドを打って操作するアプリ）で次の1行を打つと数えられます。

grep -o '"type":"tool_use"' 会話のファイル名.jsonl | wc -l

自分の長い会話を1つ選んで数えてみてください。 数百回という数字が出ることもあります。「1回の返事の裏」の実感がつかめます。

③ 道具の種類 必ず覚える

公式の説明では、基本の道具は大きく5種類に分かれます。

種類 できること
ファイル操作 読む・書く・直す・名前を変える
検索 ファイル名や中身を探す
実行 コマンドを動かす（テストの実行なども）
Web 検索する・ページを読む
コードの補助 型の間違いなどを見る（追加の仕組みが必要。事務の仕事ではほぼ使いません）

このほかに、サブエージェントを呼ぶ、あなたに質問する、スキルを呼ぶ、といった「段取り用」の道具もあります。

道具が無ければ、AIは文章で答えることしかできません。 道具があるので、AIは文章を返すだけでなく、実際に作業を進められます。

あとから道具を足す仕組みがスキル・MCP などです。 MCP（外のサービスにつなぐ約束事。No.11で扱います）の道具は、使うまでは名前だけが机に置かれ、細かい説明は必要になった時に読み込まれます（公式）。

④ 止まる時（許可）は「実行の直前」 必ず覚える

「やっていいですか」と聞かれる位置は、決まっています。 モデルが依頼を出したあと、道具を実際に動かす前です。

モデルの依頼 → 【許可の判定】 → 実行 → 結果をモデルへ

公式の説明では、読むだけの操作（作業場の中のファイル読み取りなど）は確認なしで進みます。コマンドの実行や、ファイルの書き換えは確認が入るのが標準です（許可の設定によって変わります）。

では、断られたらどうなるのでしょうか。 断られたことも「結果」としてモデルに返ります。モデルは「拒否された」という結果を見て、別のやり方を試すか、できなかったと報告します。止まって終わり、ではありません。

許可の細かい判定順は No.13 で、実行の直前に割り込む仕組み（フック）は No.10 で扱います。

第2章 あなたは輪の中にいる

① 途中で止める・向きを変える さらっと

この往復の途中で、あなたはいつでも割り込めます。

どちらも公式に書かれた動きです。 「ずっと見ていないといけないのですか」と聞かれたら、「途中でいつでも向きを変えられるから、任せっぱなしでも手綱は握れます」と答えられます。

② 終わり方 さらっと

往復が終わるのは、基本的にはモデルが道具を呼ばずに答えた時です。 自分で動かす場合（No.16で扱います）は、往復の回数や使う金額の上限を決めておくこともできます。

第3章 講義で使える図のたとえ

仕組み 事務所のたとえ
モデル 指示を出す上司
Claude Code 実際に動く事務員
道具を呼ぶ依頼 「この資料を持ってきて」というメモ
許可の判定 事務員が「これは動かしていいですか」と確認する
結果を返す 事務員が資料を上司の机に置く
何往復もする 上司が資料を見て、また次のメモを書く

上司（モデル）は、自分の席から動きません。 手足になっているのは、事務員（Claude Code）です。この関係を図にして見せると、受講生に伝わりやすくなります。

○ 受講生によく聞かれる質問① 「一言頼んだだけなのに、なんで何分も動いているの？」
　答え方：1回の返事の裏で、道具を呼んで結果を見て次を決める、を何周も回しているからです。長い作業ほど周数が増えます。記録を数えて見せると伝わります
○ 受講生によく聞かれる質問② 「AIが直接パソコンを触っているんですか？」
　答え方：いいえ。モデルは依頼を出すだけで、実行するのは Claude Code です。だから実行の直前で止めたり、拒否したりできます
○ 受講生によく聞かれる質問③ 「なんで急に『やっていいですか』って聞くの？」
　答え方：現実を変える道具（書き換え・コマンド実行）の、実行の直前に判定があるからです。故障ではありません。許可の設定で、聞く範囲は変えられます（No.13）
○ 補足：「ターン」は資料によって範囲が違います。公式の用語集では、あなたが送ってから Claude が答え終えるまでの1回分（途中の道具の呼び出しを含む）。SDKの説明では、依頼→実行→結果の1周分です。講義で使うときは、どちらの意味かを一言添えると混乱しません
○ 関係する単元：No.01（モデルは依頼文を作るだけ）／No.10（フック）／No.13（許可）

モデルは道具を「使って」と依頼するだけで、実行するのは Claude Code。結果が会話に戻り、モデルが次を決める。これが1回の返事の裏で何周も回る。止まる位置は、実行の直前。

確認問題

問1　受講生が「AIはファイルを直接開いて読んでいるんですよね？」と聞いてきました。仕組みからの答えは？

問2　「テストを直して」と一言頼んだら、裏で何周も動いていました。この動きの説明として正しいのは？

問3　「やっていいですか」と聞かれる位置は、仕組みのどこ？

出典：Claude Code 公式「How Claude Code works」（https://code.claude.com/docs/en/how-claude-code-works）／Anthropic 公式「How tool use works」（https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works）／Claude Code 公式「How the agent loop works」（https://code.claude.com/docs/en/agent-sdk/agent-loop）／「Configure permissions」（https://code.claude.com/docs/en/permissions）／「Glossary」（https://code.claude.com/docs/en/glossary）。内容は2026年10月時点の公式。

← 前へ次へ →