04. 实践路径：从会用到能开发 Agent 系统
这份路径按「可验证产出」组织。每个阶段都应该有可演示结果，而不是只读完文档。
阶段 1：做一个可观察的 Chat Agent
目标：从前端页面切入 Agent 应用。
功能：
- 用户输入问题
- 后端调用模型
- 前端展示 streaming response
- 支持 loading、error、retry
- 返回结构化结果
- LangSmith 记录 trace
建议技术：
- TypeScript
- React / Next.js
- LangChain JS
- LangSmith tracing
验收标准：
- 页面能展示模型流式输出。
- 出错时有明确错误态。
- 每次请求都能在 LangSmith 中找到 trace。
- trace 中能看到 prompt、model response、latency。
阶段 2：把真实 API 封装成工具
目标：理解 tool calling。
选择 2-3 个工具，例如：
- 搜索文档
- 查询 GitHub issue
- 创建 Linear task
- 查询数据库只读接口
- 读取 Notion 页面
每个工具需要：
- 清晰命名
- 清晰描述
- 参数 schema
- 权限边界
- 错误返回
- 稳定输出结构
验收标准：
- Agent 能在合适场景选择工具。
- 工具参数能被 schema 校验。
- 工具失败时 Agent 能解释失败，而不是胡编结果。
- LangSmith trace 中能看到 tool input / output。
阶段 3：做一个 RAG Agent
目标：构建有证据的回答系统。
功能：
- ingest 一组文档
- chunk 文档
- embedding
- vector search
- 生成带引用的回答
- 支持 no-answer
建议文档来源：
- 团队 README
- API 文档
- 产品 FAQ
- 技术方案文档
验收标准：
- 回答必须带 citation。
- 检索不到充分证据时能拒答。
- LangSmith trace 中能看到 retrieval chunks。
- 至少整理 10 个 hallucination 或 retrieval failure 样例。
阶段 4：建立 Dataset 和 Evaluation
目标：从「手动试」升级到「可重复评估」。
Dataset 结构建议：
- input：用户问题
- reference：期望答案或行为
- context：必要背景
- category：问题类型
- risk：风险等级
Eval 维度建议：
- correctness
- groundedness
- citation correctness
- tool-use accuracy
- refusal correctness
- latency
- cost
验收标准：
- 至少 30 条 dataset 样例。
- 能比较 prompt v1 和 v2。
- 能输出失败分类报告。
- 修改 prompt 后能用 experiment 证明是否变好。
阶段 5：用 LangGraph 做 Workflow
目标：从简单 Agent loop 进入可控 workflow。
可选项目：
Router Workflow
按问题类型路由：
- 文档问答
- API 查询
- 任务创建
- 无法处理
Orchestrator-Worker Workflow
主 Agent 拆任务，worker 执行：
- 搜索
- 总结
- 校验
- 输出
Evaluator-Optimizer Workflow
先生成答案，再由 evaluator 检查：
- 是否有证据
- 是否满足格式
- 是否需要重试
验收标准：
- graph 有清晰 state。
- 每个 node 职责单一。
- 支持 checkpoint 或恢复。
- LangSmith trace 能看清节点流转。
阶段 6：加入 Human-in-the-loop
目标：让高风险动作可控。
适用场景：
- 发送消息
- 创建或修改任务
- 写入数据库
- 调用付费 API
- 删除或覆盖内容
实现要求：
- Agent 先生成计划
- 用户确认后执行
- trace 记录确认前后的状态
- destructive action 必须有显式确认
验收标准：
- 高风险工具不能静默执行。
- UI 能展示即将执行的动作。
- 用户可以 approve / reject / edit。
阶段 7：产品化和上线
目标：不只做 demo，而是能持续运营。
需要加入：
- feedback UI
- LangSmith dashboard
- alert
- CI eval gate
- prompt version promotion
- regression dataset
- cost tracking
- latency tracking
验收标准：
- 差评 trace 能被追踪到。
- 线上失败能进入 dataset。
- CI 中能跑关键 eval。
- 重要指标能在 dashboard 中查看。
推荐作品集项目
项目 1：文档问答 Agent
必须包含：
- RAG
- citation
- no-answer
- LangSmith trace
- dataset eval
- prompt comparison
- feedback loop
展示重点：
- 失败样例如何收集
- 如何分类失败
- 如何修复
- 如何验证修复有效
项目 2：工作流 Agent
必须包含：
- LangGraph workflow
- 多工具调用
- human approval
- checkpoint
- trace
- dashboard
- CI eval gate
展示重点：
- 为什么不用简单 Agent loop
- state 如何设计
- 工具权限如何控制
- 上线后如何监控
评估自己是否进入 Agent Engineer 状态
你能回答这些问题，就说明已经从「会调模型」进入「会做 Agent 工程」：
- 这个 Agent 的核心失败模式是什么？
- 失败样例是否进入 dataset？
- 哪个 eval 能防止这类失败复发？
- trace 能否解释一次线上错误？
- 工具调用是否有权限边界？
- prompt 修改是否有版本和回滚机制？
- 线上反馈如何进入下一轮改进？
- latency 和 cost 的主要来源是什么？