最初のエージェントを作る ― 最小構成とループ

💡 「1回のAPI呼び出し」との違いはループだけ。 LLMに1回聞いて答えをもらうだけなら、それは単なるAPI利用です。そこに「ツールを実行して結果を戻し、もう一度考えさせる」という繰り返しが加わった瞬間、エージェントになります。増えるのは実質このループ1つ。だからこそ、まずループを完全に理解するのが近道です。

# 最小のエージェントループ（擬似コード）
messages = [ user("先月の平均気温を調べて要約して") ]

while True:
    reply = llm.think(messages, tools=[search_tool])   # STEP1 考える

    if reply.wants_tool:                              # ツール要求あり?
        result = run_tool(reply.tool_name, reply.args) # STEP2 呼ぶ
        messages.append(assistant(reply))
        messages.append(tool_result(result))           # STEP3 戻す
    else:
        return reply.text                             # STEP4 完了で止める

⚠️ 上限回数を必ず入れる。 上の擬似コードは説明のためwhile Trueにしていますが、本物では必ず「最大N周まで」の歯止めを入れます。LLMが延々とツールを呼び続ける無限ループは、実際によく起きる事故です。詳しくはつまずきポイントで扱います。

# ① と ② … LLMに渡すツール定義
search_tool = {
    "name": "search_weather",
    "description": "都市と月を渡すと平均気温(℃)を返す",
    "input_schema": {
        "city":  "string",
        "month": "number",
    },
}

# ③ … 手元に置く実体。ただの関数
def run_tool(name, args):
    if name == "search_weather":
        return weather_db.lookup(args["city"], args["month"])
    return "unknown tool"

📊 説明文はプロンプトの一部。 ツールのdescriptionは、LLMが「いつ使うか」を決める唯一の手がかりです。曖昧だと使ってくれなかったり、変な場面で使ったりします。「何を返すか・いつ使うべきか」を人に説明するつもりで書くのがコツ。ツール設計は次章のMCPでさらに深掘りします。

# A. 手書きループ（擬似コード / Claudeのメッセージ風）
messages = [ user(goal) ]

for step in range(MAX_STEPS):          # ← 上限で歯止め
    reply = client.messages.create(
        model="claude-…",
        messages=messages,
        tools=[search_tool],
    )
    log(step, reply)                       # ← 観察のため必ず記録

    if reply.stop_reason == "tool_use":
        out = run_tool(reply.tool_name, reply.tool_args)
        messages += [ assistant(reply), tool_result(out) ]
    else:
        break                              # 最終回答が出た → 終了

# B. SDKのツールランナーに任せる（擬似コード）
runner = ToolRunner(
    model="claude-…",
    tools=[search_tool],       # 定義
    handlers={"search_weather": run_tool},  # 実体
)
answer = runner.run(goal)      # ループは内部で回る

💡 正確なメソッド名は公式ドキュメントで。 ここでのclient.messages.createやToolRunnerは雰囲気を伝えるための擬似コードです。実際の引数名・戻り値の形・モデルIDは各社SDKで異なり、更新も頻繁なので、必ず公式ドキュメントで最新版を確認してください。まず概念を掴み、細部はドキュメントで埋める――これが遠回りしないやり方です。手順を追った入門はAIエージェントの作り方（入門）も参考に。

✅ ログは"高級な機能"ではなく最初から必須。 エージェントは中身が見えにくいぶん、ログがないと「なぜそう動いたか」がまったく分かりません。今はprint1行でも十分。この観察を体系化した評価と可観測性は第5章で本格的に扱います。まずは「見る癖」をここで付けておきましょう。

📊 3つとも「文脈の設計」の問題。 無限ループも戻り値の肥大もコンテキスト膨張も、根っこは「LLMに何を、どれだけ渡すか」という文脈設計に行き着きます。この考え方はコンテキストエンジニアリングとして体系化されており、エージェント開発の背骨になります。まずは「渡しすぎない・溜めすぎない」を合言葉に。

• 最小のエージェント＝4要素を一番小さく組んだもの。1回のAPI利用との違いはループだけ。
• ループは「考える→ツールを呼ぶ→結果を戻す→また考える→完了で止める」の1周を繰り返す。上限回数の歯止めは必須。
• ツールは定義（名前・説明・引数）をLLMに渡し、実体の関数は手元で実行する。LLMは要求するだけ。
• 実装は手書きループ（学習向き）とSDKのツールランナー（実務向き）の2通り。中身は同じ。
• 最初からログで観察し、無限ループ・戻り値肥大・コンテキスト膨張という定番のつまずきを見つける。