Claude Agent SDK実装ガイド｜Python/TypeScript対応

結論

結論: Claude Agent SDKは、Claude Codeと同じエージェントループ・ツール・コンテキスト管理をPython/TypeScriptからプログラマティックに利用できる開発キットであり、2026年3月時点で最も実用的なAIエージェント構築基盤の一つ。

この記事の要点:

• 要点1: Claude Agent SDKはファイル操作・コマンド実行・コード編集などのビルトインツールを標準搭載し、ゼロから環境構築する必要がない
• 要点2: カスタムツール（Pythonデコレーター）とMCPサーバー連携で、業務固有のエージェントを柔軟に構築可能
• 要点3: Hooks機能でエージェントの行動を制御でき、本番環境での安全な運用が現実的

対象読者: AIエージェント開発に興味があるエンジニア・テックリード
読了後にできること: Claude Agent SDKで独自のAIエージェントを実装し、カスタムツールやMCPサーバーと連携させることができる

はじめに

「AIエージェントを自社プロダクトに組み込みたい」——そう考えたとき、どのフレームワークを選ぶべきでしょうか？

CrewAI、LangGraph、OpenAI Agents SDKなど選択肢が乱立するなか、2026年2月にAnthropicがリリースしたClaude Agent SDKが急速に注目を集めています。その理由は明確で、開発者向けAIツールとして圧倒的な支持を得ているClaude Codeと同じエージェントループをAPI経由で使えるからです。

Apple XcodeがClaude Agent SDKのネイティブ統合を発表（Xcode 26.3）するなど、エコシステムの広がりも加速しています。この記事では、Claude Agent SDKの概要から実装コード、OpenAI Agents SDKとの比較まで、実践的な開発ガイドをお届けします。

まず試したい「5分即効」セットアップ3選

即効1: 最小構成でエージェントを動かす

# 動作環境: Python 3.10+
# pip install claude-agent-sdk

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(
        prompt="Pythonでフィボナッチ数列を計算する関数を書いて、テストも追加して"
    ):
        if hasattr(message, 'content'):
            print(message.content)

anyio.run(main)

ポイント: query()はClaude Codeと同じエージェントループを起動します。Claudeが自律的にファイルを読み書きし、コマンドを実行し、コードを編集します。非同期イテレーターでストリーミング出力を受け取れるため、リアルタイムな進捗表示も簡単です。

# 注意: ANTHROPIC_API_KEY 環境変数の設定が必要です。

即効2: オプション付きでコードレビューエージェント

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def code_review():
    options = ClaudeAgentOptions(
        system_prompt=(
            "あなたはシニアソフトウェアエンジニアです。"
            "コードのバグ、セキュリティ問題、パフォーマンス改善点を指摘してください。"
            "日本語で回答してください。"
        ),
        max_turns=5,  # 最大5ターンで完了
        model="claude-sonnet-4-6",  # コスパ重視ならSonnet
    )

    async for message in query(
        prompt="src/ ディレクトリのPythonファイルをレビューして、改善点をまとめて",
        options=options,
    ):
        if hasattr(message, 'content'):
            print(message.content)

anyio.run(code_review)

ポイント: ClaudeAgentOptionsでシステムプロンプト、最大ターン数、モデルを指定できます。max_turnsを制限することで、コストとレイテンシを制御しながら実用的な出力を得られます。

即効3: TypeScriptで使う場合

// npm install @anthropic-ai/claude-agent-sdk
import { query } from '@anthropic-ai/claude-agent-sdk';

async function main() {
  for await (const message of query({
    prompt: 'package.jsonの依存関係を分析して、セキュリティリスクがあるものを報告して',
    options: {
      systemPrompt: 'セキュリティ専門家として分析してください。日本語で回答。',
      maxTurns: 3,
    },
  })) {
    if (message.content) {
      console.log(message.content);
    }
  }
}

main();

ポイント: TypeScript版も同じAPIデザイン。Node.js 18+で動作し、Python版と完全に同等の機能を持ちます。フロントエンドチームでもバックエンドチームでも、得意な言語で開発を始められます。

Claude Agent SDKの全体像

Claude Agent SDKは、Claude Codeの内部で使われているエージェントループをそのまま外部から利用可能にしたものです。

カスタムツールの実装 — 業務固有のエージェントを作る

Claude Agent SDKの最大の強みは、カスタムツールの実装が極めて簡単なことです。Pythonの@toolデコレーターで関数を定義するだけで、Claudeが必要に応じて自動的に呼び出します。

from claude_agent_sdk import (
    tool, create_sdk_mcp_server,
    ClaudeAgentOptions, ClaudeSDKClient
)

# 社内DBから顧客情報を取得するカスタムツール
@tool(
    name="get_customer",
    description="顧客IDから顧客情報を取得する",
    params={"customer_id": str}
)
async def get_customer(args):
    # 実際にはDBクエリを実行
    customer = await db.fetch_customer(args["customer_id"])
    return {
        "content": [
            {"type": "text", "text": json.dumps(customer, ensure_ascii=False)}
        ]
    }

# Slack通知を送信するカスタムツール
@tool(
    name="send_slack",
    description="Slackチャンネルにメッセージを送信する",
    params={"channel": str, "message": str}
)
async def send_slack(args):
    result = await slack_client.post_message(
        channel=args["channel"],
        text=args["message"]
    )
    return {
        "content": [
            {"type": "text", "text": f"送信完了: {result['ts']}"}
        ]
    }

# MCPサーバーとして登録
server = create_sdk_mcp_server(
    name="business-tools",
    version="1.0.0",
    tools=[get_customer, send_slack]
)

# エージェントに組み込む
options = ClaudeAgentOptions(
    system_prompt="あなたはカスタマーサポートエージェントです。",
    mcp_servers={"biz": server},
    allowed_tools=["mcp__biz__get_customer", "mcp__biz__send_slack"],
)

async with ClaudeSDKClient(options=options) as client:
    result = await client.query(
        "顧客ID C-1234 の最近の問い合わせを確認して、対応状況をSlackの #support に報告して"
    )

なぜこれが革新的か: 従来のエージェントフレームワーク（LangChainなど）では、ツール定義にJSON Schemaの記述やチェーン構築が必要でした。Claude Agent SDKではPythonデコレーター1つで完結し、インプロセスMCPサーバーとして動作するため、別プロセスの管理も不要です。

Hooksでエージェントの行動を制御する

本番環境でAIエージェントを運用する際、最も重要なのは安全性です。Hooks機能を使えば、エージェントがツールを実行する前後に任意のバリデーションを挟めます。

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher

# 危険なBashコマンドをブロックするHook
async def block_dangerous_commands(input_data, tool_use_id, context):
    if input_data["tool_name"] != "Bash":
        return {}

    command = input_data["tool_input"].get("command", "")

    # 本番DBへの書き込みコマンドをブロック
    dangerous = ["DROP", "DELETE FROM", "rm -rf", "sudo"]
    for pattern in dangerous:
        if pattern.lower() in command.lower():
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason":
                        f"安全のためブロック: '{pattern}' を含むコマンドは実行できません",
                }
            }
    return {}

# 全ツール実行をログに記録するHook
async def audit_log(input_data, tool_use_id, context):
    logger.info(f"Tool: {input_data['tool_name']}, Input: {input_data['tool_input']}")
    return {}

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

実運用のポイント: Hooksは「PreToolUse（実行前）」「PostToolUse（実行後）」など複数のイベントポイントで発火します。本番環境では最低限、以下の3つのHookを設定することを推奨します。

1. コマンドフィルター: 破壊的なBashコマンドをブロック
2. 監査ログ: 全ツール実行を記録
3. コスト制限: トークン使用量が閾値を超えたら停止

OpenAI Agents SDK vs Claude Agent SDK — どちらを選ぶ？

2026年3月時点で、エージェントSDKの二大選択肢はOpenAI Agents SDKとClaude Agent SDKです。設計思想が大きく異なるため、用途に応じた選択が重要です。

選定の目安:

• Claude Agent SDKが向くケース: データを自社インフラ内に留めたい、MCPで既存ツールと連携したい、コード生成・レビュー系タスク、長文ドキュメント処理
• OpenAI Agents SDKが向くケース: マネージドインフラで素早く立ち上げたい、ビジュアルなAgent Builder UIで非エンジニアも参加させたい、Web検索やファイル検索のビルトインツールを多用するタスク

APIコストの目安

エージェントは1タスクで複数回のAPI呼び出しを行うため、通常のチャットよりもコストが高くなります。以下は実測ベースの目安です。

料金情報の最終確認: 2026-03-03（Anthropic公式料金ページ参照）

コスト最適化のコツ:

• max_turnsを設定してターン数を制限する
• 定型タスクはHaiku 4.5（$1/$5）、判断が必要なタスクはSonnet 4.6（$3/$15）を使い分ける
• プロンプトキャッシングで同一プロンプトのコストを最大90%削減
• 大量バッチ処理はBatch API（50%割引）を活用

【要注意】よくある失敗パターンと回避策

失敗1: max_turnsを設定しない

❌ エージェントが延々とツールを呼び続け、コストが想定の10倍に
✅ max_turns=10程度を上限に設定し、超過時は人間にエスカレーション

失敗2: allowed_toolsを指定しない

❌ エージェントがBashで意図しないコマンドを実行するリスク
✅ allowed_toolsで使用可能なツールを明示的にホワイトリスト化

失敗3: エラーハンドリングを忘れる

❌ API呼び出しの失敗やタイムアウトで処理が途中で停止
✅ try/exceptで囲み、セッションIDを保存して再開できる設計にする

# セッション再開のパターン
async with ClaudeSDKClient(options=options) as client:
    try:
        result = await client.query("大規模なリファクタリングを実行して")
        session_id = result.session_id  # セッションIDを保存
    except Exception as e:
        logger.error(f"エラー発生: {e}")
        # 保存したsession_idで再開
        result = await client.resume(session_id=saved_session_id)

実践例: 社内ドキュメント検索エージェントの構築

Claude Agent SDKとMCPを組み合わせた実践的なユースケースとして、社内ドキュメントを検索して質問に回答するエージェントを構築してみましょう。

import anyio
from claude_agent_sdk import (
    query, ClaudeAgentOptions,
    tool, create_sdk_mcp_server
)

# ベクトルDBから類似ドキュメントを検索するツール
@tool(
    name="search_docs",
    description="社内ドキュメントを意味検索する。質問文を受け取り、関連する文書を返す",
    params={"query": str, "top_k": int}
)
async def search_docs(args):
    # ChromaDB等のベクトルDBに接続
    results = collection.query(
        query_texts=[args["query"]],
        n_results=args.get("top_k", 5)
    )
    docs = []
    for doc, meta in zip(results["documents"][0], results["metadatas"][0]):
        docs.append(f"[{meta['title']}]n{doc}")

    return {
        "content": [
            {"type": "text", "text": "nn---nn".join(docs)}
        ]
    }

server = create_sdk_mcp_server(
    name="doc-search",
    version="1.0.0",
    tools=[search_docs]
)

async def answer_question(question: str):
    options = ClaudeAgentOptions(
        system_prompt=(
            "あなたは社内ドキュメントアシスタントです。"
            "search_docsツールで関連文書を検索し、根拠を示しながら回答してください。"
            "文書に情報がない場合は「確認が必要です」と正直に伝えてください。"
        ),
        mcp_servers={"docs": server},
        allowed_tools=["mcp__docs__search_docs"],
        max_turns=3,
        model="claude-sonnet-4-6",
    )

    async for message in query(prompt=question, options=options):
        if hasattr(message, 'content'):
            print(message.content)

# 使用例
anyio.run(lambda: answer_question("有給休暇の申請方法を教えてください"))

この設計のメリット: ドキュメント検索をカスタムツールとして切り出すことで、検索エンジンの差し替え（ChromaDB→Pinecone→OpenSearch等）がエージェント側のコード変更なしで可能です。MCP標準に準拠しているため、将来的に他のAIエージェントからも同じツールを再利用できます。

あわせて読みたい

• LNAI入門｜AIコーディングツール設定を1ファイルで統一する方法 — Agent SDKの設定もLNAIで統一管理できる
• AIコーディングツールで開発は速くなるのか？2026年最新研究が示す意外な結果 — AIコーディングツールの生産性に関する定量研究

参考・出典

• Agent SDK overview — Anthropic公式ドキュメント（参照日: 2026-03-03）
• Agent SDK Quickstart — Anthropic公式ドキュメント（参照日: 2026-03-03）
• Custom Tools — Anthropic公式ドキュメント（参照日: 2026-03-03）
• claude-agent-sdk-python — GitHub（参照日: 2026-03-03）
• Apple’s Xcode now supports the Claude Agent SDK — Anthropic（参照日: 2026-03-03）
• Claude API Pricing — Anthropic（参照日: 2026-03-03）
• Claude Code Plugins完全解説2026 — Claude Codeのプラグイン機能で開発体験を拡張する方法

あわせて読みたい:

• MCP（Model Context Protocol）とは？AIエージェントの新しい標準規格を解説
• CrewAI vs LangGraph vs AutoGen徹底比較｜マルチエージェント構築ガイド
• Claude Code vs Cursor徹底比較｜AIコーディングツールはどちらを選ぶべき？

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。
100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。
SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。

ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。

あわせて読みたい

• AIエージェントとは？仕組み・種類・活用事例を徹底解説
• AIエージェントフレームワーク比較2026
• ChatGPT API ビジネス自動化ガイド

AIエージェントの導入・活用についてのご相談は、Uravationのサービス一覧をご覧ください。