9. 最佳实践
一句话理解：Agent Runtime 的最佳实践不是追求功能最全，而是根据任务复杂度选择合适抽象，并在可观测、安全、评测上从第一天就建立底线。
1. 模型选择
- 强模型 + 简单框架 > 弱模型 + 复杂编排。当 Claude 3.7 / o1 / Gemini 3 能一次调用完成规划与执行时，不要把简单任务拆成多步图。
- 按任务选模型：简单分类用便宜模型；复杂推理用强模型；代码生成用 coding 模型。
- 不要锁死一家：通过 LLM Gateway 支持多模型 fallback。
2. 工具设计
- 工具数量宁少勿多。给 Agent 太多工具会降低决策质量。
- 工具描述要清晰。描述直接决定模型调用准确率。
- 参数命名自解释。避免
arg1、arg2。 - 返回结构化结果。JSON 比自由文本更容易被模型继续消费。
- 危险工具加标签。例如
destructive、write、network，供 Guardrails 使用。
3. ReAct 循环调优
- 设置最大迭代次数。通常 5~15 步，根据任务复杂度调整。
- 检测循环与重复。如果模型连续调用同一工具且参数相同，应强制终止或提示。
- 控制上下文长度。长工具输出应摘要后再回注。
- 让模型在无法完成时承认。训练/提示模型在信息不足时返回
I don't know。
4. 记忆与上下文
- 工作记忆保留完整对话，但超过 token 阈值时摘要。
- 长期记忆按需检索，不要一次性塞进上下文。
- 敏感信息不入长期记忆。例如用户密码、Token、PII。
- 多会话共享记忆需要用户授权。
5. 护栏
- 输入护栏：过滤越狱、提示注入、越权请求。
- 工具前置护栏：检查参数、调用次数、权限标签。
- 工具后置护栏：检查结果是否包含敏感信息。
- 输出护栏：确保最终答案合规。
- 资源护栏：限制迭代次数、超时、token 预算。
6. 人机协同（HITL）
- 高风险操作必须人工确认：写文件、转账、删除数据、对外发送邮件。
- HITL 不应阻塞无关任务：只在需要时中断当前 session。
- 提供清晰的上下文：人类审批时应看到任务目标、工具、参数、风险说明。
7. 可观测
- 从 Day 0 接入 trace。没有 trace 的 Agent 无法调试。
- 记录完整执行路径：thought、tool call、observation、guardrail 事件。
- 关注关键指标：任务成功率、平均步数、工具调用错误率、token 成本。
- 按 tenant/user 拆分大盘。
8. 沙箱
- 任何会执行代码或访问外部系统的工具都必须沙箱。
- 最小权限原则：只开放必要的路径、网络、API。
- 超时与资源限制：CPU、内存、网络超时都要设上限。
- 审计日志：记录沙箱内所有行为。
9. 评测
- 建立评测集再调优。没有评测集的优化是盲调。
- 覆盖成功、失败、边界、安全场景。
- 用影子运行做回归：新版本与旧版本并行对比。
- 把评测集成到 CI/CD：每次代码变更跑一遍 eval。
10. 避免过度编排
- 单 Agent 能解决的问题不要上 Multi-Agent。
- 简单线性任务用 SDK 或轻量 Runtime。
- 复杂有状态任务才用 LangGraph 等图编排框架。
- 不要为了用框架而用框架。
最佳实践速查表
| 维度 | 推荐做法 |
|---|---|
| 模型 | 强模型 + 简单框架；按任务选模型；多模型 fallback |
| 工具 | 少而精、描述清晰、参数自解释、危险工具加标签 |
| 循环 | 设 max_steps、检测重复、控制上下文 |
| 记忆 | 工作记忆 + 摘要；长期记忆按需检索；敏感信息不入记忆 |
| 护栏 | 输入/工具前置/工具后置/输出/资源多层护栏 |
| HITL | 高风险操作必须确认；提供清晰上下文 |
| 可观测 | Day 0 trace；记录完整路径；按 tenant 分大盘 |
| 沙箱 | 代码/外部访问必须隔离；最小权限；审计 |
| 评测 | 先建 eval 集；影子运行；CI 集成 |
| 编排 | 按需选型，避免过度设计 |
本章小结
Agent Runtime 的最佳实践覆盖了模型选择、工具设计、循环调优、记忆、护栏、HITL、可观测、沙箱、评测与编排十个方面。核心原则是：用 Runtime 把复杂性与风险集中收敛，让业务方只关心“定义目标与工具”。
参考来源