单 Agent 最小可用版本（MVP）设计清单：从目标到上线
单 Agent 的 MVP 不是“能聊两句”就算完成，而是能在有限工具、有限预算下稳定完成一类任务。本文给出可直接落地的工程 checklist：目标定义、工具边界、状态与日志、失败策略、指标与灰度，帮助你用最小成本做出可上线版本。
📷 Photo by Pixabay via Pexels
先对齐一句话：MVP 的目标不是“展示”，是“可重复完成”
单 Agent 的 MVP 最常见翻车方式是：
- Demo 看起来很强
- 一旦输入稍有变化就崩
- 出问题无法复盘，只能“再跑一次”
所以这篇文章不讲花活，只给一个可以直接贴到项目里的 checklist。
你可以把它当作验收表：每一项都回答“是否可上线”。
一、目标定义：把“任务”写成可测的合同
1）只选一类任务，定义清楚输入与输出
MVP 阶段建议只选一个主任务类型，例如：
- 整理会议纪要并生成待办
- 根据工单记录生成周报
- 根据知识库回答产品问题并给出处
然后把它写成“输出合同”（Output Contract）：
- 输出格式（JSON / Markdown / 表格）
- 必填字段
- 允许的枚举值
- 失败时的返回（拒答/追问）
如果你现在无法写出输出合同，说明任务边界还不清晰。
2）定义“完成”与“失败”
很多团队只定义了完成，没有定义失败。
建议至少写出：
- 完成：包含哪些字段、满足哪些约束
- 失败：哪些情况必须停止（权限不足、证据不足、风险动作）
- 追问：哪些情况需要向用户补信息
二、工具边界：把能力做窄，失败面才小
1）工具接口要“窄而硬”
工具设计要点：
- 输入参数有 Schema（并且
additionalProperties: false） - 输出有统一的结果结构（success/data/error）
- 明确超时与重试策略（不要默认无限重试）
MVP 的工具数量建议控制在 1-3 个。
2）高风险工具先禁用或强制人工确认
例如：
- 发邮件/发短信
- 付费/扣费
- 删除数据
MVP 不要追求全自动，把“可控”放在第一位。
三、状态与日志：可复盘是第一生产力
1）最小状态机
你不需要复杂工作流引擎，但建议至少有这些状态：
PLANNINGRUNNINGWAITING_TOOLDONEFAILED
并且每次状态变化都要落日志。
2）事件日志（Event Log）而不是“聊天记录”
建议记录：
- 任务 ID、用户 ID、输入摘要
- 计划版本（prompt/model/tool set）
- 每次工具调用：参数（脱敏）、耗时、结果、错误类型
- 最终输出与校验结果
这样你才能做到：
- 排障：为什么失败
- 回归：修完是否变好
- 成本：每类任务平均消耗
四、失败策略：把失败变成“可预期路径”
1）错误分类 + 对应动作
最小分类建议：
- 参数错误：不重试，修复 prompt/schema
- 超时/429：短重试 + 退避，必要时降级
- 业务拒绝：立即停止并解释原因
- 半成功：记录幂等键，走补偿/确认
2）幂等：重复触发是常态
无论是用户连点、网络重放、队列重复投递，都会产生重复请求。
MVP 阶段就要做到：
- 每次“写操作”都有幂等键
- 幂等冲突可观测（指标/日志）
五、质量与成本：先建最小评测集
1）准备 20-50 条“真实样本”
别用你自己编的 3 条样例。
建议收集（或模拟）真实用户输入，覆盖：
- 信息完整
- 信息缺失（需要追问）
- 约束冲突
- 工具异常（超时/返回空）
2）最小指标
上线前你至少要能回答：
- 通过率：固定样本集的任务完成率
- 失败原因分布：主要卡在什么环节
- 成本：平均 token、平均工具调用次数
- 时延：端到端 p95
六、上线与灰度：不要“一键全量”
MVP 也要有发布策略：
- 小流量灰度（例如 1% → 10% → 50%）
- 快速回滚（切回旧 prompt/旧模型/禁用工具）
- 告警阈值（失败率、超时率、429）
如果没有回滚，你的 MVP 不是 MVP，而是“事故预告”。
七、MVP 验收清单（可直接复制到 PR）
- 任务定义：输出合同已写清（格式/字段/失败与追问）
- 工具边界：工具数量 ≤ 3，接口有 Schema，输出结构统一
- 状态机：最小状态机已实现，状态可持久化
- 事件日志：每次工具调用可追踪（参数脱敏）
- 幂等：写操作具备幂等键，冲突可观测
- 失败策略：错误分类 + 重试/降级/停止策略
- 评测集：至少 20 条真实样本，能跑通过率
- 灰度回滚：可限流、可禁用工具、可快速切版本
做到这里，你的单 Agent 才算“能上线”，而不只是“能演示”。
常见问题
我应该先做 Planner-Executor 吗？
如果你的任务步骤多、工具调用多，Planner-Executor 分层能显著降低“幻觉执行”。但 MVP 阶段也可以先用“串行执行 + 严格校验”顶住，等日志与失败分类稳定后再引入更复杂分层。
要不要一开始就做 RAG？
取决于你的任务是否依赖外部事实。若依赖，最小 RAG（top-k + 简单过滤）比“把文档塞进 prompt”更可控。若不依赖，先把状态、工具与观测做稳更划算。