附录B：常见问题 FAQ
收集了学习和使用 AI Agent 过程中最常被问到的问题，每个都给你掰开揉碎了讲清楚。
1. Agent 和普通聊天机器人有什么区别？
一句话回答：聊天机器人只动嘴，Agent 能动手。
详细解释：
| 对比项 | 普通聊天机器人 | Agent |
|---|---|---|
| 交互方式 | 你问一句，它答一句 | 你给一个任务，它自己拆解、执行、完成 |
| 能不能用工具 | 不能，只能生成文字 | 能，可以执行代码、读写文件、调 API、查数据库 |
| 有没有自主性 | 没有，完全被动 | 有，能自己决定下一步干什么 |
| 能不能循环 | 不能，一问一答就结束 | 能，想-做-看循环，直到任务完成 |
| 典型场景 | 闲聊、问答 | 写代码、数据分析、自动化流程 |
举个例子：你问聊天机器人"北京今天天气怎么样？"，它只能根据训练数据猜一个（大概率是错的）。而 Agent 会去调用天气 API，拿到实时数据，然后告诉你准确的天气信息。
2. Agent 和 RAG 有什么区别？
一句话回答：RAG 是 Agent 的一种能力，不是同一个层面的东西。
详细解释：
- RAG（检索增强生成） 是一种技术方案——先从文档库里搜出相关内容，再把这些内容喂给 AI 让它回答。核心目的是让 AI 能回答训练数据里没有的内容（比如你公司的内部文档）。
- Agent 是一种应用形态——能自主决策、调用工具、循环执行的 AI 程序。
Agent 可以把 RAG 当作自己的一个工具来使用。比如一个客服 Agent，遇到用户问产品问题，就先用 RAG 从产品文档里搜出相关信息，然后再回答。但 Agent 还能做很多 RAG 做不了的事，比如帮用户下单、修改配置、执行代码等。
简单说：RAG 是"开卷考试"，Agent 是"全能助手"。RAG 只是助手工具箱里的一件工具。
3. 用 Claude Agent SDK 一个月大概要花多少钱？
一句话回答：看你用多少，从几块钱到几百美元都有可能。
详细费用估算（基于 2025 年 Claude API 定价）：
Claude 模型定价参考：
| 模型 | 输入价格（每百万 token） | 输出价格（每百万 token） |
|---|---|---|
| Claude Haiku 3.5 | $0.80 | $4.00 |
| Claude Sonnet 4 | $3.00 | $15.00 |
| Claude Opus 4 | $15.00 | $75.00 |
不同使用场景的月费估算：
| 使用场景 | 模型选择 | 预估月费 |
|---|---|---|
| 个人学习、跑教程示例 | Haiku 3.5 | $1 - $5 |
| 个人开发者日常使用 | Sonnet 4 | $10 - $50 |
| 小团队生产环境 | Sonnet 4 | $50 - $200 |
| 重度使用（大量 Agent 并行） | Opus 4 | $200 - $1000+ |
省钱技巧：
- 学习阶段用 Haiku，够用且便宜
- 用好 Prompt Caching，系统提示词缓存后成本降 90%
- 设置成本上限（maxTotalCost），防止 Agent 失控烧钱
- 控制上下文长度，定期清理不需要的对话历史
- 能用 Subagent + 小模型解决的子任务，就不要用大模型
注意：以上价格可能随时调整，请以 Anthropic 官方定价页面 为准。
4. 能用免费/开源模型替代 Claude 吗？
一句话回答：理论上可以，但效果会差不少。
详细解释：
Claude Agent SDK 的设计是基于 Claude 模型的能力的，特别是 Claude 的 Tool Use 能力。但如果你想用其他模型：
可行的替代方案：
- 通过兼容 API 适配：一些开源模型（如 Llama 3、Qwen 2.5、DeepSeek）通过 vLLM 或 Ollama 部署后，可以提供 OpenAI 兼容的 API，但需要自己做适配层
- 使用 OpenClaw/NanoClaw/ZeroClaw：本教程提到的这些项目就是简化版的 Agent SDK 实现，可以更容易地换模型
- 本地模型：用 Ollama 跑本地模型，零成本但效果有限
现实情况：
- 开源模型的 Tool Use / Function Calling 能力普遍不如 Claude 稳定
- Agent 需要模型有很强的指令遵循能力和长上下文理解能力，小模型容易出错
- 复杂任务（多步推理、多工具协同）基本只有一线大模型能胜任
- 简单任务（单工具调用、短对话）用开源模型可以凑合
建议：学习阶段先用 Claude（花不了多少钱），等理解了 Agent 原理后，再尝试用开源模型替换。
5. Agent 会不会失控？怎么防止？
一句话回答：有可能，但有很多防护手段。
可能的"失控"场景：
- Agent 进入死循环，一直调工具但完不成任务（烧钱）
- Agent 执行了不该执行的命令（比如
rm -rf /） - Agent 被 Prompt Injection 攻击，做了不该做的事
- Agent 产生幻觉，胡编乱造结果
防护措施（从简单到复杂）：
- 设置费用上限：
maxTotalCost参数，超过预算自动停止 - 限制循环次数：
maxTurns参数，最多循环多少次 - 权限控制：Permission Mode 设置，危险操作必须人工确认
- 沙箱隔离：让 Agent 在 Docker 容器里运行，搞不坏真实环境
- Hook 检查：在执行工具前用 Hook 检查命令是否安全
- 输入验证：对用户输入做过滤，防止 Prompt Injection
- 输出校验：对 Agent 的输出做检查，发现异常及时中断
- 日志监控：记录 Agent 的所有行为，事后可以审计
最佳实践：
开发阶段 -> 宽松权限，方便调试
测试阶段 -> 中等权限，逐步收紧
生产阶段 -> 严格权限 + 沙箱 + 监控 + 费用上限
6. Windows 能跑 Claude Agent SDK 吗？
一句话回答：能，但推荐用 WSL。
详细说明：
- 直接在 Windows 上跑：Claude Agent SDK 的 TypeScript 版和 Python 版理论上都支持 Windows，但可能遇到一些路径分隔符、命令兼容性之类的小问题
- 推荐用 WSL（Windows Subsystem for Linux）：在 Windows 上装一个 WSL2，就有了一个 Linux 环境，跟 Mac/Linux 上的体验一样，基本不会遇到兼容性问题
- Docker Desktop for Windows：如果用 Docker 跑 Agent，Windows 也完全支持
安装 WSL 的步骤：
# 以管理员身份打开 PowerShell
wsl --install
# 装好后重启电脑，打开 Ubuntu 终端
# 然后按照教程第三章的 Linux 环境设置步骤操作即可
IDE 推荐：VS Code + WSL 扩展，在 Windows 上写代码，在 WSL 里运行，两全其美。
7. 需要 GPU 吗？
一句话回答：不需要。
详细解释：
Claude Agent SDK 是调用 Anthropic 的云端 API，大模型是在 Anthropic 的服务器上跑的，你本地只是发请求和接收结果，一台普通笔记本就够了。
什么时候才需要 GPU：
- 你要在本地跑开源大模型（比如用 Ollama 跑 Llama）
- 你要做向量嵌入计算（但也可以调云端 API）
- 你要做模型微调（Fine-tuning）
本教程的所有内容，一台 4GB 内存的笔记本都能跑。主要消耗的是网络带宽而不是计算资源。
8. Claude Agent SDK 和 Anthropic API SDK 有什么区别？
一句话回答：Anthropic API SDK 是"发动机"，Claude Agent SDK 是"整车"。
对比：
| 对比项 | Anthropic API SDK | Claude Agent SDK |
|---|---|---|
| 是什么 | API 调用的封装库 | Agent 开发的完整框架 |
| 做什么 | 发消息、收回复 | 构建完整的 Agent 应用 |
| 有没有循环 | 没有，调一次收一次 | 有，内置 Agentic Loop |
| Tool Use | 你自己实现调度逻辑 | 框架自动处理 |
| 会话管理 | 你自己管理 | 框架提供 |
| 适合谁 | 想自己造轮子的人 | 想快速搭 Agent 的人 |
关系：Claude Agent SDK 底层就是调用 Anthropic API SDK。就像 React 底层用了 JavaScript DOM API 一样——你可以直接用 DOM API 写网页，但用 React 更高效。
选择建议：
- 学习 Agent 原理 -> 先用 Anthropic API SDK 手写一遍，理解底层
- 快速开发 Agent 应用 -> 用 Claude Agent SDK
- 两个都学了最好
9. 什么时候该用 Agent，什么时候不该用？
该用 Agent 的场景：
- 任务需要多步骤、多工具协作（比如"分析这个 CSV 文件，找出异常数据，生成报告"）
- 任务的步骤不确定，需要根据中间结果动态决策
- 重复性的自动化流程（比如每天自动审查 PR、生成日报）
- 需要与多个系统交互的复杂工作流
不该用 Agent 的场景：
- 简单的一问一答（直接调 API 就行，不需要 Agent 的循环开销）
- 确定性流程（步骤完全固定的任务，写个脚本更可靠）
- 对延迟要求极高的场景（Agent 需要多轮思考，比直接调 API 慢）
- 不能容忍任何错误的关键场景（Agent 有概率出错，人命关天的事别全交给 AI）
判断标准：如果你能用 if-else 把流程完全写死，那就不需要 Agent。如果流程中有"看情况决定"的部分，Agent 就有用武之地。
10. Agent 的上下文窗口满了怎么办？
一句话回答：要么压缩，要么分段，要么用外部存储。
具体策略：
上下文压缩/摘要：让 AI 把之前的对话总结成一段摘要，用摘要替代原始对话。Claude Agent SDK 支持自动上下文管理。
滑动窗口：只保留最近的 N 轮对话，旧的自动丢弃。适合实时对话场景。
分段处理：把大任务拆成多个小任务，每个小任务用独立的 Session。Subagent 就是干这个的。
外部存储：重要信息存到文件或数据库里，需要时让 Agent 用工具去读取，而不是全放在上下文里。
Prompt Caching：把不变的系统提示词缓存起来，虽然不减少上下文大小，但能减少 token 消耗和成本。
Fork Session：当上下文快满时，fork 一个新 session，把关键信息带过去，从"干净"的状态继续。
预防胜于治疗：
- 给工具的返回结果做截断，别把整个文件内容都塞进上下文
- 让 Agent 每完成一个子任务就把结果写入文件，而不是记在脑子里
- 合理使用 Subagent，每个 Subagent 有独立的上下文
11. 怎么降低 Agent 的使用成本？
按效果排序的省钱方法：
- 选对模型：简单任务用 Haiku（便宜 20 倍），只有复杂任务才用 Opus
- 用 Prompt Caching：系统提示词开启缓存，反复使用的提示词成本降 90%
- 控制上下文长度：别让上下文无限膨胀，及时清理无用的历史
- 用 Subagent + 小模型：主 Agent 用 Sonnet 统筹，Subagent 用 Haiku 干活
- 设置费用上限：
maxTotalCost防止意外烧钱 - 优化工具返回：工具返回结果做截断，别返回一大堆无用信息
- 批量处理：能批量做的事别一个一个做，减少 API 调用次数
- 缓存重复请求：相同的问题不要重复问 AI，在应用层做缓存
- 用结构化输出：让 AI 返回精确的 JSON，而不是一大段废话
实际案例：一个代码审查 Agent，优化前每次审查花 $0.50，优化后（Prompt Caching + Subagent + 截断返回）降到 $0.08。
12. MCP 和直接调 API 有什么区别？
一句话回答：MCP 是标准化的工具接口，直接调 API 是自己写适配代码。
对比：
| 对比项 | 直接调 API | 用 MCP |
|---|---|---|
| 接入方式 | 每个 API 写一套调用代码 | 统一接口，即插即用 |
| 工具描述 | 你自己写 JSON Schema | MCP Server 自动提供 |
| 可复用性 | 你写的代码只有你能用 | MCP Server 所有人都能用 |
| 生态 | 没有 | 越来越多现成的 MCP Server |
| 学习成本 | 每个 API 都要看文档 | 学一次 MCP 协议就够了 |
| 适用场景 | 简单、一次性的集成 | 需要接入多个工具的场景 |
什么时候用 MCP：
- 你需要接入多个外部服务
- 已经有现成的 MCP Server
- 你希望工具可以在不同项目中复用
什么时候直接调 API：
- 只需要接入一两个简单的 API
- 没有现成的 MCP Server，也不想自己写
- 追求最简单最直接的方案
13. Subagent 最多能嵌套几层？
一句话回答：技术上没有硬性限制，但实际上不建议超过 2-3 层。
详细解释：
Claude Agent SDK 没有规定 Subagent 的最大嵌套深度。理论上 Agent A 可以创建 Agent B，B 创建 C，C 创建 D……
但实际限制来自：
- 成本：每层 Subagent 都要消耗 token，嵌套越深越贵
- 延迟：每层 Subagent 都需要时间思考和执行，嵌套越深越慢
- 可靠性：每层都有出错的概率，嵌套越深，整体出错的概率越大
- 可调试性：层数越多越难排查问题
推荐的模式：
主 Agent（统筹协调）
├── Subagent 1（搜索资料）
├── Subagent 2（写代码）
├── Subagent 3（跑测试）
└── Subagent 4（写文档）
扁平优于深层嵌套——一个主 Agent 管多个并行的 Subagent，而不是一层套一层。
14. Agent 能访问互联网吗？
一句话回答：不能直接上网，但可以通过工具间接上网。
详细解释：
Claude 模型本身不能上网，它只能根据训练数据回答问题。但 Agent 可以通过工具来访问互联网：
- 通过 MCP Server：比如用
fetchMCP Server 来抓取网页、调用 API - 通过自定义工具：你写一个工具函数，里面调用
fetch/requests，Agent 就能通过这个工具访问互联网 - 通过命令行：如果 Agent 有执行命令的权限，可以用
curl等命令抓取网页
安全提醒：
- 让 Agent 上网要特别小心，因为网页内容可能包含 Prompt Injection 攻击
- 建议对抓取的内容做清洗和过滤再喂给 Agent
- 生产环境中要限制 Agent 能访问的域名
15. 怎么让 Agent 记住之前的对话？
一句话回答：用会话存储或者外部记忆系统。
几种方案：
Session 持久化：Claude Agent SDK 支持保存和恢复 Session，下次可以 Resume 继续聊。最简单，但上下文有限。
文件系统记忆：让 Agent 把重要信息写入文件（比如
memory.md），下次启动时先读这个文件。简单粗暴但有效。数据库记忆：用 SQLite 或其他数据库存储对话历史和关键信息，Agent 通过工具查询。
向量数据库：用 RAG 方案，把历史对话和知识存成向量，每次对话时搜出最相关的内容放进上下文。
摘要记忆：定期让 AI 把对话历史总结成摘要，下次对话时带上摘要而不是全部历史。
推荐方案：
- 短期记忆（同一任务内）-> Session 自带的上下文
- 中期记忆（跨会话）-> 文件系统 + Resume
- 长期记忆（永久知识）-> 数据库 + RAG
16. Agent 写代码靠谱吗？
一句话回答：简单代码很靠谱，复杂代码需要人审核。
实际体验：
| 代码类型 | 靠谱程度 | 说明 |
|---|---|---|
| 简单函数/脚本 | 很靠谱（90%+） | 常见模式，模型见过很多 |
| CRUD 接口 | 靠谱（85%+） | 模板化程度高 |
| 单元测试 | 靠谱（80%+） | 适合 AI 的结构化任务 |
| 复杂业务逻辑 | 一般（60-70%） | 需要理解业务细节 |
| 系统架构设计 | 需要谨慎（50-60%） | AI 可能过度设计 |
| 性能优化 | 需要人工审核 | AI 不擅长性能瓶颈分析 |
最佳实践：
- 让 Agent 写代码后跑一遍测试
- 关键代码人工 review
- 用"写代码 -> 跑测试 -> 看报错 -> 修代码"的循环，让 Agent 自己迭代
- 提供清晰的需求和示例，AI 就能写得更好
17. 有没有中文文档？
一句话回答：官方暂时没有完整中文文档，但有一些资源。
目前可用的中文资源：
- 本教程：你正在读的这套教程就是全中文的
- Anthropic 官方文档：目前只有英文，但可以用翻译工具辅助阅读
- 社区翻译：GitHub 上有一些社区维护的中文翻译
- Claude 自己：你可以直接用中文问 Claude 任何 API 和 SDK 的使用问题，它能很好地用中文回答
小窍门：遇到英文文档看不懂的地方，直接复制给 Claude 说"用大白话翻译一下这段文档"，效果比机翻好很多。
18. OpenClaw、NanoClaw、ZeroClaw 怎么选？
一句话回答：看你的技术栈和需求深度。
| 项目 | 语言 | 定位 | 适合谁 |
|---|---|---|---|
| OpenClaw | TypeScript | 最完整的开源复刻 | 想深入了解 Claude Code 架构的人 |
| NanoClaw | TypeScript | 精简版，核心功能 | 想快速上手、基于此二次开发的人 |
| ZeroClaw | Python | 从零实现的 Python 版 | Python 开发者、想理解底层原理的人 |
选择建议：
- 如果你是 TypeScript 开发者，想参考成熟实现 -> OpenClaw
- 如果你是 TypeScript 开发者，想要轻量起步 -> NanoClaw
- 如果你是 Python 开发者 -> ZeroClaw
- 如果你是 纯学习目的 -> 三个都看看，对比着学效果最好
19. Claude Agent SDK 支持哪些编程语言？
一句话回答：官方支持 TypeScript 和 Python。
详细说明：
- TypeScript 版：
@anthropic-ai/claude-code-sdk，功能最完整，更新最快，毕竟 Claude Code 本身就是 TypeScript 写的 - Python 版：
claude-code-sdk，适合 Python 开发者，功能与 TypeScript 版基本对齐
其他语言：
- 官方没有 Go、Java、Rust 等版本的 Agent SDK
- 但 Anthropic API SDK 支持更多语言（Python、TypeScript、Go、Java 等）
- 你可以基于 Anthropic API SDK 自己搭建 Agent 框架（本教程就教你这个）
- 任何能发 HTTP 请求的语言都能调用 Claude API，只是需要自己实现 Agentic Loop
20. 学完这套教程后应该去哪里继续学习？
循序渐进的学习路径：
第一步：动手做项目
- 别只看不做，把教程里的代码全部跑一遍
- 在教程的基础上改改，做一个自己的小项目
- 推荐入门项目：个人知识库助手、自动化代码审查工具、日报生成器
第二步：深入官方文档
- Anthropic 官方文档 —— API 的权威参考
- Claude Agent SDK GitHub —— 看源码、看 examples
- MCP 规范 —— 深入理解 MCP
第三步：跟进前沿动态
- 关注 Anthropic 官方博客
- 关注 GitHub 上 Claude Agent SDK 的 Release Notes
- 加入 Discord 社区，和其他开发者交流
第四步：扩展技术栈
- 学习 LangChain、LlamaIndex 等其他 Agent 框架，对比思路
- 了解 OpenAI Agents SDK、Google ADK 等竞品
- 学习 Prompt Engineering 的高级技巧
- 如果做生产项目，还需要学习部署、监控、安全等运维知识
第五步：参与社区
- 给 Claude Agent SDK 提 Issue 或 PR
- 写自己的 MCP Server 并开源
- 写博客分享你的经验
- 在社区里帮助其他新手
记住：AI Agent 这个领域发展极快，你看到的"最佳实践"可能半年后就过时了。保持学习的习惯比记住具体的 API 更重要。
21. 为什么我的 Agent 老是不按预期调用工具？
常见原因和解决方法：
工具描述不清楚：工具的
description写得太简单，AI 不知道什么时候该用。解决：写清楚工具干什么、什么情况下该用、参数是什么意思。工具太多：一次注册了太多工具，AI 选择困难。解决：减少工具数量，或者用 Tool Search 按需加载。
System Prompt 没写好：没有明确告诉 AI 应该怎么使用工具。解决：在 System Prompt 中加入示例和规则。
参数格式不对：JSON Schema 定义有问题，AI 传的参数不符合预期。解决：检查 Schema 定义，用 Zod/Pydantic 做验证。
模型能力不足：用了 Haiku 做复杂的多工具协调。解决：换 Sonnet 或 Opus。
22. Agent 执行任务时报错了，怎么排查？
排查步骤：
看日志：首先看 Agent 的输出日志，一般会打印 AI 的思考过程和工具调用记录
检查工具返回：看工具返回了什么。很可能是工具本身出了错（API 超时、权限不足等）
检查上下文：看看是不是上下文太长被截断了，导致 AI 丢失了关键信息
隔离测试：把出错的那一步单独拿出来测试，确认是 AI 的问题还是工具的问题
看 API 响应：如果怀疑是 API 层面的问题，用
console.log或断点看原始的 API 请求和响应简化复现：用最简单的输入复现问题，排除干扰因素
常见错误：
rate_limit_error：请求太频繁，等一会儿再试overloaded_error：Anthropic 服务器繁忙，稍后重试context_length_exceeded：上下文超了，需要压缩- 工具返回
error：检查工具实现代码
23. 能不能让多个 Agent 一起协作？
一句话回答：可以，这就是 Agent Swarm（智能体群）。
协作模式：
主从模式（最常用）：一个主 Agent 分配任务，多个 Subagent 执行
主 Agent: "分析这个项目" ├── Subagent A: 分析代码质量 ├── Subagent B: 分析安全漏洞 └── Subagent C: 分析性能瓶颈 主 Agent: 汇总三个报告流水线模式：A 做完交给 B，B 做完交给 C
Agent A (研究) -> Agent B (编码) -> Agent C (测试)对等协作：多个 Agent 角色平等，通过消息通道协调
注意事项：
- 协作的 Agent 越多越难调试
- 成本是单个 Agent 的 N 倍
- 从简单开始，确认单个 Agent 能力后再扩展到多 Agent
还有问题？ 直接问 Claude 就好——毕竟它就是你的 AI 助手。把问题描述清楚，它大概率能帮你解决。