Claude Agent SDK 实战指南：从零构建自定义 AI Agent
前言
AI 聊天机器人只能回答问题的时代已经过去了。2026 年的前沿是 AI Agent——自主规划、推理、调用工具、执行多步任务的程序，几乎不需要人工干预。据 Deloitte 的企业 AI 调研，超过 60% 的企业已在试点 Agentic AI 工作流，两年前这个数字不到 10%。从"AI 回答问题"到"AI 执行任务"的转变正在全面展开。
这场运动的核心是 Claude Agent SDK——Anthropic 发布的开源框架，给开发者提供了与 Claude Code 完全相同的工具链。如果你想构建一个能读文件、写代码、搜索网络、查询数据库并编排子任务的 Agent，这个 SDK 是从想法到生产的最短路径。
本文将从零开始构建自定义 AI Agent，连接真实世界的数据源（如电商 API），并部署到生产环境。
Claude Agent SDK 是什么？
Claude Agent SDK 是一个开源 Python 和 TypeScript 框架，用于在 Anthropic 的 Claude 模型之上构建 AI Agent。正如 Anthropic 在构建高效 Agent 的博客中所说，最好的 Agent 架构往往出人意料地简单——SDK 的设计理念正是如此。
SDK 开箱即用的内置工具包括：
- Read、Write、Edit — 文件系统操作：读取、创建和修改文件
- Bash — 执行 shell 命令，支持超时和后台运行
- Glob、Grep — 按模式快速搜索文件，按正则搜索内容
- WebSearch、WebFetch — 搜索互联网和获取网页内容
- Agent — 派生子 Agent，实现并行和委派执行
定价模式很直接：SDK 本身免费开源，你只需为 Agent 执行过程中消耗的 Claude API token 付费。这使得实验成本很低，同时可以随生产用量线性扩展。
Claude Agent SDK 区别于 LangChain 或 CrewAI 的关键在于与 Claude 原生工具调用能力的深度集成。没有中间翻译层——工具是模型推理循环中的一等公民。
搭建你的第一个 Agent
上手只需不到五分钟。安装 SDK：
pip install claude-agent-sdk
SDK 提供两个主要接口：query() 用于简单的一次性任务，ClaudeSDKClient 用于交互式有状态对话。对于大多数自动化场景，query() 就够了：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
model="claude-sonnet-4-6",
tools=["Read", "Write", "Bash", "WebSearch"],
)
async for message in query(prompt="分析 data.csv 中的销售数据并生成总结报告", options=options):
if hasattr(message, 'result'):
print(message.result)
asyncio.run(main())
Agent 运行时会进入自主循环：读取指令、决定调用哪些工具、执行操作、解读结果，循环往复直到任务完成。它可能用 Read 工具读取 data.csv，通过 Bash 运行 pandas 命令，再用 Write 生成 Markdown 报告——全程无需你指定步骤。
TypeScript 的使用同样简洁：
npm install @anthropic-ai/claude-agent-sdk
import { query } from "@anthropic-ai/claude-agent-sdk";
const messages = query({
prompt: "分析 data.csv 中的销售数据并生成总结报告",
options: {
model: "claude-sonnet-4-6",
tools: ["Read", "Write", "Bash", "WebSearch"],
},
});
for await (const message of messages) {
if (message.type === "result") {
console.log(message.result);
}
}
核心理念是：你不编排步骤——模型来编排。你描述目标，Agent 自行决定工具调用序列。这就是"会用工具的 LLM"和"真正的 Agent"之间的本质区别。
通过 MCP 连接外部数据源
内置工具覆盖了本地操作，但真实世界的 Agent 需要访问外部系统——数据库、API、SaaS 平台和专有数据源。这就是 Model Context Protocol（MCP） 的用武之地。
MCP 是一个开放标准，定义了 AI 模型如何连接外部工具和数据源。可以把它想象成 AI 的 USB-C 接口：任何 MCP 兼容的服务器都能接入任何 MCP 兼容的客户端。Claude Agent SDK 对 MCP 有一等支持。
接入电商数据的 MCP 集成
真正强大的是当你连接暴露丰富领域能力的 MCP 服务器。例如，连接 ZooData MCP 服务器，让你的 Agent 访问实时 Amazon 产品数据、市场分析和竞品情报：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
model="claude-sonnet-4-6",
mcp_servers={
"apiclaw": {
"type": "http",
"url": "https://api.apiclaw.io/mcp",
"headers": {"Authorization": "Bearer hms_xxx"},
}
},
)
async for message in query(
prompt="查找月销量超过 500 件、价格低于 $30 的瑜伽垫产品 Top 10",
options=options,
):
if hasattr(message, 'result'):
print(message.result)
asyncio.run(main())
Agent 会自动发现 MCP 服务器暴露的工具——产品搜索、关键词分析、市场趋势、竞品查询——并按需调用来完成指令。无需手动注册工具。
这种模式对电商自动化极其强大。想象一个 Agent 能够：
- 使用 ZooData 的市场数据搜索热门品类
- 识别需求超过供给的空白市场
- 分析竞品定价和评论情感
- 生成选品建议报告
所有这些，只需一条自然语言指令。
立即 安装 ZooData Skills 到你的 AI Agent 中 — 无需编写代码。
多 Agent 协作模式
单个 Agent 适合专注的任务，但复杂工作流适合将工作拆分到多个 Agent。Claude Agent SDK 的内置 Agent 工具原生支持这种模式。正如 Nader Dabit 的 Claude Agent SDK 指南所展示的，编排模式比你想象的要简单。
编排者-工作者模式
最常见的模式是一个编排 Agent 规划工作，然后委派给专门的子 Agent：
options = ClaudeAgentOptions(
model="claude-sonnet-4-6",
tools=["Agent", "Read", "Write"],
system_prompt="""你是一个调研编排者。将复杂的调研任务拆解为子任务，
委派给子 Agent。每个子 Agent 专注于一个具体方面。
最后将各方结果综合成一份完整报告。""",
)
async for message in query(
prompt="""调研美国瑜伽垫市场：
1. 按营收找出 Top 20 产品
2. 分析"瑜伽垫"相关关键词趋势
3. 识别定价甜区和市场空白
4. 总结发现并给出可执行建议""",
options=options,
):
if hasattr(message, 'result'):
print(message.result)
编排者调用 Agent 工具时，会派生一个独立运行的子 Agent。一个关键设计细节：子 Agent 内部的所有中间工具调用都被封装——只有最终结果消息返回给编排者。这让父 Agent 的上下文窗口保持整洁。
何时不需要多 Agent
不是每个问题都需要多个 Agent。Anthropic 的指导意见很明确：先用单个 Agent，只有当单个上下文窗口无法容纳完整任务时才加复杂度。子 Agent 会增加延迟和 token 成本，只在确实需要并行执行或专用工具集时才使用。
生产环境注意事项
从原型到生产会带来一系列 SDK 本身不解决的问题。以下是我们在部署 Agent 系统时总结的最有效模式。
成本控制
Agentic 工作流中 Claude API token 消耗很快，单个任务可能涉及数十次工具调用。SDK 提供了内置护栏：
options = ClaudeAgentOptions(
model="claude-sonnet-4-6",
max_turns=50, # 限制自主循环迭代次数
max_budget_usd=1.00, # 单次运行费用硬上限（$1）
)
对于多租户系统，在应用层追踪每个用户的 token 消耗并执行预算限制。
状态持久化
Agent 默认是无状态的——每次 query() 调用都从零开始。对于长时间运行的工作流或需要记忆的对话式 Agent，可以使用 ClaudeSDKClient 类进行会话管理，或外部持久化状态：
- Redis — 会话级状态（当前任务上下文、最近工具结果）
- PostgreSQL — 持久状态（对话历史、任务结果、审计日志）
- 对象存储 — 产出物（生成的报告、导出的文件）
错误处理和重试
Agentic 工作流本质上是非确定性的。相同的提示在不同运行中可能产生不同的工具调用序列。设计时要考虑韧性：
- 设置
max_turns防止无限循环 - 设置
max_budget_usd限制失控 Agent 的开支 - 记录所有工具调用和结果，便于调试
- 自动化管道使用
permission_mode="dontAsk"，需要人工监督时使用"default"
安全和权限
SDK 的权限系统控制 Agent 可以使用哪些工具以及允许哪些操作。生产部署建议：
options = ClaudeAgentOptions(
model="claude-sonnet-4-6",
allowed_tools=["Read", "Grep", "WebSearch"], # 白名单指定工具
disallowed_tools=["Bash"], # 显式禁止危险工具
permission_mode="dontAsk", # 自动化场景无交互提示
)
这确保 Agent 无法执行任意 shell 命令、修改系统文件，或访问超出预期范围的工具。
总结
Claude Agent SDK 消除了"AI 回答问题"和"AI 完成任务"之间的鸿沟。用 query() 做简单自动化，用 MCP 接入外部数据，用子 Agent 做复杂编排——你可以构建端到端处理真实世界工作流的生产级 Agent 系统。
最有价值的 Agent 不是最复杂的——而是连接了正确数据源的。一个通过 ZooData MCP 服务器访问结构化实时产品数据的 Agent，可以自动化竞品分析、定价优化和市场调研工作流，这些过去需要数小时的人工操作。