Coggle数据科学 | 小白学大模型：Claude Agent SDK 使用指南

本文来源公众号“Coggle数据科学”，仅用于学术分享，侵权删，干货满满。

原文链接：https://mp.weixin.qq.com/s/A59J_Pz8BVFp_ulpAxPwNw

Anthropic 现已推出 Claude Agent SDK（原名 Claude Code SDK），这是一个功能强大且全面的工具包，专为帮助开发者构建生产级 AI 智能体而设计。无论您是想创建高级编码助手、专业的业务代理，还是其他创新应用，该 SDK 都为您提供了所需的全部构建模块。

https://docs.claude.com/en/docs/agent-sdk/overview

为什么选择 Claude Agent SDK？

Claude Agent SDK 建立在驱动 Claude Code 的智能体核心（agent harness）之上，它集成了 Anthropic 在构建高性能 AI 智能体方面的经验，提供了一系列关键功能：

• 上下文管理（Context Management）：自动压缩和管理上下文，确保您的智能体不会耗尽上下文限制，保持高效运行。

• 丰富的工具生态系统（Rich Tool Ecosystem）：原生支持文件操作、代码执行、Web 搜索，并可通过 Model Context Protocol (MCP) 进行扩展。

• 高级权限控制（Advanced Permissions）：对智能体的能力进行细粒度控制，通过 allowedTools、disallowedTools 和 permissionMode 来定义工具使用权限。

• 生产级必备要素（Production Essentials）：内置错误处理、会话管理和监控功能。

• 优化的 Claude 集成（Optimized Claude Integration）：包含自动提示缓存和性能优化，确保流畅高效的体验。

好的，这是 Claude Agent SDK Python 库的中文 API 参考概览，包括关键函数、类和类型定义。

Claude Agent Python SDK

Claude Agent SDK 为 Python 应用提供了构建和管理 AI 智能体的完整工具集。

使用 pip 即可轻松安装：

pip install claude-agent-sdk

SDK 提供了两种主要的交互模式，以适应不同的使用场景：

特性	query()	ClaudeSDKClient
会话	每次创建新会话	复用相同会话
对话	单次交互	多次交互（持续对话）
上下文	无记忆（每次从头开始）	保持上下文
连接	自动管理	手动控制
中断	❌ 不支持	✅ 支持
Hooks / 自定义工具	❌ 不支持	✅ 支持
使用场景	一次性任务 、简单脚本	持续对话 、交互式应用

所有交互数据都通过以下消息类型和内容块结构进行异步传输：

类型	描述	关键属性
Message	所有消息的联合类型。	-
UserMessage	用户输入。	content
AssistantMessage	智能体响应。	content , model
ResultMessage	最终结果消息 。	total_cost_usd , usage, is_error
TextBlock	纯文本内容。	text
ToolUseBlock	智能体请求使用工具。	id , name, input
ToolResultBlock	工具执行结果。	tool_use_id , content

💬 智能体输入模式：流式输入 vs. 单消息输入

https://docs.claude.com/en/docs/agent-sdk/streaming-vs-single-mode

Claude Agent SDK 支持两种截然不同的输入模式，用于与您的 AI 智能体进行交互。理解这两种模式能帮助您为应用选择最合适的方法。

流式输入模式是使用 Claude Agent SDK 的首选方式。它将智能体作为一个长期运行的、持久的交互式会话进程来操作，从而提供对所有高级功能的完整访问。

在这种模式下，您的应用程序通过异步生成器 (AsyncGenerator/AsyncIterable) 将消息流式传输给 Claude 智能体。会话会一直保持活动状态，文件系统状态和对话上下文得以维持。

优势	描述
持久上下文	自然地保持 多轮对话的上下文和会话状态。
实时反馈	响应内容在生成时即刻流式传回，提供实时用户体验。
工具与 Hook 支持	全面访问 所有内置工具、自定义 MCP 服务器和生命周期 Hooks。
排队与中断	可以发送多个排队消息进行顺序处理，并支持实时中断。
图像上传	能够直接在消息中附加图像进行视觉分析。

单消息输入模式更为简单，但功能有所限制。它适用于一次性的、无状态的查询。

每次调用 query() 或发送消息都相当于一个**一锤子买卖 (one-shot query)**。虽然可以通过指定选项（如 continue: true）来管理会话状态或恢复（resuming）先前会话，但它本质上不是一个持久的、交互式的进程。

特性	流式输入模式 (Streaming Input Mode)	单消息输入 (Single Message Input)
推荐度	高（默认）	低
会话性质	长期运行、持久、交互式	一次性、非持久
图像附件	✅ 支持	❌ 不支持
消息排队	✅ 支持	❌ 不支持
实时中断	✅ 支持	❌ 不支持
Hooks	✅ 支持	❌ 不支持
客户端	Python SDK 中需使用 ClaudeSDKClient	Python SDK 中可使用单次 query() 函数

🔒 处理权限：控制 Claude Agent SDK 中的工具使用

https://docs.claude.com/en/docs/agent-sdk/permissions

Claude Agent SDK 提供了强大的权限控制机制，允许您精确管理智能体在您的应用中调用工具的方式。这些控制措施对于确保安全性和可预测性至关重要。

SDK 提供了四种互补的方式来控制工具的使用，您可以根据需求选择最合适的方法：

控制方式	描述	主要用途
权限模式 (Permission Modes)	全局行为设置 ，影响所有工具（如默认、自动接受编辑）。	设置整体操作策略（例如：快速原型开发 vs. 严格控制）。
canUseTool 回调	运行时权限处理程序 。在工具使用未被其他规则覆盖时触发。	实现交互式用户审批或动态权限逻辑。
Hooks	细粒度的程序化控制 。在工具执行前后拦截和修改。	审计、修改输入或基于复杂逻辑进行允许/拒绝。
权限规则 (settings.json)	声明式策略 （允许/拒绝规则），支持智能 Bash 命令解析。	静态、可配置的策略，适用于团队共享的安全标准。

Claude Agent SDK 提供的会话管理功能是实现连续对话和持久化工作流程的关键。会话允许智能体记住完整的对话历史和上下文，以便在多次交互中继续工作。

当您发起一个新的查询（query()）时，SDK 会自动创建一个会话。会话 ID 包含在返回的第一个系统初始化消息 (system:init) 中。您需要捕获并保存这个 ID，以便将来恢复会话。

1. 调用 query() 发起会话。

2. 迭代返回的消息。

3. 检查消息类型是否为 system 且子类型为 init。

4. 从该消息的 session_id 属性中提取 ID。

☁️ 托管 Agent SDK：生产环境部署指南

https://docs.claude.com/en/docs/agent-sdk/hosting

Claude Agent SDK 与传统的无状态 LLM API 不同，因为它维护对话状态并在持久化环境中执行命令。这要求在部署时进行特定的架构考虑，以确保安全性、隔离性和稳定性。

每个 SDK 实例需要：

要求类别	详情
运行时依赖	Python 3.10+ (Python SDK) 或 Node.js 18+ (TypeScript SDK)
CLI 依赖	Node.js (Claude Code CLI 所需)
SDK CLI	必须安装 Claude Code CLI (npm install -g @anthropic-ai/claude-code)
资源分配	推荐：  1GiB RAM、5GiB 磁盘空间、1 CPU（根据任务复杂性调整）
网络访问	出站 HTTPS  到 api.anthropic.com；可选地，访问 MCP 服务器或外部工具。

与无状态 API 不同，Claude Agent SDK 作为一个长期运行的进程运行。它在会话期间执行以下操作：

• 在持久化的 Shell 环境中执行命令。

• 在工作目录内管理文件操作。

• 处理工具执行，并利用先前交互的上下文。

✍️ 修改系统提示词：定制 Claude 的行为

https://docs.claude.com/en/docs/agent-sdk/modifying-system-prompts

系统提示词是定义 Claude 在整个对话中行为、能力和响应风格的初始指令集。Claude Agent SDK 提供了四种主要方法来定制这些提示词，以适应您的特定应用和工作流程。

默认情况下，Agent SDK 使用空系统提示词以提供最大的灵活性。如果您想使用 Claude Code 提供的内置功能（工具说明、代码指南、安全提示等），您必须在 Python 中指定 system_prompt="claude_code" 或在 TypeScript 中指定 systemPrompt: { preset: "claude_code" }。

🔌 MCP 在 SDK 中的应用：扩展 Claude 的自定义工具

https://docs.claude.com/en/docs/agent-sdk/mcp

Model Context Protocol (MCP) 是一种协议，允许您通过自定义服务器来扩展 Claude Agent SDK 的能力和工具集。通过 MCP，您可以将 Claude 连接到数据库、内部 API 或其他外部服务。

配置 MCP 服务器主要通过 ClaudeAgentOptions 中的 mcp_servers 选项来实现。

类型	描述	配置字段
SSE (Server-Sent Events)	适合需要实时流式数据的服务器。	type: "sse" , url
HTTP	适合传统的 RESTful 请求/响应模式。	type: "http" , url

MCP 服务器可以暴露资源（Resources），允许 Claude 通过 mcp__list_resources 和 mcp__read_resource 工具来查询和读取数据，例如数据库表、API 端点列表或配置文件。

🛠️ 自定义工具：扩展 Claude Agent SDK 功能

https://docs.claude.com/en/docs/agent-sdk/mcp

自定义工具允许您通过进程内 MCP 服务器（In-process MCP servers）将 Claude 的能力扩展到外部服务、API 或专业操作。这是赋予您的智能体特定、专业能力的关键步骤。

您可以使用 SDK 提供的 @tool 装饰器（Python）和 create_sdk_mcp_server 函数来定义具有类型安全的自定义工具。

1. 定义工具逻辑：使用 @tool 装饰器定义一个异步函数作为工具的处理程序（handler）。

2. **定义输入模式 (Schema)**：提供一个清晰的输入模式（例如使用 Python 的类型提示或字典）来指导 Claude 如何调用该工具。

3. 创建 MCP 服务器：使用 create_sdk_mcp_server 将一个或多个工具函数打包成一个 MCP 服务器实例。

工具处理程序应该包含 try...except 块，以捕获外部 API 调用或其他操作中的错误。当发生错误时，将错误信息格式化为工具结果返回给 Claude。

🤖 Subagents：使用子智能体进行专业化和并行化

https://docs.claude.com/en/docs/agent-sdk/subagents

在 Claude Agent SDK 中，子智能体（Subagents） 是由主智能体协调和调度的专业化 AI 实例。它们是管理复杂任务上下文和实现工作流并行化的强大工具。

优势	描述
上下文管理	每个子智能体维护独立的上下文。这可以防止中间结果或不相关的细节污染主对话，确保主智能体始终关注核心任务。
并行化	多个子智能体可以并发运行。例如，在代码审查中，可以同时启动安全扫描器、样式检查器和测试执行器，大幅缩短整体完成时间。
专业化知识	每个子智能体可以拥有量身定制的系统提示词，赋予其特定的专业知识、约束和最佳实践，使其在特定领域表现更出色。
工具限制	可以为子智能体限制工具集，从而降低意外操作的风险。例如，一个文档审核子智能体可能只被授权访问 Read 工具。

SDK 提供了两种定义子智能体的方式：程序化定义（推荐）和基于文件系统定义。

程序化定义（推荐）是 SDK 应用的首选方法。您直接在 query() 调用的 agents 参数中以字典形式定义子智能体。

THE END !

文章结束，感谢阅读。您的点赞，收藏，评论是我继续更新的动力。大家有推荐的公众号可以评论区留言，共同学习，一起进步。