OSS Agents JP
オープンソース AI エージェント 日本語ガイド
← 一覧へ
Claude Agent SDK (Python)
CLAUDE

Claude Agent SDK (Python)

Claude Agent SDK (Python)

Anthropic 公式の Claude Agent SDK Python 実装。Claude Code の機能(ツール / サブエージェント / MCP)を Python アプリに直接組み込めるようにする。

#SDK#Python#公式
EDITOR'S TAKE

編集部メモ

Claude Code の機能を Python アプリに直接組み込める公式 SDK

Anthropic 公式の Python SDK で、Claude Code の自動実行機能(ツール実行、ファイル編集、シェルコマンド実行など)を既存 Python アプリケーションに統合できます。async/await ベースのシンプルな API で、複雑な設定なしにプロンプト入力で Claude を自律的に動作させられるのが特徴です。Claude Code の CLI が自動でバンドルされているため、セットアップが簡潔です。既存 Python アプリケーションへの統合やエージェント型アプリケーション開発に向きます。一方、Python 3.10+ が必須で、強力なツール実行機能のため権限管理を丁寧に設定する必要があります。

USE CASES

こんな場面で使う

  • 既存の Python アプリケーションやマイクロサービスに Claude の自動実行機能を統合し、AI による自動化を実現する
  • LLM ベースのエージェント型アプリケーションをプロトタイプ段階から本番環境まで Python エコシステム内で迅速に開発する
  • Claude Code のツール実行機能を活用した自動コード生成・修正パイプラインやドキュメント自動化を構築する
DIFFERENTIATOR

類似ツールとの違い

Anthropic 公式の SDK であり Claude Code の最新機能をいち早く提供します。非公式の Claude Python ラッパーや LangChain の Claude インテグレーションと異なり、Claude Code 固有の Read/Write/Edit/Bash などのツール実行機能を直接利用でき、ツール実行の細かい権限制御も可能です。CLI が自動でバンドルされるため初期セットアップも簡潔です。
CAVEAT

注意点・向かない用途

⚠️ Python 3.10 以上が必須のため古いプロジェクトはアップグレードが必要です。powerful なツール実行機能を持つため、本番環境では allowed_tools と disallowed_tools で権限を慎重に設定する必要があります。
BEST FOR

向いている読者

Python 開発者AI/エージェント開発者既存 Python アプリケーション拡張者

— OSS Agents JP 編集部による独自評価(Claude Agent SDK (Python) に関する観察)

REPO STATS

リポジトリ統計

⭐ Stars
-
🍴 Forks
-
⚠️ Open Issues
-
🌿 Language
-
📄 License
-
🕒 最終更新
-
📅 公開日
-
🌿 Branch
-
REFERENCE

公式ドキュメント(README)

本ハブの独自評価は上記「編集部メモ」が一次情報です。以下は GitHub README の参考転載(折りたたみ)。

📖 GitHub README の日本語訳を読む(AI 自動翻訳 / 参考情報)

— AI による自動翻訳 (2026.05.08 更新)。正確な情報は GitHub の原文 をご確認ください。

Python 用 Claude Agent SDK

Claude Agent の Python SDK です。詳細はClaude Agent SDK ドキュメントを参照してください。

インストール

pip install claude-agent-sdk

前提条件:

  • Python 3.10 以上

注記:Claude Code CLI はパッケージに自動的にバンドルされており、別途インストールは不要です!SDK はデフォルトでバンドルされた CLI を使用します。システム全体へのインストールまたは特定のバージョンを使用したい場合は、以下のようにできます:

  • Claude Code を別途インストール:curl -fsSL https://claude.ai/install.sh | bash
  • カスタムパスを指定:ClaudeAgentOptions(cli_path="/path/to/claude")

クイックスタート

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)

基本的な使い方: query()

query() は Claude Code をクエリするための非同期関数です。レスポンスメッセージの AsyncIterator を返します。src/claude_agent_sdk/query.py を参照してください。

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

# Simple query
async for message in query(prompt="Hello Claude"):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)

# With options
options = ClaudeAgentOptions(
    system_prompt="You are a helpful assistant",
    max_turns=1
)

async for message in query(prompt="Tell me a joke", options=options):
    print(message)

ツールの使用

デフォルトでは、Claude は完全な Claude Code ツールセット(Read、Write、Edit、Bash など)にアクセスできます。allowed_tools は許可アクセスリストです:リストされたツールは自動承認され、リストされていないツールは permission_modecan_use_tool で判断されます。これは Claude のツールセットからツールを削除しません。特定のツールをブロックするには、disallowed_tools を使用してください。完全な評価順序については、許可ガイド を参照してください。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],  # auto-approve these tools
    permission_mode='acceptEdits'  # auto-accept file edits
)

async for message in query(
    prompt="Create a hello.py file",
    options=options
):
    # Process tool use and results
    pass

作業ディレクトリ

from pathlib import Path

options = ClaudeAgentOptions(
    cwd="/path/to/project"  # or Path("/path/to/project")
)

ClaudeSDKClient

ClaudeSDKClient は Claude Code との双方向対話会話をサポートします。src/claude_agent_sdk/client.py を参照してください。

query() とは異なり、ClaudeSDKClient はさらにカスタムツールフックを有効にし、両方とも Python 関数として定義できます。

カスタムツール(インプロセス SDK MCP サーバーとして)

カスタムツール は、Claude が必要に応じて呼び出すために Claude に提供できる Python 関数です。

カスタムツールはインプロセス MCP サーバーとして実装されており、Python アプリケーション内で直接実行され、通常の MCP サーバーが必要とする別プロセスの必要性が排除されます。

エンドツーエンドの例については、MCP Calculator を参照してください。

シンプルなツールの作成

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

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

# Create an SDK MCP server
server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

# Use it with Claude. allowed_tools pre-approves the tool so it runs
# without a permission prompt; it does not control tool availability.
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Greet Alice")

    # Extract and print response
    async for msg in client.receive_response():
        print(msg)

外部MCP サーバーに対する利点

  • サブプロセス管理が不要 - アプリケーションと同じプロセスで実行されます
  • パフォーマンス向上 - ツール呼び出しのIPC オーバーヘッドがありません
  • デプロイが簡単 - 複数のプロセスではなく、単一の Python プロセスです
  • デバッグが容易 - すべてのコードが同じプロセスで実行されます
  • 型安全性 - 型ヒント付きの直接的な Python 関数呼び出し

外部サーバーからの移行

# BEFORE: External MCP server (separate process)
options = ClaudeAgentOptions(
    mcp_servers={
        "calculator": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "calculator_server"]
        }
    }
)

# AFTER: SDK MCP server (in-process)
from my_tools import add, subtract  # Your tool functions

calculator = create_sdk_mcp_server(
    name="calculator",
    tools=[add, subtract]
)

options = ClaudeAgentOptions(
    mcp_servers={"calculator": calculator}
)

混合サーバーサポート

SDK と外部 MCP サーバーを一緒に使用することができます:

options = ClaudeAgentOptions(
    mcp_servers={
        "internal": sdk_server,      # In-process SDK server
        "external": {                # External subprocess server
            "type": "stdio",
            "command": "external-server"
        }
    }
)

フック

フックは、Claude Code アプリケーション(Claude ではなく)が Claude エージェントループの特定の時点で呼び出す Python 関数です。フックは決定論的な処理と Claude への自動フィードバックを提供できます。詳細は エージェント動作をインターセプトおよび制御するフック を参照してください。

その他の例は examples/hooks.py を参照してください。

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher

async def check_bash_command(input_data, tool_use_id, context):
    tool_name = input_data["tool_name"]
    tool_input = input_data["tool_input"]
    if tool_name != "Bash":
        return {}
    command = tool_input.get("command", "")
    block_patterns = ["foo.sh"]
    for pattern in block_patterns:
        if pattern in command:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"Command contains invalid pattern: {pattern}",
                }
            }
    return {}

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

async with ClaudeSDKClient(options=options) as client:
    # Test 1: Command with forbidden pattern (will be blocked)
    await client.query("Run the bash command: ./foo.sh --help")
    async for msg in client.receive_response():
        print(msg)

    print("\n" + "=" * 50 + "\n")

    # Test 2: Safe command that should work
    await client.query("Run the bash command: echo 'Hello from hooks example!'")
    async for msg in client.receive_response():
        print(msg)

完全な型定義は src/claude_agent_sdk/types.py を参照してください:

  • ClaudeAgentOptions - 設定オプション
  • AssistantMessage, UserMessage, SystemMessage, ResultMessage - メッセージタイプ
  • TextBlock, ToolUseBlock, ToolResultBlock - コンテンツブロック

エラーハンドリング

from claude_agent_sdk import (
    ClaudeSDKError,      # Base error
    CLINotFoundError,    # Claude Code not installed
    CLIConnectionError,  # Connection issues
    ProcessError,        # Process failed
    CLIJSONDecodeError,  # JSON parsing issues
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("Please install Claude Code")
except ProcessError as e:
    print(f"Process failed with exit code: {e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"Failed to parse response: {e}")
RELATED

同じカテゴリの他のツール