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_KEYyour-api-keypython 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调用形成上下文。我踩过的坑坑1Tool Use的死循环这是我遇到的最坑的问题。我在做一个数据库查询Agent用户用自然语言提问Claude把问题转成SQL执行查询返回结果。听起来很简单对吧但Claude有时候会这样用户问上个月的销售额是多少Claude调用工具执行SQL查询返回结果“上个月销售额为100万元”Claude觉得不够详细又调用一次工具换个SQL查更细的数据返回结果Claude还是觉得不够再调一次……循环到对话轮次超限原因分析Claude的追求完美有时候会过度。它会不断地想我是不是还能提供更多信息然后反复调用工具。解决方案MAX_TOOL_ROUNDS5# 最大工具调用轮次foriinrange(MAX_TOOL_ROUNDS):responseclient.messages.create(modelclaude-sonnet-4-20250514,messagesmessages,toolstools,max_tokens1024)ifresponse.stop_reasonend_turn:# Claude认为任务完成跳出循环breakifresponse.stop_reasontool_use:# 执行工具调用把结果加入messages# ...pass另外在系统提示词里加一句如果已经获取到足够信息直接回答不要重复查询也有帮助。坑2RAG的上下文窗口管理我一开始的做法是检索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.typecontent_block_start:ifevent.content_block.typetool_use:tool_nameevent.content_block.name tool_input_jsonelifevent.typecontent_block_delta:ifevent.delta.typeinput_json_delta:tool_input_jsonevent.delta.partial_jsonelifevent.typecontent_block_stop:iftool_name:tool_inputjson.loads(tool_input_json)# 执行工具调用...这个逻辑不复杂但容易忽略。建议直接参考官方实现别自己造轮子。坑4API 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可能会不断地规划→执行→再规划→再执行你需要一个明确的终止条件。官方示例用的是双重机制最大轮次限制硬性上限防止无限循环Claude主动判断每一步都问Claude任务完成了吗如果Claude回答完成了就停止这两个条件缺一不可。只有最大轮次限制的话有时候Claude会在轮次用完之前就完成了任务但你不让它停下来只有Claude主动判断的话有时候Claude会永远觉得自己没完成。怎么用这个仓库我的建议是先全部跑一遍每个子项目都clone下来装依赖跑起来。不用仔细看代码先看看每个示例能做什么。重点精读Tool Use和Agent这两个部分的代码量不大但设计模式很有参考价值。基于示例改造不要从零开始写把示例代码fork出来改成自己的业务逻辑。我做数据库查询Agent的时候就是从Tool Use示例改的省了很多时间。注意版本更新Claude API还在快速迭代示例代码可能会过时。定期git pull看看有没有更新。环境配置# Python 3.10python--version# 安装Anthropic SDKpipinstallanthropic# 设置API KeyexportANTHROPIC_API_KEYsk-ant-xxx# 或者在代码里设置importanthropic clientanthropic.Anthropic(api_keysk-ant-xxx)如果你在国内可能需要配置代理才能访问Anthropic API。这个不在本文讨论范围内。项目地址https://github.com/anthropics/claude-quickstarts如果你在开发过程中遇到问题欢迎在评论区交流。