如何使用 Claude API 构建可靠的 AI 助手
内容提要
本教程讲解如何用 Claude API 构建生产级客服助手 ShopHelper，包括安全存储 API 密钥、管理对话历史、用 XML 标签和系统提示组织上下文、定义并校验工具调用、安全处理多块响应，以及工作流与代理、链式、并行、路由、评估优化等模式，并强调用测试用例评估提示质量。
延伸解读
安全与权限：工具调用的关键防线
文章强调，Claude 不会直接执行工具函数，而是返回 tool_use 请求，由应用层负责验证和执行。这意味着开发者必须自行校验工具名称、参数格式以及用户权限，例如检查订单号是否符合模式、是否属于当前用户。这种设计将安全责任明确交给应用，避免了模型直接访问敏感数据，是构建可靠助手的重要原则。
对话历史管理：平衡上下文与成本
Claude 不会自动记住之前的请求，每次都需要发送完整历史。但历史无限增长会增加输入 token 并可能分散模型注意力。文章提供了两种策略：只保留最近消息，或摘要旧对话并保留近期消息。摘要应作为独立状态传入，而不是直接插入用户消息，以避免连续用户消息导致请求无效。这有助于在保持上下文的同时控制成本和性能。
工作流与代理：根据场景选择模式
文章区分了工作流和代理：工作流按预定义步骤执行，适合流程固定、需要可重复性的任务；代理则让 Claude 决定下一步行动，更灵活但需要验证和最大步数限制。此外，链式、并行、路由和评估优化等模式各有适用场景：链式用于依赖阶段，并行用于独立任务，路由用于分类后走专用流程，评估优化则在质量要求高时增加额外调用。
评估提示质量：用测试用例驱动改进
文章建议使用代表性测试用例来评估提示质量，例如覆盖退款、配送和一般咨询等不同请求类型。在修改系统提示、示例、模型或路由指令后，运行相同用例并计算通过率。对于标签和 JSON 等结构化输出，可用代码评分；对于语气、准确性和有用性，则需人工或模型评分。这种可重复的评估方法能帮助判断改动是否真正提升了效果。
Q&A
如何安全地存储和使用 Claude API 密钥？
将 API 密钥放在 .env 文件中，使用 python-dotenv 加载，并确保 .env 被加入 .gitignore。永远不要将密钥放在浏览器 JavaScript、移动应用代码或客户端配置中。如果添加 Web 界面，密钥应保留在后端，请求路径为：浏览器 → 你的后端 → Claude API。
Claude API 的对话历史是如何管理的？
Claude 不会自动记住之前的请求，每次请求都需要发送相关的历史消息。可以维护一个消息列表，每次调用时追加用户消息和助手回复。当历史增长时，可以只保留最近的消息（如最近10条），或者总结较早的对话并保留最近几条，同时注意不要插入连续的用户消息。
如何用 XML 标签和系统提示来组织 Claude 的上下文？
XML 标签是普通文本，用于明确区分提示的不同部分，例如 <customer_reviews>、<sales_data>、<task>。系统提示单独传递，定义助手的整体行为，如语气、禁止编造信息等。这样可以让 Claude 更准确地理解上下文和指令。
如何定义和校验 Claude 的工具调用？
通过 JSON schema 定义工具，包括名称、描述和输入参数。当 Claude 返回 tool_use 块时，应用需要验证工具名称、参数格式和用户权限，然后执行函数。结果以 tool_result 块返回，并用 tool_use_id 关联原始请求。应用负责授权和执行，Claude 不直接执行函数。
Claude 的响应可能包含多个内容块，应该如何处理？
不要假设 response.content[0] 总是文本。应遍历每个块，根据类型处理：text 块显示文本，tool_use 块验证并执行工具，thinking 块忽略，未知块记录日志。这样可以安全处理多块响应。
工作流和代理在 Claude 应用中有何区别？
工作流遵循预定义的步骤序列，适合步骤已知且需要可重复性的场景。代理更灵活，由 Claude 决定是否使用工具以及下一步行动，但需要验证和最大步数限制。根据任务的可预测性选择：步骤固定用工作流，动态决策用代理。
有哪些常见的 Claude 应用模式，如链式、并行、路由和评估优化？
链式：将每个阶段的结果传递给下一个阶段，适用于依赖任务。并行：使用 ThreadPoolExecutor 并发运行独立任务。路由：先分类请求，再选择专门的工作流。评估优化：生成、审查并修订答案，循环直到通过或达到轮数。根据任务依赖性和质量要求选择模式。
如何评估提示质量并确保改进有效？
使用代表性的测试用例，覆盖不同请求类型。在更改系统提示、示例、模型、令牌限制或路由指令后，运行相同的测试用例，计算通过率。对于标签和 JSON 使用代码评分器，对于语气、准确性和帮助性使用人工或模型评分器。
