Python Agent SDK 提供两种与 Claude Code 交互的方式：query() 适合一次性任务，每次调用默认创建新会话；ClaudeSDKClient 维护多轮对话上下文，支持中断、文件回退和 MCP 服务状态查询。使用 pip install claude-agent-sdk 安装后，通过 @tool 装饰器定义自定义工具，用 create_sdk_mcp_server() 集成到会话中。需要注意 TypedDict 配置项（如 ThinkingConfig）在运行时是普通字典，必须用键访问而非属性。

Claude Code Agent SDK Python 参考：query 与 ClaudeSDKClient #

Python Agent SDK 的完整 API 参考，包括函数、类型和类的详细说明。

安装 #

pip install claude-agent-sdk

选择 query() 还是 ClaudeSDKClient #

Python SDK 提供两种与 Claude Code 交互的方式：

快速对比 #

什么时候用 query()（一次性任务） #

适合场景：

• 不需要对话历史的一次性问题
• 不依赖之前交换上下文的独立任务
• 简单的自动化脚本
• 每次希望从头开始的情况

什么时候用 ClaudeSDKClient（连续对话） #

适合场景：

• 继续对话 - 需要 Claude 记住上下文
• 追问 - 基于之前的回答继续提问
• 交互式应用 - 聊天界面、REPL
• 响应驱动逻辑 - 下一步动作取决于 Claude 的回答
• 会话控制 - 明确管理对话生命周期

函数 Functions #

query() #

默认情况下，每次与 Claude Code 交互时都会创建一个新会话。返回一个异步迭代器，按到达顺序产生消息。每次调用 query() 都是全新开始，不记得之前的交互，除非在 ClaudeAgentOptions 中传递 continue_conversation=True 或 resume。参见会话。

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

参数 Parameters #

返回值 Returns #

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

参数 Parameters #

输入 schema 选项 Input schema options #

1. 简单类型映射（推荐）：

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

2. JSON Schema 格式（复杂校验）：

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

返回值 Returns #

一个装饰器函数，包装工具实现并返回 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

参数 Parameters #

返回值 Returns #

返回 McpSdkServerConfig 对象，可以传递给 ClaudeAgentOptions.mcp_servers。

示例 #

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],  # 传递装饰后的函数
)

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

参数 Parameters #

返回类型: 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]

参数 Parameters #

返回类型: 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

参数 Parameters #

返回 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

参数 Parameters #

如果 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

参数 Parameters #

如果 session_id 不是有效 UUID 或 tag 清理后为空，则抛出 ValueError；如果找不到会话，则抛出 FileNotFoundError。

示例 #

给会话打标签，然后在后续读取时按标签过滤。传递 None 可清除现有标签。

from claude_agent_sdk import list_sessions, tag_session

# 给会话打标签
tag_session("550e8400-e29b-41d4-a716-446655440000", "needs-review")

# 稍后：查找所有带有该标签的会话
for session in list_sessions(directory="/path/to/project"):
    if session.tag == "needs-review":
        print(session.summary)

类 Classes #

ClaudeSDKClient #

在多次消息交换之间维持对话会话。 这是 TypeScript SDK 中 query() 函数内部工作的 Python 等价物——它创建一个可以继续对话的客户端对象。

主要特性 Key Features #

• 会话连续性：在多次 query() 调用之间维持对话上下文
• 同一对话：会话保留之前的消息
• 中断支持：可以在任务执行中途停止
• 显式生命周期：你可以控制会话的开始和结束
• 响应驱动流程：可以对响应做出反应并发送后续问题
• 自定义工具和钩子：支持自定义工具（用 @tool 装饰器创建）和钩子

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

方法 Methods #

上下文管理器支持 Context Manager Support #

客户端可以用作异步上下文管理器，实现自动连接管理：

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:
        # 第一个问题
        await client.query("What's the capital of France?")

        # 处理响应
        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}")

        # 后续问题 - 会话保留了之前的上下文
        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}")

        # 继续追问 - 仍在同一对话中
        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():
    """动态生成消息。"""
    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:
        # 向 Claude 流式输入
        await client.query(message_stream())

        # 处理响应
        async for message in client.receive_response():
            print(message)

        # 同一会话中继续提问
        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:
        # 启动一个长时间运行的任务
        await client.query("Count from 1 to 100 slowly, using the bash sleep command")

        # 让它运行一会儿
        await asyncio.sleep(2)

        # 中断任务
        await client.interrupt()
        print("Task interrupted!")

        # 清空中断任务的残留消息（包括它的 ResultMessage）
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(f"Interrupted task finished with subtype={message.subtype!r}")
                # 对于被中断的任务，subtype 是 "error_during_execution"

        # 发送新命令
        await client.query("Just say hello instead")

        # 现在接收新的响应
        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())

中断后的缓冲区行为： interrupt() 发送停止信号，但不清除消息缓冲区。中断任务已产生的消息（包括 ResultMessage，其 subtype="error_during_execution"）仍然留在流中。在读取新查询的响应之前，必须用 receive_response() 将它们排空。如果在 interrupt() 后立即发送新查询，且只调用一次 receive_response()，你将收到中断任务的消息，而不是新查询的响应。

示例 - 高级权限控制 #

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:
    """自定义工具权限逻辑。"""

    # 阻止写入系统目录
    if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
        return PermissionResultDeny(
            message="System directory write not allowed", interrupt=True
        )

    # 重定向敏感文件操作
    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}
        )

    # 其他所有情况都允许
    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():
            # 将使用沙箱路径代替
            print(message)


asyncio.run(main())

类型 Types #

@dataclass vs TypedDict： 此 SDK 使用两种类型。带有 @dataclass 装饰器的类（如 ResultMessage、AgentDefinition、TextBlock）在运行时时是对象实例，支持属性访问：msg.result。使用 TypedDict 定义的类（如 ThinkingConfigEnabled、McpStdioServerConfig、SyncHookJSONOutput）在运行时时是普通字典，需要键访问：config["budget_tokens"]，而不是 config.budget_tokens。两种类型都支持 ClassName(field=value) 调用语法，但只有数据类产生具有属性的对象。

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 进程通信。

这是一个低级内部 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
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  # 已废弃
    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  # 已废弃，改用 thinking
    thinking: ThinkingConfig | None = None
    effort: EffortLevel | 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 字段：

# output_format 的预期字典形状
{
    "type": "json_schema",
    "schema": {...},  # 你的 JSON Schema 定义
}

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 #

禁用文件系统设置：

# 不从磁盘加载用户、项目或本地设置
from claude_agent_sdk import query, ClaudeAgentOptions

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

在 Python SDK 0.1.59 及更早版本中，空列表被视为与省略选项相同，因此 setting_sources=[] 不会禁用文件系统设置。如果你需要空列表生效，请升级到更新版本。TypeScript SDK 不受影响。

显式加载所有文件系统设置：

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)

仅加载特定设置来源：

# 仅加载项目设置，忽略用户和本地设置
async for message in query(
    prompt="Run CI checks",
    options=ClaudeAgentOptions(
        setting_sources=["project"]  # 仅 .claude/settings.json
    ),
):
    print(message)

测试和 CI 环境：

# 确保 CI 行为一致，排除本地设置
async for message in query(
    prompt="Run tests",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # 仅团队共享设置
        permission_mode="bypassPermissions",
    ),
):
    print(message)

仅 SDK 应用：

# 全部通过编程方式定义。
# 传递 [] 以不加载文件系统设置来源。
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 项目指令：

# 加载项目设置以包含 CLAUDE.md 文件
async for message in query(
    prompt="Add a new feature following project conventions",
    options=ClaudeAgentOptions(
        system_prompt={
            "type": "preset",
            "preset": "claude_code",  # 使用 Claude Code 的系统提示
        },
        setting_sources=["project"],  # 从项目加载 CLAUDE.md
        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: EffortLevel | int | None = None
    permissionMode: PermissionMode | None = None

AgentDefinition 字段名称使用驼峰式（camelCase），如 disallowedTools、permissionMode 和 maxTurns。这些名称直接映射到与 TypeScript SDK 共享的网络格式。这与 ClaudeAgentOptions 不同，后者使用 Python 的 snake_case 表示等效顶层字段，如 disallowed_tools 和 permission_mode。因为 AgentDefinition 是数据类，传递 snake_case 关键字会在构造时抛出 TypeError。

PermissionMode #

用于控制工具执行的权限模式。

PermissionMode = Literal[
    "default",          # 标准权限行为
    "acceptEdits",      # 自动接受文件编辑
    "plan",             # 计划模式 - 仅允许只读工具
    "dontAsk",          # 拒绝任何未预先批准的操作，而不是提示
    "bypassPermissions", # 绕过所有权限检查（谨慎使用）
]

EffortLevel #

指导思维深度的努力程度。

EffortLevel = Literal[
    "low",      # 最小思维，最快响应
    "medium",   # 中等思维
    "high",     # 深度推理
    "xhigh",    # 扩展推理（仅 Opus 4.7 支持；其他模型回退到 "high"）
    "max",     # 最大努力
]

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  # 未来：中止信号支持
    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 #

权限回调结果的联合类型。

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 #

控制扩展思维行为。是三种配置的联合：

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"，因此设置 "summarized" 可以在 ThinkingBlock 输出中接收思考内容。

因为这些是 TypedDict 类，运行时时是普通字典。可以构建为字典字面量或像构造函数一样调用类；两者都产生 dict。使用 config["budget_tokens"] 访问字段，而不是 config.budget_tokens：

from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

# 选项1：字典字面量（推荐，无需导入）
options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

# 选项2：构造函数式（返回普通 dict）
config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
print(config["budget_tokens"])  # 20000
# config.budget_tokens 会引发 AttributeError

SdkBeta #

SDK Beta 功能的文字类型。

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

与 ClaudeAgentOptions 的 betas 字段一起使用以启用 Beta 功能。

context-1m-2025-08-07 Beta 已于 2026 年 4 月 30 日退役。将此标头传递给 Claude Sonnet 4.5 或 Sonnet 4 没有任何效果，超过标准 200k Token 上下文窗口的请求会返回错误。要使用 100 万 Token 上下文窗口，请迁移到 Claude Sonnet 4.6、Claude Opus 4.6 或 Claude Opus 4.7，它们以标准定价包含 100 万上下文，无需 Beta 标头。

McpSdkServerConfig #

使用 create_sdk_mcp_server() 创建的 SDK MCP 服务器的配置。

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

McpServerConfig #

MCP 服务器配置的联合类型。

McpServerConfig = (
    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
)

McpStdioServerConfig #

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # 向后兼容可选
    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 传输变体的联合，加上一个仅输出类型的 claudeai-proxy 变体，用于通过 claude.ai 代理的服务器。

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 Types #

Message #

所有可能消息的联合类型。

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 字典包含以下键（如果存在）：

model_usage 字典将模型名称映射到各模型的使用情况。内部字典键使用驼峰式，因为值是从底层 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]  # 原始 Claude API 流事件
    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 #

后台任务的 Token 和时间数据。

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

内容块类型 Content Block Types #

ContentBlock #

所有内容块的联合类型。

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

错误类型 Error Types #

ClaudeSDKError #

所有 SDK 错误的基础异常类。

class ClaudeSDKError(Exception):
    """Claude SDK 基础错误。"""

CLINotFoundError #

当 Claude Code CLI 未安装或未找到时引发。

class CLINotFoundError(CLIConnectionError):
    def __init__(
        self, message: str = "Claude Code not found", cli_path: str | None = None
    ):
        """
        参数:
            message: 错误消息（默认："Claude Code not found"）
            cli_path: 未找到的 CLI 的可选路径
        """

CLIConnectionError #

当与 Claude Code 的连接失败时引发。

class CLIConnectionError(ClaudeSDKError):
    """连接 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):
        """
        参数:
            line: 解析失败的文本行
            original_error: 原始的 JSON 解码异常
        """
        self.line = line
        self.original_error = original_error

钩子类型 Hook Types #

关于使用钩子的完整指南（含示例和常见模式），参见钩子指南。

HookEvent #

支持的钩子事件类型。

HookEvent = Literal[
    "PreToolUse",          # 工具执行前调用
    "PostToolUse",         # 工具执行后调用
    "PostToolUseFailure",  # 工具执行失败时调用
    "UserPromptSubmit",    # 用户提交提示时调用
    "Stop",                # 停止执行时调用
    "SubagentStop",        # 子代理停止时调用
    "PreCompact",          # 消息压缩前调用
    "Notification",        # 通知事件时调用
    "SubagentStart",       # 子代理启动时调用
    "PermissionRequest",   # 需要权限决策时调用
]

TypeScript SDK 支持更多钩子事件，Python 尚不可用：SessionStart、SessionEnd、Setup、TeammateIdle、TaskCompleted、ConfigChange、WorktreeCreate、WorktreeRemove 和 PostToolBatch。

HookCallback #

钩子回调函数的类型定义。

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

参数：

• input：基于 hook_event_name 的强类型钩子输入（参见 HookInput）
• tool_use_id：可选的工具使用标识符（用于与工具相关的钩子）
• context：带有额外信息的钩子上下文

返回 HookJSONOutput，其中可能包含：

• decision："block" 用于阻止该操作
• systemMessage：向用户显示的警告消息
• hookSpecificOutput：特定于钩子的输出数据

HookContext #

传递给钩子回调的上下文信息。

class HookContext(TypedDict):
    signal: Any | None  # 未来：中止信号支持

HookMatcher #

用于将钩子匹配到特定事件或工具的配置。

@dataclass
class HookMatcher:
    matcher: str | None = (
        None  # 要匹配的工具名称或模式（如 "Bash"、"Write|Edit"）
    )
    hooks: list[HookCallback] = field(
        default_factory=list
    )  # 要执行的回调列表
    timeout: float | None = (
        None  # 此匹配器中所有钩子的超时秒数（默认：60）
    )

HookInput #

所有钩子输入类型的联合类型。实际类型取决于 hook_event_name 字段。

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

BaseHookInput #

所有钩子输入类型中存在的基字段。

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

PreToolUseHookInput #

PreToolUse 钩子事件的输入数据。

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 钩子事件的输入数据。

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 钩子事件的输入数据。在工具执行失败时调用。

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 钩子事件的输入数据。

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

StopHookInput #

Stop 钩子事件的输入数据。

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

SubagentStopHookInput #

SubagentStop 钩子事件的输入数据。

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

PreCompactHookInput #

PreCompact 钩子事件的输入数据。

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

NotificationHookInput #

Notification 钩子事件的输入数据。

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

SubagentStartHookInput #

SubagentStart 钩子事件的输入数据。

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

PermissionRequestHookInput #

PermissionRequest 钩子事件的输入数据。允许钩子以编程方式处理权限决策。

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

HookJSONOutput #

钩子回调返回值的联合类型。

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

SyncHookJSONOutput #

带有控制和决策字段的同步钩子输出。

class SyncHookJSONOutput(TypedDict):
    # 控制字段
    continue_: NotRequired[bool]  # 是否继续（默认：True）
    suppressOutput: NotRequired[bool]  # 从记录中隐藏 stdout
    stopReason: NotRequired[str]  # 当 continue_ 为 False 时的消息

    # 决策字段
    decision: NotRequired[Literal["block"]]
    systemMessage: NotRequired[str]  # 向用户显示的警告消息
    reason: NotRequired[str]  # 给 Claude 的反馈

    # 特定于钩子的输出
    hookSpecificOutput: NotRequired[HookSpecificOutput]

在 Python 代码中使用 continue_（带下划线）。发送给 CLI 时会自动转换为 continue。

HookSpecificOutput #

包含钩子事件名称和特定于事件的字段的 TypedDict。形状取决于 hookEventName 值。关于每个钩子事件可用字段的完整详情，参见使用钩子控制执行。

事件特定输出类型的区分联合。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]  # 已废弃：改用 updatedToolOutput，适用于所有工具


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 #

将钩子执行推迟的异步钩子输出。

class AsyncHookJSONOutput(TypedDict):
    async_: Literal[True]  # 设为 True 以推迟执行
    asyncTimeout: NotRequired[int]  # 超时毫秒数

在 Python 代码中使用 async_（带下划线）。发送给 CLI 时会自动转换为 async。

钩子使用示例 Hook Usage Example #

此示例注册了两个钩子：一个阻止危险的 bash 命令（如 rm -rf /），另一个记录所有工具使用以供审计。安全钩子仅对 Bash 命令运行（通过 matcher），而记录钩子对所有工具运行。

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]:
    """验证并可能阻止危险的 bash 命令。"""
    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]:
    """记录所有工具使用以供审计。"""
    print(f"Tool used: {input_data.get('tool_name')}")
    return {}


options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash", hooks=[validate_bash_command], timeout=120
            ),  # 2 分钟用于验证
            HookMatcher(
                hooks=[log_tool_use]
            ),  # 适用于所有工具（默认 60s 超时）
        ],
        "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
    }
)

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

工具输入/输出类型 Tool Input/Output Types #

所有内置 Claude Code 工具的输入/输出 schema 文档。虽然 Python SDK 不将这些导出为类型，但它们代表消息中工具输入和输出的结构。

Agent #

工具名称： Agent（之前是 Task，仍可作为别名接受）

输入：

{
    "description": str,  # 任务的简短描述（3-5 个词）
    "prompt": str,  # 代理执行的任务
    "subagent_type": str,  # 要使用的专业代理类型
}

输出：

{
    "result": str,  # 来自子代理的最终结果
    "usage": dict | None,  # Token 使用统计
    "total_cost_usd": float | None,  # 估计总成本（美元）
    "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,  # 合并的 stdout 和 stderr 输出
    "exitCode": int,  # 命令的退出码
    "killed": bool | None,  # 命令是否因超时被终止
    "shellId": str | None,  # 后台进程的 Shell ID
}

Monitor #

工具名称： Monitor

在后台运行一个脚本，并将每行 stdout 作为事件传递给 Claude，以便它可以无需轮询即可做出反应。Monitor 遵循与 Bash 相同的权限规则。参见 Monitor 工具参考了解行为和提供者可用性。

输入：

{
    "command": str,  # Shell 脚本；每行 stdout 是一个事件，退出结束监听
    "description": str,  # 通知中显示的简短描述
    "timeout_ms": int | None,  # 在此截止时间后终止（默认 300000，最大 3600000）
    "persistent": bool | None,  # 在会话生命周期内运行；用 TaskStop 停止
}