AI Agent 开发 — 公共学习路线图

面向初入 AI Agent 开发领域的程序员实用指南。本文聚焦于开源 Harness 项目、主流框架以及何时该构建什么——无需从零手写 Agent 运行时。

更新时间： 2026-09-05

1. 心智模型：四层架构

在挑选工具之前，先把任何 Agent 系统解构成四个层次：

┌─────────────────────────────────────────┐
│  4. 记忆 / 知识 (RAG、数据库、Playbook)    │
├─────────────────────────────────────────┤
│  3. 工具 / 插件 (MCP、API、CLI)          │
├─────────────────────────────────────────┤
│  2. 流程编排    (谁来决定下一步？)       │
├─────────────────────────────────────────┤
│  1. 底层模型    (GPT、Claude、本地模型)  │
└─────────────────────────────────────────┘

核心认知： 大多数初学者过度关注第 1 层（用什么模型）。生产环境的真正差距其实拉在第 2–4 层（编排、工具、记忆）。

Agent 绝非普通聊天机器人（Chatbot）。Agent 的本质是：

模型 + 工具 + 循环（Loop）+（可选的）记忆

2. 两大核心编排范式

维度	工作流型 Agent（代码编排）	自主型 Agent（工具编排）
控制权	开发者在代码中预定义流程	LLM 在运行时自主选择工具
LLM 角色	流水线内部的决策/处理节点	驱动主循环的调度器 / 大脑
工具调用	代码逻辑决定何时调用何物	LLM 自行阅读工具 Schema 并决断
状态机	显式状态图：`A → B → 条件门控 → C`	隐式循环：思考 → 行动 → 观察 → 重复
输出约束	强 Schema 校验（严格的 JSON Schema）	约束偏弱；主要依赖 Prompt 与工具说明
可预测性	高	中至低
灵活性	低（扩展能力需改动图逻辑）	高（扩展能力只需补充工具及文档）

形象比喻

工作流型 Agent ≈ 工厂流水线 + 某个质检环节设立的智能检测站
自主型 Agent   ≈ 携带工具箱的专家；你给目标，他自主规划步骤

选型原则

何时选择工作流编排：

动手写代码前就能画出完整的业务流程图
成功标准可被明确量化（测试全部通过、指标达成阈值）
需要无人值守的批量执行、完整的审计跟踪与失败回滚
错误容忍度极低、容错成本高昂（如金融、运维、合规等场景）

何时选择自主编排：

第一步该做什么无法提前预知
任务需要跨系统临场发挥（结合代码、数据库、日志、工单）
交互过程中始终有人类在旁边把关与纠偏
工具生态持续膨胀，不希望频繁重构流程图

决策捷径： 问自己一句——“写代码前我能画出流程图吗？”。若能，首选工作流；若不能，选择自主循环并配合强护栏（Schema 校验、状态回滚、人工审批）。

混合架构（生产环境最常见）

层级	常见落地策略
外层壳体	采用工作流处理批处理作业、Cron 定时任务及 API 外部触发
内部节点	嵌入 LLM 负责局部决策（例如：分类判断、生成修复建议）
记忆系统	结构化 Playbook（高置信度事实）+ Markdown 技能库（人机通用）
安全把关	人工介入审批（Human-in-the-loop）、中断节点（`interrupt`）、上线发布流水线

3. 六种常见 Agent 架构

除上述两大编排范式外，这六种属于组合设计模式，而非孤立形态：

模式分类	流程控制者	常见脚手架 / 底座	核心实现内容
工作流 / 状态机	代码逻辑	LangGraph、Temporal、n8n	状态图结构与节点执行逻辑
工具调用 / ReAct	LLM 自主驱动	Cursor、OpenAI Agents SDK、Claude Code	工具实现、MCP 协议、Prompt 指令
RAG（检索增强）	检索策略 + LLM	LlamaIndex、Dify	文档处理流水线与检索 Prompt
多智能体（Multi-agent）	协同调度协议	CrewAI、AutoGen、LangGraph 子图	角色定义与任务交接规则（Handoff）
人机协同（HITL）	代码逻辑 + 人工	LangGraph `interrupt` 节点	关键节点的人工审批拦截门控
评估优化循环	代码逻辑 + 评分器	LangGraph 循环、自定义 Eval 套件	打分逻辑与动态重试机制

生产项目通常混合使用——例如：工作流壳体 + 评估重试循环 + 人工审批门控 + 局部 LLM 自主决策。

4. 框架 vs Harness vs 平台

类别	定义	代表项目	适用场景
框架（Framework）	提供编排能力的库	LangGraph、OpenAI Agents SDK	需要自建完整的业务产品外壳
Harness（运行时底座）	包含循环、会话、工具、插件的完整 Agent 运行时	Hermes、OpenClaw、OpenCode、DeepSeek Harness	学习、二次开发或定制完整的 Agent 终端产品
平台（Platform）	提供低代码可视化画布、UI 与托管环境	Dify、Flowise、Coze	快速上线问答/机器人；定制化运维逻辑少

是否需要从零手写运行时？ 绝大多数情况下不需要。

目标	推荐方案	避免踩坑
学习基础概念	使用成熟平台或开源 Harness	第一天就手写底层 ReAct 循环
扩展团队 AI 能力	编写 MCP 服务或业务 API 插件	自研通用聊天底座
生产级批处理流水线	LangGraph + 业务系统代码	依赖纯 Prompt 调用的简易脚本
日常辅助编程	Cursor / Claude Code / OpenCode	重造一个代码辅助 Agent
企业内部文档问答	Dify / LlamaIndex	从零自建向量检索基础设施

核心准则： 需求越偏向“通用智能”，越应复用现成宿主；需求越强依赖“个性化业务规则”，越需要自己掌控编排层。

5. 开源 Harness 项目解析

以下 4 个项目属于自建 Agent 运行时（Harness）——它们并非对 LangGraph 或 Dify 的简单封装，而是完全自主掌控 ReAct 循环、会话管理、工具派发与插件系统。LLM 仅是其中的一个执行组件。

项目	核心特质	Agent 循环实现	是否基于 LangGraph？	技术栈
DeepSeek Harness	纯粹的插件化设计	基于 Cordis 插件系统（循环本身可热拔插）	否（基于 Cordis）	TypeScript
OpenClaw	个人/团队助理 + 接入网关	自研循环（`@openclaw/agent-core`）	否	TypeScript
Hermes Agent	全栈通用 Agent	自研 Python 版 `AIAgent` 运行时	否	Python
OpenCode	终端原生代码 Agent	基于 Effect 架构的提示词驱动循环	否（仅使用 LangSmith 追踪）	TypeScript

Harness 的本质构成： 会话管理 + 工具路由 + 权限控制 + 记忆系统 + 多渠道/UI 接入 + 可观测性追踪。

5.1 DeepSeek Harness — 万物皆插件

cordis.yml
    ↓
Cordis 内核（挂载 / 卸载 / 依赖注入）
    ↓
插件生态：模型 / 工具 / Agent 循环 / 沙箱 / 会话日志 / 交互 UI ...

极致插件化架构：连 Agent 自身的思考循环都可以作为插件热替换
会话采用 Append-only 事件流管理（天然支持恢复、分支 Fork、历史重放）
深度支持 MCP、ACP、AGENTS.md / CLAUDE.md 规范
目前处于开发者预览阶段——适合用于架构思想研读，暂不推荐直接作为生产底座

5.2 OpenClaw — 网关 + 嵌入式运行时

WhatsApp / Telegram / Slack / Webhook ...
    ↓
Gateway 网关（WebSocket 控制平面、会话路由、任务队列）
    ↓
runEmbeddedAgent 核心（ReAct 循环）
    ↓
Tools / Skills / Plugins / 生命周期 Hooks

擅长多渠道（Multi-channel）分发接入与本地网关化部署
内置完善的安全钩子（如 before_tool_call 拦截校验）
Hermes 项目专门提供了从 OpenClaw 配置迁移的工具脚本

5.3 Hermes Agent — 生产级 Python Harness 标杆

CLI / Gateway / ACP / Cron / REST API
    ↓
AIAgent.run_conversation()
    ↓
Prompt 组装 + Provider 动态解析 + 工具分发路由
    ↓
70+ 内置工具 / MCP 协议 / Skills 技能 / Subagents 子智能体
    ↓
底层沙箱环境：本地、Docker 容器、SSH 远程、Modal、Daytona 等

完全手写的轻量调度循环（不依赖第三方重型编排库）
自成体系的认知闭环：支持技能沉淀、动态记忆提取、跨会话搜索
内置 2.5 万行级单元/集成测试——最扎实的企业级代码架构教材

推荐精读顺序：

Architecture（总体架构）
Agent Loop Internals（循环内核）
Tools Runtime（工具执行系统）
Gateway Internals（网关实现）
Plugin Guide（插件开发）
Security（权限安全）

5.4 OpenCode — 终端优先的开源编码智能体

TUI 终端界面 / 桌面客户端 / IDE 扩展
    ↓
OpenCode Server 服务端（基于 Effect AppLayer 架构）
    ↓
Session + Agent + ToolRegistry + Plugin + LSP 语言服务
    ↓
Prompt 循环 → LLM 解析 → 工具调用 → 递归循环

深度集成 LSP（Language Server Protocol），代码理解能力远超普通 Grep 检索
具备明确的模式隔离：build（完整读写执行权限）与 plan（只读分析模式）
目前开源生态中最接近商业化 Cursor 编码体验的实现形态之一

5.5 Harness 与框架的关系梳理

框架/协议	在上述开源 Harness 项目中的定位
LangGraph	基本不使用——Harness 本身就是独立产品级的编排层
Dify	不使用——属于不同层面的产品形态
LangChain	极少作为核心依赖（OpenCode 仅引入 LangSmith 用于调用追踪）
OpenAI Agents SDK	不使用——自主实现 ReAct 状态循环与工具调度
MCP	全面支持——作为工具生态的标准扩展载体
Skills / AGENTS.md	全面支持——用于外部注入领域上下文与 SOP 约束

行业落地规律：

产品级 Agent 终端（个人助手、编程 Agent）→ 倾向于自建/采用专业 Harness
企业后台业务链路（数据批处理、严格合规）→ 倾向于 LangGraph
内部知识问答助手 → 倾向于 Dify

6. 主流框架对比：LangGraph vs OpenAI Agents SDK vs Dify

对比维度	LangGraph	OpenAI Agents SDK	Dify Agent
一句话定位	基于状态图的高精度编排引擎	官方轻量级工具调用 SDK	集成对话 UI 与 RAG 的低代码平台
流程主导权	开发者定义图结构；模型在节点内推演	模型主导驱动整个工具调用链	界面配置为主；支持可视化分支画布
代码量要求	高（全代码构建）	中等	极低（零代码/轻代码）
前端聊天 UI	需自行开发	需自行开发	内置开箱即用
确定性工作流	极强	较弱（高度依赖 Prompt 诱导）	中等
人工介入审批	原生支持（`interrupt` 机制）	需自行基于状态机封装	功能支持相对有限
状态回滚与快照	内置 Checkpoint 快照机制	需自行实现	不支持
RAG 知识库	需自行接入向量库与检索链	需自行接入	内置且功能完善
可测试性	极高（支持单节点独立单元测试）	中等	较低（偏黑盒调试）
学习曲线	较陡峭	平缓	最易上手

选型口诀：

流程明确成图 + 需要极高可靠性    →  选择 LangGraph
快速构建工具代理 + 探索开放场景    →  选择 OpenAI Agents SDK
快速交付知识问答 + 不想折腾前端    →  选择 Dify

框架学习建议路线：

OpenAI Agents SDK（1–2 天）：快速建立模型自主调用工具的直观感受
LangGraph（1–2 周）：掌握何时必须从模型手中收回流程控制权
Dify（半天）：了解低代码平台的效率天花板及其能力边界

7. 如何选择 Agent 宿主（Host）

在自主型 Agent 场景下，如果你只打算编写插件（MCP、自定义工具、规则文档），优先借力成熟宿主：

五维筛选法

1. 工作场景在哪里？   IDE / 终端环境 / 网页端 / 后端常驻服务
2. 目标用户是谁？     个人使用 / 团队内部协作 / 面向外部 C 端客户
3. 数据隐私要求？     必须本地化部署 / 允许调用商用 Cloud API
4. 自主决策级别？     建议咨询型 / 半自动（人工审核） / 全自动无人值守
5. 预算约束情况？     按月付费订阅 / 本地自备 GPU 算力

宿主类型矩阵

宿主类型	代表产品	你的开发重心	最佳应用场景
IDE / 开发者工具	Cursor、Claude Code、OpenCode	编写 MCP 插件、配置规则、沉淀 Skill	日常辅助编码、代码排错
可嵌入 SDK	OpenAI Agents SDK、LangGraph、Vercel AI SDK	编写业务工具 + API 网关 + 自研前端	嵌入既有 SaaS 产品作为新功能
低代码可视化平台	Dify、Flowise、Coze	维护知识库数据、调优 Prompt	快速搭建智能客服、知识库助手
后端后台流水线	LangGraph、Temporal + LLM	编写业务状态图 + 设计安全护栏	批处理、高 SLA 任务、严格审计

选型决策树

日常需要高频写代码、排查环境 Bug？
  └─ 选 Cursor 或 Claude Code + 接入自定义 MCP

企业内部资料与产品手册问答？
  └─ 选 Dify 或 LlamaIndex + 直接上传文档建库

需要把 AI 功能嵌入到现有的产品服务中？
  └─ 选 OpenAI Agents SDK 或 LangGraph + 封装自身 API

运行无人值守、步骤严格的后台批处理？
  └─ 选 LangGraph 工作流编排

打造企业级综合自治助理（对接群聊、执行运维）？
  └─ 深入研读 Hermes + OpenClaw；结合 LangGraph 补充审批节点

8. 8–12 周学习路线图

按业余时间（每晚/周末）投入规划，可根据实际进度调节节奏。

阶段 0 — 建立直觉（第 1–2 周，轻代码）

学习目标： 厘清 Agent 的能力边界与技术定位。

选用 Cursor 或 Claude Code 完成一项实际开发任务；细致观察它何时检索文件、何时执行 Shell、何时主动请求确认
精读 Anthropic 经典报告：Building effective agents
掌握核心术语概念：Harness、Tool、Skill、MCP、Memory、ReAct、Interrupt

阶段通关标准： 能向同行条理分明地讲清楚四层架构模型与两种编排范式的差异。

阶段 1 — 成为工具（MCP）开发者（第 2–3 周）

学习目标： 不重复造轮子，先通过扩展已有 Agent 获取最高投入产出比。

研读 modelcontextprotocol.io 官方规范文档
动手编写一个轻量级 MCP Server（例如：封装只读 HTTP 接口，或读取本地 JSON 数据）
将该 MCP 服务挂载接入 Cursor / Claude Code
刻意练习工具描述文本（Tool Description）编写——好的文档说明决定了模型的路由准确率

实战项目：

编写一个运维 MCP 服务：暴露只读的 /health 检测与任务状态查看接口
→ 使宿主 Agent 能够准确回答“服务当前存活吗？”与“后台批处理任务完成度如何？”

阶段通关标准： Agent 能稳定在预期场景下触发工具调用，而不是胡乱捏造接口参数。

阶段 2 — 编写规则（Rules）与技能（Skills）（第 3–4 周）

学习目标： 学会利用结构化文档精准约束模型行为，避免把 Prompt 无限制拉长。

研究 Cursor 的 .mdc 规则机制与自动化 Skill 工作原理
提炼并编写一条团队铁律：不可违背的硬性限制（如：严禁未经确认执行数据删除）
提炼并编写一个技能文件：针对某种高频任务的可执行标准作业程序（SOP）

阶段通关标准： 当 Agent 遇到对应场景时，能在无需人工反复贴上下文的情况下自动遵循该 SOP。

阶段 3 — 基于 LangGraph 构建工作流 Agent（第 4–7 周）

学习目标： 掌握企业级工程化模式——状态传递、条件路由、错误回滚与链路追踪。

完成 LangGraph 官方入门：构建经典的 3 节点图（用户输入 → LLM 分类路由 → 业务输出）
引入条件分支边（Conditional Edge）与自动重试环路
引入 interrupt 节点实现人工确认机制
接入链路追踪套件（Langfuse 或 LangSmith）

阶段通关标准： 拥有一套完整的状态图工程，能对分支路由逻辑执行单元测试，且 LLM 输出均通过 Schema 校验。

阶段 4 — 构建自主工具型 Agent（第 7–9 周）

学习目标： 透彻对比 ReAct 自主循环与工作流状态机之间的取舍与权衡。

使用 OpenAI Agents SDK 或 LangGraph 的 create_react_agent 重写阶段 3 的业务任务
挂载 2–3 个执行工具
横向评测：在稳定性、Token 开销、边界失效模式上与纯图方案做差异对比

阶段通关标准： 能给出充分的技术依据，论证特定场景下何时该放权给模型自主探索，何时必须收归状态图硬编码。

阶段 5 — 攻坚主流 Harness：Hermes Agent（第 3–6 周，可与阶段 3 并行）

学习目标： 彻底吃透一套生产级 Python Harness 的完整代码实现。

本地安装与体验：hermes 命令行交互、hermes gateway 网关模式、查看 hermes tools 注册列表
研读架构文档（重点参考 §5.3）
关键源码断点调试跟踪：run_agent.py、tools/registry.py 以及网关路由入口
尝试手写一个原生插件，或挂载自定义 MCP 服务

阶段通关标准： 能手绘完整的调用拓扑链路图：接收外部指令 → 驱动思考循环 → 动态解析派发工具 → 格式化响应输出。

阶段 6 — 攻坚网关与产品形态：OpenClaw（第 5–7 周，并行推进）

学习目标： 掌握多渠道接入控制、网关层隔离与执行前拦截机制。

研读 OpenClaw 网关设计与安全权限模块
分析其生命周期 Hooks（拦截器）、会话排队机制与插件 SDK
与 Hermes 架构做横向比对：两者在抽象层面上哪些殊途同归，哪些取舍不同

阶段通关标准： 能向他人解释如何扩展一个全新的通讯软件适配器，以及如何在执行高危工具前插入权限拦截钩子。

阶段 7 — 知识库增强与效果评估（第 9–10 周，进阶可选）

学习目标： 应对强专业知识依赖的复杂场景。

选型脚手架：引入 LlamaIndex 或私有化部署 Dify
深入认知：在事实准确率上，切片策略（Chunking）与向量表征质量对最终效果的影响远高于单纯替换大模型
构建闭环：设计“生成 → 评估打分 → 不合格反思重试”的自优化链路

阶段 8 — 毕业设计：端到端 POC 落地（第 10–12 周）

动手开发一个具备企业实战雏形的小型闭环项目。推荐选题：只读式 VPS 服务器诊断排错助理

架构分工	推荐技术落地
接入层	命令行 CLI 或轻量 Gateway 网关
核心循环	参考 Hermes 的自主循环，或 LangGraph 混合架构
工具层	3–5 个安全只读工具（云平台查询 API + 白名单只读 SSH 命令）
安全控制	任何产生写操作/状态变更的命令必须经过人工二次确认
可观测性	全量操作审计日志入库 + LLM 调用追踪（Trace）

这一步的实战收益远胜于泛泛精读十个开源仓库。

精力分配建议（主攻企业级自主 Agent 方向）

学习对象	精力占比	重点攻坚模块	初学者可先跳过的部分
Hermes Agent	40%	思考主循环、工具注册派发、网关架构、插件扩展、测试体系	无需通读自带的全部 70+ 工具细节
OpenClaw	25%	Gateway 网关、安全设计、Hooks 拦截机制、多渠道转发	繁杂的非核心渠道适配器代码
LangGraph	25%	`interrupt` 节点、快照持久化机制、条件分支边	试图强行拿它重造通用的桌面助理
OpenCode	10%	LSP 服务的集成方式、`plan/build` 模式状态切换	复杂多变的代码生成特定优化细节
DeepSeek Harness	5%	学习基于 Cordis 的极端插件化抽象构想	不要直接照搬用于搭建团队生产系统

9. 实战场景指南（Playbooks）

9.1 场景一：低成本代码库 Bug 诊断 Agent

核心定位： 在已有代码库中实现自主故障排查与溯源——切忌从零再造一个 IDE。

严禁踩坑（Don’t）	推荐做法（Do）
尝试重写交互界面与 ReAct 底层循环	直接将 Cursor / Claude Code / OpenHands 作为宿主底座
重新用代码写一遍 `read_file`、`grep`、`find`	全面复用宿主自带的工具链；仅封装专属领域 MCP
一上来就设计多个 Agent 协同分工	采用单 Agent + 结构化 SOP + 3–5 个专用 MCP 工具
盲目微调（Fine-tune）代码大模型	使用顶级通用模型 + 针对性 Rules/Skills + 关键上下文检索

极简架构设计：

现成 Agent 宿主（Cursor / Claude Code / OpenHands）
        │
   ┌────┼────┐
   ▼    ▼    ▼
领域文档  专用 MCP  校验机制
 Rules   Tools    脚本/测试用例
Skills           可量化验收指标

必须落地的四个层级：

领域知识文档 — Rules（不可违背的红线）、Skills（标准化作业程序）、历史 Case 库
专用 MCP 服务 — 问题复现、状态观察、数据检索（严控在 3–5 个核心接口内）
回归验证工具 — 执行单元测试与 Lint 检测（确保“没有引入新的破坏”）
确定性验收 — 跑通量化指标或验收脚本（确保“Bug 确实被根治”）

故障排查标准化流程（Skill 模板示例）：

1. 问题复现 —— 优先调用工具采集关键环境信息与报错上下文
2. 对照契约 —— 认真核对接口文档与业务规范，严禁靠常识盲猜
3. 提出假设 —— 一次只定位一个最可疑的根本原因（Root Cause）
4. 最小修改 —— 实施最小范围的精确代码调整
5. 回归验证 —— 触发执行既有的自动化回归测试集
6. 效果验收 —— 运行可量化的验证脚本；严禁主观判断“代码看着没问题了”
7. 失败回滚 —— 一旦指标未达标，立即撤销修改，转向下一个备选假设

4 周分步交付规划：

周期	核心交付目标
第 1 周	编写 1 份 SOP 技能文件 + 1 个只读 MCP 接口；确保 Agent 能够稳定触发该工具
第 2 周	将回归验证与可量化验收脚本接入到 SOP 的执行末端
第 3 周	建立历史典型 Case 库（按“症状特征 → 根因归纳 → 专项测试”格式沉淀）
第 4 周	（可选）接入 CI 流程，通过 OpenHands 或 LangGraph 实现夜间批量排查

9.2 场景二：云厂商 VPS 智能控制台助手（面向 C 端产品）

核心定位： 嵌入在云服务控制台中的对话助手——可查询机器状态、通过 SSH 执行安全排查，并在经用户二次确认后安装排障环境。

此场景无法采用 Cursor 作为宿主。 必须自建包含前端 UI、编排后端与 SSH 隔离网关的完整系统。

系统架构拓扑：

C 端 Web 对话界面（支持打字流式响应、审批弹窗交互、执行日志折叠展示）
        │ HTTPS / WebSocket 通讯
BFF 业务聚合层 / Agent API（鉴权认证、租户资源隔离、会话上下文管理、审计存证）
        │
   ┌────┼────┐
   ▼    ▼    ▼
LangGraph编排层   工具执行层       记忆存储层
（状态机与审批门控） 云 API + SSH 网关  会话状态库 + 运维知识库

安全底层原则：

严禁让大模型直接面对原生 SSH Shell 交互——必须封装成参数强校验的 Tool API
默认权限一律设为只读模式；所有涉及写入、重启、安装的操作必须弹出卡片由用户点击确认
完整留存所有执行命令与返回参数的审计追溯日志

阶段演进路线：

阶段	交付范围	周期预估
第 1 阶段（MVP）	搭建交互 UI、对接云控制台只读 API、打通只读白名单 SSH 命令通道、仅提供建议不自动执行	4–8 周
第 2 阶段（可操作态）	引入人工审批后执行环境安装/服务重启、对 SSH 网关进行安全沙箱加固、接入排障 RAG	+6–10 周
第 3 阶段（成熟产品态）	接入主动异常预警、多机批量巡检能力、细粒度 RBAC 权限控制、云资源成本优化分析	长期迭代

推荐技术选型：

层次划分	推荐选型方案
交互前端	React + Vercel AI SDK（或复用现有控制台前端组件体系）
业务服务端	Python FastAPI 或 Go 服务
编排框架	LangGraph（利用其原生 `interrupt` 特性支撑审批流）
底层模型	商业主流大模型 API（按数据合规与资质要求选型）
检索数据库	PostgreSQL + pgvector 插件或 Milvus 向量库
SSH 通信网关	自研隔离网关（或集成 Teleport / Boundary 等开源访问控制设施）
运维可观测	Langfuse 链路追踪 + 业务数据库审计日志表

10. 最佳实践

10.1 动手前先自问：“真的需要 Agent 吗？”

适合使用 Agent 的场景：

任务执行步骤不固定，需根据中间返回动态调整
存在海量非结构化、半结构化信息需要提炼综合
处于开放式的探索排查流程中

使用 Agent 属于过度设计的场景：

业务逻辑与判断规则 100% 可以被代码分支穷举 → 请直接写传统业务代码
系统对吞吐有极高要求，要求毫秒级低延迟响应 → 严禁链路引入 LLM

10.2 严格防线（Guardrails）远胜于技巧调优

强制 Schema 校验格式    >  在 Prompt 中苦苦哀求模型返回 JSON
代码层具备回滚机制      >  轻信模型保证“我一定会小心操作”
默认拒绝（Fail-closed） >  出事时依赖“尽力而为”的兜底
人工审核晋级知识库      >  允许模型自主把记忆回写到生产知识库

10.3 第一天就必须做好可观测性

尽早引入 Langfuse / LangSmith 或在内网落盘结构化 JSONL 日志
完整持久化每一次 LLM 调用的原始 Prompt 与输出 Token
完整记录每一次工具调用的入参、执行耗时与返回内容

如果缺乏可追溯的链路监控，复杂的 Agent 系统在排错时就是一个彻底无法调试的暗室。

10.4 测试工程化策略

被测对象	测试方案
工具层接口 / API	编写常规的单元测试（确保入参校验与容错正常）
状态图流转路由	给定固定 Mock 状态 → 断言下一跳目标节点是否准确
LLM 返回内容	强校验 JSON Schema 结构 + 维护黄金基准测试集（Golden Fixtures）
全流程端到端表现	建立典型测试用例库进行批跑回归 + 定期人工随机抽样抽查

千万不要通过编写 assert llm_output == "某段具体的字符串" 来测试 Agent。

10.5 记忆体系的分层治理

存储层级	主要记录内容	写入更新机制
会话短期记忆	当前轮次上下文与历史对话	由运行时框架自行压栈管理
结构化记忆	经过校准的 Playbook、YAML 配置、事实档案	业务代码更新 + 必须经过人工复核
RAG 检索层	外部技术手册、代码全量索引	自动化 ETL 摄入与切片流水线
自由文本反思记忆	模型自行总结的“经验教训”	谨慎引入——极易导致幻觉污染并在后续轮次自我发酵

11. 应避免的反模式

同时并行精读 4 个 Harness 项目源码 — 各家架构设计多有交集，容易混淆思路；务必单点突破、有序推进
把 DeepSeek Harness 直接用于生产环境底座 — 其极致的插件机制极富学习价值，但现阶段尚不具备成熟商业交付的稳定性
只死磕 LangGraph — 它是优秀的业务流水线编排器，但无法直接等同于一套开箱即用的产品级自主 Agent 终端
只掌握 Dify 等无代码平台 — 交付普通对话机器人效率极高，但无法支撑需要深度与底层系统交互、精细把控权限的复杂场景
在没有代码积累的第一天手写 ReAct 底层循环 — 建议先看透 Hermes 和 OpenClaw 的成熟实现，再评估自身是否真有重造轮子的必要
一口气给模型挂载过多工具 — 起手严格限制在 3–5 个；工具调用的失误率与选项数量呈指数级正相关
依靠主观感受评估优化效果 — 务必引入确定性脚本与测试集；绝不可让模型自己给自己打分断言“修复得很好”
过早引入复杂的多智能体架构（Multi-agent） — 在绝大部分落地场景中，一个配置了清晰 SOP 与完备上下文的单 Agent 表现远比一群缺乏约束乱发消息的智能体更稳健

12. 参考链接

概念与理论

主流框架

开源 Harness 项目

可观测性工具

核心要点速查卡（Cheat Sheet）

常见疑问	结论与建议
Agent 只有两种类型吗？	不是。核心分野在于代码控制编排还是模型自主编排；其他架构均为二者的不同组合与派生。
我需要从零手写运行时吗？	不需要。优先选择现有成熟的开源 Harness、专业 SDK 或可视化平台。
以纯编写插件为主，该怎么选宿主？	开发者日常：Cursor / Claude Code；产品系统开发：SDK / LangGraph；内部轻量问答：Dify。
新手入门的最佳落地路线？	编写 MCP 工具 → 编写 Rules/Skills 规范 → 掌握 LangGraph 编排 → 深入 ReAct 机制对比。
攻坚企业级自主 Agent 该如何分配精力？	以 Hermes 为核心教材 + 借鉴 OpenClaw 的网关/安全控制 + 结合 LangGraph 补充审批节点。
想学习极致的插件化架构思想？	深入阅读 DeepSeek Harness 的 Cordis 插件调度机制。
想研究开源的代码助手 Agent 实现？	深入研读 OpenCode 项目对 LSP 与执行模式的设计。