这两年几乎每个做 AI 应用的人都在做一个同样的动作把「聊天机器人」升级成「能自己干活的智能体Agent」。但真动手了才发现事情远比想象中复杂。它不再是「写一段更长的 Prompt」那么简单——你要让它自己规划步骤、调用工具、记住上下文、在出错的循环里自己走回来还要在它「越界」之前把它拦住。一个能演示的 Agent 和一个能上线的 Agent中间隔着一整套工程能力。这就是这个系列想解决的问题。为什么不写「怎么调 API」而是写「怎么搭一个能上线的 Agent」市面上讲 Agent 的内容大多停在两个层面要么是概念科普讲一堆术语要么是「十分钟搭一个 Demo」跑一遍就结束。但真正卡住人的恰恰是 Demo 之后的那一段路设计时没想清楚边界开发到一半发现状态机根本支撑不了复杂任务工具调得乱七八糟参数没有校验、失败没有重试线上一天崩三次多智能体一协作消息满天飞出了问题谁都定位不到最要命的——安全没做Agent 被一段外部内容牵着走越权操作了不该动的系统。光会「跑通」不等于「敢上线」。这个系列的定位维度设定目标读者有 Python/TS 基础的开发者、架构师、技术负责人不要求有 AI 背景学完能做到独立完成需求分析、架构设计、编码、评估、上线、安全加固的全流程与普通教程的差异讲「为什么这么设计」和「踩过的坑」不只讲 API 怎么调评估、可观测、安全这些别人跳过的部分单独成篇内容原则原理优先于框架每篇有案例、有取舍分析、有可运行产物篇数28 篇导览 1 设计 10 开发 10 安全 6 毕业项目 1贯穿全系列的主线案例SupportPilot客服工单 Agent一个 Agent 随系列逐步长大设计篇定义需求、画架构、设计工具和记忆。开发篇实现并接入知识库加评估、监控和部署。安全篇对它做威胁建模用提示注入攻击它、加固它并核验它的输出可信度。每篇另配一个轻量副案例代码审查、数据分析、研究助手等避免只会一种场景。每篇固定结构问题场景真实工作中会遇到的痛点一段案例只作引子核心概念用类比和一张图讲清设计取舍常见方案对比、什么时候用哪个动手实现对应主线项目的增量代码或配置踩坑清单常见错误、反模式和排查方法设计篇改为「典型失败模式」★产物与自测可交付物 3~5 道自检题下一篇预告★说明本篇产物如何被下一篇接着用配套一个 GitHub 仓库每篇对应一个分支或目录可单独运行。四、文章规划序章建立正确认知#标题核心内容可落地产物01Agent 到底是什么何时该用何时不该用从 Chatbot、Workflow 到 Agent 的自治度光谱Agent 模型 工具 循环多数场景用 Workflow 更好自主性与可控性的权衡★ 系列地图一个 Agent 从设计到上线要过哪几关① 适用性决策表 ② 50 行最小 Agent 代码第一部分设计篇02–11目标动手写代码之前能把 Agent 想清楚、画清楚。#标题核心内容可落地产物02Agent 架构全景图模型、工具、记忆、规划、编排、护栏、评估、可观测八大模块的职责与边界后续各篇在图中的位置参考架构图 模块职责表03从业务需求到 Agent 设计任务拆解、成功标准、自治级别谁决策、谁兜底、ROI★ 失败模式先行★ 状态机与终止条件设计一页纸设计文档模板含失败模式表、状态流转图填好 SupportPilot 版04模式选型单 Agent、Workflow 还是多 Agent提示链、路由、并行、编排者-执行者、评估-优化等模式每种的适用场景与代价模式选型决策树05提示词与上下文工程System Prompt 结构化写法上下文窗口预算动态上下文装配长任务的上下文压缩Prompt 模板 上下文预算表06工具设计Agent 的「人机界面」工具粒度、命名与描述、参数设计、错误信息给模型看、幂等与可回滚★ 工具契约schema、返回值规范、错误语义、副作用声明工具契约模板 设计 checklist 3 个工具 schema 示例07记忆与状态设计短期/长期/情景/语义记忆什么该记、什么该忘摘要、检索、写入策略会话状态 vs 持久状态记忆架构方案图 数据模型08规划与推理策略ReAct、Plan-and-Execute、反思纠错★ 三种范式的混合编排★ 成功/失败/超时三类终止条件★ 动态重规划与进度追踪的设计步数与预算限制规划器设计说明 循环预算配置 终止条件表09知识接入设计RAG 与 Agentic RAG何时需要 RAG切分、检索、重排的取舍让 Agent 自己决定检索什么知识库接入方案含数据流图10多 Agent 协作设计角色划分、通信与交接、共享状态★ 消息协议与责任边界多 Agent 的真实成本什么时候不该用多 Agent 拓扑图 职责与消息协议契约模板11人机协同与交互设计审批点怎么选、何时中断与澄清、置信度升级、失败时的体验、让用户看得到 Agent 在做什么人工介入流程图 审批点清单第二部分开发篇12–21目标把设计变成稳定运行、可评估、可上线的系统。#标题核心内容可落地产物12从零手写 Agent 循环再决定用不用框架函数调用协议、消息历史管理、结构化输出、流式响应★ 脚手架与运行时目录结构、配置管理理解底层后再比较 LangGraph、OpenAI Agents SDK、Claude Agent SDK、Pydantic AI 等的取舍与模型选型方法约 200 行可运行 AgentSupportPilot v0.1 选型评分表 项目脚手架13工具实现与可靠性并行调用、超时、重试、参数校验、错误回传★ 超时熔断与降级有副作用的工具如何做幂等与确认沙箱执行工具库 单元测试14MCP 与工具生态MCP 协议的角色自己写一个 MCP Server接入第三方 Server 的注意点一个可被 Agent 调用的 MCP Server15规划器与工作流编排图/状态机编排★ 子目标依赖管理、执行中动态重规划、进度追踪检查点、断点续跑、人工审批中断恢复长任务异步处理带 checkpoint 的规划与工作流工单处理流程16记忆与 RAG 落地向量库与混合检索重排长期记忆的写入、更新、遗忘检索质量排查可运行的 RAG 记忆模块17多 Agent 实战编排者-执行者实现子 Agent 的上下文隔离★ 消息与交接协议的实现、责任边界怎么落结果汇总与冲突处理多 Agent 研究助手副案例18评估体系EvalsAgent 开发的地基构建测试集结果评估 vs 轨迹评估★ 多维指标任务成功率、步骤正确率、越权率、成本/时延LLM-as-Judge 校准回归测试与 CI 集成评估数据集 评估脚本 CI 配置19可观测与调试Trace、日志、指标★ 执行回放定位「从哪一步开始错」成本、延迟、工具成功率监控Tracing 接入 回放脚本 监控看板配置20性能、成本与稳定性优化提示缓存、模型路由大小模型分工、并发、限流、降级与兜底成本优化清单 模型路由实现21部署、发布与运维服务化封装、异步任务与队列、流式接口★ 环境隔离、灰度放量与快速回滚Prompt 与工具的变更管理监控告警Docker 部署 API 服务 发布 checklist含回滚预案第三部分安全篇22–27目标把 Agent 看成「拥有权限、会被攻击、也会出错」的软件系统而不只是模型应用。#标题核心内容可落地产物22Agent 威胁建模攻击面全景信任边界OWASP LLM / Agentic 风险对照「私有数据 不可信输入 对外通信」三要素叠加的风险SupportPilot 威胁模型文档 风险矩阵23提示注入与间接注入防御直接与间接注入网页、邮件、文档、工具返回值纵深防御★ 指令分层、外部内容隔离、★ 内容进入上下文前的实时拦截、输出校验、关键操作二次确认为什么不能只靠「提示词里写不许」防护层代码 攻击测试集按类别与生成方法组织24权限、身份与工具安全最小权限凭证管理沙箱隔离MCP 与第三方工具的供应链风险★ 高危操作分级只读 / 可逆写入 / 不可逆及对应授权方式权限矩阵 动作分级表 沙箱配置25★ 幻觉、失真与错误传播为什么 Agent 的幻觉比 Chatbot 更危险错误会成为下一步的输入比对工具输出与 Agent 声称结论与证据绑定追踪错误如何跨步传播低置信度时升级人工事实核验中间件 错误传播链追踪脚本 失真案例集26数据安全、隐私与审计PII 识别与脱敏记忆投毒与数据泄露★ 全量审计日志合规要点脱敏中间件 审计日志规范27红队测试、护栏与应急响应自动化红队输入输出护栏的取舍与误伤实时拦截策略的上线与调参线上监控与告警事故响应流程★ 快速回滚演练红队用例集 上线前安全检查表终章整合交付#标题核心内容可落地产物28毕业项目独立交付一个生产级 Agent用设计文档、代码、评估、监控、安全检查表走完全流程复盘常见失败模式能力自测与后续学习路线完整 SupportPilot 仓库 全流程检查表 能力自测表五、学习路径与能力对照学习路径读者角色建议路径完整学习者01 → 28 顺序读约 8~10 周想先快速上手的开发者01 → 12 → 13 → 18 → 23再回头补设计篇架构师 / 技术负责人01–11 → 18–20 → 22–27安全或平台团队01 → 02 → 06 → 22–27学完能做什么工作任务对应文章判断一个需求该不该用 Agent、用哪种模式01、03、04写出 Agent 设计文档并评审02–11实现带工具、记忆、知识库的 Agent12–16做多 Agent 或长流程工作流10、15、17证明 Agent 好不好用防止改坏出错时能定位18、19、25控制成本、保证稳定、完成上线与回滚20、21识别并防御 Agent 特有的安全风险22–27六、下一篇预告Agent 系列01Agent 到底是什么何时该用何时不该用