阅读来源：Claude Agent SDK 完全指南

一、核心定位：从 “问答” 到 “干活”

Claude Agent SDK 是将 Claude Code 的全部能力封装成的可编程库，它解决了基础 API 无法实现的 “自主完成复杂任务” 的需求：

• 基础 API/SDK：“你问它答”，仅能实现对话、简单工具调用

• Agent SDK：“你下单它干活”，Claude 可自主执行工具、迭代任务，直到任务完成

它可以让 Claude 自主完成读文件、跑命令、搜代码、改 Bug、验证结果等全流程工作，无需开发者手动处理工具调用循环。

二、核心对比：它和其他方案有什么不同？

1. 与基础 anthropic SDK 的区别

对比项	基础 anthropic SDK	Claude Agent SDK
工具执行	开发者自行实现	Claude 自主执行
工具循环	开发者自行维护	内置 Agent Loop
内置工具	无，需自行定义	读写文件、Bash、搜索等开箱即用
上下文管理	开发者自行维护	自动压缩、自动管理
适合场景	聊天、生成、简单 tool use	自主完成复杂任务

代码示例对比：

• 基础 SDK：需要开发者手动写循环处理工具调用、结果回传

• Agent SDK：一行调用即可，Claude 自动完成全流程

2. 与其他 Agent 框架的区别

框架	最适合的场景
Claude Agent SDK	让 Claude 自主完成代码开发、文件操作、命令执行
LangChain	构建复杂的通用 AI 应用，需要高度自定义流程
CrewAI	模拟多角色协作场景（如虚拟团队、角色扮演）
LlamaIndex	检索增强生成（RAG）场景

三、核心概念

Agent SDK 的运行原理：收集上下文 → 执行动作 → 验证结果 → 重复，和人类开发者的工作流程完全一致。

两种使用模式

1. query()** 函数：无状态，单次任务**
   适合一次性的独立任务，无需保留上下文。

   async for message in query(
       prompt="这个目录下有哪些文件？",
       options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
   ):
       if hasattr(message, "result"):
           print(message.result)
   

2. ClaudeSDKClient****：有状态，多轮对话
   适合需要保留上下文的多轮交互，比如先读模块再找调用点，第二轮会保留第一轮的上下文。
   通过 session_id 恢复会话状态实现。

四、内置工具：开箱即用的能力

Agent SDK 内置了大量常用工具，无需开发者自行实现，通过 allowed_tools 可以控制 Agent 的工具权限：

工具	功能	典型用途
Read	读取文件	查看代码、配置文件
Write	创建文件	生成新代码、报告
Edit	精确编辑文件	修复 Bug、代码重构
Bash	执行终端命令	跑测试、装依赖、Git 操作
Glob	按模式查找文件	批量匹配代码文件
Grep	正则搜索文件内容	查找函数定义、TODO
WebSearch	网页搜索	查询文档、技术方案
WebFetch	抓取网页内容	读取在线文档
Task	启动子 Agent	并行处理子任务

权限控制示例：

# 只读 Agent：仅能查看，无法修改
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="bypassPermissions"
)

五、高级功能

1. Hooks：自定义执行节点逻辑

可以在 Agent 执行的关键节点插入自定义代码，实现审计、拦截、通知等能力：

• 支持的 Hook 类型：PreToolUse（工具执行前）、PostToolUse（工具执行后）、Stop、SessionStart、SessionEnd 等

• 典型用途：审计日志、安全拦截、通知推送、成本监控

2. 子 Agent：任务拆分与专家协作

可以定义多个专门的子 Agent，主 Agent 自动分配子任务，每个子 Agent 有独立的指令和工具权限，互不干扰，适合复杂大任务的拆分。

3. MCP 集成：接入外部系统

通过 Model Context Protocol（MCP），可以让 Agent 连接数据库、浏览器、第三方 API 等外部系统，社区已有数百个可直接使用的 MCP 服务器：

• 常见场景：Playwright 浏览器自动化、数据库操作、Slack / 邮件通知、GitHub 仓库操作等

六、实战场景

经过社区验证的典型落地场景：

场景	核心工具	难度
自动修 Bug	Read, Edit, Bash, Grep	入门
代码审查	Read, Glob, Grep	入门
CI/CD 自动修复	Read, Edit, Bash	中级
技术调研报告	WebSearch, WebFetch, Write	入门
浏览器自动化	MCP (Playwright)	中级
多 Agent 协作	Task + AgentDefinition	高级
数据库操作	MCP (PostgreSQL/MySQL)	中级
邮件 / 通知助手	MCP (Slack/Email)	中级

典型场景示例

1. 自动修 Bug Agent：给 Bug 描述，Agent 自动找代码、定位问题、修复、跑测试验证

2. 代码审查 Agent：只读权限，审查代码的安全漏洞、性能问题、规范问题

3. CI/CD 集成：在流水线中自动分析失败测试、尝试修复

4. 研究 Agent：自动搜索网络、读文档，输出技术选型报告

5. 全栈 Agent：结合 MCP 操作浏览器，写完代码后自动验证效果

七、适用场景选择

不是所有场景都需要 Agent SDK，根据需求选择合适的工具：

你想做的事	推荐工具
简单对话、文本生成、翻译	基础 anthropic SDK
单次 tool use（查天气、算数）	基础 anthropic SDK
自主完成多步骤开发任务	Agent SDK
嵌入 CI/CD 流水线	Agent SDK
构建能操作文件系统的应用	Agent SDK
日常交互式开发	Claude Code CLI
一次性快速任务	Claude Code CLI

八、企业级设计思考

Agent SDK 可以构建企业级的自动化流水线，核心设计原则：

1. 权限最小化：不同 Agent 分配不同权限，比如审查 Agent 仅只读，修复 Agent 才有写权限

2. 可审计：通过 Hook 记录所有操作，问题可回溯

3. 结果串联：上一个 Agent 的输出作为下一个的输入，形成流水线

4. 成本可控：通过 max_turns、预算限制防止失控

5. 可扩展：可灵活添加新的环节，比如文档检查、性能测试

九、总结

Claude Agent SDK 的核心价值是把 “模型推理” 升级为 “可控执行”，它不只是生成文本，而是能在可审计、可约束的系统中真正完成任务。

其设计哲学是：给 agent 一台电脑，让它像人一样工作。

好的 Agent 应用 = 清晰的工具设计 + 明确的任务边界 + 适当的人工监督，三者缺一不可。

参考资料

官方资源

• Agent SDK 官方文档

• GitHub - claude-agent-sdk-python

• GitHub - claude-agent-sdk-typescript

• 示例 Agent 项目

博客与教程

• Building agents with the Claude Agent SDK

• Claude Agent SDK Python 学习指南