Claude API开发实战：从claude-quickstarts仓库到Tool Use和Agent的完整指南

Anthropic官方出的Claude API示例项目集合，11k+ Star。我建议每个想用Claude API做应用的开发者都先把里面的示例跑一遍。

先聊一个问题：为什么要看这个仓库

Claude API的文档写得还行，API Reference、Quickstart Guide、Conceptual Guide都有。但光看文档你会漏掉很多东西。

比如Tool Use，文档告诉你怎么定义工具schema、怎么处理工具调用响应。但没告诉你的是：Claude可能会连续调用同一个工具三次然后死循环；工具调用失败的时候你需要怎么回退；多个工具同时可用的时候Claude的选择逻辑是什么。

比如RAG，文档告诉你Claude支持200K tokens的上下文窗口。但没告诉你的是：你塞太多检索结果进去，Claude反而会"迷路"，回答质量不升反降。

这些东西，看代码比看文档快十倍。而claude-quickstarts仓库就是Anthropic官方写的"最佳实践代码"。

项目地址：https://github.com/anthropics/claude-quickstarts

仓库里有什么

这个仓库不是单个项目，而是一堆独立的quickstart子项目，每个子项目都是一个完整可运行的应用。我按重要程度排一下：

1. 基础对话（重要程度：⭐⭐）

最简单的Claude API调用，展示流式输出、系统提示词设置、多轮对话的实现方式。

cdquickstarts/basic-conversation pipinstall-rrequirements.txtexportANTHROPIC_API_KEY="your-api-key"python main.py

代码本身没什么好看的，几行就搞定了。但里面的错误重试逻辑值得参考——API调用会有rate limit、网络超时等情况，官方的处理方式是指数退避重试，这个模式可以直接复用。

2. Tool Use（重要程度：⭐⭐⭐⭐⭐）

这是我重点推荐的部分。

Tool Use的核心不是"调用一个函数"，而是一个对话循环。流程是这样的：

用户提问 → Claude决定是否调用工具 → 你执行工具 → 把结果返回给Claude → Claude生成最终回答

工具的定义方式：

tools=[{"name":"get_weather","description":"Get the current weather in a given location","input_schema":{"type":"object","properties":{"location":{"type":"string","description":"City name"}},"required":["location"]}}]

调用Claude的时候把tools参数传进去，Claude的响应里会告诉你它要不要调用工具、调用哪个、传什么参数。你需要自己执行工具调用，然后把结果再发给Claude。

官方示例里的实现很完整，覆盖了以下情况：

• Claude决定不调用工具，直接回答
• Claude调用一个工具
• Claude连续调用多个工具
• 工具调用结果的格式化

这个模式可以直接用在生产环境。我做数据库查询Agent的时候就是参考这个实现的。

3. RAG应用（重要程度：⭐⭐⭐⭐）

检索增强生成的完整实现，包含：

• 文档切分（chunking）
• 向量存储（embedding + vector store）
• 语义检索（semantic search）
• 上下文拼接
• 回答生成

几个值得学习的设计：

top-k检索：不是把所有文档都塞给Claude，而是只检索最相关的k个片段。k值太大（比如20个）会稀释相关信息，k值太小（比如2个）可能遗漏关键信息。示例里默认用的是5，这个值在大多数场景下是合理的。

相关性评分：检索结果不是直接拼接，而是先做相关性评分，低于阈值的直接丢弃。这避免了"检索到了但不相关"的噪音。

上下文窗口管理：即使Claude支持200K tokens，也不意味着你应该把所有检索结果都塞进去。示例里有明确的token计数和截断逻辑。

4. Agent应用（重要程度：⭐⭐⭐⭐）

包含工具调用循环、多步规划等Agent核心模式。

Agent和普通的Tool Use有什么区别？普通的Tool Use是"用户问一个问题，Claude调一次工具，回答"。Agent是"Claude自己决定要调用几次工具、以什么顺序调用，直到它认为任务完成"。

示例里的Agent实现有几个关键设计：

最大轮次限制：防止Claude无限循环地调用工具。这个很重要，我在后面会详细说。

任务完成判断：Claude会在每一步判断"我是否已经完成了任务"，如果完成了就停止，不需要你手动判断。

中间结果传递：每一步的工具调用结果会传递给下一步的Claude调用，形成上下文。

我踩过的坑

坑1：Tool Use的死循环

这是我遇到的最坑的问题。

我在做一个数据库查询Agent：用户用自然语言提问，Claude把问题转成SQL，执行查询，返回结果。听起来很简单对吧？

但Claude有时候会这样：

1. 用户问"上个月的销售额是多少"
2. Claude调用工具执行SQL查询
3. 返回结果：“上个月销售额为100万元”
4. Claude觉得不够详细，又调用一次工具，换个SQL查更细的数据
5. 返回结果
6. Claude还是觉得不够，再调一次……
7. 循环到对话轮次超限

原因分析：Claude的"追求完美"有时候会过度。它会不断地想"我是不是还能提供更多信息"，然后反复调用工具。

解决方案：

MAX_TOOL_ROUNDS=5# 最大工具调用轮次foriinrange(MAX_TOOL_ROUNDS):response=client.messages.create(model="claude-sonnet-4-20250514",messages=messages,tools=tools,max_tokens=1024)ifresponse.stop_reason=="end_turn":# Claude认为任务完成，跳出循环breakifresponse.stop_reason=="tool_use":# 执行工具调用，把结果加入messages# ...pass

另外，在系统提示词里加一句"如果已经获取到足够信息，直接回答，不要重复查询"也有帮助。

坑2：RAG的上下文窗口管理

我一开始的做法是：检索top-20个相关片段，全部塞给Claude，让它自己挑有用的信息。

结果发现回答质量很差——Claude会把不相关的信息也混进回答里，有时候还会"幻觉"出一些检索结果里没有的内容。

后来改成top-5 + 相关性阈值过滤，效果好很多。

经验：RAG的质量取决于检索质量，不取决于塞给Claude多少内容。检索做得好，5个片段就够了；检索做得差，塞100个也没用。

坑3：流式输出的解析差异

Claude API的流式输出在普通文本和Tool Use场景下的解析方式不一样。

普通文本流式输出，你直接拼接content_block_delta事件的text就行。

但Tool Use场景下，Claude的响应里会包含tool_use类型的content block，这个block的JSON是分块传输的（input_json_delta事件）。你需要把多个delta拼接起来，然后JSON parse，才能得到完整的工具调用参数。

如果你直接把所有delta当文本拼接，会得到一堆乱码JSON。

官方示例里的处理逻辑：

ifevent.type=="content_block_start":ifevent.content_block.type=="tool_use":tool_name=event.content_block.name tool_input_json=""elifevent.type=="content_block_delta":ifevent.delta.type=="input_json_delta":tool_input_json+=event.delta.partial_jsonelifevent.type=="content_block_stop":iftool_name:tool_input=json.loads(tool_input_json)# 执行工具调用...

这个逻辑不复杂，但容易忽略。建议直接参考官方实现，别自己造轮子。

坑4：API Key的安全管理

这个看起来是小事，但我见过太多人在代码里硬编码API Key了。特别是前端直接调Claude API的场景，Key暴露在浏览器里就是白送。

正确的做法：

• 后端调用Claude API，前端只和后端通信
• API Key用环境变量管理
• 生产环境用密钥管理服务（AWS Secrets Manager、HashiCorp Vault等）
• 定期轮换Key

最值钱的两个部分

说实话，仓库里的基础对话示例没什么好看的。真正值得精读的是Tool Use和Agent这两个部分。

Tool Use的核心不是函数调用

很多人把Tool Use理解成"让Claude调用函数"，这理解太简单了。Tool Use的核心是一个对话状态机：

用户输入 → [Claude决策] → 是否需要工具？ ├── 不需要 → 直接生成回答 └── 需要 → 调用工具 → 获取结果 → [Claude决策] → 是否还需要工具？ ├── 不需要 → 生成最终回答 └── 需要 → 继续调用 → ...

你需要处理的状态包括：

• 单次工具调用
• 连续多次工具调用
• 多个工具并行调用
• 工具调用失败的错误处理
• 工具返回结果过大需要截断

Agent的核心是何时终止

Agent的实现不难，难的是什么时候让它停下来。

Claude可能会不断地"规划→执行→再规划→再执行"，你需要一个明确的终止条件。官方示例用的是双重机制：

1. 最大轮次限制：硬性上限，防止无限循环
2. Claude主动判断：每一步都问Claude"任务完成了吗"，如果Claude回答"完成了"就停止

这两个条件缺一不可。只有最大轮次限制的话，有时候Claude会在轮次用完之前就完成了任务但你不让它停下来；只有Claude主动判断的话，有时候Claude会永远觉得自己没完成。

怎么用这个仓库

我的建议是：

1. 先全部跑一遍：每个子项目都clone下来，装依赖，跑起来。不用仔细看代码，先看看每个示例能做什么。

2. 重点精读Tool Use和Agent：这两个部分的代码量不大，但设计模式很有参考价值。

3. 基于示例改造：不要从零开始写，把示例代码fork出来，改成自己的业务逻辑。我做数据库查询Agent的时候就是从Tool Use示例改的，省了很多时间。

4. 注意版本更新：Claude API还在快速迭代，示例代码可能会过时。定期git pull看看有没有更新。

环境配置

# Python 3.10+python--version# 安装Anthropic SDKpipinstallanthropic# 设置API KeyexportANTHROPIC_API_KEY="sk-ant-xxx"# 或者在代码里设置importanthropic client=anthropic.Anthropic(api_key="sk-ant-xxx")

如果你在国内，可能需要配置代理才能访问Anthropic API。这个不在本文讨论范围内。

项目地址：https://github.com/anthropics/claude-quickstarts

如果你在开发过程中遇到问题，欢迎在评论区交流。