Claude Agent SDK 完全ガイド — Python・TypeScript で自律型 AI エージェントを 10 分で構築する方法

Claude Agent SDK とは

Claude Agent SDK は、Claude Code を動かしているのと同じツール群・コンテキスト管理機能を、Python と TypeScript のライブラリとして提供するものです。2026年に「Claude Code SDK」から改名されました。

通常の API クライアントでは「ツールを呼ぶ→結果を受け取る→再度 API を呼ぶ」というループをアプリ側で実装しますが、Claude Agent SDK では query() 関数を呼ぶだけで Claude がツール実行・結果解釈・次のアクション決定をすべて自律的に行います。

対応プラットフォームは Anthropic API のほか、Amazon Bedrock・Google Vertex AI・Microsoft Azure AI Foundry にも対応しています。

インストールと初期設定

インストールはコマンド一発です。

# Python
pip install claude-agent-sdk

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

TypeScript 版はネイティブの Claude Code バイナリを同梱しているため、Claude Code CLI を別途インストールする必要はありません。

インストール後、Anthropic Console（https://platform.claude.com/）で取得した API キーを環境変数にセットします。

export ANTHROPIC_API_KEY=your-api-key

query() 関数の基本

Claude Agent SDK のエントリポイントは query() 関数です。非同期イテレータを返し、Claude が作業しながらリアルタイムにメッセージをストリームします。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="auth.py のバグを見つけて修正してください",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

TypeScript でも同様に for await ループで書けます。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

ループは Claude がタスクを完了またはエラーになるまで続き、思考・ツール呼び出し・ツール結果・最終成果物が順番に流れてきます。

14 種の組み込みツール

公式ドキュメント（Agent SDK overview）によると、Claude Agent SDK には次の組み込みツールが用意されています。

allowedTools に使わせたいツール名を渡すだけで有効になります。

フックでライフサイクルをカスタマイズする

フックを使うと、ツール実行の前後に任意のコードを差し込めます。利用可能なフックは PreToolUse・PostToolUse・Stop・SessionStart・SessionEnd・UserPromptSubmit など多数あります。

次の例は、Edit または Write が実行されるたびに変更ファイルパスを監査ログに記録します。

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
from datetime import datetime

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="utils.py をリファクタリングしてください",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

サブエージェントで複雑なタスクを分散処理する

Claude Agent SDK では、メインエージェントから専門サブエージェントを起動して作業を委譲できます。allowed_tools に "Agent" を加え、agents 辞書でサブエージェントを定義します。

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="code-reviewer エージェントでコードレビューしてください",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="品質・セキュリティ専門のコードレビュアー",
                    prompt="コード品質を分析して改善点を提案してください。",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

サブエージェント内のメッセージには parent_tool_use_id フィールドが付与されるため、どのサブエージェントが何を行ったか追跡できます。

MCP サーバーで外部システムと連携する

Model Context Protocol（MCP）サーバーを接続すると、データベース・ブラウザ・外部 API など数百種類のサービスとの連携が可能になります。次の例は Playwright MCP サーバーでブラウザ操作を行います。

async for message in query(
    prompt="example.com を開いて内容を説明してください",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
        }
    ),
):
    if hasattr(message, "result"):
        print(message.result)

セッション管理でコンテキストを跨いだ会話を実現する

セッション ID を保存して resume オプションに渡すと、前の会話のコンテキスト（読んだファイル・分析結果・会話履歴）を引き継いで作業を継続できます。

from claude_agent_sdk import SystemMessage

session_id = None
async for message in query(
    prompt="認証モジュールを読んでください",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

# 同じセッションで続きを依頼
async for message in query(
    prompt="それを呼び出している箇所をすべて探してください",
    options=ClaudeAgentOptions(resume=session_id),
):
    ...

パーミッションモードで安全性を制御する

permission_mode オプションでエージェントの権限レベルを変更できます（Quickstart 参照）。

Client SDK・Claude Code CLI・Managed Agents との違い

公式ドキュメント（Agent SDK overview）は 3 つの比較を提供しています。

Client SDK との違い：Client SDK ではツールループをアプリ側で実装しますが、Claude Agent SDK では Claude がループを自律管理します。

Claude Code CLI との違い：同等の機能を持ちますが、CLI は対話的な開発向け、SDK は CI/CD パイプラインやカスタムアプリケーションの自動化向けです。多くのチームが両方を使い分けます。

Managed Agents との違い：Claude Agent SDK はコードが自分のインフラで動作するライブラリです。一方 Managed Agents は Anthropic がインフラを管理するホスト型 REST API です。ローカルでプロトタイピングしたあと、本番環境で Managed Agents へ移行するパスが推奨されています。

実践：バグ修正エージェントを作る

公式クイックスタート（Quickstart）では次の流れでバグ修正エージェントを作ります。

1. pip install claude-agent-sdk または npm install @anthropic-ai/claude-agent-sdk でインストール
2. ANTHROPIC_API_KEY を環境変数にセット
3. バグのあるサンプルコード utils.py を作成
4. query() でバグ修正を依頼するスクリプトを実行

Claude は Read でファイルを読み、ロジックを分析し、Edit でエラーハンドリングを追加します。人間が一行もコードを書かずに修正が完了するのが最大の魅力です。

Opus 4.7（claude-opus-4-7）を使う場合は SDK バージョン v0.2.111 以降が必要です。古いバージョンでは thinking.type.enabled API エラーが発生します。

Claude Agent SDK の全ドキュメントは https://code.claude.com/docs/en/agent-sdk/overview で公開されています。Python リファレンスは Agent SDK reference - Python、TypeScript リファレンスは TypeScript SDK を参照してください。GitHub サンプルは claude-agent-sdk-demos にあります。