Claude SDKで作る自律型Pythonエージェント

課題：AIは賢いが「実行力」に欠けている

誰もが経験したことがあるでしょう。Claudeのシステムプロンプトを何時間もかけて完成させ、エレガントなPythonコードを書かせ、50ページのPDFを数秒で要約させ、ブランドボイスを完璧に模倣させる。しかし、リアルタイムの在庫データベースを確認したり、Slackチャンネルに通知を送ったりといった、実際に「何かをする」ことを求めた途端、AIは壁に突き当たります。

多くの開発者は「チャットボックスの罠」に陥っています。メッセージを送信し、APIがテキストを返し、そこでやり取りが終了する。AIは真空状態に置かれています。このギャップを手動のコードで埋めようとすると、AIがいつ関数を実行したいのかを推測しようとする200行ものif/elseの悪夢に陥りがちです。それは脆弱であり、Claudeの言い回しが1語変わっただけで壊れてしまいます。

なぜ標準的なLLM統合では不十分なのか

不満の原因は単純な断絶にあります。「推論」は「実行」ではないということです。大規模言語モデル（LLM）は世界クラスのテキスト予測器であって、システム管理者ではありません。本質的に「状態」や「副作用」を理解しているわけではないのです。標準的なチャットボットに「古いログをアーカイブして」と頼めば、サーバーのディスク容量が99%のままであっても、自信満々に「ログをアーカイブしました」と答えるでしょう。

本番環境において、受動的なチャットボットから能動的なエージェントへと移行できるかどうかが、週末の趣味のプロジェクトと、1時間に5,000件のユーザーリクエストを処理するツールの分かれ目となります。主な技術的ハードルには以下が含まれます。

• 文脈の逸脱（Context Drift）: ステップ数の多いタスクの途中で会話の文脈を見失う。
• パラメータのハルシネーション: スキーマに存在しない引数をAIが勝手に捏造して関数に渡そうとする。
• セキュリティリスク: エージェントが「私のアカウントを削除して」を「本番データベース全体を削除して」と解釈するのを防ぐ必要がある。

エージェント戦略の比較

Claude Agent SDKは従来の手法と比べてどうでしょうか？数値とワークフローを見てみましょう。

Claude SDKは構造化された「ハンドシェイク」を提供します。推測する代わりに、Claudeは明示的にコードに対して指示を出します。「待ってください。get_inventory_count(item_id='sku_123')を実行する必要があります。その結果を受け取ってから、話を続けます」と。

設計図：制御されたエージェングループの構築

エージェントを構築する最も堅牢な方法は、Tool Use（ツール利用）パターンです。これにより、Claudeが考え、行動し、結果を観察し、次のステップを洗練させるというループが生まれます。

1. 環境セットアップ

AnthropicコンソールからAPIキーを取得してください。今回は、これらの複雑なやり取りをネイティブに処理する公式のanthropicライブラリを使用します。

pip install anthropic python-dotenv

2. ツールスキーマの定義

ツールとは、JSONスキーマとペアになった標準的なPython関数です。このスキーマはAIにとっての「マニュアル」として機能します。ユーザーのアカウントステータスを確認するツールを作成してみましょう。

import anthropic
import os
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

def get_user_status(user_id):
    # 本番環境のPostgreSQLやRedisへのクエリをシミュレートします
    mock_db = {
        "user_123": "Active",
        "user_456": "Suspended"
    }
    return mock_db.get(user_id, "ユーザーが見つかりません")

tools = [
    {
        "name": "get_user_status",
        "description": "特定のユーザーIDのアカウントステータスを返します。ユーザーが購入を許可されているか確認するために使用してください。",
        "input_schema": {
            "type": "object",
            "properties": {
                "user_id": {"type": "string", "description": "一意のID（例：user_123）"}
            },
            "required": ["user_id"]
        }
    }
]

3. 実行ループの実装

エージェントには「思考ループ（Brain loop）」が必要です。Claudeにプロンプトを送信し、ツールの呼び出しが要求されたかを確認し、Pythonコードを実行して、その結果をモデルにフィードバックします。これはタスクが完了するまで繰り返されます。

def run_agent(user_prompt):
    messages = [{"role": "user", "content": user_prompt}]
    
    response = client.messages.create(
        model="claude-3-5-sonnet-20240620",
        max_tokens=1024,
        tools=tools,
        messages=messages
    )

    # このループで多段階の推論を処理します
    while response.stop_reason == "tool_use":
        messages.append({"role": "assistant", "content": response.content})
        
        # ツールのリクエストを抽出
        tool_use = next(block for block in response.content if block.type == "tool_use")
        tool_name = tool_use.name
        tool_input = tool_use.input
        
        print(f"[エージェント] 実行中: {tool_name}({tool_input})")

        if tool_name == "get_user_status":
            result = get_user_status(tool_input["user_id"])

        messages.append({
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use.id,
                    "content": str(result),
                }
            ],
        })

        # 新しいデータを使用してClaudeに再クエリ
        response = client.messages.create(
            model="claude-3-5-sonnet-20240620",
            max_tokens=1024,
            tools=tools,
            messages=messages
        )

    return response.content[0].text

print(run_agent("user_456は注文できますか？"))

エージェントの信頼性に関する教訓

ターミナルで動作するエージェントを作るのは簡単です。しかし、本番環境でハルシネーションを起こさないエージェントを作るのは困難です。これらのシステムを大規模にデプロイする中で学んだ教訓を紹介します。

• 説明文（Description）はプロンプトである: ツールスキーマのdescriptionフィールドは、あなたが書くコードの中で最も重要な部分です。単に「データを取得する」と書くのではなく、「ユーザーが請求サイクルや購読プランを明示的に尋ねた場合にのみ、このツールを使用すること」のように記述してください。
• 優雅な失敗（Graceful Failure）: API呼び出しがタイムアウトしても、単にクラッシュさせないでください。エラー文字列をtool_resultとしてClaudeに返します。そうすれば、Claudeはユーザーに謝罪し、代替案を提案したり、再試行したりできます。
• 「サーキットブレーカー」: 常に最大反復回数（例：5ループ）を設定してください。これがないと、2つのツールが誤って互いを呼び出し合い無限ループに陥り、数分で50ドル分のAPIクレジットを使い果たす可能性があります。
• ペルソナの制御: システムプロンプトを使用して境界線を定義します。エージェントに対し、「あなたは読み取り専用のサポートアシスタントです。ユーザーが6桁の確認コードを提供しない限り、ユーザーデータの変更を試みてはいけません」と伝えてください。

単純なクエリを超えて

基本のループをマスターすれば、可能性は広がります。知識のカットオフを回避するためのsearch_webツールや、レポートを作成するためのwrite_to_fileツールをClaudeに与えることができます。Claude SDKを使用することで、「仕事について話すチャットボット」の構築から、「実際に仕事を遂行するエージェント」の構築へとシフトできます。それはテキスト生成から、真のユーティリティへの転換なのです。