Claude Agent SDK

Claude Agent SDK 快速入门

一句话卖点：Anthropic 把 Agent 能力从”附赠功能”升级为”独立产品”，用一套 SDK 就能让 Claude 变成能自己干活、能管子 Agent、能接企业治理的”数字员工”。

这是什么？适合谁？

Claude Agent SDK 是 Anthropic 于 2026 年推出的独立计费 Agent 开发套件。在此之前，Agent 能力（如 Computer Use、Tool Use）只是 Claude API 的附加功能；而 Agent SDK 将其升级为独立商业品类，拥有自己的计费模型、治理框架和生命周期管理。

核心能力包括：

• query() 原语：统一的 Agent 调用接口，一条 query 即可触发多步骤自主任务；
• 生命周期 Hooks：在 Agent 执行前/中/后插入自定义逻辑（如审批、审计、日志）；
• 子 Agent 编排：主 Agent 可创建和调度多个子 Agent，各自拥有独立上下文；
• 治理 Schema：定义 Agent 的权限边界、可调用工具白名单、预算上限；
• 流式输出：实时获取 Agent 的思考过程、工具调用和中间结果；
• 独立计费：与 Claude 订阅分离，按 Agent 执行步数和资源消耗计费。

适合谁？企业开发者——需要将 Agent 集成到生产系统并实现合规治理；SaaS 厂商——想在产品中嵌入可控的 AI Agent 能力；安全合规团队——需要对 Agent 行为进行审计和权限管控的团队。

不适合纯个人探索或一次性对话场景——那种情况直接用 Claude.ai 或 Claude API 更简单。

准备工作

1. Anthropic API Key：从 console.anthropic.com 获取；
2. Agent SDK 许可证：Agent SDK 需要单独开通，与普通 API Key 不同，需联系 Anthropic 销售或通过控制台申请；
3. Python 3.10+ 或 Node.js 18+：SDK 提供 Python 和 TypeScript 两种绑定；
4. 企业治理需求文档（可选但推荐）：明确 Agent 的权限边界、预算上限、审批流程，方便直接映射到治理 Schema。

3 步快速上手

第 1 步：安装 SDK

Python 用户：

pip install anthropic-agent-sdk

Node.js 用户：

npm install @anthropic/agent-sdk

验证安装：

python -c "import anthropic_agent; print(anthropic_agent.__version__)"

第 2 步：配置 Agent 并定义治理 Schema

创建一个 Agent 配置文件 agent_config.yaml：

agent:
  name: "客服工单处理Agent"
  model: "claude-sonnet-4-20250514"
  max_steps: 20
  budget_cap: 5.00  # 单次任务最大花费 $5

governance:
  allowed_tools:
    - "search_knowledge_base"
    - "create_ticket"
    - "send_email"
  forbidden_actions:
    - "delete_ticket"
    - "modify_billing"
  require_approval_for:
    - "send_email"  # 发邮件需人工审批

hooks:
  pre_execution:
    - log_audit_trail
    - check_budget
  post_execution:
    - validate_output
    - update_dashboard

第 3 步：发起第一个 Agent 任务

from anthropic_agent import AgentClient

client = AgentClient(
    api_key="sk-ant-agent-xxx",  # Agent SDK 专用 Key
    config="agent_config.yaml"
)

# 用 query() 原语发起任务
result = client.query(
    prompt="处理今天收到的 15 条客户投诉工单，分类优先级，给高优工单自动回复确认邮件",
    sub_agents=[
        {"name": "分类器", "task": "按紧急度排序工单"},
        {"name": "回复生成器", "task": "为高优工单起草回复邮件"}
    ],
    stream=True  # 实时查看 Agent 思考和工具调用
)

for event in result:
    print(f"[{event.type}] {event.content}")

print(f"\n任务完成！消耗预算: ${result.cost:.2f}")

常见踩坑

1. API Key 权限不足：Agent SDK 需要专门的 Agent 级 Key（前缀 sk-ant-agent-），普通 API Key（sk-ant-）无法使用 Agent SDK 的全部功能；
2. 预算超限导致任务中断：Agent 执行到一半发现预算用完，任务直接中断——在治理 Schema 里把 budget_cap 设得太低是新手常见错误；
3. 子 Agent 上下文丢失：子 Agent 默认不共享主 Agent 的上下文，需要在 sub_agents 配置里显式传递 shared_context；
4. 审批 Hook 阻塞：配置了 require_approval_for 但没有实现审批回调，Agent 会一直等待直到超时；
5. 流式输出乱序：stream=True 时事件可能乱序到达，生产环境务必用 event.timestamp 排序；
6. 模型版本不兼容：Agent SDK 最低要求 Claude Sonnet 4 及以上模型，Haiku 3.5 等早期模型不支持 Agent 原语。

初级用法

• 自动化工单处理：Agent 读取 Zendesk / Jira 工单，自动分类、打标签、分配给对应工程师；
• 代码审查 Agent：收到 Pull Request 后 Agent 自动跑测试、检查代码规范、在评论区输出审查意见；
• 定时报告生成：Agent 每天 9 点从数据库拉数据，生成日报发到 Slack 频道；
• 知识库问答：Agent 接入公司 Confluence / Notion，员工用自然语言提问即可获得带引用来源的回答。

高级玩法

• 多 Agent 研发团队：用主 Agent 扮演 PM，下设”前端 Agent""后端 Agent""测试 Agent”三个子 Agent，各自负责不同模块，PM Agent 负责协调；
• 动态治理调整：在 post_execution Hook 里根据 Agent 的历史表现动态调整 max_steps 和 budget_cap——高风险 Agent 自动收紧、稳定 Agent 自动放宽；
• 合规审计链：每个 Agent 操作的输入/输出/工具调用全量写入审计日志，接入 SIEM（如 Splunk），满足 SOC2 / HIPAA 合规要求；
• 跨平台 Agent 联邦：Agent SDK 的治理 Schema 可导出为 Open Policy Agent（OPA）格式，与 Kubernetes、Terraform 等基础设施集成。

小技巧

1. 先用 Claude.ai 验证思路，再用 SDK 落地：Agent SDK 的计费是独立的，直接在生产环境试错成本高。先在 Claude.ai 或 Workbench 里用自然语言验证任务可行性，确认没问题再用 SDK 代码化；
2. budget_cap 设”软上限+硬上限”两层：软上限（80%）发送告警，硬上限（100%）中断任务，避免任务跑了 90% 才发现预算不够；
3. 子 Agent 命名要有业务含义：sub_agents[0].name 不要叫 agent_1，叫 工单分类器 或 邮件起草器，日志和审计里一目了然；
4. 善用 post_execution Hook 做质量检查：Agent 完成任务后自动跑一遍 validate_output（比如检查邮件是否包含退订链接），不合格自动重试；
5. 关注 Anthropic 的 Agent SDK 更新：Agent SDK 是 Anthropic 2026 年的战略产品，迭代非常快，建议订阅 Anthropic 邮件列表 或关注其 Changelog。

常见问题 FAQ

Q1: Claude Agent SDK 和普通 Claude API 有什么区别？

A: 普通 Claude API 是”一问一答”的对话接口，你需要自己管理上下文、工具调用、多步执行。Agent SDK 提供了完整的 Agent 运行时：统一的 query() 原语、子 Agent 编排、生命周期 Hooks、治理 Schema、流式输出。简单类比：API 是”发动机”，Agent SDK 是”整车”。

Q2: Agent SDK 如何计费？

A: Agent SDK 的计费与 Claude 订阅独立，采用 按执行步数 + 资源消耗 双重计费：(1) 每步 Agent 操作（工具调用、子 Agent 调度、Hook 执行）按模型 token 消耗计费，约 $0.01-0.05/步；(2) 子 Agent 按各自消耗累加计入总账单；(3) 治理功能（审计日志、Schema 校验）有少量额外费用。详细定价见 Anthropic 定价页，建议联系销售获取企业报价。

Q3: Agent SDK 需要有 Agent 经验吗？

A: 不需要。如果你用过 Claude API 或 Claude.ai，上手 Agent SDK 的核心差异就是多学了几个概念（query 原语、Hooks、治理 Schema）。Anthropic 官方文档提供了完整的 Quickstart 和示例项目，从第一个 Agent 到生产部署大约需要 2-3 天。

Q4: Agent SDK 支持哪些编程语言？

A: 官方支持 Python 和 TypeScript/JavaScript。Python SDK 最成熟，功能最全；TypeScript SDK 紧随其后。社区有非官方的 Go 和 Rust 绑定，但功能覆盖不全。

Q5: 子 Agent 之间如何通信？

A: 子 Agent 之间通过主 Agent 中转——每个子 Agent 的 query() 结果返回给主 Agent，主 Agent 决定是否传递给其他子 Agent。如果需要子 Agent 直接通信，可以在治理 Schema 的 allowed_tools 里添加 send_message_to_agent 工具。

参考链接

• Claude Agent SDK 官方文档：https://docs.anthropic.com/en/docs/agents-and-tools/agent-sdk
• Anthropic 控制台：https://console.anthropic.com
• Anthropic 定价：https://www.anthropic.com/pricing
• Claude API 文档：https://docs.anthropic.com/en/api
• Anthropic 博客：https://www.anthropic.com/news