参考数据：Agent SDK 参考 — Python

Data: Agent SDK reference — Python

v2.1.63

Python Agent SDK reference including installation, quick start, custom tools via MCP, and hooks

Agent SDK — Python

Claude Agent SDK 提供了一个高级接口，用于构建具备内置工具、安全特性和智能体能力的 AI 智能体。

安装

bash

pip install claude-agent-sdk

快速开始

python

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Explain this codebase",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

anyio.run(main)

内置工具

工具	描述
Read	读取工作空间中的文件
Write	创建新文件
Edit	对现有文件进行精确编辑
Bash	执行 shell 命令
Glob	按模式查找文件
Grep	按内容搜索文件
WebSearch	在网络上搜索信息
WebFetch	获取并分析网页
AskUserQuestion	向用户询问澄清性问题
Agent	生成子智能体

主要接口

`query()` — 简单的一次性使用

query() 函数是运行智能体的最简单方式。它返回一个消息的异步迭代器。

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Explain this codebase",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
):
    if isinstance(message, ResultMessage):
        print(message.result)

`ClaudeSDKClient` — 完全控制

ClaudeSDKClient 提供了对智能体生命周期的完全控制。当您需要自定义工具、hook、流式传输或中断执行的能力时使用它。

python

import anyio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock

async def main():
    options = ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Explain this codebase")
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

anyio.run(main)

ClaudeSDKClient 支持：

上下文管理器 (async with) 用于自动资源清理
client.query(prompt) 用于向智能体发送提示
receive_response() 用于流式传输消息直到完成
interrupt() 用于在任务中途停止智能体执行
自定义工具所必需 (通过 SDK MCP 服务器)

权限系统

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Refactor the authentication module",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Write"],
        permission_mode="acceptEdits"  # 自动接受文件编辑
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

权限模式：

"default": 对危险操作进行提示
"plan": 仅规划，不执行
"acceptEdits": 自动接受文件编辑
"dontAsk": 不提示 (适用于 CI/CD)
"bypassPermissions": 跳过所有提示 (需要在选项中设置 allow_dangerously_skip_permissions=True)

MCP (Model Context Protocol) 支持

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Open example.com and describe what you see",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
        }
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

Hook

使用回调函数通过 hook 自定义智能体行为：

python

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get('tool_input', {}).get('file_path', 'unknown')
    print(f"Modified: {file_path}")
    return {}

async for message in query(
    prompt="Refactor utils.py",
    options=ClaudeAgentOptions(
        permission_mode="acceptEdits",
        hooks={
            "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])]
        }
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

可用的 hook 事件：PreToolUse, PostToolUse, PostToolUseFailure, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest, Setup, TeammateIdle, TaskCompleted, ConfigChange

常用选项

query() 接受一个顶层的 prompt (字符串) 和一个 options 对象 (ClaudeAgentOptions)：

python

async for message in query(prompt="...", options=ClaudeAgentOptions(...)):

选项	类型	描述
`cwd`	string	文件操作的工作目录
`allowed_tools`	list	智能体可以使用的工具 (例如 `["Read", "Edit", "Bash"]`)
`tools`	list	要提供的内置工具 (限制默认集合)
`disallowed_tools`	list	明确禁止使用的工具
`permission_mode`	string	如何处理权限提示
`allow_dangerously_skip_permissions`	bool	必须为 `True` 才能使用 `permission_mode="bypassPermissions"`
`mcp_servers`	dict	要连接的 MCP 服务器
`hooks`	dict	用于自定义行为的 hook
`system_prompt`	string	自定义系统提示
`max_turns`	int	停止前的最大智能体轮次
`max_budget_usd`	float	查询的最大预算 (美元)
`model`	string	模型 ID (默认值：由 CLI 确定)
`agents`	dict	子智能体定义 (`dict[str, AgentDefinition]`)
`output_format`	dict	结构化输出模式
`thinking`	dict	思考/推理控制
`betas`	list	要启用的 Beta 功能 (例如 `["context-1m-2025-08-07"]`)
`setting_sources`	list	要加载的设置 (例如 `["project"]`)。默认值：无 (无 CLAUDE.md 文件)
`env`	dict	为会话设置的环境变量

消息类型

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage

async for message in query(
    prompt="Find TODO comments",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
):
    if isinstance(message, ResultMessage):
        print(message.result)
    elif isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.session_id  # 捕获以供稍后恢复

子智能体

python

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

async for message in query(
    prompt="Use the code-reviewer agent to review this codebase",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Expert code reviewer for quality and security reviews.",
                prompt="Analyze code quality and suggest improvements.",
                tools=["Read", "Glob", "Grep"]
            )
        }
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

错误处理

python

from claude_agent_sdk import query, ClaudeAgentOptions, CLINotFoundError, CLIConnectionError, ResultMessage

try:
    async for message in query(
        prompt="...",
        options=ClaudeAgentOptions(allowed_tools=["Read"])
    ):
        if isinstance(message, ResultMessage):
            print(message.result)
except CLINotFoundError:
    print("Claude Code CLI not found. Install with: pip install claude-agent-sdk")
except CLIConnectionError as e:
    print(f"Connection error: {e}")

最佳实践

始终指定 allowed_tools — 明确列出智能体可以使用的工具
设置工作目录 — 始终为文件操作指定 cwd
使用适当的权限模式 — 从 "default" 开始，仅在需要时升级
处理所有消息类型 — 检查 ResultMessage 以获取智能体输出
限制 max_turns — 通过合理的限制防止智能体失控

英文原文 / English Original

Agent SDK — Python

The Claude Agent SDK provides a higher-level interface for building AI agents with built-in tools, safety features, and agentic capabilities.

Installation

bash

pip install claude-agent-sdk

Quick Start

python

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Explain this codebase",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

anyio.run(main)

Built-in Tools

Tool	Description
Read	Read files in the workspace
Write	Create new files
Edit	Make precise edits to existing files
Bash	Execute shell commands
Glob	Find files by pattern
Grep	Search files by content
WebSearch	Search the web for information
WebFetch	Fetch and analyze web pages
AskUserQuestion	Ask user clarifying questions
Agent	Spawn subagents

Primary Interfaces

`query()` — Simple One-Shot Usage

The query() function is the simplest way to run an agent. It returns an async iterator of messages.

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Explain this codebase",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
):
    if isinstance(message, ResultMessage):
        print(message.result)

`ClaudeSDKClient` — Full Control

ClaudeSDKClient provides full control over the agent lifecycle. Use it when you need custom tools, hooks, streaming, or the ability to interrupt execution.

python

import anyio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock

async def main():
    options = ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Explain this codebase")
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

anyio.run(main)

ClaudeSDKClient supports:

Context manager (async with) for automatic resource cleanup
client.query(prompt) to send a prompt to the agent
receive_response() for streaming messages until completion
interrupt() to stop agent execution mid-task
Required for custom tools (via SDK MCP servers)

Permission System

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Refactor the authentication module",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Write"],
        permission_mode="acceptEdits"  # Auto-accept file edits
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

Permission modes:

"default": Prompt for dangerous operations
"plan": Planning only, no execution
"acceptEdits": Auto-accept file edits
"dontAsk": Don't prompt (useful for CI/CD)
"bypassPermissions": Skip all prompts (requires allow_dangerously_skip_permissions=True in options)

MCP (Model Context Protocol) Support

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async for message in query(
    prompt="Open example.com and describe what you see",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
        }
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

Hooks

Customize agent behavior with hooks using callback functions:

python

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get('tool_input', {}).get('file_path', 'unknown')
    print(f"Modified: {file_path}")
    return {}

async for message in query(
    prompt="Refactor utils.py",
    options=ClaudeAgentOptions(
        permission_mode="acceptEdits",
        hooks={
            "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])]
        }
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

Available hook events: PreToolUse, PostToolUse, PostToolUseFailure, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest, Setup, TeammateIdle, TaskCompleted, ConfigChange

Common Options

query() takes a top-level prompt (string) and an options object (ClaudeAgentOptions):

python

async for message in query(prompt="...", options=ClaudeAgentOptions(...)):

Option	Type	Description
`cwd`	string	Working directory for file operations
`allowed_tools`	list	Tools the agent can use (e.g., `["Read", "Edit", "Bash"]`)
`tools`	list	Built-in tools to make available (restricts the default set)
`disallowed_tools`	list	Tools to explicitly disallow
`permission_mode`	string	How to handle permission prompts
`allow_dangerously_skip_permissions`	bool	Must be `True` to use `permission_mode="bypassPermissions"`
`mcp_servers`	dict	MCP servers to connect to
`hooks`	dict	Hooks for customizing behavior
`system_prompt`	string	Custom system prompt
`max_turns`	int	Maximum agent turns before stopping
`max_budget_usd`	float	Maximum budget in USD for the query
`model`	string	Model ID (default: determined by CLI)
`agents`	dict	Subagent definitions (`dict[str, AgentDefinition]`)
`output_format`	dict	Structured output schema
`thinking`	dict	Thinking/reasoning control
`betas`	list	Beta features to enable (e.g., `["context-1m-2025-08-07"]`)
`setting_sources`	list	Settings to load (e.g., `["project"]`). Default: none (no CLAUDE.md files)
`env`	dict	Environment variables to set for the session

Message Types

python

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage

async for message in query(
    prompt="Find TODO comments",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
):
    if isinstance(message, ResultMessage):
        print(message.result)
    elif isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.session_id  # Capture for resuming later

Subagents

python

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

async for message in query(
    prompt="Use the code-reviewer agent to review this codebase",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Expert code reviewer for quality and security reviews.",
                prompt="Analyze code quality and suggest improvements.",
                tools=["Read", "Glob", "Grep"]
            )
        }
    )
):
    if isinstance(message, ResultMessage):
        print(message.result)

Error Handling

python

from claude_agent_sdk import query, ClaudeAgentOptions, CLINotFoundError, CLIConnectionError, ResultMessage

try:
    async for message in query(
        prompt="...",
        options=ClaudeAgentOptions(allowed_tools=["Read"])
    ):
        if isinstance(message, ResultMessage):
            print(message.result)
except CLINotFoundError:
    print("Claude Code CLI not found. Install with: pip install claude-agent-sdk")
except CLIConnectionError as e:
    print(f"Connection error: {e}")

Best Practices

Always specify allowed_tools — Explicitly list which tools the agent can use
Set working directory — Always specify cwd for file operations
Use appropriate permission modes — Start with "default" and only escalate when needed
Handle all message types — Check for ResultMessage to get agent output
Limit max_turns — Prevent runaway agents with reasonable limits

参考数据：Agent SDK 参考 — Python ​

Agent SDK — Python ​

安装 ​

快速开始 ​

内置工具 ​

主要接口 ​

query() — 简单的一次性使用 ​

ClaudeSDKClient — 完全控制 ​

权限系统 ​

MCP (Model Context Protocol) 支持 ​

Hook ​

常用选项 ​

消息类型 ​

子智能体 ​

错误处理 ​

最佳实践 ​

Agent SDK — Python ​

Installation ​

Quick Start ​

Built-in Tools ​

Primary Interfaces ​

query() — Simple One-Shot Usage ​

ClaudeSDKClient — Full Control ​

Permission System ​

MCP (Model Context Protocol) Support ​

Hooks ​

Common Options ​

Message Types ​

Subagents ​

Error Handling ​

Best Practices ​

参考数据：Agent SDK 参考 — Python

Agent SDK — Python

安装

快速开始

内置工具

主要接口

`query()` — 简单的一次性使用

`ClaudeSDKClient` — 完全控制

权限系统

MCP (Model Context Protocol) 支持

Hook

常用选项

消息类型

子智能体

错误处理

最佳实践

Agent SDK — Python

Installation

Quick Start

Built-in Tools

Primary Interfaces

`query()` — Simple One-Shot Usage

`ClaudeSDKClient` — Full Control

Permission System

MCP (Model Context Protocol) Support

Hooks

Common Options

Message Types

Subagents

Error Handling

Best Practices