claude-agent-sdk

Claude Agent SDK

概要

Claude Agent SDK を使用すると、フィードバックループアーキテクチャを通じて Claude を活用した自律型 AI エージェントを構築できます。Python（3.10 以降）と TypeScript（Node 18 以降）で利用できます。

リポジトリ：

• Python：https://github.com/anthropics/claude-agent-sdk-python
• TypeScript：https://github.com/anthropics/claude-agent-sdk-typescript

ドキュメント： https://platform.claude.com/docs/en/agent-sdk/overview

インストール

# Python
pip install claude-agent-sdk

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

コアアーキテクチャ：フィードバックループパターン

すべてのエージェントは、次のサイクルに従います。

1. コンテキストを収集する → ファイルシステムのナビゲーション、サブエージェント、ツール
2. アクションを実行する → ツール、bash、コード生成、MCP
3. 作業を検証する → ルールベース、ビジュアル、LLM による評価
4. 繰り返す → 完了するまで反復する

このパターンは、シンプルなスクリプトから複雑なマルチエージェントシステムまで、どちらを構築する場合にも適用できます。

実行メカニズム（優先順位順）

タスクの要件に基づいてメカニズムを選択します。

1. カスタムツール → 主要なワークフロー（コンテキスト内で目立つように表示されます）
2. Bash → 柔軟な単発の操作
3. コード生成 → 複雑で再利用可能な出力（リントのフィードバックには TypeScript を推奨）
4. MCP → 事前構築された外部連携（Slack、GitHub、データベース）

ルール： 繰り返し実行する操作にはツールを、探索には bash を、検証可能な構造化出力が必要な場合にはコード生成を使用します。

クイックスタートパターン

Python：基本的なクエリ

from claude_agent_sdk import query

result = await query(
    model="claude-sonnet-4-5",
    system_prompt="You are a helpful coding assistant.",
    user_message="List files in current directory",
    working_dir=".",
)
print(result.final_message)

TypeScript：セッション管理

import { ClaudeSdkClient } from '@anthropic-ai/agent-sdk';

const client = new ClaudeSdkClient({ apiKey: process.env.ANTHROPIC_API_KEY });

const result = await client.query({
  model: 'claude-sonnet-4-5',
  systemPrompt: 'You are a helpful coding assistant.',
  userMessage: 'List files in current directory',
  workingDir: '.',
});

console.log(result.finalMessage);

主なコンポーネント

1. カスタムツール（SDK MCP サーバー）

サブプロセスのオーバーヘッドがない、プロセス内ツールです。エージェントを構築するための主要な要素です。

Python：

from claude_agent_sdk.mcp import tool, create_sdk_mcp_server

@tool(
    name="calculator",
    description="Perform calculations",
    input_schema={"expression": str}
)
async def calculator(args):
    result = eval(args["expression"])  # Use safe eval in production
    return {"content": [{"type": "text", "text": str(result)}]}

server = create_sdk_mcp_server(name="math", tools=[calculator])

TypeScript：

import { createSdkMcpServer, tool } from '@anthropic-ai/agent-sdk';
import { z } from 'zod';

const calculator = tool({
  name: 'calculator',
  description: 'Perform calculations',
  inputSchema: z.object({ expression: z.string() }),
  async execute({ expression }) {
    const result = eval(expression); // Use safe eval in production
    return { content: [{ type: 'text', text: String(result) }] };
  },
});

const server = createSdkMcpServer({ name: 'math', tools: [calculator] });

外部 MCP と比べた利点： パフォーマンスの向上、デバッグの容易さ、メモリ空間の共有、IPC オーバーヘッドの解消。

2. フック（ライフサイクルコールバック）

特定のタイミングでエージェントの動作を捕捉し、変更します。

利用可能なフック：

• PreToolUse → 実行前にツール呼び出しを検証／変更／拒否します
• PostToolUse → ツールの結果を処理／記録／変更します
• Stop → 完了イベントを処理します

Python による検証の例：

async def validate_command(input_data, tool_use_id, context):
    if "rm -rf" in input_data["tool_input"].get("command", ""):
        return {
            "hookSpecificOutput": {
                "permissionDecision": "deny",
                "permissionDecisionReason": "Dangerous command blocked"
            }
        }

TypeScript によるログ記録の例：

const loggingHook = {
  matcher: (input) => input.toolName === 'bash',
  async handler(input, toolUseId, context) {
    console.log(`Executing: ${input.toolInput.command}`);
  }
};

3. 権限システム

制限の度合いが段階的に低くなる、4 つのモードがあります。

• default → ツールを使用するたびにプロンプトを表示します
• plan → エージェントは自由に読み取りや探索を行えますが、変更にはプロンプトを表示します
• acceptEdits → ファイル編集は自動承認し、bash／破壊的な操作にはプロンプトを表示します
• bypassPermissions → 完全に自律的に動作します（慎重に使用してください）

canUseTool による動的な制御：

async def permission_callback(tool_name, tool_input, context):
    if tool_name == "bash" and "git push" in tool_input.get("command", ""):
        return False  # Deny
    return True  # Allow

4. サブエージェント

別々のコンテキストウィンドウと専門的な機能を持つ、隔離されたエージェントです。

使用する場面：

• 独立したタスクを並列処理する場合
• コンテキストを分離する場合（1 つのタスクによってメインコンテキストが肥大化するのを防ぐ）
• 異なるツール／モデルを使う専門エージェントが必要な場合

Python：

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    subagent_definitions={
        "researcher": {
            "tools": ["read", "grep", "glob"],
            "model": "claude-haiku-4",
            "description": "Fast research agent"
        }
    }
)

TypeScript：

const options = {
  subagentDefinitions: {
    researcher: {
      tools: ['read', 'grep', 'glob'],
      model: 'claude-haiku-4',
      description: 'Fast research agent'
    }
  }
};

5. コンテキスト管理

エージェントによる検索（推奨）： セマンティック検索を使う前に、bash とファイルシステムのナビゲーション（grep、ls、tail）を使用します。よりシンプルで信頼性があります。

自動圧縮： トークン制限に近づくと、SDK がメッセージを自動的に要約します。透過的かつ自動的に行われます。

コンテキストエンジニアリングとしてのフォルダー構成： ファイルを意図的に整理します。ディレクトリ構成はエージェントから見えるため、エージェントの理解に影響します。

検証パターン

ルールベース（推奨）

明示的な検証によって自己修正が可能になります。

# In PostToolUse hook
if tool_name == "write":
    # Run linter on generated file
    lint_result = run_linter(tool_output)
    if lint_result.has_errors:
        return {"continue": True}  # Let agent fix errors

ビジュアルフィードバック

UI タスクでは、スクリーンショットを撮って再評価します。

@tool(name="check_ui", description="Verify UI matches requirements")
async def check_ui(args):
    screenshot = take_screenshot(args["url"])
    # Return screenshot to agent for evaluation
    return {"content": [{"type": "image", "source": screenshot}]}

LLM による評価

ルールが機能しない曖昧な基準に限って使用します（レイテンシーが高くなります）。

judge_result = await secondary_model.evaluate(
    criteria="Does output match tone guidelines?",
    output=agent_output
)

よくある問題と解決策

1. システムプロンプトが読み込まれない

症状： CLAUDE.md が無視される、カスタムプロンプトが適用されない 解決策： setting_sources=["project"] または ["user", "project"] を設定します

# Python
options = ClaudeAgentOptions(setting_sources=["project"])

# TypeScript
const options = { settingSources: ['project'] };

2. ツールが利用できない

症状： 「Tool not found」エラー 解決策： MCP ツールの命名を確認します：mcp__{server_name}__{tool_name}

3. 権限が拒否される

症状： エージェントがディレクトリにアクセスできない 解決策： ディレクトリを明示的に追加します。

options = ClaudeAgentOptions(add_dirs=["/path/to/data"])

4. Python のキーワード競合

症状： async または continue パラメーターで構文エラーが発生します 解決策： async_ と continue_ を使用します（SDK が自動的に変換します）

# Use async_ not async
hook_result = {"async_": True, "continue_": False}

5. コンテキストのオーバーフロー

症状： トークン制限エラーが発生します 解決策： サブエージェントを使って分離するか、自動圧縮に任せます

6. ツールの実行失敗

症状： ツールが何も通知せずに失敗するか、エラーの内容が不明確です 解決策： ツールの応答に構造化されたエラーメッセージを返します。

return {
    "content": [{
        "type": "text",
        "text": "Error: Invalid input. Expected format: ...",
        "isError": True
    }]
}

7. 外部 MCP サーバーに接続できない

症状： stdio／SSE MCP サーバーがタイムアウトします 解決策： サーバーが実行可能で、ログにアクセスできることを確認します。

# Check server stderr in context.mcp_server_logs
async def debug_hook(input_data, tool_use_id, context):
    print(context.mcp_server_logs.get("server_name"))

言語固有の考慮事項

Python と TypeScript の比較

項目	Python	TypeScript
ランタイム	anyio.run(main)	ネイティブの async/await
最小バージョン	Python 3.10+	Node.js 18+
型安全性	型ヒントは任意	Zod による厳密な型
フックフィールド	async_、continue_	async、continue
CLI	同梱（インストール不要）	別途インストールが必要
ツールの検証	Dict ベースのスキーマ	Zod スキーマ

TypeScript の利点

• リンティングにより、生成されたコードに追加のフィードバックが得られます
• より強い型安全性により、エラーを早期に検出できます
• IDE との統合が優れています

Python の利点

• データサイエンスのワークフローでセットアップがより簡単です
• ML／データツールと直接統合できます
• スクリプト作成タスクをより簡潔に記述できます

判断基準

Claude Agent SDK を使用する場合

✅ 使用するケース：

• コンピューターへのアクセスが必要な自律型エージェントを構築する
• 検証ループを伴う反復的なワークフローを実行する
• コンテキストとツールの使用を必要とする複数ステップのタスクを実行する
• カスタムツールとの統合が必要である
• 権限管理と安全性が必要である

❌ 使用しないケース：

• シンプルな API 呼び出しで十分である（Messages API を使用）
• ツールやコンピューターへのアクセスが不要である
• 会話のみのアプリケーションである
• リアルタイムのストリーミング応答が不可欠である

ツール、Bash、コード生成の使い分け

カスタムツールを使用する場合：

• 操作を頻繁に繰り返す
• 構造化された入出力の検証が必要である
• エージェントのコンテキスト内で目立つ位置に配置したい
• エラー処理と再試行ロジックが必要である

Bash を使用する場合：

• 一度限りの調査やデバッグを行う
• システム操作（git、ファイル管理）を実行する
• 形式的な構造に縛られない柔軟なスクリプトを作成する

コード生成を使用する場合：

• 構造化された再利用可能な出力が必要である
• リンティングやコンパイルで検証できる
• コンポーネントやモジュールを構築する
• フィードバックの品質を重視して TypeScript を使用する

SDK MCP と外部 MCP の使い分け

SDK MCP（プロセス内）を使用する場合：

• エージェント用のカスタムツールを構築する
• パフォーマンスが重要である（サブプロセスのオーバーヘッドがない）
• メインプロセスと状態を共有する必要がある
• ツールのロジックをデバッグする

外部 MCP（stdio／SSE）を使用する場合：

• サードパーティーサービスと統合する
• ツールを分離する必要がある
• 既成の MCP サーバーを使用する
• 複数の言語にまたがるツールが必要である

セッション管理

セッションの再開

Python：

# First run
result1 = await query(user_message="Create a file", working_dir=".")

# Resume with new message
result2 = await query(
    user_message="Now modify it",
    working_dir=".",
    session_id=result1.session_id
)

TypeScript：

// First run
const result1 = await client.query({ userMessage: 'Create a file' });

// Resume
const result2 = await client.query({
  userMessage: 'Now modify it',
  sessionId: result1.sessionId
});

セッションのフォーク

ある時点から別のブランチを作成します。

# Fork for different approach
result_fork = await query(
    user_message="Try different implementation",
    session_id=original_result.session_id,
    fork_session=True
)

予算管理

米ドルでの支出上限を設定します。

options = ClaudeAgentOptions(budget={"usd": 5.00})

予算を超過するとエージェントは停止します。本番環境でのコスト管理に役立ちます。

テストパターン

テスト用のモックツール

Python：

import pytest
from unittest.mock import AsyncMock

@pytest.fixture
def mock_tool():
    return AsyncMock(return_value={
        "content": [{"type": "text", "text": "mocked"}]
    })

async def test_agent(mock_tool):
    server = create_sdk_mcp_server(name="test", tools=[mock_tool])
    # Test with mocked tool

TypeScript：

import { jest } from '@jest/globals';

const mockTool = {
  name: 'test',
  execute: jest.fn().mockResolvedValue({
    content: [{ type: 'text', text: 'mocked' }]
  })
};

統合テスト

分離された環境で実際のツールを使ってテストします。

import tempfile
import os

async def test_file_operations():
    with tempfile.TemporaryDirectory() as tmpdir:
        result = await query(
            user_message="Create test.txt with content 'hello'",
            working_dir=tmpdir,
            permission_mode="bypassPermissions"
        )
        assert os.path.exists(f"{tmpdir}/test.txt")

Claude Code SDK からの移行

非推奨の claude-code-sdk から移行する場合：

1. パッケージ名の変更： claude-code-sdk → claude-agent-sdk
2. システムプロンプトはデフォルトでは設定されません： 明示的に設定するか、setting_sources で有効にする必要があります
3. 型名の変更（Python）： ClaudeCodeOptions → ClaudeAgentOptions
4. 設定ソースは自動では設定されません： setting_sources=["project"] を設定する必要があります

移行ガイドを参照してください：https://platform.claude.com/docs/en/agent-sdk/migration-guide

パフォーマンスの最適化

1. シンプルなタスクにはHaikuを使用する → 5分の1のコストで、調査や探索も高速です
2. 外部MCPよりSDK MCPを使用する → サブプロセスのオーバーヘッドがありません
3. 操作をまとめて実行する → 可能な場合はファイル操作をまとめます
4. ターン数の上限を設定する → 無限ループを防ぎます（turn_limitパラメーター）
5. トークン使用量を監視する → 本番環境では予算管理機能を使用します

セキュリティのベストプラクティス

1. ツールの入力は必ず検証する → 検証されていない入力は決して信頼しません
2. 権限コールバックを使用する → 危険な操作を動的に拒否します
3. ファイルシステムへのアクセスを制限する → add_dirsを使用して対象範囲を限定します
4. 外部MCPサーバーをサンドボックス化する → サードパーティのツールを隔離します
5. 予算を設定する → コストの予期せぬ増大を防ぎます
6. すべてのツール使用を記録する → PostToolUseフックを通じて監査証跡を残します
7. APIキーをハードコードしない → 環境変数を使用します

重要な原則

1. フォルダー構成はコンテキストエンジニアリングです → 意図を持って整理します
2. ルールベースのフィードバックで自己修正が可能になります → リンティングと検証を追加します
3. エージェントによる検索から始める → セマンティック検索の前にBashでナビゲーションします
4. ツールを主に使い、Bashは補助的に使う → 繰り返し可能な操作にはツールを使用します
5. 生成コードにはTypeScriptを使用する → 追加のフィードバック層によって品質が向上します
6. 検証によってループを完結させる → エージェントの作業は必ず検証します
7. 分離にはサブエージェントを使用する → コンテキストの肥大化を防ぎ、並列処理を可能にします

その他のリソース

• APIリファレンス（Python）： https://platform.claude.com/docs/en/agent-sdk/python
• APIリファレンス（TypeScript）： https://platform.claude.com/docs/en/agent-sdk/typescript
• サンプルリポジトリ： https://github.com/anthropics/claude-agent-sdk-demos
• エンジニアリングブログ： https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk