Agent Engineering Roadmap

Agent Engineering Roadmap 是本库总结的学习路线和知识地图，不是一个行业标准术语。它的目标不是推荐某个 Agent 框架，而是把 Agent 工程拆成一组可验证、可组合、可追溯的能力：模型调用、工具协议、上下文、记忆、handoff、沙箱、评估、护栏和 harness。

核心判断可以压缩成一句话：Agent 不是会循环的 chatbot，而是一个有工具、状态、记忆、验证和权限边界的执行系统。 因此学习路线也不应从框架名词开始，而应从原生 API、最小 Agent Loop（智能体循环）、工具契约和 Harness Engineering（驾驭工程）开始。

总体路线

这条路线可以分成六层，从“理解 Agent 是什么”逐步走到“生产级 Agent runtime 如何持续改进”：

这不是线性读完材料的清单，而是一组工程能力依赖。没有最小 loop，就很难理解 SDK 帮你隐藏了什么；没有工具和结构化输出，就很难把模型接进业务系统；没有 context、memory 和 eval，Agent 越能行动，越容易把错误行动放大。

第一层：先建立 Agent 判断力

起点是先分清 Workflow（工作流） 和 Agent。

• Workflow 是预定义代码路径：步骤、条件分支和工具调用由应用代码控制。
• Agent 是模型动态决定流程和工具使用：适合开放任务、路径未知、需要模型持续根据环境反馈改计划的场景。

工程上的判断标准不是“能不能做成 Agent”，而是“复杂度是否带来可测量收益”。如果任务有稳定路径、固定输入输出和确定性验收，用普通 workflow、RAG 或单次 LLM 调用通常更可靠。只有当任务路径无法预先穷举，或者工具选择、搜索方向和子任务拆分需要模型判断时，才值得引入 Agent。

这也解释了为什么不应从 LangChain / LangGraph 这类框架入门。框架可以加速实现，但最先需要掌握的是底层 primitive：模型调用、工具调用、状态、上下文、权限和验证。

第二层：手写最小 Agent Loop

最小 Agent 不神秘，本质是：

flowchart LR
    U["用户输入"] --> M["模型调用"]
    M --> D{"是否请求工具?"}
    D -->|"是"| T["应用执行工具"]
    T --> O["追加工具结果"]
    O --> M
    D -->|"否"| F["最终回答 / 停止"]

在这一层，关键不是 SDK 语法，而是 backend contract：

• 模型如何用 Function Calling（函数调用）或 Claude tool_use 请求外部动作
• 工具 schema 如何让参数可解析、可校验、可拒绝
• Structured Outputs（结构化输出）如何把 Agent 输出接进业务系统
• 应用代码何时让模型调用工具，何时由传统业务逻辑控制
• 停止条件如何定义：最终回答、无工具调用、错误、最大 turn、预算耗尽或人工审批

把这个 loop 手写一遍的价值，是获得一条清晰边界：model 负责提出下一步，application code 负责执行、约束、记录和验证。 后续使用 OpenAI Agents SDK、Claude Agent SDK或其他框架时，才知道哪些复杂度被 SDK 承担，哪些仍必须由业务系统负责。

第三层：从能跑到能工程化

Agent 能跑之后，问题会从“如何调用模型”转为“谁拥有运行时边界”。这一阶段可以用五个问题检查自己的设计：

1. model 负责什么？
2. application code 负责什么？
3. tool schema 怎么定义？
4. state / context 放哪里？
5. 失败后如何验证、回滚、重试？

这五个问题正是 Harness Engineering（驾驭工程）的入口。生产 Agent 需要的不只是 while-loop，而是 loop 周围的一整套控制面：工具注册、权限、状态存储、上下文管理、沙箱、trace、eval、handoff、人工确认和错误恢复。

Model Context Protocol（模型上下文协议）在这一层解决工具和数据接入标准化问题。它不是替代 harness，而是让 Jira、GitHub、数据库、日志平台和文件系统等能力以更一致的方式暴露给 Agent。真正的工程问题仍然是：哪些工具应该暴露、何时暴露、结果返回多少、凭证如何隔离、错误如何可恢复。

第四层：Coding Agent 工作流

对软件工程场景，Claude Code 和 Codex是最有参考价值的生产形态。这里的学习目标不是“写更好的 prompt”，而是把 coding agent 组织成可控工作流：

flowchart LR
    S["SPEC.md / PLAN.md\n任务规格与计划"] --> A["Codex / Claude Code\n实现"]
    A --> V["tests / build / lint / trace\n验证证据"]
    V --> R["review agent\n独立检查"]
    R --> P{"通过?"}
    P -->|"否"| A
    P -->|"是"| C["PR / commit\n交付"]

这一层的关键实践包括：

• 先 explore，再 plan，再 code，避免一开始解决错误问题
• 给 Agent 可运行的验证方式，让它能根据失败证据修复
• 用 AGENTS.md、CLAUDE.md、PLANS.md、SPEC.md 这类文件化 artifact 承载长期任务状态
• 用 Subagent（子智能体）做只读调查、并行检查或独立 review，而不是让主上下文吞下全部搜索过程
• 把 repair loop 的终止权交给测试、构建、review 或 eval，而不是由生成者自称完成

这一层的关键对象可以这样理解：

第五层：上下文、技能和子 Agent

Context Engineering（上下文工程）、Skills 和 Subagents 位于 Agent 工程中段，因为这三者解决同一个问题：不要把 conversation 当唯一 state。

长任务中，conversation 会快速混入文件搜索、失败命令、旧计划、工具结果和临时假设。上下文工程的目标不是塞满窗口，而是让模型每步看到最小高信号 token。对应策略：

• Write：把计划、进度、笔记和记忆写到上下文窗口之外
• Select：按需读取文件、工具说明、知识库和历史记录
• Compress：摘要长输出和旧轨迹，保留决策和证据
• Isolate：用子 Agent 隔离研究、review、并行任务和高噪声探索

Agent Skills是渐进披露的具体机制：启动时只暴露 name / description，需要时才读取完整 SKILL.md 和 references。这样可以把组织流程、工程经验和领域知识做成可复用包，而不是永久塞进系统 prompt。

第六层：多 Agent、长任务与生产可靠性

进入生产级可靠性后，重点变成五个问题：

• Agent 如何长时间工作而不丢状态？
• 多个 worker 如何并行而不污染彼此上下文和工作区？
• 危险权限如何被沙箱、审批和护栏隔离？
• 失败如何转化为 eval / repair loop，而不是一次性调试记录？
• 真实运行 trace 如何反向推动 harness 改进？

Multi-Agent Research System（多智能体研究系统）展示了一类多 Agent 生产结构：planner 拆任务，parallel agents 搜索，最后合成结果。关键经验不是“多 Agent 天然更聪明”，而是它用更多 token 和并行搜索换取覆盖率，需要 checkpoint、trace、部署控制和评估体系支撑。

Long-running Agent Harness则说明长任务不能只靠自动压缩。可恢复任务需要把连续性外化到环境里：progress file、git history、feature list、初始化脚本、测试状态和增量提交共同构成接力制度。

面向 Agent 的工具设计和 Model Context Protocol（模型上下文协议）进一步提醒：工具不是越多越好。大规模 MCP 场景里，把上百个 tool definition 全塞进上下文会制造选择噪声和 token 成本；更好的做法可能是代码执行式访问、命名空间治理、按需检索和工具响应压缩。

第七层：Eval、安全和改进飞轮

最后一层是 Evals（评估）、Agent Guardrails（Agent 护栏）、Agent Sandbox（Agent 沙箱）和可观测性。它们决定 Agent 是否能从“偶尔成功”进入“可持续改进”。

Agent eval 的核心边界是：被测对象不是模型本身，而是模型 + agent harness + 工具 + 环境 的组合。评估系统要记录 trace / transcript，检查 outcome，调用 grader，并把结果转成回归样本。早期应先用 trace grading 发现 failure mode，再沉淀 dataset 和 eval run。

最贴合工程飞轮的是 Agent Improvement Loop：

flowchart LR
    T["真实 traces"] --> F["human / model feedback"]
    F --> E["生成 evals"]
    E --> G["eval gate"]
    G --> H["HALO / Codex handoff\n修改 harness"]
    H --> T

这个飞轮把一次性观察变成长期资产：每次失败 trace 都能沉淀为未来回归测试，每次反馈都能转成工具、prompt、guardrail、输出契约或 harness 代码的修改。没有这层，Agent 改进容易停留在“这次多写一句 prompt”；有这层，改进才可复跑、可比较、可审查。

安全层的重点不是一味弹窗，而是把风险分级：低风险动作自动批准，高风险动作进入人工审批，绝对禁止的动作交给 sandbox、permission 或 hook 确定性阻断。减少 approval fatigue 不能等于取消护栏；更合理的是用 classifier、策略和执行边界替代一部分低价值确认。

推荐学习顺序

如果只按最小闭环读，可以这样排：

1. 建立 workflow / agent / framework 判断力。
2. 判断需求是否真的需要 Agent。
3. 掌握 function calling、structured outputs 和工具调用边界。
4. 把 coding agent 变成可验证工作流。
5. 理解 context、memory、NOTES.md 和 durable artifacts。
6. 理解独立上下文 worker 和按需能力包。
7. 理解多 Agent 的真实成本与收益。
8. 理解跨上下文窗口的长任务接力。
9. 打磨工具表面和大规模工具接入。
10. 把失败 trace 变成评估和 harness 改进。

如果只保留六个重点，应优先覆盖：Agent 判断力、coding agent 工作流、上下文工程、多 Agent 生产结构、长任务 harness、trace 到 eval 的改进飞轮。

反面清单

几类低 ROI 方向适合作为概念补充，而不是主线：

• 过早学习大型 Agent framework，而没有先手写最小 loop
• 把 Agent Builder / UI 编排工具当成长期主线，而不是优先 code-first SDK 和 harness
• 把模型发布稿当工程教程，只看能力信号即可
• 把 Dify、ComfyUI 等产品视为 backend / runtime 根能力；它们更适合找 workflow inspiration
• 把“多 Agent”当架构目标，而不是在工具过载、上下文污染、并行搜索或独立验证确有收益时再拆

与相关概念的关系

• AI Agent（智能体） — 路线图的对象层
• Agentic System Patterns（智能体设计模式） — 0 -> 1 阶段的架构判断
• Agent Loop（智能体循环） — 最小运行结构
• Harness Engineering（驾驭工程） — 生产运行时的核心工程面
• Context Engineering（上下文工程） — 长任务和多工具 Agent 的信息管理层
• 面向 Agent 的工具设计 — 工具 schema、命名、响应和错误反馈的设计原则
• Evals（评估） — Agent 是否真的变好的外部尺子
• Loop Engineering（循环工程） — 把 Agent 放进可验证、可停止、可恢复的持续工作流