初めてのAIエージェントの作り方：モデルと、いくつかのツールと、ループ

「AIエージェント」と聞くと、フレームワークやベクトルデータベース、そして週末を丸ごと使うセットアップが必要なように思える。だが、そうではない。Anthropic自身による定義は、拍子抜けするほどシンプルだ。エージェントとはLLMがツールをループの中で自律的に使うことである。このパターンが一度見えてしまえば、100行に満たないコードで役に立つ最初のエージェントを作れるようになる。そして同じくらい大切なのは、いつ作るべきでないかが分かるようになることだ。

中核となるループ

どんなに凝ったものであっても、すべてのエージェントは同じ4ステップのサイクルでできている。

1. モデルに目標と、呼び出してよいツールのリストを渡す。
2. モデルが、直接答えるかツールを呼び出すかを判断する。
3. あなたのコードがそのツールを実行し、結果をモデルに返す。
4. モデルが「完了」と言うまで繰り返す。

モデルがあなたのファイルシステムやネットワークに自ら触れることは決してない。モデルはあくまでツールの実行を依頼するだけで、実際にそれを行うかどうか、どう行うかを決めるのはあなたのコードだ。その隙間こそが、安全性のすべてが宿る場所である。

具体的な例

以下は、電卓ツールを使って質問に答えられる最小限のエージェントだ。重要なのはその構造であり、同じ形がファイル編集、ウェブ検索、データベースクエリへとそのままスケールする。

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

この while ループこそがエージェントだ。モデルは質問を見て、"1894 * 37 + 12" を引数に calculator を呼び出すよう依頼し、あなたのコードがそれを実行し、70090 を返し、モデルが最終的な答えを書く。電卓を read_file／write_file のペアに置き換えれば、原始的なコーディングエージェントの出来上がりだ。

実際に肝心なのはツールの部分

モデルは、あなたが与えるツールの能力以上のことはできない。そして、最初のエージェントの多くがつまずくのは、ツールの設計だ。エージェント向けのツールを書くことに関するAnthropicのガイダンスは、いくつかのルールに集約される。

• 新しいチームメイトに向けて書くつもりで、ツールに名前を付け、説明を書く。 search_invoices(customer_id, date_range) は、あいまいな query(sql) に勝る。契約（インターフェース）が明確であるほど、誤った呼び出しは減る。
• 生のダンプではなく、シグナルの高い結果を返す。 ツールが5,000行のJSONを返すなら、それはモデルのコンテキスト予算をノイズに費やしたことになる。役立つものだけに絞り込もう。
• エラーは示唆に富むものにする。 「ファイルが見つかりません。config.yaml のことですか？」ならモデルは立ち直れるが、素のスタックトレースではたいていそうはいかない。

実行させる前のガードレール

すべてのツール呼び出しを実行するのはあなたのコードなので、安全性はあなたが負う。エージェントが本物の何かに触れる前に追加すべきガードレールが3つある。

• ループに上限を設ける。 最大反復回数を設けて、混乱したエージェントが永遠に回り続けない（そして料金がかさまない）ようにする。
• 破壊的な操作にはゲートを設ける。 削除・送信・支払いを伴うものはすべて、確認を必須にするか、まずはサンドボックスに対して実行させるべきだ。
• ツールの入力を検証する。 信頼できない文字列を決して eval() してはならず、モデルの出力をそのままシェルに渡してもならない。すべてのツール引数を、信頼できないユーザー入力として扱うこと——実際、事実上そうなのだから。

エージェントを作るべきでないとき

早いうちに学んでおくと最も役に立つことがある。多くの問題は、そもそもエージェントをまったく必要としないのだ。手順が事前に分かっている場合——データを取得し、要約し、その要約をメールで送る——なら、1〜2回のモデル呼び出しを伴うただのスクリプトの方が、安く、速く、デバッグもしやすい。Anthropicはこれらをワークフローと呼び、経路が予測可能なときには常にこちらを推奨している。本物のエージェントに手を伸ばすのは、見つけたものに基づいて次に何をすべきかをモデルが本当に判断する必要があるときだけにしよう。

まずは上記の4ステップのループから始め、よく説明された1〜2個のツールを与え、反復回数に上限を設け、そして本物のタスクを追加してみよう。1つの動くエージェントから学べることは、どんなに大量のフレームワークのドキュメントから学べることよりも多いはずだ。