Claude Agent SDKとは

Claude Agent SDKは、Anthropicが提供するAIエージェント構築フレームワークです。Claude APIの上に構築されており、ツール実行・ループ制御・マルチエージェント連携といったエージェント開発に必要な機能を統合的に提供します。

従来のClaude APIでは、ツール呼び出しのループ制御やエラーハンドリングを開発者が自前で実装する必要がありました。Agent SDKはこれらの定型処理を抽象化し、ビジネスロジックに集中できる開発体験を実現します。

参考: Anthropic Agent SDK ドキュメント 参考: DoltHub - Building Agents with Claude

セットアップ手順

Python環境

pip install claude-agent-sdk

TypeScript/Node.js環境

npm install @anthropic-ai/agent-sdk

環境変数の設定

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

| 項目 | Python | TypeScript | |---|---|---| | パッケージマネージャ | pip / poetry | npm / yarn / pnpm | | インストールコマンド | pip install claude-agent-sdk | npm install @anthropic-ai/agent-sdk | | 最低ランタイム | Python 3.10+ | Node.js 18+ | | 型サポート | dataclass / Pydantic | 組み込み型定義 | | 非同期処理 | asyncio | async/await (ネイティブ) |

基本的なエージェントの作成

最もシンプルなエージェントは、以下のように数行で作成できます。

Pythonでの実装例

from claude_agent_sdk import Agent, Runner

agent = Agent(
    name="アシスタント",
    instructions="あなたは親切な日本語アシスタントです。",
    model="claude-sonnet-4-20250514"
)

result = Runner.run_sync(agent, "東京の天気を教えてください")
print(result.final_output)

TypeScriptでの実装例

import { Agent, Runner } from '@anthropic-ai/agent-sdk';

const agent = new Agent({
  name: 'アシスタント',
  instructions: 'あなたは親切な日本語アシスタントです。',
  model: 'claude-sonnet-4-20250514',
});

const result = await Runner.run(agent, '東京の天気を教えてください');
console.log(result.finalOutput);

カスタムツールの定義

エージェントの真価は、外部処理を実行できるカスタムツールにあります。ファイル操作、API呼び出し、データベース検索など、任意の処理をツールとして定義できます。

from claude_agent_sdk import Agent, Runner, tool

@tool
def search_database(query: str, limit: int = 10) -> str:
    """データベースからクエリに一致するレコードを検索します。"""
    # 実際のDB検索処理
    results = db.execute(f"SELECT * FROM products WHERE name LIKE '%{query}%' LIMIT {limit}")
    return format_results(results)

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """指定されたアドレスにメールを送信します。"""
    # メール送信処理
    smtp_client.send(to=to, subject=subject, body=body)
    return f"{to}にメールを送信しました"

agent = Agent(
    name="業務アシスタント",
    instructions="あなたは業務効率化を支援するアシスタントです。",
    tools=[search_database, send_email],
    model="claude-sonnet-4-20250514"
)

ツール定義のベストプラクティス

| ポイント | 説明 | 例 | |---|---|---| | 明確なdocstring | ツールの用途を具体的に記述する | 「データベースから商品名で検索」 | | 型ヒントの活用 | 引数と戻り値に型を指定する | query: str, limit: int = 10 | | エラーハンドリング | 例外時に分かりやすいメッセージを返す | return "検索に失敗しました: 接続エラー" | | 最小権限の原則 | 必要最低限の操作のみ許可する | 読み取り専用DBユーザーを使用 | | 冪等性の確保 | 同じ入力で同じ結果を返すようにする | キャッシュ・重複チェックの実装 |

MCP（Model Context Protocol）との統合

Agent SDKはMCPサーバーとの統合をネイティブにサポートしています。既存のMCPサーバーをそのままエージェントのツールとして利用できます。

from claude_agent_sdk import Agent, Runner
from claude_agent_sdk.mcp import MCPServerStdio

async def main():
    github_server = MCPServerStdio(
        command="npx",
        args=["@modelcontextprotocol/server-github"],
        env={"GITHUB_TOKEN": "ghp_xxxxx"}
    )

    agent = Agent(
        name="開発アシスタント",
        instructions="GitHubのissueとPRを管理するアシスタントです。",
        mcp_servers=[github_server],
        model="claude-sonnet-4-20250514"
    )

    result = await Runner.run(agent, "未対応のissueを一覧にしてください")
    print(result.final_output)

活用できるMCPサーバーの例

• GitHub MCP: issue管理、PR作成、コードレビュー
• Slack MCP: メッセージ送信、チャンネル検索
• PostgreSQL MCP: データベースクエリの実行
• Filesystem MCP: ファイルの読み書き操作

マルチエージェント構成

複雑なワークフローは、複数のエージェントに分割して処理できます。各エージェントに専門領域を持たせ、協調動作させることで精度と効率が向上します。

researcher = Agent(
    name="リサーチャー",
    instructions="与えられたテーマについてWeb検索し、情報を収集します。",
    tools=[web_search],
)

writer = Agent(
    name="ライター",
    instructions="収集された情報をもとに記事を執筆します。",
    tools=[write_file],
)

editor = Agent(
    name="エディター",
    instructions="記事の品質をチェックし、修正指示を出します。",
    handoff_agents=[researcher, writer],
)

handoff_agentsを指定することで、エディターエージェントが必要に応じてリサーチャーやライターに処理を委譲できます。

ガードレールの設定

本番運用では、エージェントの出力を検証するガードレールが不可欠です。

from claude_agent_sdk import Agent, Runner, GuardrailFunctionOutput

def check_pii(output: str) -> GuardrailFunctionOutput:
    """個人情報が含まれていないかチェック"""
    has_pii = detect_personal_info(output)
    return GuardrailFunctionOutput(
        should_block=has_pii,
        message="個人情報が検出されたため出力をブロックしました" if has_pii else None
    )

agent = Agent(
    name="カスタマーサポート",
    instructions="顧客からの問い合わせに回答します。",
    output_guardrails=[check_pii],
    model="claude-sonnet-4-20250514"
)

実践的なユースケース

1. カスタマーサポートの自動化

顧客からの問い合わせをFAQデータベースと照合し、適切な回答を自動生成するエージェント。回答できない場合は人間のオペレーターにエスカレーションします。

2. コードレビューボット

PRが作成されたタイミングでコードを分析し、バグの可能性・セキュリティリスク・パフォーマンス改善点をコメントするエージェント。GitHub MCPとの連携で実現できます。

3. データ分析パイプライン

CSVやデータベースからデータを取得し、統計分析・可視化・レポート生成までを自動化するエージェント。Pythonのpandas・matplotlibと組み合わせて使います。

4. ドキュメント生成

ソースコードを解析してAPIドキュメントやREADMEを自動生成するエージェント。Filesystemツールでコードを読み取り、構造化されたドキュメントを出力します。

コスト管理のポイント

エージェントはループ実行するため、トークン消費が通常のAPI呼び出しより多くなります。

| パラメータ | 説明 | 推奨値 | |---|---|---| | max_turns | エージェントの最大ループ回数 | 10〜30 | | model | 使用するモデル | コスト重視ならHaiku、品質重視ならSonnet | | instructions | システムプロンプト | 簡潔で具体的な指示 | | tool選択 | 必要なツールのみ登録 | 不要なツールは除外 |

max_turnsを設定しないとエージェントが無限ループに陥る可能性があるため、必ず上限を指定してください。

まとめ

Claude Agent SDKは、AIエージェント開発のハードルを大きく下げるフレームワークです。カスタムツール・MCP連携・マルチエージェント・ガードレールといった機能を活用することで、実用的な業務自動化エージェントを構築できます。

まずはシンプルな単一エージェントから始めて、徐々にツールやMCPサーバーを追加していくアプローチが推奨されます。本番運用時にはガードレールとmax_turnsの設定を忘れずに行いましょう。