Claude Agent SDK 完全ガイド【2026年最新】｜Python・TypeScriptでAIエージェントを構築する実践手法

この記事の内容

• 1. Claude Agent SDKとは？ — Claude Codeのエンジンをライブラリ化
• 2. 5分でわかるクイックスタート — Python・TypeScriptで最初のエージェント
• 3. アーキテクチャ深掘り — エージェントループの内部構造
• 4. 9つのビルトインツール完全リファレンス
• 5. 権限モードとセキュリティ設計
• 6. Hooksで実現するガードレールと監査ログ
• 7. サブエージェントで専門AIチームを構築
• 8. MCP連携：外部ツールとのシームレスな統合
• 9. セッション管理：会話の永続化とフォーク
• 10. 実践ユースケース5選
• 11. コスト計算と最適化戦略
• 12. フレームワーク横断比較
• 13. 本番デプロイ：Docker化からモニタリングまで
• 14. よくある質問（FAQ）
• 15. まとめ：AIエージェント開発ロードマップ

名称変更について：2026年初頭、「Claude Code SDK」から「Claude Agent SDK」に正式名称が変更されました。パッケージ名はclaude-agent-sdk（Python）および@anthropic-ai/claude-agent-sdk（TypeScript）です。

# Python
pip install claude-agent-sdk

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

export ANTHROPIC_API_KEY=your-api-key

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

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

Client SDKとの比較：従来のAnthropic Client SDKではwhile response.stop_reason == "tool_use"のループを自分で実装する必要がありました。Agent SDKではquery()を呼ぶだけで、Claudeが自律的にツールを使いながらタスクを完了します。

# 読み取り専用エージェント（コードレビュー向き）
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"]
)

# コード修正エージェント（書き込み権限あり）
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Glob", "Grep"]
)

# フルアクセスエージェント（Bash実行含む）
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
)

⚠️ セキュリティ警告：bypassPermissionsはすべての安全チェックを無効にします。本番環境では必ずDockerコンテナやサンドボックス内で使用してください。サブエージェントにも伝播するため、特に注意が必要です。

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher


BLOCKED_PATTERNS = ["rm -rf", "DROP TABLE", "DELETE FROM", "format c:"]


async def block_dangerous_commands(input_data, tool_use_id, context):
    command = input_data["tool_input"].get("command", "")
    for pattern in BLOCKED_PATTERNS:
        if pattern.lower() in command.lower():
            return {
                "systemMessage": f"コマンド '{pattern}' はポリシーにより禁止されています。",
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"Blocked pattern: {pattern}",
                },
            }
    return {}


options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Bash", hooks=[block_dangerous_commands])
        ]
    }
)

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const auditLogger: HookCallback = async (input, toolUseID, { signal }) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  const logEntry = `${new Date().toISOString()} | ${input.tool_name} | ${filePath}\n`;
  await appendFile("./agent-audit.log", logEntry);
  return {};
};

for await (const message of query({
  prompt: "Refactor the authentication module",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [auditLogger] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])
        ]
    }
)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="Review the authentication module for security issues",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer for quality and security reviews.",
                    prompt="Analyze code quality, identify vulnerabilities, and suggest improvements.",
                    tools=["Read", "Glob", "Grep"],
                    model="sonnet",
                ),
                "test-runner": AgentDefinition(
                    description="Runs and analyzes test suites.",
                    prompt="Run tests, analyze output, identify failures, suggest fixes.",
                    tools=["Bash", "Read", "Grep"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

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

for await (const message of query({
  prompt: "Review the authentication module for security issues",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Agent"],
    agents: {
      "code-reviewer": {
        description: "Expert code reviewer for quality and security reviews.",
        prompt: "Analyze code quality, identify vulnerabilities, and suggest improvements.",
        tools: ["Read", "Glob", "Grep"],
        model: "sonnet"
      },
      "test-runner": {
        description: "Runs and analyzes test suites.",
        prompt: "Run tests, analyze output, identify failures, suggest fixes.",
        tools: ["Bash", "Read", "Grep"]
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

注意：サブエージェントは独自のサブエージェントを生成できません（Agentをサブエージェントのtoolsに含めないでください）。また、Agent Teamsとの連携も可能です。

# Python: GitHub MCPサーバーに接続
import os
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

options = ClaudeAgentOptions(
    mcp_servers={
        "github": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
        }
    },
    allowed_tools=["mcp__github__list_issues", "mcp__github__search_issues"],
)

async for message in query(
    prompt="List the 3 most recent issues in our repository",
    options=options,
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

// TypeScript: HTTP MCPサーバーに接続
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-docs__*"]  // ワイルドカードで全ツール許可
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

@tool("greet", "Greet a user by name", {"name": str})
async def greet_user(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

# Python: ClaudeSDKClientで自動セッション管理
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Grep"]
)) as client:
    # 最初のクエリ
    await client.query("Analyze the auth module")
    async for message in client.receive_response():
        print_response(message)

    # 2回目：同じセッションを自動的に継続
    await client.query("Now refactor it to use JWT")
    async for message in client.receive_response():
        print_response(message)

// TypeScript: セッションIDを保存して後から再開
let sessionId: string | undefined;

for await (const message of query({
  prompt: "Analyze the auth module",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result") sessionId = message.session_id;
}

// 後から再開（プロセス再起動後でもOK）
for await (const message of query({
  prompt: "Now implement the suggested refactoring",
  options: { resume: sessionId, allowedTools: ["Read", "Edit", "Write"] }
})) {
  if ("result" in message) console.log(message.result);
}

# フォーク：OAuth2アプローチを試す
async for message in query(
    prompt="Instead of JWT, implement OAuth2",
    options=ClaudeAgentOptions(resume=session_id, fork_session=True),
):
    if isinstance(message, ResultMessage):
        forked_id = message.session_id  # 新しいセッションID

# 元のセッションは影響なし
async for message in query(
    prompt="Continue with the JWT approach",
    options=ClaudeAgentOptions(resume=session_id),
):
    pass

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def review_pr():
    async for message in query(
        prompt="Review the latest PR. Check for bugs, security issues, and code quality.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash", "Agent"],
            agents={
                "security-reviewer": AgentDefinition(
                    description="Security vulnerability scanner",
                    prompt="Check for OWASP Top 10 vulnerabilities, SQL injection, XSS.",
                    tools=["Read", "Grep", "Glob"],
                    model="opus",
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(review_pr())

async for message in query(
    prompt="Migrate all JavaScript files in src/ to TypeScript. Add proper type annotations.",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Edit", "Glob", "Grep", "Bash"],
        permission_mode="acceptEdits",
        cwd="/path/to/project",
    ),
):
    if hasattr(message, "result"):
        print(message.result)

for await (const message of query({
  prompt: "Generate API documentation for all exported functions in src/api/",
  options: {
    allowedTools: ["Read", "Write", "Glob", "Grep"],
    permissionMode: "acceptEdits"
  }
})) {
  if ("result" in message) console.log(message.result);
}

async for message in query(
    prompt="""Read src/utils/validation.py and generate comprehensive unit tests.
Cover edge cases, error handling, and boundary values. Use pytest.""",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Glob", "Grep", "Bash"],
        permission_mode="acceptEdits",
    ),
):
    if hasattr(message, "result"):
        print(message.result)

async def incident_response(error_log: str):
    async for message in query(
        prompt=f"""Incident detected. Analyze this error and find the root cause:
{error_log}

Steps: 1) Find related code 2) Identify the bug 3) Suggest a fix 4) Check for similar issues""",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            hooks={
                "Notification": [HookMatcher(hooks=[slack_notifier])]
            },
        ),
    ):
        if hasattr(message, "result"):
            return message.result

FROM python:3.12-slim

WORKDIR /app

# Node.js（MCP stdio サーバー用）
RUN apt-get update && apt-get install -y curl && \
    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs && \
    rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# 安全な権限設定
RUN useradd -m agent && chown -R agent:agent /app
USER agent

ENV ANTHROPIC_API_KEY=""
CMD ["python", "main.py"]

services:
  agent:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/app/workspace
      - agent-sessions:/home/agent/.claude
    restart: unless-stopped
    mem_limit: 2g
    cpus: 1.0

volumes:
  agent-sessions:

本番環境のセキュリティ：Docker内でbypassPermissionsを使用する場合でも、ネットワーク分離（--network=noneまたは制限付きネットワーク）と最小権限のファイルシステムマウントを設定してください。TDDアプローチでエージェントの動作を事前に検証することも有効です。