Agent 开发很容易被框架名称和演示效果带偏。一个 Agent 偶尔成功调用工具， 与一个能够被真实用户持续使用的系统之间，还隔着状态、权限、并发、恢复、 评测、成本和大量产品决策。这个系列记录的正是中间那段工程距离。
01
为什么写这个系列
这个系列来自两类问题。一类来自真实产品：怎样把用户一句模糊目标， 逐步变成可以保存、检查和继续修改的结果；另一类来自 Agent 岗位： 为什么招聘要求反复出现 Tool Use、Workflow、Context、RAG、Memory、 Trace、Replay、Eval、安全和高可用。
两类问题最终指向同一件事：模型只是系统中的一个不确定组件。 Agent 工程的工作，是让这个组件在明确边界内读取信息、调用工具、改变状态， 并让每一次成功和失败都可以被理解。
本系列不以“会使用多少 Agent 框架”为目标，而以“能否把一个 Agent 产品 设计、实现、上线、观测和持续改进”为判断标准。
系列边界
- 重点讨论 Agent 应用、Runtime、Harness 和工程平台。
- 包含产品设计、后端、前端、数据、基础设施和技术管理。
- 不把大模型训练、算法研究和论文复现作为主线。
- 不为展示概念而强行使用多 Agent、MCP 或复杂框架。
02
先建立一张系统地图
一个生产级 Agent 可以先被看成五层。后续每篇文章都会回到这张地图， 解释某项技术位于哪里、依赖什么，以及失败会影响哪一层。
| 层次 | 核心问题 | 典型技术 |
|---|---|---|
| 产品层 | 用户要完成什么，何时需要人工控制？ | 任务流程、流式界面、版本、反馈 |
| 运行层 | 任务怎样拆分、推进、暂停和恢复？ | 状态机、DAG、Checkpoint、队列 |
| 智能层 | 模型此刻应该看到什么、决定什么？ | Prompt、Context、RAG、Memory |
| 工具层 | 模型可以调用什么，权限边界在哪里？ | Tool Calling、MCP、Schema、审计 |
| 证据层 | 为什么成功或失败，版本是否真的更好？ | Trace、Replay、Eval、指标 |
安全、可靠性和成本不单独属于某一层。它们贯穿所有层次：产品需要解释失败， Runtime 需要保持状态一致，工具需要最小权限，证据层需要发现回归和异常成本。
03
八篇文章如何组织
专题入口固定为 /series/agent-engineering/。子文章使用语义化 URL， 不在路径中写序号；阅读顺序由专题页维护，因此以后调整顺序不会破坏链接。
生产级 Agent 的边界与架构
区分模型调用、聊天应用、工作流与 Agent 系统，建立从用户目标到运行结果的最小架构。
- 什么问题需要 Agent
- 确定性代码与模型判断
- Agent Runtime 的核心组件
- 生产级验收标准
模型接口、结构化输出与工具契约
把不稳定的模型输出收敛为可校验、可授权、可恢复的工具调用和业务协议。
- 流式与结构化输出
- Function Calling
- 工具输入输出契约
- 模型路由与降级
Runtime、状态机与长任务工作流
用状态、任务依赖和检查点管理规划、执行、人工确认、重试与恢复。
- Planner 与 Orchestrator
- DAG 与状态机
- 异步任务和并发
- 幂等、补偿与恢复
Context、RAG 与 Memory
让 Agent 在有限上下文中获得正确事实，同时控制来源、权限、时效和 Token 成本。
- 上下文分层与预算
- 完整 RAG 链路
- 记忆类型与生命周期
- 检索和引用评测
Trace、Replay 与 Eval
回答一次运行为什么成功或失败，并用固定测试集比较模型、Prompt 和工作流版本。
- Run / Step / Event
- Trace 与指标
- 安全 Replay
- 离线评测与线上反馈
可靠性、安全与权限治理
处理超时、重复执行、第三方故障、Prompt Injection、越权工具和敏感数据。
- 错误分类与降级
- 工具最小权限
- 人工确认与审计
- 容量、限流与故障复盘
把 Agent 做成可以上线的产品
把底层能力收进真实用户流程，通过前端状态、版本、成本和反馈形成完整产品闭环。
- 从用户任务开始
- Agent 产品交互
- 部署与可观测性
- 指标驱动迭代
Agent 项目的技术领导与团队交付
将系统拆成小团队可并行交付的模块，并管理接口、质量、风险、排期和技术债。
- 模块与责任边界
- 任务拆分和验收
- 技术决策与 Code Review
- 跨团队推进与复盘
当前只发布总览页。子文章会在内容完成后再建立正式路由，避免搜索引擎和读者 进入只有标题、没有论证和实践证据的占位页面。
04
用真实产品验证知识
系列的主要实践载体是 AI Story Writer。用户的目标不是“运行一个 Agent”， 而是把零散想法变成大纲、分页正文、插图和可以继续编辑的故事资产。 这条流程天然包含规划、工具、长上下文、异步媒体任务、人工确认和局部重试。
每个技术主题都要回到产品问题。例如，Memory 不是为了保存更多聊天记录， 而是为了在多轮创作中保持角色和用户偏好；Replay 不是重新运行整个故事， 而是从安全检查点只修复失败的一页；Eval 也不是得到一个抽象总分， 而是发现年龄适配、角色一致性、图文一致性和内容安全是否发生回归。
实践约束
文章会明确区分已经上线的能力、正在验证的设计和未来计划。 测试数据不会被包装成生产数据，相邻项目经验也不会被写成已经完成的功能。
05
什么才算真正掌握
系列中的每个核心主题都采用同一套证据标准。概念解释只是起点， 一项能力至少要从“理解”走到“实现”，关键能力最终要走到“生产”。
| 层级 | 判断标准 | 文章需要提供的证据 |
|---|---|---|
| 理解 | 能解释用途、边界和取舍 | 问题定义、反例和方案比较 |
| 实现 | 能完成受控功能并验证 | 协议、关键代码、测试和状态变化 |
| 生产 | 能处理真实运行与失败 | Trace、指标、成本、故障与修复 |
| 负责 | 能做架构与团队交付 | 决策记录、任务拆分、验收和复盘 |
- 一条完整 Trace：模型、上下文、工具、耗时、费用和错误。
- 一次安全 Replay：说明哪些副作用不会被重复执行。
- 一套固定评测：能够比较 Prompt、模型或工作流版本。
- 一个失败案例：包含根因、修复和防止再次发生的措施。
- 一组运行指标：成功率、P95、成本和错误分布。
06
写作与发布顺序
文章不必严格按目录顺序写。优先发布已经有真实实现和问题素材的主题， 再通过后续产品建设补齐 RAG、Replay、Eval 和高并发等证据不足的部分。
- 先写 Runtime 与长任务工作流，因为已有异步任务、并发和恢复实践。
- 再写模型接口与工具契约，沉淀现有 Function Calling 和资产版本协议。
- 随后完成 Context、RAG 与 Memory，并同时建立检索评测。
- 有统一运行数据后再写 Trace、Replay 与 Eval，避免停留在概念层。
- 最后汇总可靠性、安全、产品上线和技术领导，形成端到端案例。
每篇文章都应独立回答一个工程问题，同时链接回专题地图。系列完成后， 读者既可以按顺序学习，也可以从一次生产故障、一个技术名词或一项产品需求切入。