跳到主要内容
版本：1.0

构建好的 Agent：设计原则

"如何构建一个好的 Agent"的答案，一半是工程纪律，一半是对 LLM 能力边界的尊重。以下原则按投入回报排序，前四条几乎适用于所有项目。

原则一：从最简单的方案开始​

这是最重要也最常被违反的原则。需求出现时，先问：这个问题真的需要 Agent 吗？

提示工程（单次 LLM 调用 + 好的提示词）
   ↓ 不够？
Workflow（固定流程编排 LLM 节点）
   ↓ 不够？
单 Agent（循环 + 少量工具）
   ↓ 不够？
多 Agent / 自主性升级

每一级升级都在引入新的故障面：workflow 引入节点间数据传递问题，Agent 引入非确定性与循环失控，多 Agent 引入角色协调与成本倍增。只在简单方案被证明不足时才升级——"证明"意味着有具体的失败案例（如评测集中固定流程无法解决的分支问题），而不是"听起来 Agent 更先进"。

大量真实需求止步于第二级。把固定流程硬塞进自主循环，是最常见的过度设计。

原则二：把工具当作模型的用户界面​

模型看不到你的代码架构，只看到工具的名称、描述、参数和返回值。工具设计是 Agent 项目中回报最高的工程投入：

  • 描述写给模型看，写给"一个聪明但不了解你系统的新同事"看——说明用途、适用场景、返回结构，必要时给出调用示例；
  • 参数强类型、少而精，枚举值用 enum 约束而不是让模型自由发挥；
  • 错误信息可行动："部门不存在，可选值：教研部/IT部/市场部" 远好于 "查询失败"——模型能据此自我修正，而不是盲目重试；
  • 控制单次可见工具数量，工具多时按任务分组或做工具检索（详见工具设计与函数调用）。

一个实用的检验方法：把工具清单打印出来给同事看，不解释任何背景。同事能猜对每个工具该何时用、怎么用，模型大概率也能。

原则三：给模型可观察的反馈​

Agent 与单次调用的本质差异在循环，而循环质量取决于观察质量：

  • 工具执行成功时，返回足够的信息让模型判断下一步，而不是只回一个 "ok"；
  • 失败时保留原始错误细节，让模型能区分"参数错了"（可自我修正）与"服务挂了"（该停止或换路）；
  • 每轮把关键状态（已完成步骤、剩余目标）注入上下文，长任务中模型对早期轮次的注意力会衰减。

反馈链路设计的反面教材是静默兜底：工具失败时空字符串返回、异常被吞掉。模型拿到空观察会编造或死循环，问题最终以更难排查的形态出现在终点。

原则四：先建护栏再放开自主​

自主性必须圈在护栏内：

护栏作用
步数上限 / token 预算防循环失控、成本爆炸
工具白名单 + 参数校验模型只能做被允许的事
高危操作确认（human-in-the-loop）不可逆动作必须过人工
超时与降级路径Agent 卡死时回退到固定流程或人工
输出校验最终产物过 schema / 规则校验再交付

护栏不是对模型的不信任，而是把失败模式从"事故"降级为"可控降级"。上线初期可以把自主性收紧（更多确认、更少工具），观察真实轨迹后再逐步放宽——自主性是逐步授予的，不是一次性配置的。

原则五：让轨迹可观测​

调试 Agent 最大的痛点是"答案错了但不知道错在哪一步"。从第一天起就要持久化完整轨迹：

{
  "run_id": "xxx",
  "goal": "分析月度报告",
  "steps": [
    {"turn": 1, "thought": "先读取报告文件", "tool": "read_file", "args": {"path": "report.md"}, "output_summary": "8300 字符", "latency_ms": 120},
    {"turn": 2, "thought": "检索环比数据", "tool": "query_db", "args": {"sql": "..."}, "output_summary": "12 行", "latency_ms": 340}
  ],
  "final_output": "…",
  "total_tokens": 28500,
  "status": "completed"
}

记录的关键字段：每轮的决策（thought / tool call）、观察摘要、延迟与 token 消耗。答案只是轨迹的最后一个点，排错需要的是整条线。

原则六：用评测驱动迭代​

Agent 的改动（换模型、改提示词、加工具）没有评测集支撑，等于盲飞。最小可行的评测资产：

  1. 30-50 个真实任务，覆盖常规、边界与已知失败模式；
  2. 每个任务带可校验的预期结果（精确匹配 / 断言 / LLM 评审规则）；
  3. 每次变更全量回归，同时盯成功率、平均轮数、平均 token 成本三个指标。

成功率涨但成本翻倍的改动未必值得。评测的专门方法（轨迹评测、组件级评测）见评测与安全。

原则七：管理上下文预算​

Agent 循环天然导致上下文膨胀，而上下文质量直接决定后续决策质量：

  • 工具返回大结果时先摘要或截断（附带"完整结果可按需获取"的机制）；
  • 历史轮次超长时做压缩（保留决策与关键观察，丢弃冗余原文）；
  • 长期信息移出上下文、转入外部记忆按需检索。

把上下文当作预算管理的稀缺资源，而不是随用随取的无限缓冲区。

常见失败模式​

症状通常病因
无限循环 / 重复调用同一工具观察信息不足、无步数护栏
选错工具 / 编参数工具描述差、工具过多、模型能力不足
前几轮正确后面跑偏上下文膨胀稀释注意力、缺状态注入
答案正确但过程离谱只看结果不看轨迹的"幸运通过"，评测缺失
成本失控无 token 预算、大结果全量入上下文

对症下药的位置基本都在上面的原则里。下一步：Agent 设计模式给出可复用的架构模板，框架选型讨论何时需要引入框架。