ループがなければエージェントは存在しません

エージェントは具体的に何をしているのですか?

ターミナルで Claude Code を実行し、「すべての TODO コメントをリストに整理」すると、最初に grep、次に cat といういくつかのファイルを独自に決定し、その後 Markdown を出力することがわかります。 モデルはコード自体を実行しません - 実行を要求するだけです。実際に「手と足がある」ように見えるのは、その周りにある 30 行ほどの接着コードです。

このレッスンは、接着剤の輪を分解して、はっきりと見ることです。これはエージェント ループ (エージェント ループ) と呼ばれ、その構造は次のとおりです。

while response.stop_reason == "tool_use":
    response = LLM(messages, tools)      # 1. ask the model
    execute_tools(response.tool_calls)   # 2. run what it asked for
    messages.append(tool_results)        # 3. feed results back

それだけです。もうない。本番環境の Claude コードには、パーミッション、フック、サブエージェント、ワークツリー分離、メモリ圧縮がその上に積み重ねられていますが、核となるのは依然としてこの 4 行です。

重要な直感: モデルが応答するたびに、「ツールを調整したい」か「完了しました」のどちらかになります。ループは、前の状態である限り継続します。後者の状態に入ると、ループは終了します。 基準は、応答の stop_reason フィールドです。

メッセージ[] が段階的に成長するのを確認してください

次のループ シミュレーションのタスクは次のとおりです: 「現在のディレクトリにはどのようなファイルがありますか? 次に、package.json を読み取ります」。 「ステップ」をクリックします。押すたびに、サイクル内のアクションが 1 つ進みます。左側は人間が見た吹き出しで、右側はモデルに詰め込まれた実際の messages[] 配列です。どのように成長するかに注目してください。

ツールの結果をメッセージ履歴に再​​入力する必要がある

初心者にとって最も簡単な落とし穴は、「実行ツール」 を副作用とみなすことです。実行されたらそれで終わりです。しかし、モデルは次の推論ラウンドで messages[] しか認識できず、 モデルはモデルに含まれていないことが起こったことを認識しません。追加ステップがないと、ループ全体が間違ってしまいます。

すべての間違いが同じというわけではありません。一般的な 2 つのタイプ:

• 追加については忘れてください: モデルは次回結果を確認せず、同じツールを再度要求することになります - そして無限ループが発生します。
• 追加したが tool_use_id を失う: Anthropic API はエラー tool_result must have tool_use_id を直接報告し、ループは API 呼び出しステップで崩壊します。

同じタスク: 「プロジェクト内に存在する Python ファイルの数を数える」。 2 つのバージョンを並べて実行して、エンディングの違いを確認します。

stop_reason を理解する

モデルは返されるたびに stop_reason をもたらします。ループを続行するかどうかを決定するには、このフィールドを確認するだけです。

• tool_use — モデルはツールを調整してサイクルを継続したいと考えています。
• end_turn — モデルは完了したと感じてループを終了します。
• max_tokens — トークンの上限が生成されると、トークンは切り捨てられループを終了します (通常、出力が不完全であることをユーザーに促す例外として処理されます)。
• stop_sequence — カスタム停止文字列が見つかったらループを終了します。

「tool_useがない限り継続」と誤って書いたり、max_tokensを無視してそのまま正常終了として扱ったりするのはよくあるバグです。

行動を起こして実行する

ローカル クローン shareAI-lab/learn-claude-code:

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env  # fill in ANTHROPIC_API_KEY
python agents/s01_agent_loop.py

次に、実際に何かを実行させます: 帮我数一下这个仓库里有多少 .py 文件。 ls -R を送信し、出力を確認し、別の find . -name "*.py" | wc -l を送信して、答えを返すことがわかります。プロセス全体がこのループです。

[]

while True:
    resp = LLM(msgs, tools)
    msgs.append({"role":"assistant",
                 "content": resp.content})
    if resp.stop_reason != "tool_use":
        return
    results = execute(resp.tool_uses)
    msgs.append({"role":"user",
                 "content": results})

while True:
    resp = LLM(msgs, tools)
    msgs.append({"role":"assistant",
                 "content": resp.content})
    if resp.stop_reason != "tool_use":
        return
    results = execute(resp.tool_uses)
    # BUG: forgot to append results
    # msgs.append(...)