Python SDK API 参考

Python SDK 提供两种交互方式：query() 函数（每次调用创建新会话，适合一次性任务）和 ClaudeSDKClient（维护同一会话，适合多轮对话）。

核心机制

query() vs ClaudeSDKClient 对比：

特性	query()	ClaudeSDKClient
会话	每次新建	复用同一会话
多轮对话	需要 resume 选项	自动维护
流式输入	支持	支持
中断	不支持	支持
适用场景	一次性任务	持续对话

ClaudeAgentOptions 核心字段：

• allowed_tools：预批准工具列表
• permission_mode：权限模式（default/acceptEdits/dontAsk/bypassPermissions/plan）
• system_prompt：系统提示（字符串或 preset 对象）
• setting_sources：文件系统配置来源
• max_turns：最大工具调用轮次
• max_budget_usd：费用上限
• effort：推理深度（low/medium/high/xhigh/max）
• model：模型 ID
• cwd：工作目录
• mcp_servers：MCP 服务器配置
• hooks：Hook 回调配置
• agents：子 Agent 定义
• resume：恢复的 session ID
• fork_session：是否 fork 会话
• output_format：结构化输出 Schema
• skills：可用 Skills 控制
• plugins：插件列表
• env：环境变量覆盖

关键细节

query() 函数签名：

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

ClaudeSDKClient 使用模式：

async with ClaudeSDKClient(options=options) as client:
    await client.query("First question")
    async for message in client.receive_response():
        print(message)
 
    await client.query("Follow-up question")  # 自动延续同一会话
    async for message in client.receive_response():
        print(message)

消息类型导入：

from claude_agent_sdk import (
    query, ClaudeAgentOptions, ClaudeSDKClient,
    SystemMessage, AssistantMessage, UserMessage, ResultMessage,
    TextBlock, ToolUseBlock, ToolResultBlock,
    HookMatcher, AgentDefinition,
)
from claude_agent_sdk.types import StreamEvent, PermissionResultAllow, PermissionResultDeny

工具函数：

from claude_agent_sdk import (
    tool, create_sdk_mcp_server,  # 自定义工具
    list_sessions, get_session_messages,  # 会话管理
    get_session_info, rename_session, tag_session,
)

与其他概念的关联

• overview - SDK 整体架构
• agent-loop - 消息类型详解
• sessions - ClaudeSDKClient 的会话管理
• typescript - TypeScript SDK 对应参考

实践要点

• ClaudeSDKClient 必须作为 async context manager 使用（async with）
• query() 适合脚本和无状态场景，ClaudeSDKClient 适合交互式应用
• Python SDK 不支持 SessionStart/SessionEnd 回调 Hook（TypeScript 支持）
• env 字段在 Python 中是合并到继承环境，TypeScript 中是完全替换