Agent 项目设计与实践记录
设计一个领域 Agent，可以从一个完整任务开始：谁发起请求，输入有哪些不确定性，系统能读取什么、执行什么，哪些条件必须满足，以及用什么证据验收。本文把这些问题组织成一份可用于立项、实现和复盘的设计记录。
下面统一使用假想的企业知识与工单助手。所有流程、字段和失败情形都是教学设计，没有对应的生产运行成绩。
先写任务边界
用户希望找到适用的制度；若仍需处理，则形成一份可审阅的工单草稿。第一版可以只读取授权文档和保存草稿，实际提交由明确的交互触发。把权限与任务边界先写下来，后续才能判断增加工具是否有必要。
| 设计项 | 示例定义 | 需要明确的问题 |
|---|---|---|
| 服务对象 | 内部员工 | 身份、部门和地区从哪里取得 |
| 任务结果 | 有依据的制度答复或工单草稿 | 什么条件算完成 |
| 信息范围 | 当前用户可访问的有效制度 | 权限变化和文档版本怎样生效 |
| 操作范围 | 查询、澄清、生成与保存草稿 | 谁能提交，重复点击如何处理 |
| 不支持情形 | 缺少依据、身份无法确认、请求超出权限 | 如何说明原因或移交人工 |
需求应包含成功、失败和不确定三类结局。“没有适用文档，明确告知并停止猜测”可能是正确结果；强行生成一个流畅答案反而违反验收条件。
架构从需求复杂度出发
Anthropic 的架构经验建议先尝试简单方案，再根据实际需求增加复杂度。这里将其作为选型起点，具体组合仍需用项目样本比较。
| 形态 | 适合的任务特征 | 需要承担的额外代价 |
|---|---|---|
| 单次模型调用与工具 | 目标清楚、调用少、状态简单 | 严格校验输入输出和权限 |
| 确定工作流 | 阶段、依赖、分支能够明确编码 | 分支维护，异常路径覆盖 |
| 单 Agent 动态决策 | 信息不完整，需要根据结果决定下一步 | 停止条件、预算、状态与错误累积 |
| 主代理与专职子代理 | 确有上下文、权限或并行任务隔离需求 | 调度、交接契约、重复工作和协调成本 |
工作流也可以具有分支、循环和人工节点。采用多个 Agent 不能自动证明架构更强；应解释隔离解决了什么问题，为什么一个 Agent 配合工具无法合理承担，以及收益是否抵得过额外调用。
走通一条完整输入链
教学输入：“上次说的差旅补助，这次去上海适用吗？如果不符合，先帮我写个咨询单。”
第一步是理解“上次说的”指什么，并检查出差日期、地区和人员类别是否已知。缺少影响制度适用性的条件时，先澄清；历史画像只能提供候选线索，不能覆盖用户本轮明确说明。
第二步是输出结构化任务：查询适用制度，必要时生成咨询草稿。查询意图和写入动作应分开，不能把一句“帮我看看”扩大为自动提交。
第三步是查询授权数据源，获取制度正文、版本、生效范围与定位信息。无结果、多个版本冲突或数据权限不足，应成为显式状态，不能伪装成“没有限制”。
第四步是组织上下文，保留本轮条件和可信证据；模型生成答复或草稿，由规则检查必填字段、引用和操作边界。最后向用户呈现可读结果，并说明哪些内容仍待确认。
输入与授权上下文
→ 指代消解 / 必要澄清
→ 任务与约束状态
→ 授权检索 / 版本检查
→ 回答或草稿生成
→ 条件与证据校验
→ 展示结果 / 用户后续动作
这张流程图描述本案例的稳定主干。是否需要计划生成或多轮动态检索，要由任务的不确定性决定，不能为了凑齐概念而强制加入所有机制。
让状态与工具有可检查的契约
状态中区分用户目标、硬约束、事实、推断和执行结果。工具结果带来源和版本，推断保留待确认状态；任务事实更新后，使依赖旧事实的计划和结果失效。
{
"task_id": "demo-travel-query",
"task_version": 1,
"goal": "answer_policy_or_prepare_draft",
"constraints": {"submit_ticket": false},
"facts": {"destination": "上海"},
"pending_fields": ["travel_date", "employee_category"],
"evidence_refs": [],
"status": "needs_clarification"
}
示例只展示字段结构。权限身份必须来自可信会话和业务系统，不能把模型输出中的 role 当成授权依据。工具契约则说明：做什么、何时可调用、参数格式、返回值、错误分类、副作用、幂等能力，以及超时后的状态查询方式。
如果保存草稿成功但响应丢失，应先查询操作状态或依赖幂等键判断结果。直接重试可能重复写入。外部操作已经发生时，回退内部任务状态也不代表撤销了外部结果。
用失败路径检验设计是否完整
| 情形 | 设计动作 | 应保留的证据 |
|---|---|---|
| 用户更改出差日期 | 更新任务版本，重查适用制度 | 新旧约束与失效的证据 |
| 检索结果只有旧制度 | 检查有效期，补充检索或说明未知 | 版本、日期、停止原因 |
| 工具超时但可能已写入 | 查询状态，确认后再恢复 | 操作标识、幂等键、外部状态 |
| 上下文压缩丢失地区 | 从结构化事实恢复并重新校验 | 压缩前后状态差异 |
| 候选文档含越权信息 | 在数据访问边界拒绝并审计 | 授权规则版本、拒绝原因 |
| 任务长期没有进展 | 比较已完成条件与证据增量，收束或移交 | 步数、剩余预算、阻塞点 |
每次恢复只重做受影响部分，但前提是先校验剩余结果的依赖和有效性。来自旧权限、旧版本或旧用户约束的“成功产物”，不能因为生成成本高就强行复用。
将评估与交付一起设计
在开发前准备代表性样本，包括正常查询、跨轮指代、无答案、版本冲突、越权和重复提交。为不同阶段准备可验证产物：输入理解看结构化条件，检索看证据覆盖，操作看系统状态，结果看用户目标是否满足。
可以按三个阶段推进：
- 基线验证：用最小流程验证数据是否可用、规则是否清楚、任务能否完成。
- 针对性改进：根据真实失败增加必要机制，例如只为跨轮指代补充状态，不一次引入所有高级组件。
- 受控运行：观察目标、约束、时延与成本，保存版本和回滚路径；无法确认收益时保留不确定结论。
评价方法详见Agent 评估、反馈与可观测性。这里关注的是每个里程碑交付什么，而不是预设一个漂亮的指标目标。
用设计记录沉淀个人贡献
一份可复查的项目记录可以包含以下内容：
| 记录项 | 填写内容 |
|---|---|
| 问题与基线 | 原流程如何工作，具体哪里失败 |
| 个人职责 | 自己实现、参与或仅调研的范围 |
| 方案比较 | 候选方案、取舍原因和约束 |
| 关键机制 | 状态、工具、上下文、检索如何协作 |
| 失败与修复 | 一个具体反例、定位依据和改动 |
| 验证结果 | 样本、版本、运行条件、指标与局限 |
| 后续工作 | 未解决问题、验证办法和优先级 |
写“优化检索”时，应能说明改了哪一部分、对比了什么、样本是否相同，以及哪些场景变好或变差。写“负责架构”时，应能指出本人决策与团队职责边界。未实现的方案可以写成设计提案，教学案例若实际运行过，可以写成注明环境的实验记录；尚未运行的模拟方案应写成设计案例，都不需要包装成线上成绩。
这一记录也能支持简历和面试表达，但技术笔记应保留失败条件与边界。具体提问和表达练习集中在Agent 系统设计面试题与项目表达。