Agent SDK リファレンス - Python

Python Agent SDK の完全な API リファレンス。すべての関数、型、クラスを含みます。

インストール

pip install claude-agent-sdk

query() と ClaudeSDKClient の選択

Python SDK は Claude Code と対話するための 2 つの方法を提供します。

クイック比較

query() を使用する場合（毎回新しいセッション）

最適な用途：

• 会話履歴が不要な 1 回限りの質問
• 前の交換からのコンテキストが不要な独立したタスク
• シンプルな自動化スクリプト
• 毎回新しく開始したい場合

ClaudeSDKClient を使用する場合（継続的な会話）

最適な用途：

• 会話を続ける - Claude がコンテキストを記憶する必要がある場合
• フォローアップ質問 - 前の回答に基づいて構築する
• インタラクティブなアプリケーション - チャットインターフェース、REPL
• 応答駆動ロジック - 次のアクションが Claude の応答に依存する場合
• セッション制御 - 会話ライフサイクルを明示的に管理する

関数

query()

Claude Code との各インタラクションのために新しいセッションを作成します。メッセージが到着するにつれて生成される非同期イテレータを返します。query() への各呼び出しは、前のインタラクションのメモリなしで新しく開始します。

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeAgentOptions | None = None,
    transport: Transport | None = None
) -> AsyncIterator[Message]

パラメータ

戻り値

会話からのメッセージを生成する AsyncIterator[Message] を返します。

例 - オプション付き

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are an expert Python developer",
        permission_mode="acceptEdits",
        cwd="/home/user/project",
    )

    async for message in query(prompt="Create a Python web server", options=options):
        print(message)


asyncio.run(main())

tool()

型安全性を備えた MCP ツールを定義するためのデコレータ。

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any],
    annotations: ToolAnnotations | None = None
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

パラメータ

入力スキーマオプション

1. シンプルな型マッピング（推奨）：

   {"text": str, "count": int, "enabled": bool}
   

2. JSON Schema 形式（複雑な検証用）：

   {
       "type": "object",
       "properties": {
           "text": {"type": "string"},
           "count": {"type": "integer", "minimum": 0},
       },
       "required": ["text"],
   }
   

戻り値

ツール実装をラップし、SdkMcpTool インスタンスを返すデコレータ関数。

例

from claude_agent_sdk import tool
from typing import Any


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

ToolAnnotations

mcp.types から再エクスポート（from claude_agent_sdk import ToolAnnotations としても利用可能）。すべてのフィールドはオプションのヒントです。クライアントはセキュリティ決定のためにこれらに依存すべきではありません。

from claude_agent_sdk import tool, ToolAnnotations
from typing import Any


@tool(
    "search",
    "Search the web",
    {"query": str},
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
)
async def search(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}

create_sdk_mcp_server()

Python アプリケーション内で実行されるインプロセス MCP サーバーを作成します。

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig

パラメータ

戻り値

ClaudeAgentOptions.mcp_servers に渡すことができる McpSdkServerConfig オブジェクトを返します。

例

from claude_agent_sdk import tool, create_sdk_mcp_server


@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}


@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply(args):
    return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}


calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply],  # Pass decorated functions
)

# Use with Claude
options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
)

list_sessions()

メタデータを含む過去のセッションをリストします。プロジェクトディレクトリでフィルタするか、すべてのプロジェクト全体のセッションをリストします。同期的です。すぐに返します。

def list_sessions(
    directory: str | None = None,
    limit: int | None = None,
    include_worktrees: bool = True
) -> list[SDKSessionInfo]

パラメータ

戻り値の型：SDKSessionInfo

例

プロジェクトの 10 個の最新セッションを出力します。結果は last_modified の降順でソートされるため、最初の項目が最新です。directory を省略するとすべてのプロジェクト全体を検索します。

from claude_agent_sdk import list_sessions

for session in list_sessions(directory="/path/to/project", limit=10):
    print(f"{session.summary} ({session.session_id})")

get_session_messages()

過去のセッションからメッセージを取得します。同期的です。すぐに返します。

def get_session_messages(
    session_id: str,
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0
) -> list[SessionMessage]

パラメータ

戻り値の型：SessionMessage

例

from claude_agent_sdk import list_sessions, get_session_messages

sessions = list_sessions(limit=1)
if sessions:
    messages = get_session_messages(sessions[0].session_id)
    for msg in messages:
        print(f"[{msg.type}] {msg.uuid}")

get_session_info()

プロジェクトディレクトリ全体をスキャンせずに、ID でシングルセッションのメタデータを読み取ります。同期的です。すぐに返します。

def get_session_info(
    session_id: str,
    directory: str | None = None,
) -> SDKSessionInfo | None

パラメータ

SDKSessionInfo を返すか、セッションが見つからない場合は None。

例

プロジェクトディレクトリをスキャンせずに、シングルセッションのメタデータを検索します。前の実行からセッション ID を既に持っている場合に便利です。

from claude_agent_sdk import get_session_info

info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
if info:
    print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")

rename_session()

カスタムタイトルエントリを追加することでセッションの名前を変更します。繰り返し呼び出しは安全です。最新のタイトルが優先されます。同期的です。

def rename_session(
    session_id: str,
    title: str,
    directory: str | None = None,
) -> None

パラメータ

session_id が有効な UUID でない場合、または title が空の場合は ValueError を発生させます。セッションが見つからない場合は FileNotFoundError。

例

最新のセッションの名前を変更して、後で見つけやすくします。新しいタイトルは、その後の読み取りで SDKSessionInfo.custom_title に表示されます。

from claude_agent_sdk import list_sessions, rename_session

sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    rename_session(sessions[0].session_id, "Refactor auth module")

tag_session()

セッションにタグを付けます。None を渡してタグをクリアします。繰り返し呼び出しは安全です。最新のタグが優先されます。同期的です。

def tag_session(
    session_id: str,
    tag: str | None,
    directory: str | None = None,
) -> None

パラメータ

session_id が有効な UUID でない場合、またはサニタイズ後に tag が空の場合は ValueError を発生させます。セッションが見つからない場合は FileNotFoundError。

例

セッションにタグを付けてから、後の読み取りでそのタグでフィルタします。既存のタグをクリアするには None を渡します。

from claude_agent_sdk import list_sessions, tag_session

# Tag a session
tag_session("550e8400-e29b-41d4-a716-446655440000", "needs-review")

# Later: find all sessions with that tag
for session in list_sessions(directory="/path/to/project"):
    if session.tag == "needs-review":
        print(session.summary)

クラス

ClaudeSDKClient

複数の交換にわたってセッションを維持します。 これは TypeScript SDK の query() 関数が内部的にどのように機能するかの Python 同等物です。会話を続けることができるクライアントオブジェクトを作成します。

主な機能

• セッション継続性：複数の query() 呼び出しにわたって会話コンテキストを維持します
• 同じ会話：セッションは前のメッセージを保持します
• 割り込みサポート：タスク途中で実行を停止できます
• 明示的なライフサイクル：セッションの開始と終了を制御します
• 応答駆動フロー：応答に反応してフォローアップを送信できます
• カスタムツールと hooks：カスタムツール（@tool デコレータで作成）と hooks をサポートします

class ClaudeSDKClient:
    def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None)
    async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
    async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
    async def receive_messages(self) -> AsyncIterator[Message]
    async def receive_response(self) -> AsyncIterator[Message]
    async def interrupt(self) -> None
    async def set_permission_mode(self, mode: str) -> None
    async def set_model(self, model: str | None = None) -> None
    async def rewind_files(self, user_message_id: str) -> None
    async def get_mcp_status(self) -> McpStatusResponse
    async def reconnect_mcp_server(self, server_name: str) -> None
    async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
    async def stop_task(self, task_id: str) -> None
    async def get_server_info(self) -> dict[str, Any] | None
    async def disconnect(self) -> None

メソッド

コンテキストマネージャーサポート

クライアントは自動接続管理のための非同期コンテキストマネージャーとして使用できます：

async with ClaudeSDKClient() as client:
    await client.query("Hello Claude")
    async for message in client.receive_response():
        print(message)

重要： メッセージを反復処理する場合、早期に終了するために break を使用することは避けてください。これは asyncio クリーンアップの問題を引き起こす可能性があります。代わりに、反復を自然に完了させるか、フラグを使用して必要なものを見つけたときを追跡してください。

例 - 会話を続ける

import asyncio
from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage


async def main():
    async with ClaudeSDKClient() as client:
        # First question
        await client.query("What's the capital of France?")

        # Process response
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Follow-up question - the session retains the previous context
        await client.query("What's the population of that city?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Another follow-up - still in the same conversation
        await client.query("What are some famous landmarks there?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")


asyncio.run(main())

例 - ClaudeSDKClient でのストリーミング入力

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def message_stream():
    """Generate messages dynamically."""
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Analyze the following data:"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "What patterns do you see?"},
    }


async def main():
    async with ClaudeSDKClient() as client:
        # Stream input to Claude
        await client.query(message_stream())

        # Process response
        async for message in client.receive_response():
            print(message)

        # Follow-up in same session
        await client.query("Should we be concerned about these readings?")

        async for message in client.receive_response():
            print(message)


asyncio.run(main())

例 - 割り込みの使用

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage


async def interruptible_task():
    options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")

    async with ClaudeSDKClient(options=options) as client:
        # Start a long-running task
        await client.query("Count from 1 to 100 slowly, using the bash sleep command")

        # Let it run for a bit
        await asyncio.sleep(2)

        # Interrupt the task
        await client.interrupt()
        print("Task interrupted!")

        # Drain the interrupted task's messages (including its ResultMessage)
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(f"Interrupted task finished with subtype={message.subtype!r}")
                # subtype is "error_during_execution" for interrupted tasks

        # Send a new command
        await client.query("Just say hello instead")

        # Now receive the new response
        async for message in client.receive_response():
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(f"New result: {message.result}")


asyncio.run(interruptible_task())

例 - 高度なパーミッション制御

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import (
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


async def custom_permission_handler(
    tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    """Custom logic for tool permissions."""

    # Block writes to system directories
    if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
        return PermissionResultDeny(
            message="System directory write not allowed", interrupt=True
        )

    # Redirect sensitive file operations
    if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
        safe_path = f"./sandbox/{input_data['file_path']}"
        return PermissionResultAllow(
            updated_input={**input_data, "file_path": safe_path}
        )

    # Allow everything else
    return PermissionResultAllow(updated_input=input_data)


async def main():
    options = ClaudeAgentOptions(
        can_use_tool=custom_permission_handler, allowed_tools=["Read", "Write", "Edit"]
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Update the system config file")

        async for message in client.receive_response():
            # Will use sandbox path instead
            print(message)


asyncio.run(main())

型

SdkMcpTool

@tool デコレータで作成された SDK MCP ツールの定義。

@dataclass
class SdkMcpTool(Generic[T]):
    name: str
    description: str
    input_schema: type[T] | dict[str, Any]
    handler: Callable[[T], Awaitable[dict[str, Any]]]
    annotations: ToolAnnotations | None = None

Transport

カスタムトランスポート実装の抽象基本クラス。これを使用して、カスタムチャネル（例：ローカルサブプロセスの代わりにリモート接続）を介して Claude プロセスと通信します。

from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
from typing import Any


class Transport(ABC):
    @abstractmethod
    async def connect(self) -> None: ...

    @abstractmethod
    async def write(self, data: str) -> None: ...

    @abstractmethod
    def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...

    @abstractmethod
    async def close(self) -> None: ...

    @abstractmethod
    def is_ready(self) -> bool: ...

    @abstractmethod
    async def end_input(self) -> None: ...

インポート：from claude_agent_sdk import Transport

ClaudeAgentOptions

Claude Code クエリの設定 dataclass。

@dataclass
class ClaudeAgentOptions:
    tools: list[str] | ToolsPreset | None = None
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    strict_mcp_config: bool = False
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    max_turns: int | None = None
    max_budget_usd: float | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    fallback_model: str | None = None
    betas: list[SdkBeta] = field(default_factory=list)
    output_format: dict[str, Any] | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    cli_path: str | Path | None = None
    settings: str | None = None
    add_dirs: list[str | Path] = field(default_factory=list)
    env: dict[str, str] = field(default_factory=dict)
    extra_args: dict[str, str | None] = field(default_factory=dict)
    max_buffer_size: int | None = None
    debug_stderr: Any = sys.stderr  # Deprecated
    stderr: Callable[[str], None] | None = None
    can_use_tool: CanUseTool | None = None
    hooks: dict[HookEvent, list[HookMatcher]] | None = None
    user: str | None = None
    include_partial_messages: bool = False
    include_hook_events: bool = False
    fork_session: bool = False
    agents: dict[str, AgentDefinition] | None = None
    setting_sources: list[SettingSource] | None = None
    sandbox: SandboxSettings | None = None
    plugins: list[SdkPluginConfig] = field(default_factory=list)
    max_thinking_tokens: int | None = None  # Deprecated: use thinking instead
    thinking: ThinkingConfig | None = None
    effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None
    enable_file_checkpointing: bool = False
    session_store: SessionStore | None = None
    session_store_flush: SessionStoreFlushMode = "batched"

遅いまたは停止した API レスポンスを処理

CLI サブプロセスは、API タイムアウトと停止検出を制御するいくつかの環境変数を読み込みます。ClaudeAgentOptions.env を通じてそれらを渡します：

options = ClaudeAgentOptions(
    env={
        "API_TIMEOUT_MS": "120000",
        "CLAUDE_CODE_MAX_RETRIES": "2",
        "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000",
    },
)

• API_TIMEOUT_MS：Anthropic クライアントのリクエストごとのタイムアウト（ミリ秒単位）。デフォルト 600000。メインループとすべてのサブエージェントに適用されます。
• CLAUDE_CODE_MAX_RETRIES：最大 API リトライ数。デフォルト 10。各リトライは独自の API_TIMEOUT_MS ウィンドウを取得するため、最悪の場合の実時間はおおよそ API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) にバックオフを加えたものです。
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS：run_in_background で起動されたサブエージェント用の停止ウォッチドッグ。デフォルト 600000。各ストリームイベントでリセットされます。停止時にサブエージェントを中止し、タスクを失敗とマークし、部分的な結果を含むエラーを親に表示します。同期サブエージェントには適用されません。
• CLAUDE_ENABLE_STREAM_WATCHDOG=1 と CLAUDE_STREAM_IDLE_TIMEOUT_MS：ヘッダーが到着したがレスポンスボディがストリーミングを停止したときにリクエストを中止します。デフォルトではオフです。CLAUDE_STREAM_IDLE_TIMEOUT_MS はデフォルト 300000 で、その最小値にクランプされます。中止されたリクエストは通常のリトライパスを通ります。

OutputFormat

構造化出力検証の設定。これを ClaudeAgentOptions の output_format フィールドに dict として渡します：

# Expected dict shape for output_format
{
    "type": "json_schema",
    "schema": {...},  # Your JSON Schema definition
}

SystemPromptPreset

オプションの追加を含む Claude Code のプリセットシステムプロンプトを使用するための設定。

class SystemPromptPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]
    append: NotRequired[str]
    exclude_dynamic_sections: NotRequired[bool]

SettingSource

SDK が設定を読み込むファイルシステムベースの設定ソースを制御します。

SettingSource = Literal["user", "project", "local"]

デフォルト動作

setting_sources が省略されるか None の場合、query() は Claude Code CLI と同じファイルシステム設定を読み込みます：ユーザー、プロジェクト、ローカル。管理ポリシー設定はすべての場合に読み込まれます。このオプションに関係なく読み込まれる入力については settingSources が制御しないもの を参照し、それらを無効にする方法を参照してください。

setting_sources を使用する理由

ファイルシステム設定を無効にする：

# Do not load user, project, or local settings from disk
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Analyze this code",
    options=ClaudeAgentOptions(
        setting_sources=[]
    ),
):
    print(message)

すべてのファイルシステム設定を明示的に読み込む：

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Analyze this code",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project", "local"]
    ),
):
    print(message)

特定の設定ソースのみを読み込む：

# Load only project settings, ignore user and local
async for message in query(
    prompt="Run CI checks",
    options=ClaudeAgentOptions(
        setting_sources=["project"]  # Only .claude/settings.json
    ),
):
    print(message)

テストと CI 環境：

# Ensure consistent behavior in CI by excluding local settings
async for message in query(
    prompt="Run tests",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Only team-shared settings
        permission_mode="bypassPermissions",
    ),
):
    print(message)

SDK のみのアプリケーション：

# Define everything programmatically.
# Pass [] to opt out of filesystem setting sources.
async for message in query(
    prompt="Review this PR",
    options=ClaudeAgentOptions(
        setting_sources=[],
        agents={...},
        mcp_servers={...},
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    print(message)

CLAUDE.md プロジェクト指示を読み込む：

# Load project settings to include CLAUDE.md files
async for message in query(
    prompt="Add a new feature following project conventions",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",  # Use Claude Code's system prompt
        },
        setting_sources=["project"],  # Loads CLAUDE.md from project
        allowed_tools=["Read", "Write", "Edit"],
    ),
):
    print(message)

設定の優先順位

複数のソースが読み込まれる場合、設定はこの優先順位（最高から最低）でマージされます：

1. ローカル設定（.claude/settings.local.json）
2. プロジェクト設定（.claude/settings.json）
3. ユーザー設定（~/.claude/settings.json）

agents と allowed_tools などのプログラム的なオプションは、ユーザー、プロジェクト、ローカルのファイルシステム設定をオーバーライドします。管理ポリシー設定はプログラム的なオプションより優先されます。

AgentDefinition

プログラムで定義されたサブエージェントの設定。

@dataclass
class AgentDefinition:
    description: str
    prompt: str
    tools: list[str] | None = None
    disallowedTools: list[str] | None = None
    model: str | None = None
    skills: list[str] | None = None
    memory: Literal["user", "project", "local"] | None = None
    mcpServers: list[str | dict[str, Any]] | None = None
    initialPrompt: str | None = None
    maxTurns: int | None = None
    background: bool | None = None
    effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None
    permissionMode: PermissionMode | None = None

PermissionMode

ツール実行を制御するためのパーミッションモード。

PermissionMode = Literal[
    "default",  # Standard permission behavior
    "acceptEdits",  # Auto-accept file edits
    "plan",  # Planning mode - read-only tools only
    "dontAsk",  # Deny anything not pre-approved instead of prompting
    "bypassPermissions",  # Bypass all permission checks (use with caution)
]

CanUseTool

ツールパーミッションコールバック関数の型エイリアス。

CanUseTool = Callable[
    [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
]

コールバックは以下を受け取ります：

• tool_name：呼び出されるツールの名前
• input_data：ツールの入力パラメータ
• context：追加情報を含む ToolPermissionContext

PermissionResult（PermissionResultAllow または PermissionResultDeny）を返します。

ToolPermissionContext

ツールパーミッションコールバックに渡されるコンテキスト情報。

@dataclass
class ToolPermissionContext:
    signal: Any | None = None  # Future: abort signal support
    suggestions: list[PermissionUpdate] = field(default_factory=list)
    blocked_path: str | None = None
    decision_reason: str | None = None
    title: str | None = None
    display_name: str | None = None
    description: str | None = None

PermissionResult

パーミッションコールバック結果の Union 型。

PermissionResult = PermissionResultAllow | PermissionResultDeny

PermissionResultAllow

ツール呼び出しを許可すべきことを示す結果。

@dataclass
class PermissionResultAllow:
    behavior: Literal["allow"] = "allow"
    updated_input: dict[str, Any] | None = None
    updated_permissions: list[PermissionUpdate] | None = None

PermissionResultDeny

ツール呼び出しを拒否すべきことを示す結果。

@dataclass
class PermissionResultDeny:
    behavior: Literal["deny"] = "deny"
    message: str = ""
    interrupt: bool = False

PermissionUpdate

プログラムでパーミッションを更新するための設定。

@dataclass
class PermissionUpdate:
    type: Literal[
        "addRules",
        "replaceRules",
        "removeRules",
        "setMode",
        "addDirectories",
        "removeDirectories",
    ]
    rules: list[PermissionRuleValue] | None = None
    behavior: Literal["allow", "deny", "ask"] | None = None
    mode: PermissionMode | None = None
    directories: list[str] | None = None
    destination: (
        Literal["userSettings", "projectSettings", "localSettings", "session"] | None
    ) = None

PermissionRuleValue

パーミッション更新で追加、置換、または削除するルール。

@dataclass
class PermissionRuleValue:
    tool_name: str
    rule_content: str | None = None

ToolsPreset

Claude Code のデフォルトツールセットを使用するためのプリセットツール設定。

class ToolsPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]

ThinkingConfig

拡張思考動作を制御します。3 つの設定の Union：

class ThinkingConfigAdaptive(TypedDict):
    type: Literal["adaptive"]


class ThinkingConfigEnabled(TypedDict):
    type: Literal["enabled"]
    budget_tokens: int


class ThinkingConfigDisabled(TypedDict):
    type: Literal["disabled"]


ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

これらは TypedDict クラスであるため、実行時にはプレーンな dict です。dict リテラルとして構築するか、クラスをコンストラクタのように呼び出します。どちらも dict を生成します。config["budget_tokens"] でフィールドにアクセスし、config.budget_tokens ではなく：

from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

# Option 1: dict literal (recommended, no import needed)
options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

# Option 2: constructor-style (returns a plain dict)
config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
print(config["budget_tokens"])  # 20000
# config.budget_tokens would raise AttributeError

SdkBeta

SDK ベータ機能の Literal 型。

SdkBeta = Literal["context-1m-2025-08-07"]

ClaudeAgentOptions の betas フィールドで使用してベータ機能を有効にします。

McpSdkServerConfig

create_sdk_mcp_server() で作成された SDK MCP サーバーの設定。

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # MCP Server instance

McpServerConfig

MCP サーバー設定の Union 型。

McpServerConfig = (
    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
)

McpStdioServerConfig

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Optional for backwards compatibility
    command: str
    args: NotRequired[list[str]]
    env: NotRequired[dict[str, str]]

McpSSEServerConfig

class McpSSEServerConfig(TypedDict):
    type: Literal["sse"]
    url: str
    headers: NotRequired[dict[str, str]]

McpHttpServerConfig

class McpHttpServerConfig(TypedDict):
    type: Literal["http"]
    url: str
    headers: NotRequired[dict[str, str]]

McpServerStatusConfig

get_mcp_status() によって報告される MCP サーバーの設定。これは、すべての McpServerConfig トランスポートバリアント、および claude.ai を通じてプロキシされるサーバー用の出力のみの claudeai-proxy バリアントの Union です。

McpServerStatusConfig = (
    McpStdioServerConfig
    | McpSSEServerConfig
    | McpHttpServerConfig
    | McpSdkServerConfigStatus
    | McpClaudeAIProxyServerConfig
)

McpSdkServerConfigStatus は McpSdkServerConfig のシリアライズ可能な形式で、type（"sdk"）と name（str）フィールドのみです。インプロセス instance は省略されます。McpClaudeAIProxyServerConfig には type（"claudeai-proxy"）、url（str）、id（str）フィールドがあります。

McpStatusResponse

ClaudeSDKClient.get_mcp_status() からの応答。サーバーステータスのリストを mcpServers キーの下にラップします。

class McpStatusResponse(TypedDict):
    mcpServers: list[McpServerStatus]

McpServerStatus

接続された MCP サーバーのステータス。McpStatusResponse に含まれます。

class McpServerStatus(TypedDict):
    name: str
    status: McpServerConnectionStatus  # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
    serverInfo: NotRequired[McpServerInfo]
    error: NotRequired[str]
    config: NotRequired[McpServerStatusConfig]
    scope: NotRequired[str]
    tools: NotRequired[list[McpToolInfo]]

SdkPluginConfig

SDK でプラグインを読み込むための設定。

class SdkPluginConfig(TypedDict):
    type: Literal["local"]
    path: str

例：

plugins = [
    {"type": "local", "path": "./my-plugin"},
    {"type": "local", "path": "/absolute/path/to/plugin"},
]

プラグインの作成と使用に関する完全な情報については、プラグイン を参照してください。

メッセージ型

Message

すべての可能なメッセージの Union 型。

Message = (
    UserMessage
    | AssistantMessage
    | SystemMessage
    | ResultMessage
    | StreamEvent
    | RateLimitEvent
)

UserMessage

ユーザー入力メッセージ。

@dataclass
class UserMessage:
    content: str | list[ContentBlock]
    uuid: str | None = None
    parent_tool_use_id: str | None = None
    tool_use_result: dict[str, Any] | None = None

AssistantMessage

コンテンツブロック付きのアシスタント応答メッセージ。

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str
    parent_tool_use_id: str | None = None
    error: AssistantMessageError | None = None
    usage: dict[str, Any] | None = None
    message_id: str | None = None

AssistantMessageError

アシスタントメッセージの可能なエラータイプ。

AssistantMessageError = Literal[
    "authentication_failed",
    "billing_error",
    "rate_limit",
    "invalid_request",
    "server_error",
    "max_output_tokens",
    "unknown",
]

SystemMessage

メタデータ付きのシステムメッセージ。

@dataclass
class SystemMessage:
    subtype: str
    data: dict[str, Any]

ResultMessage

コストと使用状況情報を含む最終結果メッセージ。

@dataclass
class ResultMessage:
    subtype: str
    duration_ms: int
    duration_api_ms: int
    is_error: bool
    num_turns: int
    session_id: str
    stop_reason: str | None = None
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None
    structured_output: Any = None
    model_usage: dict[str, Any] | None = None
    permission_denials: list[Any] | None = None
    deferred_tool_use: DeferredToolUse | None = None
    errors: list[str] | None = None
    api_error_status: int | None = None
    uuid: str | None = None

usage dict には、存在する場合、以下のキーが含まれます：

model_usage dict はモデル名をモデルごとの使用状況にマップします。内部 dict キーは camelCase を使用します。これは、基になる CLI プロセスから変更されずに渡される値であり、TypeScript ModelUsage 型と一致するためです：

StreamEvent

ストリーミング中の部分的なメッセージ更新のためのストリームイベント。ClaudeAgentOptions で include_partial_messages=True の場合のみ受け取られます。from claude_agent_sdk.types import StreamEvent でインポートしてください。

@dataclass
class StreamEvent:
    uuid: str
    session_id: str
    event: dict[str, Any]  # The raw Claude API stream event
    parent_tool_use_id: str | None = None

RateLimitEvent

レート制限ステータスが変更されたときに発行されます（例："allowed" から "allowed_warning" へ）。ユーザーにハード制限に達する前に警告するか、ステータスが "rejected" の場合にバックオフするために使用します。

@dataclass
class RateLimitEvent:
    rate_limit_info: RateLimitInfo
    uuid: str
    session_id: str

RateLimitInfo

RateLimitEvent によって運ばれるレート制限状態。

RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
RateLimitType = Literal[
    "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
]


@dataclass
class RateLimitInfo:
    status: RateLimitStatus
    resets_at: int | None = None
    rate_limit_type: RateLimitType | None = None
    utilization: float | None = None
    overage_status: RateLimitStatus | None = None
    overage_resets_at: int | None = None
    overage_disabled_reason: str | None = None
    raw: dict[str, Any] = field(default_factory=dict)

TaskStartedMessage

バックグラウンドタスクが開始されたときに発行されます。バックグラウンドタスクは、メインターンの外で追跡されるもの：バックグラウンド Bash コマンド、Monitor ウォッチ、Agent ツール経由で生成されたサブエージェント、またはリモートエージェント。task_type フィールドはどれであるかを示します。このネーミングは Task から Agent ツールへの名前変更とは無関係です。

@dataclass
class TaskStartedMessage(SystemMessage):
    task_id: str
    description: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    task_type: str | None = None

TaskUsage

バックグラウンドタスクのトークンとタイミングデータ。

class TaskUsage(TypedDict):
    total_tokens: int
    tool_uses: int
    duration_ms: int

TaskProgressMessage

実行中のバックグラウンドタスクの進捗更新で定期的に発行されます。

@dataclass
class TaskProgressMessage(SystemMessage):
    task_id: str
    description: str
    usage: TaskUsage
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    last_tool_name: str | None = None

TaskNotificationMessage

バックグラウンドタスクが完了、失敗、または停止されたときに発行されます。バックグラウンドタスクには、run_in_background Bash コマンド、Monitor ウォッチ、バックグラウンドサブエージェントが含まれます。

@dataclass
class TaskNotificationMessage(SystemMessage):
    task_id: str
    status: TaskNotificationStatus  # "completed" | "failed" | "stopped"
    output_file: str
    summary: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    usage: TaskUsage | None = None

コンテンツブロック型

ContentBlock

すべてのコンテンツブロックの Union 型。

ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock

TextBlock

テキストコンテンツブロック。

@dataclass
class TextBlock:
    text: str

ThinkingBlock

思考コンテンツブロック（思考機能を持つモデル用）。

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

ToolUseBlock

ツール使用リクエストブロック。

@dataclass
class ToolUseBlock:
    id: str
    name: str
    input: dict[str, Any]

ToolResultBlock

ツール実行結果ブロック。

@dataclass
class ToolResultBlock:
    tool_use_id: str
    content: str | list[dict[str, Any]] | None = None
    is_error: bool | None = None

エラー型

ClaudeSDKError

すべての SDK エラーの基本例外クラス。

class ClaudeSDKError(Exception):
    """Base error for Claude SDK."""

CLINotFoundError

Claude Code CLI がインストールされていないか見つからない場合に発生します。

class CLINotFoundError(CLIConnectionError):
    def __init__(
        self, message: str = "Claude Code not found", cli_path: str | None = None
    ):
        """
        Args:
            message: Error message (default: "Claude Code not found")
            cli_path: Optional path to the CLI that was not found
        """

CLIConnectionError

Claude Code への接続に失敗した場合に発生します。

class CLIConnectionError(ClaudeSDKError):
    """Failed to connect to Claude Code."""

ProcessError

Claude Code プロセスが失敗した場合に発生します。

class ProcessError(ClaudeSDKError):
    def __init__(
        self, message: str, exit_code: int | None = None, stderr: str | None = None
    ):
        self.exit_code = exit_code
        self.stderr = stderr

CLIJSONDecodeError

JSON 解析に失敗した場合に発生します。

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: The line that failed to parse
            original_error: The original JSON decode exception
        """
        self.line = line
        self.original_error = original_error

Hook 型

hooks の使用に関する包括的なガイド、例、一般的なパターンについては、Hooks ガイド を参照してください。

HookEvent

サポートされている hook イベント型。

HookEvent = Literal[
    "PreToolUse",  # Called before tool execution
    "PostToolUse",  # Called after tool execution
    "PostToolUseFailure",  # Called when a tool execution fails
    "UserPromptSubmit",  # Called when user submits a prompt
    "Stop",  # Called when stopping execution
    "SubagentStop",  # Called when a subagent stops
    "PreCompact",  # Called before message compaction
    "Notification",  # Called for notification events
    "SubagentStart",  # Called when a subagent starts
    "PermissionRequest",  # Called when a permission decision is needed
]

HookCallback

hook コールバック関数の型定義。

HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]

パラメータ：

• input：hook_event_name に基づいた判別 Union を持つ強く型付けされた hook 入力（HookInput を参照）
• tool_use_id：オプションのツール使用識別子（ツール関連の hook 用）
• context：追加情報を含む hook コンテキスト

以下を含む可能性のある HookJSONOutput を返します：

• decision：アクションをブロックするには "block"
• systemMessage：ユーザーに表示される警告メッセージ
• hookSpecificOutput：hook 固有の出力データ

HookContext

hook コールバックに渡されるコンテキスト情報。

class HookContext(TypedDict):
    signal: Any | None  # Future: abort signal support

HookMatcher

特定のイベントまたはツールに hook をマッチングするための設定。

@dataclass
class HookMatcher:
    matcher: str | None = (
        None  # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
    )
    hooks: list[HookCallback] = field(
        default_factory=list
    )  # List of callbacks to execute
    timeout: float | None = (
        None  # Timeout in seconds for all hooks in this matcher (default: 60)
    )

HookInput

すべての hook 入力型の Union 型。実際の型は hook_event_name フィールドに依存します。

HookInput = (
    PreToolUseHookInput
    | PostToolUseHookInput
    | PostToolUseFailureHookInput
    | UserPromptSubmitHookInput
    | StopHookInput
    | SubagentStopHookInput
    | PreCompactHookInput
    | NotificationHookInput
    | SubagentStartHookInput
    | PermissionRequestHookInput
)

BaseHookInput

すべての hook 入力型に存在する基本フィールド。

class BaseHookInput(TypedDict):
    session_id: str
    transcript_path: str
    cwd: str
    permission_mode: NotRequired[str]

PreToolUseHookInput

PreToolUse hook イベントの入力データ。

class PreToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PreToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

PostToolUseHookInput

PostToolUse hook イベントの入力データ。

class PostToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_response: Any
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

PostToolUseFailureHookInput

PostToolUseFailure hook イベントの入力データ。ツール実行が失敗したときに呼び出されます。

class PostToolUseFailureHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUseFailure"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    error: str
    is_interrupt: NotRequired[bool]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

UserPromptSubmitHookInput

UserPromptSubmit hook イベントの入力データ。

class UserPromptSubmitHookInput(BaseHookInput):
    hook_event_name: Literal["UserPromptSubmit"]
    prompt: str

StopHookInput

Stop hook イベントの入力データ。

class StopHookInput(BaseHookInput):
    hook_event_name: Literal["Stop"]
    stop_hook_active: bool

SubagentStopHookInput

SubagentStop hook イベントの入力データ。

class SubagentStopHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStop"]
    stop_hook_active: bool
    agent_id: str
    agent_transcript_path: str
    agent_type: str

PreCompactHookInput

PreCompact hook イベントの入力データ。

class PreCompactHookInput(BaseHookInput):
    hook_event_name: Literal["PreCompact"]
    trigger: Literal["manual", "auto"]
    custom_instructions: str | None

NotificationHookInput

Notification hook イベントの入力データ。

class NotificationHookInput(BaseHookInput):
    hook_event_name: Literal["Notification"]
    message: str
    title: NotRequired[str]
    notification_type: str

SubagentStartHookInput

SubagentStart hook イベントの入力データ。

class SubagentStartHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStart"]
    agent_id: str
    agent_type: str

PermissionRequestHookInput

PermissionRequest hook イベントの入力データ。hooks がパーミッション決定をプログラムで処理できるようにします。

class PermissionRequestHookInput(BaseHookInput):
    hook_event_name: Literal["PermissionRequest"]
    tool_name: str
    tool_input: dict[str, Any]
    permission_suggestions: NotRequired[list[Any]]

HookJSONOutput

hook コールバック戻り値の Union 型。

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

SyncHookJSONOutput

制御フィールドと決定フィールドを持つ同期 hook 出力。

class SyncHookJSONOutput(TypedDict):
    # Control fields
    continue_: NotRequired[bool]  # Whether to proceed (default: True)
    suppressOutput: NotRequired[bool]  # Hide stdout from transcript
    stopReason: NotRequired[str]  # Message when continue is False

    # Decision fields
    decision: NotRequired[Literal["block"]]
    systemMessage: NotRequired[str]  # Warning message for user
    reason: NotRequired[str]  # Feedback for Claude

    # Hook-specific output
    hookSpecificOutput: NotRequired[HookSpecificOutput]

HookSpecificOutput

hook イベント名とイベント固有のフィールドを含む TypedDict。形状は hookEventName 値に依存します。hook イベントごとに利用可能なフィールドの詳細については、hooks で実行を制御 を参照してください。

イベント固有の出力型の判別 union。hookEventName フィールドはどのフィールドが有効かを決定します。

class PreToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PreToolUse"]
    permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]
    permissionDecisionReason: NotRequired[str]
    updatedInput: NotRequired[dict[str, Any]]
    additionalContext: NotRequired[str]


class PostToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUse"]
    additionalContext: NotRequired[str]
    updatedToolOutput: NotRequired[Any]
    updatedMCPToolOutput: NotRequired[Any]


class PostToolUseFailureHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUseFailure"]
    additionalContext: NotRequired[str]


class UserPromptSubmitHookSpecificOutput(TypedDict):
    hookEventName: Literal["UserPromptSubmit"]
    additionalContext: NotRequired[str]


class NotificationHookSpecificOutput(TypedDict):
    hookEventName: Literal["Notification"]
    additionalContext: NotRequired[str]


class SubagentStartHookSpecificOutput(TypedDict):
    hookEventName: Literal["SubagentStart"]
    additionalContext: NotRequired[str]


class PermissionRequestHookSpecificOutput(TypedDict):
    hookEventName: Literal["PermissionRequest"]
    decision: dict[str, Any]


HookSpecificOutput = (
    PreToolUseHookSpecificOutput
    | PostToolUseHookSpecificOutput
    | PostToolUseFailureHookSpecificOutput
    | UserPromptSubmitHookSpecificOutput
    | NotificationHookSpecificOutput
    | SubagentStartHookSpecificOutput
    | PermissionRequestHookSpecificOutput
)

AsyncHookJSONOutput

hook 実行を遅延させる非同期 hook 出力。

class AsyncHookJSONOutput(TypedDict):
    async_: Literal[True]  # Set to True to defer execution
    asyncTimeout: NotRequired[int]  # Timeout in milliseconds

Hook 使用例

この例は 2 つの hook を登録します：1 つは rm -rf / のような危険な bash コマンドをブロックし、もう 1 つは監査のためにすべてのツール使用をログします。セキュリティ hook は matcher を介して Bash コマンドでのみ実行され、ログ hook はすべてのツールで実行されます。

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
from typing import Any


async def validate_bash_command(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Validate and potentially block dangerous bash commands."""
    if input_data["tool_name"] == "Bash":
        command = input_data["tool_input"].get("command", "")
        if "rm -rf /" in command:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": "Dangerous command blocked",
                }
            }
    return {}


async def log_tool_use(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Log all tool usage for auditing."""
    print(f"Tool used: {input_data.get('tool_name')}")
    return {}


options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash", hooks=[validate_bash_command], timeout=120
            ),  # 2 min for validation
            HookMatcher(
                hooks=[log_tool_use]
            ),  # Applies to all tools (default 60s timeout)
        ],
        "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
    }
)

async for message in query(prompt="Analyze this codebase", options=options):
    print(message)

ツール入出力型

すべての組み込み Claude Code ツールの入出力スキーマのドキュメント。Python SDK はこれらを型としてエクスポートしませんが、メッセージ内のツール入出力の構造を表します。

Agent

ツール名： Agent（以前は Task。これはまだエイリアスとして受け入れられます）

入力：

{
    "description": str,  # タスクの短い説明（3～5 語）
    "prompt": str,  # エージェントが実行するタスク
    "subagent_type": str,  # 使用する特化したエージェントのタイプ
}

出力：

{
    "result": str,  # サブエージェントからの最終結果
    "usage": dict | None,  # トークン使用統計
    "total_cost_usd": float | None,  # 推定総コスト（USD）
    "duration_ms": int | None,  # 実行時間（ミリ秒）
}

AskUserQuestion

ツール名： AskUserQuestion

実行中にユーザーに明確化の質問をします。使用の詳細については 承認とユーザー入力を処理 を参照してください。

入力：

{
    "questions": [  # ユーザーに質問する質問（1～4 個の質問）
        {
            "question": str,  # ユーザーに質問する完全な質問
            "header": str,  # チップ/タグとして表示される非常に短いラベル（最大 12 文字）
            "options": [  # 利用可能な選択肢（2～4 個のオプション）
                {
                    "label": str,  # このオプションの表示テキスト（1～5 語）
                    "description": str,  # このオプションが何を意味するかの説明
                }
            ],
            "multiSelect": bool,  # 複数選択を許可する場合は true に設定
        }
    ],
    "answers": dict[str, str | list[str]] | None,
    # パーミッションシステムによって入力されたユーザーの回答。マルチセレクト
    # 回答はラベルのリストまたはカンマ区切り文字列の場合があります
}

出力：

{
    "questions": [  # 質問された質問
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # 質問テキストを回答文字列にマップ
    # マルチセレクト回答はカンマ区切り
}

Bash

ツール名： Bash

入力：

{
    "command": str,  # 実行するコマンド
    "timeout": int | None,  # オプションのタイムアウト（ミリ秒、最大 600000）
    "description": str | None,  # 明確で簡潔な説明（5～10 語）
    "run_in_background": bool | None,  # バックグラウンドで実行する場合は true に設定
}

出力：

{
    "output": str,  # 標準出力と標準エラーの結合出力
    "exitCode": int,  # コマンドの終了コード
    "killed": bool | None,  # タイムアウトによってコマンドが強制終了されたかどうか
    "shellId": str | None,  # バックグラウンドプロセスのシェル ID
}

Monitor

ツール名： Monitor

バックグラウンドスクリプトを実行し、各 stdout 行を Claude にイベントとして配信して、ポーリングなしで反応できるようにします。Monitor は Bash と同じパーミッションルールに従います。動作とプロバイダーの可用性については、Monitor ツールリファレンス を参照してください。

入力：

{
    "command": str,  # シェルスクリプト。各 stdout 行はイベント、終了は監視を終了
    "description": str,  # 通知に表示される短い説明
    "timeout_ms": int | None,  # この期限後に強制終了（デフォルト 300000、最大 3600000）
    "persistent": bool | None,  # セッションの期間中実行。TaskStop で停止
}

出力：

{
    "taskId": str,  # バックグラウンド監視タスクの ID
    "timeoutMs": int,  # タイムアウト期限（ミリ秒）（persistent の場合は 0）
    "persistent": bool | None,  # TaskStop またはセッション終了まで実行する場合は True
}

Edit

ツール名： Edit

入力：

{
    "file_path": str,  # 変更するファイルの絶対パス
    "old_string": str,  # 置換するテキスト
    "new_string": str,  # 置換後のテキスト
    "replace_all": bool | None,  # すべての出現を置換（デフォルト False）
}

出力：

{
    "message": str,  # 確認メッセージ
    "replacements": int,  # 実行された置換の数
    "file_path": str,  # 編集されたファイルパス
}

Read

ツール名： Read

入力：

{
    "file_path": str,  # 読み込むファイルの絶対パス
    "offset": int | None,  # 読み込みを開始する行番号
    "limit": int | None,  # 読み込む行数
}

出力（テキストファイル）：

{
    "content": str,  # 行番号付きのファイル内容
    "total_lines": int,  # ファイルの総行数
    "lines_returned": int,  # 実際に返された行数
}

出力（画像）：

{
    "image": str,  # Base64 エンコードされた画像データ
    "mime_type": str,  # 画像の MIME タイプ
    "file_size": int,  # ファイルサイズ（バイト）
}

Write

ツール名： Write

入力：

{
    "file_path": str,  # 書き込むファイルの絶対パス
    "content": str,  # ファイルに書き込むコンテンツ
}

出力：

{
    "message": str,  # 成功メッセージ
    "bytes_written": int,  # 書き込まれたバイト数
    "file_path": str,  # 書き込まれたファイルパス
}

Glob

ツール名： Glob

入力：

{
    "pattern": str,  # ファイルにマッチさせるグロブパターン
    "path": str | None,  # 検索するディレクトリ（デフォルトは cwd）
}

出力：

{
    "matches": list[str],  # マッチしたファイルパスの配列
    "count": int,  # 見つかったマッチの数
    "search_path": str,  # 使用された検索ディレクトリ
}

Grep

ツール名： Grep

入力：

{
    "pattern": str,  # 正規表現パターン
    "path": str | None,  # 検索するファイルまたはディレクトリ
    "glob": str | None,  # ファイルをフィルタリングするグロブパターン
    "type": str | None,  # 検索するファイルタイプ
    "output_mode": str | None,  # 「content」、「files_with_matches」、または「count」
    "-i": bool | None,  # 大文字小文字を区別しない検索
    "-n": bool | None,  # 行番号を表示
    "-B": int | None,  # 各マッチの前に表示する行
    "-A": int | None,  # 各マッチの後に表示する行
    "-C": int | None,  # 前後に表示する行
    "head_limit": int | None,  # 出力を最初の N 行/エントリに制限
    "multiline": bool | None,  # マルチラインモードを有効化
}

出力（content モード）：

{
    "matches": [
        {
            "file": str,
            "line_number": int | None,
            "line": str,
            "before_context": list[str] | None,
            "after_context": list[str] | None,
        }
    ],
    "total_matches": int,
}

出力（files_with_matches モード）：

{
    "files": list[str],  # マッチを含むファイル
    "count": int,  # マッチを含むファイルの数
}

NotebookEdit

ツール名： NotebookEdit

入力：

{
    "notebook_path": str,  # Jupyter ノートブックの絶対パス
    "cell_id": str | None,  # 編集するセルの ID
    "new_source": str,  # セルの新しいソース
    "cell_type": "code" | "markdown" | None,  # セルのタイプ
    "edit_mode": "replace" | "insert" | "delete" | None,  # 編集操作のタイプ
}

出力：

{
    "message": str,  # 成功メッセージ
    "edit_type": "replaced" | "inserted" | "deleted",  # 実行された編集のタイプ
    "cell_id": str | None,  # 影響を受けたセル ID
    "total_cells": int,  # 編集後のノートブックの総セル数
}

WebFetch

ツール名： WebFetch

入力：

{
    "url": str,  # コンテンツを取得する URL
    "prompt": str,  # 取得したコンテンツで実行するプロンプト
}

出力：

{
    "bytes": int,  # 取得したコンテンツのサイズ（バイト）
    "code": int,  # HTTP レスポンスコード
    "codeText": str,  # HTTP レスポンスコードテキスト
    "result": str,  # コンテンツにプロンプトを適用した処理結果
    "durationMs": int,  # コンテンツを取得して処理するのにかかった時間（ミリ秒）
    "url": str,  # 取得された URL
}

WebSearch

ツール名： WebSearch

入力：

{
    "query": str,  # 使用する検索クエリ
    "allowed_domains": list[str] | None,  # これらのドメインからのみ結果を含める
    "blocked_domains": list[str] | None,  # これらのドメインからの結果は決して含めない
}

出力：

{
    "query": str,  # 検索クエリ
    "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
    "durationSeconds": float,  # 検索時間（秒）
}

TodoWrite

ツール名： TodoWrite

入力：

{
    "todos": [
        {
            "content": str,  # タスクの説明
            "status": "pending" | "in_progress" | "completed",  # タスクのステータス
            "activeForm": str,  # 説明のアクティブな形式
        }
    ]
}

出力：

{
    "message": str,  # 成功メッセージ
    "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
}

TaskCreate

ツール名： TaskCreate

入力：

{
    "subject": str,  # 短いタスクタイトル
    "description": str,  # 詳細なタスク本文
    "activeForm": str | None,  # 進行中に表示される現在形ラベル
    "metadata": dict | None,  # 任意の呼び出し元メタデータ
}

出力：

{
    "task": {"id": str, "subject": str},  # 割り当てられた ID を持つ作成されたタスク
}

TaskUpdate

ツール名： TaskUpdate

入力：

{
    "taskId": str,  # パッチするタスクの ID
    "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
    "subject": str | None,
    "description": str | None,
    "activeForm": str | None,
    "addBlocks": list[str] | None,  # このタスクが現在ブロックするタスク ID
    "addBlockedBy": list[str] | None,  # 現在このタスクをブロックするタスク ID
    "owner": str | None,
    "metadata": dict | None,
}

出力：

{
    "success": bool,
    "taskId": str,
    "updatedFields": list[str],  # 変更されたフィールドの名前
    "error": str | None,
    "statusChange": {"from": str, "to": str} | None,
}

TaskGet

ツール名： TaskGet

入力：

{
    "taskId": str,  # 読み込むタスクの ID
}

出力：

{
    "task": {
        "id": str,
        "subject": str,
        "description": str,
        "status": Literal["pending", "in_progress", "completed"],
        "blocks": list[str],
        "blockedBy": list[str],
    } | None,  # ID が見つからない場合は None
}

TaskList

ツール名： TaskList

入力：

{}

出力：

{
    "tasks": [
        {
            "id": str,
            "subject": str,
            "status": Literal["pending", "in_progress", "completed"],
            "owner": str | None,
            "blockedBy": list[str],
        }
    ],
}

BashOutput

ツール名： BashOutput

入力：

{
    "bash_id": str,  # バックグラウンドシェルの ID
    "filter": str | None,  # 出力行をフィルタリングするオプションの正規表現
}

出力：

{
    "output": str,  # 最後のチェック以降の新しい出力
    "status": "running" | "completed" | "failed",  # 現在のシェルステータス
    "exitCode": int | None,  # 完了時の終了コード
}

KillBash

ツール名： KillBash

入力：

{
    "shell_id": str  # 強制終了するバックグラウンドシェルの ID
}

出力：

{
    "message": str,  # 成功メッセージ
    "shell_id": str,  # 強制終了されたシェルの ID
}

ExitPlanMode

ツール名： ExitPlanMode

入力：

{
    "plan": str  # ユーザーが承認するために実行するプラン
}

出力：

{
    "message": str,  # 確認メッセージ
    "approved": bool | None,  # ユーザーがプランを承認したかどうか
}

ListMcpResources

ツール名： ListMcpResources

入力：

{
    "server": str | None  # リソースをフィルタリングするオプションのサーバー名
}

出力：

{
    "resources": [
        {
            "uri": str,
            "name": str,
            "description": str | None,
            "mimeType": str | None,
            "server": str,
        }
    ],
    "total": int,
}

ReadMcpResource

ツール名： ReadMcpResource

入力：

{
    "server": str,  # MCP サーバー名
    "uri": str,  # 読み込むリソース URI
}

出力：

{
    "contents": [
        {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}
    ],
    "server": str,
}

ClaudeSDKClient を使用した高度な機能

継続的な会話インターフェースの構築

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
)
import asyncio


class ConversationSession:
    """Maintains a single conversation session with Claude."""

    def __init__(self, options: ClaudeAgentOptions | None = None):
        self.client = ClaudeSDKClient(options)
        self.turn_count = 0

    async def start(self):
        await self.client.connect()
        print("Starting conversation session. Claude will remember context.")
        print(
            "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
        )

        while True:
            user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")

            if user_input.lower() == "exit":
                break
            elif user_input.lower() == "interrupt":
                await self.client.interrupt()
                print("Task interrupted!")
                continue
            elif user_input.lower() == "new":
                # Disconnect and reconnect for a fresh session
                await self.client.disconnect()
                await self.client.connect()
                self.turn_count = 0
                print("Started new conversation session (previous context cleared)")
                continue

            # Send message - the session retains all previous messages
            await self.client.query(user_input)
            self.turn_count += 1

            # Process response
            print(f"[Turn {self.turn_count}] Claude: ", end="")
            async for message in self.client.receive_response():
                if isinstance(message, AssistantMessage):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print()  # New line after response

        await self.client.disconnect()
        print(f"Conversation ended after {self.turn_count} turns.")


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
    )
    session = ConversationSession(options)
    await session.start()


# Example conversation:
# Turn 1 - You: "Create a file called hello.py"
# Turn 1 - Claude: "I'll create a hello.py file for you..."
# Turn 2 - You: "What's in that file?"
# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
# Turn 3 - You: "Add a main function to it"
# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)

asyncio.run(main())

動作修正のための Hooks の使用

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    HookMatcher,
    HookContext,
)
import asyncio
from typing import Any


async def pre_tool_logger(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Log all tool usage before execution."""
    tool_name = input_data.get("tool_name", "unknown")
    print(f"[PRE-TOOL] About to use: {tool_name}")

    # You can modify or block the tool execution here
    if tool_name == "Bash" and "rm -rf" in str(input_data.get("tool_input", {})):
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Dangerous command blocked",
            }
        }
    return {}


async def post_tool_logger(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Log results after tool execution."""
    tool_name = input_data.get("tool_name", "unknown")
    print(f"[POST-TOOL] Completed: {tool_name}")
    return {}


async def user_prompt_modifier(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Add context to user prompts."""
    original_prompt = input_data.get("prompt", "")

    # Add a timestamp as additional context for Claude to see
    from datetime import datetime

    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

    return {
        "hookSpecificOutput": {
            "hookEventName": "UserPromptSubmit",
            "additionalContext": f"[Submitted at {timestamp}] Original prompt: {original_prompt}",
        }
    }


async def main():
    options = ClaudeAgentOptions(
        hooks={
            "PreToolUse": [
                HookMatcher(hooks=[pre_tool_logger]),
                HookMatcher(matcher="Bash", hooks=[pre_tool_logger]),
            ],
            "PostToolUse": [HookMatcher(hooks=[post_tool_logger])],
            "UserPromptSubmit": [HookMatcher(hooks=[user_prompt_modifier])],
        },
        allowed_tools=["Read", "Write", "Bash"],
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("List files in current directory")

        async for message in client.receive_response():
            # Hooks will automatically log tool usage
            pass


asyncio.run(main())

リアルタイム進捗監視

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    ToolUseBlock,
    ToolResultBlock,
    TextBlock,
)
import asyncio


async def monitor_progress():
    options = ClaudeAgentOptions(
        allowed_tools=["Write", "Bash"], permission_mode="acceptEdits"
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Create 5 Python files with different sorting algorithms")

        # Monitor progress in real-time
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, ToolUseBlock):
                        if block.name == "Write":
                            file_path = block.input.get("file_path", "")
                            print(f"Creating: {file_path}")
                    elif isinstance(block, ToolResultBlock):
                        print("Completed tool execution")
                    elif isinstance(block, TextBlock):
                        print(f"Claude says: {block.text[:100]}...")

        print("Task completed!")


asyncio.run(monitor_progress())

使用例

基本的なファイル操作（query を使用）

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
import asyncio


async def create_project():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode="acceptEdits",
        cwd="/home/user/project",
    )

    async for message in query(
        prompt="Create a Python project structure with setup.py", options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, ToolUseBlock):
                    print(f"Using tool: {block.name}")


asyncio.run(create_project())

エラー処理

from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError

try:
    async for message in query(prompt="Hello"):
        print(message)
except CLINotFoundError:
    print(
        "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
    )
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}")

クライアントでのストリーミングモード

from claude_agent_sdk import ClaudeSDKClient
import asyncio


async def interactive_session():
    async with ClaudeSDKClient() as client:
        # Send initial message
        await client.query("What's the weather like?")

        # Process responses
        async for msg in client.receive_response():
            print(msg)

        # Send follow-up
        await client.query("Tell me more about that")

        # Process follow-up response
        async for msg in client.receive_response():
            print(msg)


asyncio.run(interactive_session())

ClaudeSDKClient でカスタムツールを使用する

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    tool,
    create_sdk_mcp_server,
    AssistantMessage,
    TextBlock,
)
import asyncio
from typing import Any


# Define custom tools with @tool decorator
@tool("calculate", "Perform mathematical calculations", {"expression": str})
async def calculate(args: dict[str, Any]) -> dict[str, Any]:
    try:
        result = eval(args["expression"], {"__builtins__": {}})
        return {"content": [{"type": "text", "text": f"Result: {result}"}]}
    except Exception as e:
        return {
            "content": [{"type": "text", "text": f"Error: {str(e)}"}],
            "is_error": True,
        }


@tool("get_time", "Get current time", {})
async def get_time(args: dict[str, Any]) -> dict[str, Any]:
    from datetime import datetime

    current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    return {"content": [{"type": "text", "text": f"Current time: {current_time}"}]}


async def main():
    # Create SDK MCP server with custom tools
    my_server = create_sdk_mcp_server(
        name="utilities", version="1.0.0", tools=[calculate, get_time]
    )

    # Configure options with the server
    options = ClaudeAgentOptions(
        mcp_servers={"utils": my_server},
        allowed_tools=["mcp__utils__calculate", "mcp__utils__get_time"],
    )

    # Use ClaudeSDKClient for interactive tool usage
    async with ClaudeSDKClient(options=options) as client:
        await client.query("What's 123 * 456?")

        # Process calculation response
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Calculation: {block.text}")

        # Follow up with time query
        await client.query("What time is it now?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Time: {block.text}")


asyncio.run(main())

サンドボックス設定

SandboxSettings

サンドボックス動作の設定。これを使用してコマンドサンドボックスを有効にし、ネットワーク制限をプログラムで設定します。

class SandboxSettings(TypedDict, total=False):
    enabled: bool
    autoAllowBashIfSandboxed: bool
    excludedCommands: list[str]
    allowUnsandboxedCommands: bool
    network: SandboxNetworkConfig
    ignoreViolations: SandboxIgnoreViolations
    enableWeakerNestedSandbox: bool

使用例

from claude_agent_sdk import query, ClaudeAgentOptions, SandboxSettings

sandbox_settings: SandboxSettings = {
    "enabled": True,
    "autoAllowBashIfSandboxed": True,
    "network": {"allowLocalBinding": True},
}

async for message in query(
    prompt="Build and test my project",
    options=ClaudeAgentOptions(sandbox=sandbox_settings),
):
    print(message)

SandboxNetworkConfig

サンドボックスモード用のネットワーク固有の設定。

class SandboxNetworkConfig(TypedDict, total=False):
    allowedDomains: list[str]
    deniedDomains: list[str]
    allowManagedDomainsOnly: bool
    allowUnixSockets: list[str]
    allowAllUnixSockets: bool
    allowLocalBinding: bool
    allowMachLookup: list[str]
    httpProxyPort: int
    socksProxyPort: int

SandboxIgnoreViolations

特定のサンドボックス違反を無視するための設定。

class SandboxIgnoreViolations(TypedDict, total=False):
    file: list[str]
    network: list[str]

サンドボックスなしコマンドのパーミッションフォールバック

allowUnsandboxedCommands が有効な場合、モデルはツール入力で dangerouslyDisableSandbox: True を設定することでサンドボックスの外でコマンドを実行するようにリクエストできます。これらのリクエストは既存のパーミッションシステムにフォールバックします。つまり、can_use_tool ハンドラーが呼び出され、カスタム認可ロジックを実装できます。

from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    HookMatcher,
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


async def can_use_tool(
    tool: str, input: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    # Check if the model is requesting to bypass the sandbox
    if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
        # The model is requesting to run this command outside the sandbox
        print(f"Unsandboxed command requested: {input.get('command')}")

        if is_command_authorized(input.get("command")):
            return PermissionResultAllow()
        return PermissionResultDeny(
            message="Command not authorized for unsandboxed execution"
        )
    return PermissionResultAllow()


# Required: dummy hook keeps the stream open for can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
    return {"continue_": True}


async def prompt_stream():
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Deploy my application"},
    }


async def main():
    async for message in query(
        prompt=prompt_stream(),
        options=ClaudeAgentOptions(
            sandbox={
                "enabled": True,
                "allowUnsandboxedCommands": True,  # Model can request unsandboxed execution
            },
            permission_mode="default",
            can_use_tool=can_use_tool,
            hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
        ),
    ):
        print(message)

このパターンにより、以下が可能になります：

• モデルリクエストを監査する：モデルがサンドボックスなし実行をリクエストするときをログします
• 許可リストを実装する：特定のコマンドのみがサンドボックスなしで実行されることを許可します
• 承認ワークフローを追加する：特権操作に明示的な認可を要求します

関連項目

• SDK 概要 - 一般的な SDK 概念
• TypeScript SDK リファレンス - TypeScript SDK ドキュメント
• CLI リファレンス - コマンドラインインターフェース
• 一般的なワークフロー - ステップバイステップガイド