Claude Agent SDK とは？エージェント開発の始め方【2026年版】

# Python
pip install anthropic

# TypeScript / Node.js
npm install @anthropic-ai/sdk

import anthropic

client = anthropic.Anthropic()
# ANTHROPIC_API_KEY 環境変数を自動読み込み
# または client = anthropic.Anthropic(api_key=”sk-ant-…”)

⚠ APIキーの管理：APIキーをコードに直書きしないこと。.envファイルや環境変数で管理し、.gitignoreに必ず追加してください。

def run_agent(user_message: str, max_iterations: int = 20) -> str:
    messages = [{“role”: “user”, “content”: user_message}]
    iteration = 0

    while iteration < max_iterations:
        response = client.messages.create(
            model=“claude-sonnet-4-5”,
            max_tokens=4096,
            tools=TOOLS,
            messages=messages
        )

        # ① ループ終了：最終応答を返す
        if response.stop_reason == “end_turn”:
            return response.content[0].text

        # ② ツール呼び出し：実行してフィードバック
        if response.stop_reason == “tool_use”:
            tool_results = execute_tools(response.content)
            messages.append({“role”: “assistant”, “content”: response.content})
            messages.append({“role”: “user”, “content”: tool_results})

        iteration += 1

    # max_iterations到達：安全に終了
    raise RuntimeError(f”エージェントが{max_iterations}ターンで完了しませんでした”)

実務上の鉄則：max_iterationsは必ず設定する
無限ループはコスト爆発に直結します。本番では必ずイテレーション上限を設け、超過時は例外を上げてアラートを発火させてください。20〜50が一般的な目安ですが、タスクの性質によって調整します。

TOOLS = [
  {
    “name”: “search_web”,
    “description”: “””ウェブ検索を実行して最新情報を取得する。
    使用タイミング: ユーザーの質問に対してリアルタイム情報が必要な場合、
    または学習データに存在しない可能性がある最新の事実を確認する場合。
    使用しない場合: 一般的な知識・概念の説明は検索せずに直接回答すること。”””,
    “input_schema”: {
      “type”: “object”,
      “properties”: {
        “query”: {
          “type”: “string”,
          “description”: “検索クエリ。できる限り具体的な日本語で記述すること”
        },
        “num_results”: {
          “type”: “integer”,
          “description”: “取得件数（1〜10、デフォルト5）”,
          “default”: 5
        }
      },
      “required”: [“query”]
    }
  }
]

def execute_tools(content_blocks) -> list:
    “””レスポンス内のtool_useブロックを全て実行し、tool_resultを返す”””
    tool_results = []

    for block in content_blocks:
        if block.type != “tool_use”:
            continue

        try:
            # ツール名でディスパッチ
            result = TOOL_REGISTRY[block.name](**block.input)
            tool_results.append({
                “type”: “tool_result”,
                “tool_use_id”: block.id,
                “content”: str(result)
            })
        except Exception as e:
            # エラーもClaudeにフィードバックする（重要）
            tool_results.append({
                “type”: “tool_result”,
                “tool_use_id”: block.id,
                “content”: f”エラー: {str(e)}”,
                “is_error”: True
            })

    return tool_results

実装上の重要ポイント：エラーもフィードバックする
ツール呼び出しが失敗した場合、例外をそのまま投げるのではなく is_error: true の tool_result としてClaudeに返します。Claudeはエラーメッセージをもとにリトライ方法を変えたり、別の手段にフォールバックしたりする判断を自律的に行えます。

import anthropic
from anthropic import Anthropic

client = Anthropic()

# MCPサーバーをtool providerとして接続
# stdio経由でローカルMCPサーバーを起動・接続する例
server_params = {
    “command”: “python”,
    “args”: [“my_mcp_server.py”],
    “env”: {“DB_URL”: “postgresql://…”}
}

# MCPツールはAgents SDK経由で自動的にtool定義に変換される
# anthropic.BetaContentBlockParam等のMCP対応APIを利用

# レスポンスのusageから消費トークンを確認
response = client.messages.create(…)

input_tokens = response.usage.input_tokens
output_tokens = response.usage.output_tokens
total = input_tokens + output_tokens

print(f”入力: {input_tokens} / 出力: {output_tokens} / 合計: {total}”)

# コンテキスト上限の80%を超えたら圧縮をトリガー
CONTEXT_LIMIT = 200000  # モデルのコンテキストウィンドウ
if input_tokens > CONTEXT_LIMIT * 0.8:
    messages = compress_context(messages)

import time, random

def call_tool_with_retry(tool_fn, kwargs, max_retries=3):
    for attempt in range(max_retries):
        try:
            return tool_fn(**kwargs)
        except RateLimitError:
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
        except TimeoutError as e:
            if attempt == max_retries – 1:
                return f”ツール実行タイムアウト: {str(e)}”
            time.sleep(2 ** attempt)

# サブエージェントへの指示フォーマット（例）
task_spec = {
    “task_id”: “research_001”,
    “goal”: “2024年の日本のEV市場シェアを調査する”,
    “constraints”: {
        “max_searches”: 5,
        “output_format”: “json”,
        “required_fields”: [“market_share”, “sources”, “confidence”]
    }
}

# サブエージェントの返値フォーマット（例）
result_spec = {
    “task_id”: “research_001”,
    “status”: “success”,  # or “partial” / “failed”
    “data”: {…},
    “confidence”: 0.85,  # 信頼度スコア（オーケストレーターが活用）
    “iterations_used”: 3   # コスト把握のため
}