文档说明：本指南旨在为开发者提供构建高质量、高稳定性、可落地的 AI Agent 的最佳实践和设计规范。

1. 优秀 Agent 的评判标准

一个“好”的 Agent 应当具备以下特征：

• 目标聚焦：不偏题，不胡言乱语。
• 工具鲁棒性：调用工具失败时能自我恢复，而不是直接崩溃。
• 边界清晰：知道自己能做什么，更要知道自己不能做什么（避免危险操作）。
• 可观测性：开发者能清晰看到它的思考过程（Thought Process）。

2. 核心架构设计规范

2.1 打造强大的“大脑” (Prompt 工程)

写 Agent 的 System Prompt 与写普通对话的 Prompt 完全不同，你需要定义它的“系统级行为”。

• 角色设定 (Persona)：清晰定义它的身份和目标。
• 行为准则 (Instructions)：用编号列出严格的规则（例如：“1. 永远先搜索再回答；2. 如果工具返回 Error，尝试更换参数重试”）。
• 输出格式 (Format)：强制要求 LLM 输出 JSON 或指定的 XML 格式，以便代码精准解析。

💡 Tip: 尽量使用能力最强的模型（如 GPT-4o, Claude 3.5 Sonnet）作为核心路由大脑，开源小模型可用于执行具体的小任务。

2.2 工具设计法则 (Tools Best Practices)

工具是 Agent 与物理世界交互的触手。工具写得不好，Agent 就会变成“瞎子和聋子”。

• 原子化设计：一个工具只做一件事。不要写一个既能搜索天气又能订机票的庞大 API。
• 清晰的描述 (Docstring)：LLM 是通过阅读工具的文字描述来决定是否调用的。
  • 坏描述：get_data(query)
  • 好描述：用于获取指定城市的实时天气。输入参数 city 必须是中文城市名，如'北京'。
• 友好的错误返回：如果 API 报错，不要抛出异常中断程序，而是将错误信息包装成自然语言返回给 LLM。
  • 示例：return f"Error: 找不到该用户的订单，请检查订单号 {order_id} 格式是否正确。" 这样 Agent 看到后会重新思考并重试。

2.3 记忆管理 (Memory)

• 短期记忆 (Context)：管理好对话窗口，对于超长对话，定期使用一个“总结器 Agent”将前面的对话压缩成摘要。
• 长期记忆 (VectorDB)：对于需要记住用户偏好、历史文档的场景，使用向量数据库。每次 Agent 行动前，先去“记忆库”里检索相关经验。

2.4 规划与流程控制 (Planning & Control)

早期的 Agent（如简单的 ReAct）在面对复杂任务时极易陷入“死循环”。在生产环境中，不要给 Agent 100% 的自由。

• 引入状态机 (State Machine)：使用 LangGraph 这样的工具，将标准化的流程硬编码（如：第一步必须是资料收集），而在具体节点内部给予 Agent 自由度。这被称为**“Agentic Workflow（智能体工作流）”**。
• 人工干预 (Human-in-the-loop)：对于涉及高风险的操作（如：转账、群发邮件、删除数据库），必须在执行行动前设置“等待人工批准”的节点。

3. 开发与调试流程

1. 定义场景边界：不要试图写一个“全能助理”，先写一个解决特定业务痛点的 Agent（如“专门处理退款工单的 Agent”）。
2. 基准测试 (Benchmark)：在写代码前，先准备 20-50 个测试用例（用户可能的输入）。
3. Prompt 调试：先在纯文本界面（如 ChatGPT 网页端）模拟 Agent 和工具的交互，调优 Prompt，再写代码。
4. 日志埋点 (Logging)：在代码中打印出 Agent 的每一步 Thought（思考）、Action（调用的工具）、Action Input（输入的参数）和 Observation（工具返回的结果）。这是排查 Bug 唯一的途径。

4. 常见避坑指南 (Anti-Patterns)

• ❌ 给 Agent 太多工具：一次性塞给大模型 20 个工具，它会产生幻觉并乱用。建议单场景工具不超过 5-7 个。
• ❌ 忽视大模型的上下文限制：工具返回的文本太长（例如直接返回整个网页的 HTML 代码），会瞬间撑爆大模型的窗口。必须对工具的返回值进行截断或预提炼。
• ❌ 盲目迷信全自动：在实际落地中，“70%的固定代码流程 + 30%的大模型意图识别与总结” 往往比 “100%全靠大模型自己推理” 要稳定和实用得多。

5. 总结

写好一个 Agent，本质上是在做一场微型管理。你是一个老板（开发者），LLM 是一个绝顶聪明但缺乏常识的实习生。你需要给实习生明确的岗位说明书（Prompt）、好用的办公软件（Tools）、标准操作手册（SOP/Workflow）以及在他犯错时的及时反馈（Error Handling）。只有这样，他才能真正成为一个高效的 Agent。