Agent SDK リファレンス - Python

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

インストール

仮想環境にパッケージをインストールしてください。最近の Debian、Ubuntu、Homebrew Python インストールでは、システム Python に対して pip install を実行すると error: externally-managed-environment で失敗します。

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

uv、Windows PowerShell、API キーのセットアップについては、Agent SDK クイックスタートの「Setup」セクションを参照してください。

query() と ClaudeSDKClient の選択

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

インタラクティブなアプリケーション（チャットインターフェースなど）や、次のアクションが Claude の応答に依存する場合は、ClaudeSDKClient を使用してください。

関数

[!NOTE]

このページの署名ブロックと裸の async for / async with フラグメントは説明用です。実行するには、本体を async def main(): ... でラップして asyncio.run(main()) を呼び出してください。

query()

デフォルトでは、Claude Code との各インタラクションのために新しいセッションを作成します。メッセージが到着するにつれて生成される非同期イテレータを返します。query() への各呼び出しは、continue_conversation=True または ClaudeAgentOptions の resume を渡さない限り、前のインタラクションのメモリなしで新しく開始します。セッション を参照してください。

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",
    )

    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"],
   }
   

3. TypedDict クラス：NotRequired のキーが required から除外される型付きスキーマ。

   • Python 3.11 以降：typing から TypedDict と NotRequired をインポートします。
   • Python 3.10：typing には NotRequired がありません。TypedDict と NotRequired は typing_extensions からインポートしてください。SDK は Python 3.10 で typing_extensions をインストールします。

   from typing import Annotated, Any, NotRequired, TypedDict
   from claude_agent_sdk import tool
   
   
   class ForecastArgs(TypedDict):
       latitude: Annotated[float, "Latitude coordinate"]
       hours: NotRequired[Annotated[int, "How many hours of forecast to return"]]
   
   
   @tool("get_forecast", "Get the hourly forecast for a location", ForecastArgs)
   async def get_forecast(args: dict[str, Any]) -> dict[str, Any]:
       hours = args.get("hours", 12)
       return {"content": [{"type": "text", "text": f"{hours}-hour forecast for {args['latitude']}"}]}
   

シンプルなマッピング形式と TypedDict 形式では、型を Annotated[type, "description"] でラップすると、フィールドの説明を設定できます。

戻り値

ツール実装をラップし、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

ツールの動作ヒント。tool() の annotations 引数として渡されます。ToolAnnotations は MCP SDK の mcp.types.ToolAnnotations を maxResultSizeChars フィールドで拡張し、各ヒントを camelCase または snake_case で記述できます：ToolAnnotations(readOnlyHint=True) と ToolAnnotations(read_only_hint=True) は同等です。オブジェクトからヒントを読み取る際は、インストールされている mcp パッケージが宣言している表記を使用してください：mcp 1.x では .readOnlyHint、2.x では .read_only_hint を使用し、.maxResultSizeChars はどちらでも動作します。SDK がアノテーションを受け入れる場所であればどこでも、プレーンな mcp.types.ToolAnnotations を渡すこともできます。

snake_case 名と型付き maxResultSizeChars フィールドには Python Agent SDK 0.2.140 以降が必要です。バージョン 0.1.31 から 0.2.139 は mcp.types.ToolAnnotations を変更なしで再エクスポートします。バージョン 0.1.55 から 0.2.139 では、maxResultSizeChars をキーワード引数として渡すことができます：MCP クラスは追加フィールドを受け入れ、SDK は値を Claude Code に転送します。

すべてのフィールドはオプションです。クライアントはセキュリティ決定のためにこれらのヒントに依存すべきではありません。

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, ClaudeAgentOptions


@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,
    offset: int = 0,
    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 the most recent session
sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    tag_session(sessions[0].session_id, "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)

fork_session()

セッションのトランスクリプトを新しいセッションにコピーし、元のセッションを変更せずに会話を別の方向に進められるようにします。会話の途中の時点から分岐するには、up_to_message_id を渡します。同期的です。

def fork_session(
    session_id: str,
    directory: str | None = None,
    up_to_message_id: str | None = None,
    title: str | None = None,
) -> ForkSessionResult

パラメータ

session_id が新しいセッションの UUID である ForkSessionResult を返します。フォークを続行するには、これを resume として渡します。フォークには元のセッションのファイルチェックポイントが含まれないため、フォーク前に取得したチェックポイントまで巻き戻すことはできません。

fork_session() は次の例外を発生させます：

• ValueError：session_id または up_to_message_id が有効な UUID ではない
• ValueError：セッションにメッセージがない、または up_to_message_id がトランスクリプト内のどのメッセージにも一致しない
• FileNotFoundError：セッションが見つからない

例

最新のセッションを新しいタイトルでフォークし、そのフォークを再開します。元のセッションは独自の履歴を保持します。

from claude_agent_sdk import fork_session, list_sessions

sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    forked = fork_session(sessions[0].session_id, title="Try the OAuth approach")
    print(forked.session_id)  # pass as ClaudeAgentOptions(resume=...) to continue the fork

クラス

ClaudeSDKClient

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

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: PermissionMode) -> 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 get_context_usage(self) -> ContextUsageResponse
    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

メソッド

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

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

import asyncio
from claude_agent_sdk import ClaudeSDKClient


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


asyncio.run(main())

重要： メッセージを反復処理する場合、早期に終了するために 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 でのストリーミング入力

query() はユーザーメッセージ辞書の非同期イテレータも受け入れるため、送信時にプロンプトを組み立てたり、画像などのコンテンツブロックを含めたりできます。Claude Code は最初に生成されたメッセージが到着するとすぐに応答を開始し、イテレータが完了するのを待たず、receive_response() はそのレスポンスを終了する ResultMessage で停止します。Claude が回答する前に読むべきすべてのものを 1 つのメッセージに入れてください。このジェネレータが行うように、各 query() 呼び出しを独自の receive_response() ループとペアにしてください。

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def message_stream():
    """Assemble the prompt at send time and yield it as one user message."""
    readings = {"Temperature": "25°C", "Humidity": "60%"}
    data = ", ".join(f"{name}: {value}" for name, value in readings.items())
    yield {
        "type": "user",
        "message": {
            "role": "user",
            "content": f"Analyze the following sensor data and describe any patterns you see: {data}",
        },
    }


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: terminal_reason={message.terminal_reason!r}")
                # terminal_reason is "aborted_streaming" or "aborted_tools"
                # for interrupted turns

        # 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())

[!NOTE]

割り込み後のバッファ動作： interrupt() は停止信号を送信しますが、メッセージバッファをクリアしません。割り込まれたタスクによって既に生成されたメッセージ（その ResultMessage を含む）はストリームに残ります。新しいクエリの応答を読む前に、receive_response() でそれらをドレインする必要があります。interrupt() の直後に新しいクエリを送信し、receive_response() を 1 回だけ呼び出すと、割り込まれたタスクのメッセージが受け取られ、新しいクエリの応答ではありません。

例 - 高度な権限制御

import asyncio
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():
    # ゲートされたツールを allowed_tools にも列挙しないでください：許可ルールは can_use_tool が実行される前に呼び出しを承認します
    options = ClaudeAgentOptions(can_use_tool=custom_permission_handler)

    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())

型

[!NOTE]

@dataclass と TypedDict の違い： この SDK では 2 種類の型を使用します。@dataclass でデコレートされたクラス（ResultMessage、AgentDefinition、TextBlock など）は実行時にはオブジェクトインスタンスであり、属性アクセス（msg.result）をサポートします。TypedDict で定義されたクラス（ThinkingConfigEnabled、McpStdioServerConfig、SyncHookJSONOutput など）は実行時にはプレーンな dict であり、キーによるアクセスが必要です。config.budget_tokens ではなく config["budget_tokens"] と記述します。ClassName(field=value) の呼び出し構文はどちらでも使用できますが、属性を持つオブジェクトを生成するのは dataclass だけです。

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 プロセスと通信する場合に使用します。

[!WARNING]

これは低レベルの内部 API です。インターフェースは今後のリリースで変更される可能性があります。カスタム実装は、インターフェースの変更に合わせて更新する必要があります。

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 | SystemPromptCustom | SystemPromptFile | 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
    session_id: 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
    forward_subagent_text: bool = False
    verbatim_prompts: bool = False
    fork_session: bool = False
    resume_session_at: str | None = None
    resume_drops_turn: str | None = None
    agents: dict[str, AgentDefinition] | None = None
    setting_sources: list[SettingSource] | None = None
    skills: list[str] | Literal["all"] | 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: EffortLevel | None = None
    enable_file_checkpointing: bool = False
    session_store: SessionStore | None = None
    session_store_flush: SessionStoreFlushMode = "batched"
    load_timeout_ms: int = 60_000
    task_budget: TaskBudget | None = None

遅延または停止した API レスポンスへの対処

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

from claude_agent_sdk import ClaudeAgentOptions

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

• API_TIMEOUT_MS：各リクエストの試行がレスポンスヘッダーを待機できる時間（ミリ秒）。ヘッダーの到着後にストリーミングレスポンスが続く時間は制限しません。デフォルトは 600000 です。メインループとすべてのサブエージェントに適用されます。

• CLAUDE_CODE_MAX_RETRIES：API の最大再試行回数。デフォルトは 10 で、上限は 15 です。各再試行にはそれぞれ独自の API_TIMEOUT_MS の時間枠が適用されます。

  より長い障害を待ち続ける必要がある無人実行では、CLAUDE_CODE_RETRY_WATCHDOG=1 を設定します。これにより、一時的な容量エラーが無期限に再試行され、Claude Code v2.1.199 以降では、その他の一時的なエラーのデフォルトが 300 に引き上げられ、この変数の上限が撤廃されます。

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS：サブエージェント用の停止ウォッチドッグ。ストリームウォッチドッグがオンの間、デフォルトは CLAUDE_STREAM_IDLE_TIMEOUT_MS に 5 分を加えた値で、その変数を引き上げない限り 600000 になります。ストリームウォッチドッグがオフの場合、デフォルトは 600000 です。v2.1.257 より前は、デフォルトは常に 600000 でした。

  タイマーはストリームイベントごとにリセットされます。停止が発生すると、Claude Code はサブエージェントを中止し、停止を親に報告します。バックグラウンドのサブエージェントの場合は、タスクを失敗としてマークし、部分的な結果があればそれを添付します。

• CLAUDE_ENABLE_STREAM_WATCHDOG と CLAUDE_STREAM_IDLE_TIMEOUT_MS：ヘッダーは到着したもののレスポンスボディのストリーミングが停止した場合にリクエストを中止するストリームウォッチドッグ。このウォッチドッグはすべてのプロバイダーでデフォルトでオンになっています。無効にするには CLAUDE_ENABLE_STREAM_WATCHDOG=0 を設定します。CLAUDE_STREAM_IDLE_TIMEOUT_MS のデフォルトは 300000 で、この値が最小値として適用されます。中止後に Claude Code が何を行うかは、レスポンスがどこまで進んでいたかに応じて自動再試行で説明しています。

  ANTHROPIC_BASE_URL の背後にあるゲートウェイがキープアライブの ping でレスポンスを開いたままにしている間、ウォッチドッグがそのレスポンスを待機していると、include_partial_messages を設定しているホストは ping の StreamEvent メッセージを受信し続けます。無応答を理由にセッションをタイムアウトさせるのではなく、これらのフレームを生存確認として扱ってください。v2.1.257 より前は、これらのフレームは最後の実際のストリームイベントから 5 分後に停止していました。

OutputFormat

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

# 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]
    snapshot: NotRequired[bool]

SystemPromptCustom

オブジェクト形式のカスタムシステムプロンプトで、system_prompt に文字列を渡すことと同等ですが、snapshot も設定できます。claude-agent-sdk v0.2.153 以降が必要です。

class SystemPromptCustom(TypedDict):
    type: Literal["custom"]
    prompt: str
    snapshot: NotRequired[bool]

SystemPromptFile

カスタムシステムプロンプトを文字列として渡す代わりに、ファイルから読み込むための設定です。SDK はこれを CLI の --system-prompt-file フラグに対応付けます。プロンプトが大きい場合はファイル形式を使用してください。SDK は文字列の system_prompt を CLI サブプロセスの argv で渡すため、SDK が API リクエストを送信する前に OS のコマンドライン長の制限を受けます。Linux では、約 128 KB を超える単一の引数はプロセスの起動時に Argument list too long で失敗します。Windows ではコマンドライン全体が約 32 KB に制限されるため、文字列形式はより低いしきい値で失敗します。

class SystemPromptFile(TypedDict):
    type: Literal["file"]
    path: str

SettingSource

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

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

デフォルトの動作

setting_sources が省略されているか None で、かつ skills が設定されていない場合、query() は Claude Code CLI と同じファイルシステム設定（ユーザー、プロジェクト、ローカル）を読み込みます。skills が設定されている場合の現在のデフォルトについては、setting_sources の行を参照してください。エンドポイント管理ポリシーはすべての場合に読み込まれます。サーバー管理設定は、対象となる構成でセッションが組織の認証情報で認証されたときに取得されます。詳細については、settingSources が制御しないものを参照してください。

setting_sources を使用する理由

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

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


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


asyncio.run(main())

[!NOTE]

Python SDK 0.1.59 以前では、空のリストはオプションを省略した場合と同じように扱われていたため、setting_sources=[] ではファイルシステム設定が無効になりませんでした。空のリストを有効にする必要がある場合は、新しいリリースにアップグレードしてください。TypeScript SDK は影響を受けません。

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

# Load only project settings, ignore user and local
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Run CI checks",
        options=ClaudeAgentOptions(
            setting_sources=["project"]  # Only .claude/settings.json
        ),
    ):
        print(message)


asyncio.run(main())

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

# Define everything programmatically.
# Pass [] to opt out of filesystem setting sources.
import asyncio
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Review this PR",
        options=ClaudeAgentOptions(
            setting_sources=[],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Reviews code changes",
                    prompt="You are a code reviewer. Report issues in the diff.",
                ),
            },
            allowed_tools=["Read", "Grep", "Glob"],
        ),
    ):
        print(message)


asyncio.run(main())

CLAUDE.md のプロジェクト指示を読み込むには、setting_sources に "project" を含めます。CLAUDE.md の読み込みとシステムプロンプトのオプションがどのように相互作用するかについては、システムプロンプトの変更を参照してください。

設定の優先順位

複数のソースが読み込まれる場合、設定は次の優先順位（高い順）でマージされます。

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

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

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: EffortLevel | int | None = None
    permissionMode: PermissionMode | None = None

[!NOTE]

AgentDefinition のフィールド名には、disallowedTools、permissionMode、maxTurns のように camelCase が使用されます。これらの名前は、TypeScript SDK と共有されるワイヤーフォーマットに直接対応しています。これは、同等のトップレベルフィールドに disallowed_tools や permission_mode のような Python の snake_case を使用する ClaudeAgentOptions とは異なります。AgentDefinition は dataclass であるため、snake_case のキーワードを渡すと、構築時に TypeError が発生します。

PermissionMode

ツールの実行を制御するための権限モードです。

PermissionMode = Literal[
    "default",  # Standard permission behavior
    "acceptEdits",  # Auto-accept file edits
    "plan",  # Planning mode - Claude explores and plans
    "dontAsk",  # Deny anything not pre-approved instead of prompting
    "bypassPermissions",  # Bypass permission checks; explicit ask rules still prompt (use with caution)
    "auto",  # A model classifier reviews actions such as shell commands and network requests
]

EffortLevel

思考の深さを導くための effort レベルです。

EffortLevel = Literal[
    "low",  # Minimal thinking, fastest responses
    "medium",  # Moderate thinking
    "high",  # Deep reasoning
    "xhigh",  # Extended reasoning; falls back to "high" on models that don't support it
    "max",  # Maximum effort
]

CanUseTool

ツールの権限コールバック関数の型エイリアスです。

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

コールバックは次のものを受け取ります。

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

PermissionResult（PermissionResultAllow または PermissionResultDeny のいずれか）を返します。

このコールバックは、対話型の権限プロンプトに代わるものです。SDK は、権限評価フローがプロンプトに至った場合に can_use_tool を呼び出します。次のいずれかの方法で承認された呼び出しは、can_use_tool を呼び出さずに実行されます。

• allowed_tools のエントリまたは設定の許可ルールによって承認された呼び出し
• acceptEdits モードでのファイル編集など、権限モードによって承認された呼び出し

これらの呼び出しを確認するには、これらに対しても実行される PreToolUse フックを使用してください。

許可ルールはどのモードでも自動承認されないアクションを事前承認しません。それらのうちどれがコールバックに到達するか、また dontAsk モードと auto モードで何が起こるかについては、権限の評価方法を参照してください。

ToolPermissionContext

ツールの権限コールバックに渡されるコンテキスト情報です。

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

PermissionResult

権限コールバックの結果のユニオン型です。

PermissionResult = PermissionResultAllow | PermissionResultDeny

PermissionResultAllow

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

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

updated_permissions に 4,096 個を超える項目を含む PermissionResultAllow を返すと、Claude Code はその結果を無効として扱い、ツール呼び出しを拒否します。各 PermissionUpdate は 1 項目としてカウントされ、その rules または directories リスト内の各エントリも同様に 1 項目としてカウントされます。拒否メッセージの末尾は updatedPermissions may hold at most 4096 updates, rules and directories in all. となります。拒否を避けるには、返す項目を 4,096 個以下にしてください。

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 つの設定のユニオンです。

ThinkingDisplay = Literal["summarized", "omitted"]


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


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


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


ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

オプションの display フィールドは、思考テキストを "summarized" と "omitted" のどちらで返すかを制御します。Claude Opus 4.7 以降では API のデフォルトが "omitted" であるため、ThinkingBlock の出力で思考内容を受け取るには "summarized" を設定してください。Claude Code は、Amazon Bedrock や Google Cloud の Agent Platform などの一部のプロバイダーには display の値を渡しません。それらのプロバイダーでは、display を "summarized" に設定した場合でも、Opus 4.7 以降は空の ThinkingBlock 出力を返します。

これらは 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

TaskBudget

API 側のタスク予算（トークン単位）で、ClaudeAgentOptions の task_budget フィールドで使用します。

class TaskBudget(TypedDict):
    total: int

これは TypedDict であるため、ClaudeAgentOptions(task_budget={"total": 50000}) のようにプレーンな dict として渡します。

SdkBeta

SDK のベータ機能のリテラル型です。

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

ベータ機能を有効にするには、ClaudeAgentOptions の betas フィールドとともに使用します。

[!WARNING]

Claude API では、context-1m-2025-08-07 ベータは Claude Sonnet 4.5 と Claude Sonnet 4 で提供終了しています。いずれかのモデルでこれをまだ渡している場合、標準の 200K トークンのコンテキストウィンドウを超えるリクエストはエラーを返すため、betas から削除してください。1M トークンのコンテキストウィンドウでセッションを実行するには、model を claude-sonnet-5-5 や claude-opus-5-5 などのデフォルトで 1M のウィンドウで実行されるモデルに設定します。[1m] バリアントでのみ 1M に達するモデルの場合は、claude-opus-4-6[1m] のようにモデル ID にサフィックスを付加します。

McpSdkServerConfig

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

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

McpServerConfig

MCP サーバー設定のユニオン型です。

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 バリアントを加えたユニオンです。

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]]

ContextUsageResponse

ClaudeSDKClient.get_context_usage() からのレスポンスです。このレスポンスには、対話型セッションで Claude Code が /context コマンドのために表示するペイロードが含まれます。このペイロードには、トークン数に加えて、Claude Code が /context の使用状況グリッドを描画するために使用する color や gridRows などの表示用フィールドも含まれます。

Claude Code は、トークンカウント API に複数のリクエストを送信してこのペイロードを構築します。これらのリクエストはメッセージストリームに表示されないため、ストリームを読み取るコスト追跡ではそれらを把握できません。Anthropic API では、トークンカウントは課金されません。

class ContextUsageResponse(TypedDict):
    categories: list[ContextUsageCategory]
    totalTokens: int
    maxTokens: int
    rawMaxTokens: int
    percentage: float
    model: str
    isAutoCompactEnabled: bool
    memoryFiles: list[dict[str, Any]]
    mcpTools: list[dict[str, Any]]
    agents: list[dict[str, Any]]
    gridRows: list[list[dict[str, Any]]]
    autoCompactThreshold: NotRequired[int]
    deferredBuiltinTools: NotRequired[list[dict[str, Any]]]
    systemTools: NotRequired[list[dict[str, Any]]]
    systemPromptSections: NotRequired[list[dict[str, Any]]]
    slashCommands: NotRequired[dict[str, Any]]
    skills: NotRequired[dict[str, Any]]  # skill usage with frontmatter breakdown
    messageBreakdown: NotRequired[dict[str, Any]]  # message tokens by type
    apiUsage: NotRequired[dict[str, Any] | None]

各 ContextUsageCategory エントリは、name、tokens、color、およびオプションの isDeferred フラグを持ちます。totalTokens はセッションの現在のコンテキスト使用量で、maxTokens はその使用量を測定する基準となるウィンドウです。このウィンドウはモデルのコンテキストウィンドウ、または自動圧縮のウィンドウが適用される場合はそのより小さいウィンドウであり、rawMaxTokens は maxTokens と同じ値を持ちます。apiUsage は最新の API レスポンスからの使用量を保持するもので、セッションの累計ではありません。Claude Code はオプションの deferredBuiltinTools、systemTools、systemPromptSections のキーを設定しないため、型で宣言されていてもこれらは存在しないものと想定してください。

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
    | ConversationResetMessage
)

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
    origin: MessageOrigin | None = None

SDK は tool_use_result を CLI から変更されずに渡します。結果に resource_link ブロックを含む外部 MCP サーバー上のツールの場合、dict は TypeScript SDKMcpResourceLink 型のキーを持つ dict のリストを保持する resourceLinks キーを持ちます。Claude は各リンクをツール結果内のテキスト行として受け取ります。サーバーが返したファイルをレンダリングするには、そのテキストを解析する代わりに resourceLinks を読み取ってください。resourceLinks キーには Python Agent SDK 0.2.150 以降と Claude Code v2.1.257 以降が必要です。そのバージョンの SDK にバンドルされている CLI は Claude Code の要件を満たしています。

CLI は結果にリンクがない場合と、サブエージェントからの結果の場合、キーを省略します。CLI は結果ごとに最大 50 個のリンクを保持し、リストがシリアル化された JSON の 64 KiB に達するとリンクの追加を停止します。tool() で定義したプロセス内ツールは、SDK がその resource_link ブロックを CLI が結果を見る前にテキストにフラット化するため、キーを生成しません。

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
    stop_reason: str | None = None
    session_id: str | None = None
    uuid: str | None = None

AssistantMessageError

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

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

基になる CLI プロセスは、max_output_tokens などの Literal にリストされていないエラータイプを発行できます。SDK は値を変更されずに渡すため、このリストの外の文字列を unknown と同じ方法で扱ってください。TypeScript SDKAssistantMessageError 型は、CLI が発行できる値の完全なセットをリストしています。

SystemMessage

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

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

独自のデータクラスを持たないサブタイプは SystemMessage として届きます。ターン間のセッションを追跡するには、CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1 を設定し、subtype が session_state_changed である各メッセージで message.data["state"] を読み取ってください。SDKSessionStateChangedMessage には、このメッセージが保持できる状態がリストされています。これらを読み取るには receive_messages() で反復処理してください。receive_response() は ResultMessage で停止し、session_state_changed メッセージはその結果の後に続く場合があるためです。

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, ModelUsage] | 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
    terminal_reason: str | None = None
    origin: MessageOrigin | None = None

subtype フィールドは、他のどのフィールドが入力されるかを決定します。これは "success"、"error_during_execution"、"error_max_turns"、"error_max_budget_usd"、または "error_max_structured_output_retries" のいずれかです。Python データクラスはすべてのバリアントを 1 つの形状にフラット化するため、返された subtype に適用されないフィールドは None です。

会話がどのように終了したかについての診断詳細を含むいくつかのフィールド：

• is_error：会話がエラー状態で終了した場合は True。error_* サブタイプでは常に True。subtype="success" では、3 つのケースで True になります。それらを区別するには stop_reason を確認してください：
  • "refusal"：モデルが応答を拒否しました。拒否のテキストは result で、result が空の場合は直前の AssistantMessage で確認してください。
  • "tool_deferred_unavailable"：セッションを再開したときに、遅延されたツール が利用できなくなっていました。たとえば、その MCP サーバーが接続されていなかった場合です。以下の 2 つのケースでは、再開後に送信したプロンプトは、再開時に渡したプロンプトと同じ扱いになります：
    • プロンプトなし：呼び出しはまだ保留中です。ツールを利用可能にしてからプロンプトなしで再度再開すると、その呼び出しが最初に実行されます。
    • プロンプトあり：Claude Code はツールの結果なしでプロンプトに応答し、遅延された呼び出しは破棄されます。引き続きツールの呼び出しが必要な場合は、新しいプロンプトを送信してください。
  • その他の値：API エラーなど、Claude Code がモデルの応答の代わりに報告したエラーでターンが終了しました。原因は terminal_reason で、メッセージは result で、API が HTTP ステータスを返した場合はそのステータスを api_error_status で確認してください。
• api_error_status：終了する API エラーの HTTP ステータスコード。ターンがエラーなしで終了した場合は None。subtype="success" でのみ入力されます。
• result：subtype="success" での最終アシスタントメッセージのテキスト、または error_* サブタイプでは None。subtype="success" で is_error=True の場合、これは利用可能な場合は API エラー文字列を保持しますが、空の場合もあるため、api_error_status と前の AssistantMessage コンテンツで詳細を確認してください。
• errors：最大ターンメッセージなどのループレベルのエラー文字列。error_* サブタイプでのみ入力されます。
• terminal_reason：クエリループが終了した理由。例："completed"、"max_turns"、"api_error"、"aborted_streaming"、または "aborted_tools"。"aborted_streaming" または "aborted_tools" の値は、ターンが完了する前に中止されたことを意味します。一般的な原因は interrupt() と、interrupt=True で PermissionResultDeny を返すパーミッション コールバックです。CLI バージョンがフィールドより前の場合、/voice や /usage などのローカルコマンドの結果（クエリループをバイパス）、またはセッションが致命的に失敗したときに発行される合成エラー結果の場合は None。TypeScript SDK の SDKResultMessage.terminal_reason を反映しており、値の完全なセットをリストしています。
• origin：このターンをトリガーしたユーザーメッセージの出所。ストリーミング入力モード では、これをチェックして、origin が None または {"kind": "human"} である独自のプロンプトの結果と、バックグラウンドタスク通知などの注入されたターンの結果を区別します。Python Agent SDK 0.2.137 以降が必要です。

複数のバックグラウンドタスクが近いタイミングで終了した場合、Claude Code はそれらの通知にそれぞれ 1 ターンずつではなく、1 つのターンでまとめて応答することがあります。その場合でも、通知ごとに 1 つの ResultMessage が順番に届き、それぞれの origin の kind は "task-notification" です。最後のもの以外は num_turns が 0 に設定され、result は空になります。最後のものが、すべての通知に応答したターンを保持します。

usage dict はメインエージェントループのみをカバーし、サブエージェントおよび他のネストされた、または補助的なモデル呼び出しを除外します。ストリーミング入力モード では、値はターンごとです。トークンとコストのアカウンティングについては model_usage を優先してください。usage dict は、存在する場合、以下のキーを含みます：

model_usage dict はモデル名をモデルごとの使用状況にマップします。クエリパイプラインを通じて行われたすべてのモデル呼び出しをカバーします：メインループ、サブエージェント、および圧縮と Workflow エージェントなどの内部呼び出し。パーミッション分類器とトークンカウントリクエストなどのそのパイプラインの外のヘルパー呼び出しは、model_usage から除外されます。model_usage を推定値として扱い、請求書ではなく。

ストリーミング入力モード では、model_usage と total_cost_usd はターン全体で累積されるため、結果全体で合計するのではなく、最新の結果を読み取ってください。セッションの以前の呼び出しから復元された 合計を蓄積 も、呼び出しがセッションを再開する場合にカウントされます。リセットについては ストリーミング入力モードでコストを追跡 を、ゼロ化された結果については セッションクラッシュ後に合計を復旧 を参照してください。

model_usage の各値は ModelUsage TypedDict で、from claude_agent_sdk.types import ModelUsage でインポートされます。そのキーは 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)

ConversationResetMessage

会話が接続を終了せずに置き換えられたときに発行されます。例：/clear の後。リセットが後の ResultMessage オブジェクトの実行中の合計にどのように影響するかについては、ストリーミング入力モードでコストを追跡 を参照してください。Python Agent SDK 0.2.137 以降が必要です。

@dataclass
class ConversationResetMessage:
    new_conversation_id: str
    uuid: str
    session_id: str

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

CLI が 長い MCP ツール呼び出しをバックグラウンドに移動 する場合、その呼び出しのツール結果はプレースホルダーのみを保持し、呼び出しの実際の結果はこのメッセージに到着します。そのような呼び出しの "completed" 通知では、CLI は、ツールが参照によって返したファイルをリストする resource_links キーを追加します。UserMessage.tool_use_result の resourceLinks キーと同じエントリと制限があります。resource_links キーには Python Agent SDK 0.2.150 以降と Claude Code v2.1.257 以降が必要です。そのバージョンの SDK にバンドルされている CLI は Claude Code の要件を満たしています。

データクラスには resource_links のフィールドがありません。メッセージが SystemMessage から継承する data dict から読み取ってください：message.data.get("resource_links")。通知を tool_use_id で呼び出しと一致させてください。CLI は結果にリンクがない場合と、MCP ツール呼び出しではないタスクの通知の場合、キーを省略します。

コンテンツブロック型

ContentBlock

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

ContentBlock = (
    TextBlock
    | ThinkingBlock
    | ToolUseBlock
    | ToolResultBlock
    | ServerToolUseBlock
    | ServerToolResultBlock
)

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."""

単一ショットの query() がエラー結果で終了した場合（例えば、ターン制限エラー）、SDK は ResultError を発生させます。

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

ResultError

ターン制限エラーや API エラーなど、実行がエラーの結果メッセージで終了したために Claude Code プロセスが終了した場合に発生します。ResultError は ProcessError のサブクラスであるため、既存の except ProcessError ハンドラーもこれをキャッチします。その属性はその結果メッセージのフィールドを保持しているため、メッセージテキストを解析することなく、実行が失敗した理由に基づいて分岐できます。Python Agent SDK 0.2.140 以降が必要です。

class ResultError(ProcessError):
    subtype: str | None  # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request
    errors: list[str]  # an empty list when the result message reported none
    result: str | None
    api_error_status: int | None
    terminal_reason: str | None  # "max_turns", "api_error", ...; check after data["stop_reason"], before subtype
    session_id: str | None
    data: dict[str, Any]  # the raw result message payload

失敗を区別するには、まず data["stop_reason"] を確認し、次に terminal_reason、最後に subtype を確認してください。拒否された応答は stop_reason が "refusal" で、通常は subtype が "success" です。この場合の terminal_reason では拒否を判別できず、"completed" または "api_error" となることがあります。最終リクエストが失敗した場合、subtype は "success" となり、原因は terminal_reason に記載されます（API エラーの場合は "api_error" など）。max_turns や max_budget_usd など、設定した制限に実行が達した場合は、error_* サブタイプが返されます。

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 a prompt is submitted
    "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
]

[!NOTE]

TypeScript SDK は、Python ではまだ利用できない追加の hook イベントをサポートしています。SDK ごとのサポートについては、hook 利用可能性テーブル を参照してください。

HookCallback

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

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

パラメータ：

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

HookJSONOutput を返します。

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. When omitted, the per-event default applies:
        # 600 for most events, 30 for UserPromptSubmit
    )
    on_failure: Literal["continue", "block"] | None = (
        None  # "block" blocks the action when a callback fails
    )

on_failure の対象範囲を判断するには、コールバックが失敗したときにアクションをブロックする を参照してください。

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]]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

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]

[!NOTE]

Python コードで continue_（アンダースコア付き）を使用してください。CLI に送信されるときに自動的に continue に変換されます。

HookSpecificOutput

イベント固有の TypedDict 出力型の判別 union。hookEventName フィールドはどのフィールドが有効かを決定します。hook イベントごとに利用可能なフィールドの詳細については、hooks で実行を制御 を参照してください。

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]  # MCP tools only. Prefer updatedToolOutput, which works for all tools


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

[!NOTE]

Python コードで async_（アンダースコア付き）を使用してください。CLI に送信されるときに自動的に async に変換されます。

Hook 使用例

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

import asyncio
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 (per-event default timeout)
        ],
        "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
    }
)

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


asyncio.run(main())

ツール入出力型

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

各出力は、そのツールの UserMessage.tool_use_result から読み込む値です。キー名は Claude Code が発行する通りに表示されます。「存在する場合」または「オプション」というコメント付きで | None と注釈が付けられたキーは、適用されない場合は省略されます。

Agent

ツール名： Agent。このツールがセッションで利用可能な場合、以前の名前 Task はまだエイリアスとして受け入れられます。

初期化時の SystemMessage 内の tools リストは、後方互換性のためこのツールを Task として報告します。

入力：

{
    "description": str,  # タスクの短い説明（3～5 語）
    "prompt": str,  # エージェントが実行するタスク
    "subagent_type": str | None,  # 使用する特化したエージェントのタイプ
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # このエージェントのモデルの上書き
    "effort": "low" | "medium" | "high" | "xhigh" | "max" | None,  # このエージェントの推論エフォート
    "run_in_background": bool | None,  # 省略時のデフォルト：メインエージェントの呼び出しでは新しいエージェントがバックグラウンドで実行され、サブエージェントの呼び出しではその完了を待ちます
    "name": str | None,  # スポーンされたエージェントの名前
    "team_name": str | None,  # 非推奨。無視されます
    "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None,  # 非推奨。無視されます。サブエージェント継承ルールがサブエージェントの権限モードを決定します
    "isolation": "worktree" | "remote" | None,  # エージェントの変更の分離モード
}

複雑なマルチステップタスクを自律的に処理するための新しいエージェントを起動します。

Claude が Agent 呼び出しで run_in_background を省略した場合、デフォルトではメインエージェントは新しいエージェントを待たず、サブエージェントは待ちます。

• メインエージェントから：新しいエージェントはバックグラウンドで実行され、結果は status: "async_launched" になります。代わりにメインエージェントが新しいエージェントを待つようにするには、Claude がサブエージェントを待つかどうかを選択する を参照してください。
• サブエージェントのいずれかから：呼び出し元のサブエージェントは 新しいエージェントを待ちます。新しいエージェントの定義で background が True に設定されている場合、または CLAUDE_CODE_FORK_SUBAGENT を 0 に設定して フォークモードをオフにした 場合は、代わりに新しいエージェントがバックグラウンドで実行されます。

Python SDK v0.2.169 より前では、サブエージェントが開始したエージェントもデフォルトでバックグラウンドで実行されていました。このリリースは、Claude Code v2.1.302 以降をバンドルする最初のリリースです。

出力（ステータス："completed"）：

{
    "status": "completed",
    "agentId": str,  # 実行されたエージェントの ID
    "agentType": str | None,  # タスクを処理したサブエージェントタイプ
    "content": [  # 結果コンテンツブロック
        {
            "type": "text",
            "text": str,
            "citations": list | None,
        }
    ],
    "resolvedModel": str | None,  # サブエージェントが開始したモデル
    "modelsUsed": list[str] | None,  # 使用されたモデルの順序。連続する繰り返しは折りたたまれます
    "totalToolUseCount": int,  # エージェントが実行したツール呼び出しの数
    "totalDurationMs": int,  # 実行時間（ミリ秒）
    "totalTokens": int,  # 最終 API リクエストからのトークン数。実行全体ではありません
    "usage": {  # トークン使用統計
        "input_tokens": int,
        "output_tokens": int,
        "cache_creation_input_tokens": int | None,
        "cache_read_input_tokens": int | None,
        "server_tool_use": {"web_search_requests": int, "web_fetch_requests": int} | None,
        "service_tier": str | None,
        "cache_creation": {"ephemeral_1h_input_tokens": int, "ephemeral_5m_input_tokens": int} | None,
        "inference_geo": str | None,
        "speed": str | None,
        "iterations": Any | None,
        "output_tokens_details": {"thinking_tokens": int | None} | None,
        "fallback_credit": Any | None,
    },
    "toolStats": {  # 実行のための集計ツール活動
        "readCount": int,
        "searchCount": int,
        "bashCount": int,
        "editFileCount": int,
        "linesAdded": int,
        "linesRemoved": int,
        "otherToolCount": int,
        "frameCount": int | None,
    } | None,
    "prompt": str,  # エージェントが実行したプロンプト
    "worktreePath": str | None,  # Claude Code がサブエージェントの worktree を保持した場合に存在
    "worktreeBranch": str | None,  # Claude Code がその worktree を git で作成した場合に存在
}

出力（ステータス："async_launched"）：

{
    "status": "async_launched",
    "isAsync": bool | None,  # バックグラウンド起動時は True
    "agentId": str,  # 起動されたエージェントの ID
    "description": str,  # タスクの説明
    "resolvedModel": str | None,  # バックグラウンド化の遷移時に使用中のモデル
    "modelsUsed": list[str] | None,  # バックグラウンド化前に使用されたモデル。順序で、連続する繰り返しは折りたたまれます
    "prompt": str,  # エージェントが実行するプロンプト
    "outputFile": str,  # エージェントの出力が書き込まれるファイルパス
    "canReadOutputFile": bool | None,  # 出力ファイルを直接読み込めるかどうか
}

出力（ステータス："remote_launched"）：

{
    "status": "remote_launched",
    "taskId": str,  # ディスパッチされたタスクの ID
    "sessionUrl": str,  # クラウドセッションへのリンク
    "description": str,  # タスクの説明
    "prompt": str,  # エージェントが実行するプロンプト
    "outputFile": str,  # エージェントの出力が書き込まれるファイルパス
}

サブエージェントからの結果を返します。出力は status フィールドで判別されます。完了したタスクの場合は "completed"、バックグラウンドタスクの場合は "async_launched"、Claude Code がクラウドセッションにディスパッチしたタスクの場合は "remote_launched"。sessionUrl はそのセッションにリンクし、taskId がそれを識別します。Claude Code が サブエージェントの分離 worktree を保持した 場合、completed バリアントの worktreePath はそれを見つける場所であり、worktreeBranch は Claude Code が git で worktree を作成した場合のそのブランチです。

completed バリアントでは、resolvedModel はサブエージェントが開始したモデルを名付けます。これは availableModels または別の上書きが適用される場合、リクエストされた model 入力と異なる場合があります。このフィールドには Claude Code v2.1.174 以降が必要です。async_launched バリアントでは、resolvedModel はエージェントがバックグラウンドに移動したときに使用中のモデルを名付けるため、バックグラウンド化前に発生したスワップがそこに反映されます。両方のバリアントの modelsUsed フィールドは、使用されたモデルを順序で列挙し、連続する繰り返しは折りたたまれます。モデルが実行中にスワップされた場合にのみ設定されます。modelsUsed とバックグラウンド化時の resolvedModel 動作には Claude Code v2.1.212 以降が必要です。

Claude Code は usage と totalTokens をサブエージェントの最終 API リクエストから入力します。実行全体からではありません。存在する場合、usage 内の output_tokens_details の下の thinking_tokens はそのリクエストの出力トークンのうち思考トークンであった数です。output_tokens_details キーには Python SDK v0.2.136 以降が必要です。これは Claude Code v2.1.228 をバンドルしています。fallback_credit キーには Python SDK v0.2.162 以降が必要です。これは Claude Code v2.1.285 をバンドルしています。

AskUserQuestion

ツール名： AskUserQuestion

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

入力：

{
    "questions": [  # ユーザーに質問する質問（1～4 個の質問）
        {
            "question": str,  # ユーザーに質問する完全な質問
            "header": str,  # チップ/タグとして表示される非常に短いラベル（最大 12 文字）
            "options": [  # 利用可能な選択肢（2～4 個のオプション）
                {
                    "label": str,  # このオプションの表示テキスト（1～5 語）
                    "description": str,  # このオプションが何を意味するかの説明
                    "preview": str | None,  # オプションがフォーカスされたときにレンダリングされるプレビューコンテンツ
                }
            ],
            "multiSelect": bool,  # 複数選択を許可する場合は true に設定
        }
    ],
    "answers": dict[str, str] | None,
    # 権限システムによって入力されたユーザーの回答。マルチセレクト
    # 回答は選択されたラベルのカンマ区切り文字列です。入力時はラベルのリストが受け入れられ、その形式に強制されます
    "annotations": dict[str, dict] | None,
    # 質問テキストでキーされたユーザーからの質問ごとのアノテーション。
    # 各値は「preview」（選択されたオプションのプレビュー
    # コンテンツ）と「notes」（選択に関する自由形式のメモ）を含むことができます
    "metadata": dict | None,  # {"source": "remember"} などの分析メタデータ。ユーザーには表示されません
}

出力：

{
    "questions": [  # 質問された質問
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str, "preview": str | None}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # 質問テキストを回答文字列にマップ
    # マルチセレクト回答はカンマ区切り
    "response": str | None,
    # 質問に答える代わりに入力された自由形式の返信。設定されている場合、
    # Claude は回答リストの代わりに「ユーザーが応答しました：...」を受け取ります
    "annotations": dict[str, dict] | None,  # ユーザーの選択からの質問ごとの「preview」と「notes」
    "afkTimeoutMs": int | None,  # ユーザーの非アクティブ状態がこれだけミリ秒続いた後にダイアログが自動解決されたときに設定。ユーザーが回答したときは存在しません
}

Bash

ツール名： Bash

フォアグラウンドの上限については、タイムアウトと出力制限 を参照してください。バックグラウンド時間制限については、バックグラウンドコマンドの時間制限 を参照してください。

入力：

{
    "command": str,  # 実行するコマンド
    "timeout": int | None,  # ミリ秒。フォアグラウンド：デフォルトで 600000 でキャップされ、より高い値はクランプされます。run_in_background を使用する場合（Claude Code v2.1.285 以降）：バックグラウンド時間制限。省略時は 1800000、上限は 7200000（引き上げない限り）
    "description": str | None,  # 明確で簡潔な説明（5～10 語）
    "run_in_background": bool | None,  # バックグラウンドで実行する場合は true に設定
}

出力：

{
    "stdout": str,  # コマンドの出力。stdout と stderr はこの 1 つのインターリーブされたストリームにマージされて到着
    "stderr": str,  # ツール自体が追加する通知。コマンドの stderr ではありません
    "interrupted": bool,  # コマンドが中断されたかどうか
    "isImage": bool | None,  # stdout に画像データが含まれているかどうか
    "backgroundTaskId": str | None,  # コマンドがバックグラウンドで実行されている場合のバックグラウンドタスクの ID
}

Monitor

ツール名： Monitor

バックグラウンドソースを実行し、各イベントを Claude に配信して、ポーリングなしで反応できるようにします。command はスクリプトを実行し、stdout 行ごとに 1 つのイベントを発行し、ws は WebSocket を開き、テキストフレームごとに 1 つのイベントを発行します。command または ws のいずれか 1 つを正確に指定してください。

Monitor がコマンドを実行する場合、Bash と同じ権限ルールに従います。WebSocket ウォッチは別途承認を求めます。ws ソースには Claude Code v2.1.195 以降が必要です。動作とプロバイダーの可用性については、Monitor ツールリファレンス を参照してください。

入力：

{
    "command": str | None,  # シェルスクリプト。各 stdout 行はイベント、終了はウォッチを終了
    "ws": dict | None,  # WebSocket ソース：{"url": str, "protocols": list[str] | None}。各テキストフレームはイベント
    "description": str,  # 通知に表示される短い説明
    "timeout_ms": int | None,  # 期限（ミリ秒）（デフォルト 300000、最大 3600000。有効な期限は最大 1800000）
}

出力：

{
    "taskId": str,  # バックグラウンド監視タスクの ID
    "timeoutMs": int,  # ウォッチの有効な期限（ミリ秒）
    "persistent": bool | None,  # False：すべてのウォッチに期限があります
}

Edit

ツール名： Edit

入力：

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

出力：

{
    "filePath": str,  # 編集されたファイル
    "oldString": str,  # 置換されたテキスト
    "newString": str,  # それを置換したテキスト
    "originalFile": str | None,  # 編集前のファイルコンテンツ
    "structuredPatch": [  # 変更の差分ハンク
        {
            "oldStart": int,
            "oldLines": int,
            "newStart": int,
            "newLines": int,
            "lines": list[str],
        }
    ],
    "userModified": bool,  # ユーザーが提案された編集を受け入れる前に変更したかどうか
    "replaceAll": bool,  # すべての出現が置換されたかどうか
    "gitDiff": {  # ファイルのオプションの git 差分サマリー
        "filename": str,
        "status": "modified" | "added",
        "additions": int,
        "deletions": int,
        "changes": int,
        "patch": str,
        "repository": str | None,  # 利用可能な場合は GitHub owner/repo
    } | None,
}

Read

ツール名： Read

入力：

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

出力は Claude が読み込んだ内容に応じて、以下の形状のいずれかを取ります。type キーをチェックして区別してください。

出力（type："text"）：

{
    "type": "text",
    "file": {
        "filePath": str,  # 読み込まれたファイル
        "content": str,  # 返されたコンテンツ
        "numLines": int,  # 返されたコンテンツの行数
        "startLine": int,  # コンテンツが開始する行番号
        "totalLines": int,  # ファイルの総行数
        "truncatedByTokenCap": bool | None,  # 全ファイル読み込みがトークン上限を超えた場合に存在し True。コンテンツは最初のページ
    },
}

出力（type："image"）：

{
    "type": "image",
    "file": {
        "base64": str,  # Base64 エンコードされた画像データ
        "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp",  # 画像 MIME タイプ
        "originalSize": int,  # 元のファイルサイズ（バイト）
        "dimensions": {  # 座標マッピング用のオプションのサイジング情報
            "originalWidth": int | None,  # オプション。元の幅（ピクセル）
            "originalHeight": int | None,  # オプション。元の高さ（ピクセル）
            "displayWidth": int | None,  # オプション。リサイズ後の幅
            "displayHeight": int | None,  # オプション。リサイズ後の高さ
        } | None,
    },
}

出力（type："notebook"）：

{
    "type": "notebook",
    "file": {
        "filePath": str,  # 読み込まれたノートブック
        "cells": list,  # ノートブックセル
    },
}

出力（type："pdf"）：

{
    "type": "pdf",
    "file": {
        "filePath": str,  # 読み込まれた PDF
        "base64": str,  # Base64 エンコードされた PDF データ
        "originalSize": int,  # ファイルサイズ（バイト）
    },
}

出力（type："parts"）：

{
    "type": "parts",
    "file": {
        "filePath": str,  # 読み込まれた PDF
        "originalSize": int,  # ファイルサイズ（バイト）
        "count": int,  # 画像として抽出されたページ数
        "outputDir": str,  # 抽出されたページ画像を含むディレクトリ
    },
    "firstPage": int | None,  # オプション。最初に抽出されたページのドキュメントページ番号
}

出力（type："file_unchanged"）：

{
    "type": "file_unchanged",  # ファイルはこのセッションで Claude が最後に読み込んだ以降変更されていないため、コンテンツは繰り返されません
    "file": {
        "filePath": str,
    },
    "source": "seeded" | None,  # 以前のコピーが起動時に読み込まれた CLAUDE.md またはメモリファイルから来た場合に存在
}

Write

ツール名： Write

入力：

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

出力：

{
    "type": "create" | "update",  # 書き込みが新しいファイルを作成したか、既存のファイルを上書きしたか
    "filePath": str,  # 書き込まれたファイル
    "content": str,  # 書き込まれたコンテンツ
    "structuredPatch": [  # 差分ハンク。新しいファイル、何も変更されなかった場合、または Claude Code が差分をスキップした場合は空
        {
            "oldStart": int,
            "oldLines": int,
            "newStart": int,
            "newLines": int,
            "lines": list[str],
        }
    ],
    "originalFile": str | None,  # 以前のコンテンツ。新しいファイルの場合または以前のコンテンツが大きすぎて含められない場合は None
    "gitDiff": {  # ファイルのオプションの git 差分サマリー
        "filename": str,
        "status": "modified" | "added",
        "additions": int,
        "deletions": int,
        "changes": int,
        "patch": str,
        "repository": str | None,  # 利用可能な場合は GitHub owner/repo
    } | None,
    "userModified": bool | None,  # オプション。ユーザーが受け入れる前に提案されたコンテンツを編集したかどうか
}

Glob

ツール名： Glob

入力：

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

出力：

{
    "durationMs": int,  # 検索の実行に要した時間（ミリ秒）
    "numFiles": int,  # 返されたパスの数。切り詰め後
    "filenames": list[str],  # マッチしたファイルパス
    "truncated": bool,  # 結果が 100 ファイルの上限で切り詰められたかどうか
    "totalMatches": int | None,  # オプション。切り詰め前のマッチするファイルの総数。countIsComplete が False の場合は下限
    "countIsComplete": bool | None,  # オプション。totalMatches が正確かどうか
}

totalMatches と countIsComplete には Claude Code v2.1.191 以降が必要です。

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,  # 前後に表示する行
    "context": int | None,  # 前後に表示する行。-C はエイリアス
    "-o": bool | None,  # 各行のマッチした部分のみを出力
    "head_limit": int | None,  # 出力を最初の N 行/エントリに制限
    "offset": int | None,  # head_limit を適用する前に最初の N 行/エントリをスキップ
    "multiline": bool | None,  # マルチラインモードを有効化
}

出力：

{
    "mode": "content" | "files_with_matches" | "count" | None,  # 使用された出力モード
    "numFiles": int,  # 結果内のファイル数。content モードでは常に 0
    "filenames": list[str],  # files_with_matches モードのマッチするファイル。他のモードでは空
    "content": str | None,  # content モードのマッチする行、または count モードのファイルごとのカウント
    "numLines": int | None,  # コンテンツ内の行数。content モードに存在
    "numMatches": int | None,  # 総マッチ数。count モードに存在
    "totalFiles": int | None,  # オプション。files_with_matches モードで head_limit と offset の前の総数
    "totalLines": int | None,  # オプション。content モードで head_limit と offset の前の総数
    "appliedLimit": int | None,  # head_limit が結果を切り詰めた場合に存在
    "appliedOffset": int | None,  # オフセットが適用された場合に存在
}

Grep は各出力モードでこの dict 形状を返します。どのオプションキーが存在するかは output_mode に依存します。

totalFiles には Claude Code v2.1.208 以降が必要です。totalLines には Claude Code v2.1.210 以降が必要です。

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,  # 編集操作のタイプ
}

出力：

{
    "new_source": str,  # セルに書き込まれたソース
    "old_source": str | None,  # 以前のセルソース。replace と delete に存在
    "cell_id": str | None,  # 編集されたセルの ID。利用可能な場合
    "cell_type": "code" | "markdown",  # セルタイプ
    "language": str,  # ノートブックのプログラミング言語
    "edit_mode": str,  # 使用された編集モード
    "error": str | None,  # 操作が失敗した場合のエラーメッセージ
    "notebook_path": str,  # ノートブックファイル
    "original_file": str,  # 編集前のノートブックコンテンツ
    "updated_file": str,  # 編集後のノートブックコンテンツ
}

WebFetch

ツール名： WebFetch

入力：

{
    "url": str,  # コンテンツを取得する URL
    "prompt": str,  # 取得したコンテンツで実行するプロンプト
    "offset": int | None,  # ページの先頭からスキップする文字数。Python Agent SDK 0.2.164 以降が必要
}

出力：

{
    "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

[!NOTE]

以下のツールは、デフォルトでは Claude Opus 4.7、Claude Sonnet 4.6、Claude Haiku 4.5、およびそれ以前のモデルでのみ利用可能です。その他のすべてのモデル（Claude Code が認識しないモデル ID を含む）では、オプトインしない限り利用できません。

• TodoWrite
• TaskCreate
• TaskGet
• TaskUpdate
• TaskList

ツールが利用可能な場所では、Claude Code は 4 つの Task ツールを提供します。CLAUDE_CODE_ENABLE_TASKS=0 を設定した場合は、代わりに TodoWrite を提供します。

このデフォルトセットは Claude Code v2.1.268 以降に適用されます。これは TypeScript Agent SDK が v0.3.268 からバンドルしています。

モデルの可用性 を参照してオプトインしてください。

入力：

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

出力：

{
    "oldTodos": [  # 更新前の todo リスト
        {
            "content": str,
            "status": "pending" | "in_progress" | "completed",
            "activeForm": str,
        }
    ],
    "newTodos": [  # 更新後の todo リスト
        {
            "content": str,
            "status": "pending" | "in_progress" | "completed",
            "activeForm": str,
        }
    ],
}

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],
        }
    ],
}

TaskOutput

Claude Code v2.1.277 で削除されました。以前は実行中または完了したバックグラウンドタスクから出力を取得し、BashOutput はエイリアスとして受け入れられていました。Claude はバックグラウンドタスクの出力ファイルを Read で読み込みます。

disallowed_tools エントリまたはいずれかの名前をまだ指定している拒否ルールは、警告なしに無視されます。

TaskStop

ツール名： TaskStop。以前の名前 KillShell と KillBash は、権限ルール、フックの matcher、および tools、allowed_tools、disallowed_tools オプションで引き続き使用できます。

入力：

{
    "task_id": str | None,  # 停止するバックグラウンドタスクの ID
    "shell_id": str | None,  # 非推奨：代わりに task_id を使用してください
}

出力：

{
    "message": str,  # 操作に関するステータスメッセージ
    "task_id": str,  # 停止されたタスクの ID
    "task_type": str,  # 停止されたタスクのタイプ
    "command": str | None,  # 停止されたタスクのコマンドまたは説明
}

ExitPlanMode

ツール名： ExitPlanMode

入力：

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

出力：

{
    "plan": str | None,  # ユーザーに提示されたプラン
    "isAgent": bool,  # サブエージェントがツールを呼び出した場合は True
    "filePath": str | None,  # プランがファイルに保存された場合に存在
    "hasTaskTool": bool | None,  # オプション。現在のコンテキストで Agent ツールが利用可能かどうか
    "planWasEdited": bool | None,  # ユーザーが承認する前にプランを編集した場合に存在し True
    "awaitingLeaderApproval": bool | None,  # チームメイトがプランをチームリーダーに承認を求めて送信した場合に存在し True
    "requestId": str | None,  # その承認リクエストのオプション ID
}

ListMcpResources

ツール名： ListMcpResourcesTool

入力：

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

結果は dict ではなくリストであるため、tool_use_result はこのツールに対して list を保持します。

出力：

[  # リソースごとに 1 つのエントリ
    {
        "uri": str,  # リソース URI
        "name": str,  # リソース名
        "mimeType": str | None,  # オプション。MIME タイプ
        "description": str | None,  # オプション。説明
        "server": str,  # このリソースを提供するサーバー
    }
]

ReadMcpResource

ツール名： ReadMcpResourceTool

入力：

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

出力：

{
    "contents": [
        {
            "uri": str,  # リソース URI
            "mimeType": str | None,  # オプション。MIME タイプ
            "text": str | None,  # テキストコンテンツ、またはバイナリコンテンツに関する注記
            "blobSavedTo": str | None,  # Claude Code がバイナリコンテンツをディスクに保存した場合に存在。保存されたファイルのパス
        }
    ],
    "error": str | None,  # サーバーがリソースを読み込めなかった場合に存在
}

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

以下の例では、1 つの ClaudeSDKClient をターン全体で接続したままにするため、Claude は以前のメッセージを覚えています。new と入力して切断して再接続し、新しいセッションを開始するか、exit と入力して会話を終了します。

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())

エラー処理

以下の例は、query() 呼び出しを SDK が発生させる エラータイプ の 4 つのハンドラーでラップしています。

この例は ResultError をキャッチします。これには Python Agent SDK 0.2.140 以降が必要です。

import asyncio

from claude_agent_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    ResultError,
    CLIJSONDecodeError,
)


async def main():
    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"
        )
    # Catch ResultError before ProcessError, which it subclasses. Its message
    # carries the error text. A refusal and a failed final request both usually
    # arrive with subtype "success", so check stop_reason, then terminal_reason.
    except ResultError as e:
        if e.data.get("stop_reason") == "refusal":
            print(f"Model declined to respond: {e}")
        elif e.terminal_reason == "api_error":
            print(f"API request failed: {e}")
        else:
            print(f"Query ended with an error result ({e.terminal_reason or e.subtype}): {e}")
    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}")


asyncio.run(main())

サンドボックス設定

SandboxSettings

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

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

[!NOTE]

サンドボックスはプラットフォームサポートに依存し、Linux では bubblewrap や socat などのツールが必要です。デフォルトでは、enabled が True でもサンドボックスが起動できない場合、コマンドはサンドボックスなしで実行され、stderr に警告が表示されます。このデフォルト動作は TypeScript SDK とは異なり、TypeScript SDK では failIfUnavailable がデフォルトで true です。

サンドボックス設定で "failIfUnavailable": True を設定して、代わりに停止するようにしてください。SDK は、宣言された SandboxSettings フィールドとともに failIfUnavailable を Claude Code に転送します。その後、query() は subtype="error_during_execution" の ResultMessage を報告し、理由は errors に含まれます。これは単一ショットの query() 呼び出しであるため、SDK はそのエラー結果を生成した後に例外を発生させます。そのため、ループを try ブロックでラップして、それを超えて続行してください。エラーの仕様については 結果を処理する を参照してください。

サンドボックス化されたコマンドがファイルに書き込まないようにするには、サンドボックス設定の denyWrite にその絶対パスを記載します（例："filesystem": {"denyWrite": ["/home/user/project/.env"]}）。SDK は、宣言された SandboxSettings フィールドとともに filesystem を Claude Code に転送します。サンドボックスが起動すると、記載された各絶対パスへの書き込みがブロックされます。

使用例

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

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


async def main():
    try:
        async for message in query(
            prompt="Build and test my project",
            options=ClaudeAgentOptions(sandbox=sandbox_settings),
        ):
            print(message)
    except Exception as error:
        # A single-shot query() raises after yielding an error result,
        # such as when failIfUnavailable is set and the sandbox can't start.
        print(f"Session ended with an error: {error}")


asyncio.run(main())