AI Agent 工程实践
整理自读书笔记精华，覆盖 AI Agent 开发的工程方法、RAG 系统、多智能体协作、LangChain 实践及私有化部署。
来源书目：
- 《Harness Engineering 橙皮书：AI编程时代的工程方法论》— 花叔
- 《Building AI Agents with LLMs, RAG and Knowledge Graphs》— Salvatore Raieli, Gabriele Iuculano
- 《AI工程：大模型应用开发实战》— 奇普萱
- 《AI Agent 开发：零基础构建复合智能体》— 梁志远
- 《LangChain 大模型开发实践》— 姜春茂
- 《软件工程3.0：大模型驱动的研发新范式》— 朱少民、王千祥
- 《多智能体协同：基于大语言模型的工程实践与系统构建》— 周佺喜
- 《构建私有化大模型应用系统》— 温智凯
一、Harness Engineering：AI 编程方法论
核心公式
Agent = Model + Harness
Harness 是模型之外的一切工程系统：系统提示词、工具调用、文件系统、沙箱环境、编排逻辑、反馈回路、约束机制。模型决定上限，Harness 决定底线。
Harness 五组件
| 组件 | 作用 | 类比 | |------|------|------| | 指令（Directive） | 告诉 AI 做什么 | 岗位说明书 | | 约束（Constraint） | 告诉 AI 不能做什么，必须机械化执行 | 红线规则 | | 反馈（Feedback） | 让 AI 知道做对了还是做错了 | 质检流程 | | 记忆（Memory） | 让 AI 记住之前发生过什么 | 档案室 | | 编排（Orchestration） | 让多个 AI 协同工作 | SOP 标准流程 |
六层架构体系
| 层级 | 名称 | 优先级 | |------|------|--------| | L1 | 信息边界层 | ★★★★★ 先做 | | L2 | 工具系统层 | ★★★★☆ | | L3 | 执行编排层 | ★★★☆☆ | | L4 | 记忆与状态层 | ★★★☆☆ | | L5 | 评估与观测层 | ★★★★☆ | | L6 | 约束校验恢复层 | ★★★★★ 先做 |
优先级建议：先做 L1（信息边界）和 L6（约束与恢复），这两层投入产出比最高。（来源：《Harness Engineering 橙皮书》）
关键原则
- Harness 不是越多越好，而是越精准越好。 每一条规则都应该对应一个真实发生过的失败案例。
- If it cannot be enforced mechanically, agents will deviate. 约束必须机械化执行，文档里写不够。
- 写在 Slack 里的知识，对 Agent 来说等于不存在。 所有知识必须作为版本控制的制品放在仓库中。
- 上下文利用率控制在 40% 以内。 超过后模型表现急剧下降。
三层工程方法（嵌套关系）
- Prompt Engineering（表达层）：怎么写好指令
- Context Engineering（信息层）：给 Agent 看什么
- Harness Engineering（执行层）：整个系统怎么防崩、怎么持续运转
在长链路、可执行、低容错的真实商业场景里，Harness 才是决定成败的东西。（来源：《Harness Engineering 橙皮书》）
成熟度模型
| 阶段 | 特征 | |------|------| | Level 0 | 无 Harness，直接给 prompt | | Level 1 | AGENTS.md + 基础 Linter | | Level 2 | CI/CD + 自动化测试 + 反馈回路 | | Level 3 | 多 Agent 分工 + 分层上下文 | | Level 4 | 无人值守 + 自动熵管理 + 自修复 |
经典案例要点
- OpenAI Codex：7 人 5 个月零行手写代码交付百万行产品。关键：地图式文档（~100 行当目录）、机械化约束（自定义 Linter）、熵管理（生成速度 = 清理速度）
- Anthropic：GAN 式三智能体架构——Planner（规划）→ Generator（执行）⇄ Evaluator（评估），生成和评估拆给两个独立 Agent
- Stripe Minions：每周 1300 个 PR 的无人值守流水线。Devbox 预热池、Toolshed MCP（近 500 工具）、该确定的地方确定、该灵活的地方灵活
二、RAG（检索增强生成）
核心架构
文档 → 切分 → 嵌入 → 向量存储
↑
用户查询 → 查询改写 → 检索 → 重排序 → [知识图谱查询] → LLM 生成
RAG 效果的关键
RAG 的效果 80% 取决于数据预处理，20% 取决于检索算法。（来源：《Building AI Agents》）
文本分块（Chunking）
| 策略 | 适用场景 | 推荐大小 | |------|---------|---------| | 固定长度分块 | 通用 | 512 tokens，重叠 50-100 tokens | | 语义分块 | 长文档、结构化内容 | 按段落/标题自然分割 | | 递归分块 | 复杂文档 | 先按章节→段落→句子 |
检索优化
- 混合检索：向量检索（语义相似）+ BM25（关键词匹配），实测提升 10-20% 准确率
- Query 改写：先用 LLM 把原始问题改写成更适合检索的形式
- 重排序（Reranking）：初检 top-20 → Cross-Encoder 精排 → 取 top-5 送入 LLM
RAG 进化路径
基础版（可用） 进阶版（好用） 高级版（生产级）
───────────── ───────────── ──────────────
固定分块 → 语义分块 → 递归分块 + 元数据
纯向量检索 → 混合检索 → 查询改写 + 混合检索
直接拼接 → Reranker 精排 → 多轮检索 + 答案验证
无溯源 → 引用来源段落 → 置信度评分 + 拒绝回答
Graph RAG
向量检索找相关文本，知识图谱找实体关系，两者融合后喂给 LLM。适合关系密集型任务（"A 和 B 有什么关系"、"从 X 到 Y 的路径是什么"）。
知识图谱给了 Agent 一张地图，而不仅仅是碎片化的信息。（来源：《Building AI Agents》）
向量数据库选型
| 数据库 | 类型 | 适用场景 | |--------|------|---------| | Chroma | 嵌入式 | 开发阶段，轻量快速 | | FAISS | 库（非DB） | 纯计算最快 | | Qdrant | 独立服务 | Rust 写的，性能好 | | Milvus | 分布式 | 大规模生产环境 |
推荐路径：开发用 Chroma，生产切 Milvus/Qdrant。
Embedding 模型选型
| 模型 | 维度 | 特点 | |------|------|------| | BGE-large-zh-v1.5 | 1024 | 国产标杆，中文首选 | | GTE-large | 1024 | 阿里出品，多语言 | | text-embedding-3-small | 1536 | OpenAI 闭源 |
Embedding 模型不一定越大越好。768-1024 维通常是性价比最优区间。（来源：《构建私有化大模型应用系统》）
三、Agent 架构设计
四要素模型
┌──────────┐ ┌──────────┐
│ 感知模块 │→ │ 决策模块 │
│(输入理解) │ │(推理规划) │
└──────────┘ └────┬─────┘
↓
┌──────────┐ ┌──────────┐
│ 记忆模块 │←─│ 行动模块 │
│(上下文) │ │(工具执行) │
└──────────┘ └──────────┘
Agent 类型
| 类型 | 特点 | 适合 | |------|------|------| | ReAct | 推理+行动交替，每步先思考再执行 | 探索性任务 | | Plan-then-Execute | 先全部规划好再逐步执行 | 流程明确的任务 | | Reflection | 执行完后自我审查修正 | 质量要求高的任务 |
ReAct 循环
用户输入 → [思考(Thought)] → [行动(Action)] → [观察(Observation)]
↑ │
└────────────────────────────────────────┘
↓
生成最终回复
ReAct 让模型交替进行推理（Reasoning）和行动（Acting），几乎是所有现代 Agent 框架的底层逻辑。（来源：《Building AI Agents》）
记忆系统
| 类型 | 说明 | 实现方式 | |------|------|---------| | 短期记忆 | 对话上下文窗口内 | 对话缓冲区 | | 长期记忆 | 持久化历史交互 | 向量数据库 | | 工作记忆 | 当前任务关键状态 | 状态管理对象 |
记忆衰减机制：根据访问频率、时间久远、任务相关度计算记忆重要性，自动淘汰低价值记忆。30 天运行数据：不做衰减，查询延迟从 50ms 升到 800ms+；加入衰减后稳定在 100-150ms。
工具使用
- Function Calling：大模型调用外部函数的标准机制
- 工具注册中心：所有工具集中注册，Agent 按需发现和使用，支持热插拔
- 不可逆操作（发消息、删除数据、支付）必须加人工确认
四、多智能体系统
什么时候需要多 Agent？
| 场景特征 | 推荐 | 理由 | |---------|------|------| | 单一任务、流程固定 | 单 Agent | 多 Agent 增加不必要复杂度 | | 需要多种专业视角 | 多 Agent（专家型） | 不同 Agent 负责不同领域 | | 任务可自然分解为独立子任务 | 多 Agent（并行型） | 并行执行提升效率 | | 需要辩论和审查 | 多 Agent（对抗型） | 多角度碰撞提高决策质量 | | 实时性要求极高（<1s） | 单 Agent | 通信延迟是瓶颈 |
多 Agent 不是银弹。在用之前，先证明单 Agent 真的不行。 多 Agent 的 debug 难度是单 Agent 的 10 倍以上。（来源：《多智能体协同》）
通信模式
| 模式 | 特点 | 适用 | |------|------|------| | 广播 | 一发多收，简单但信息过载 | 通知场景 | | 点对点 | 直接通信，高效但连接复杂 | 精确协作 | | 黑板 | 共享公共信息空间，解耦好 | 最实用 | | 层级 | 管理者协调，管理者易成瓶颈 | 层级分明 | | 市场 | 竞标争取任务，灵活但复杂 | 资源动态分配 |
任务分解三层模型
| 层次 | 内容 | 关键技术 | |------|------|---------| | L1 目标分解 | 大目标→子目标（DAG 图） | MECE 原则、树状分解 | | L2 任务分配 | 子目标→Agent 映射 | 能力矩阵、负载均衡 | | L3 执行编排 | 确定顺序和并行策略 | 状态机、工作流引擎 |
Agent 数量边际递减
Agent 数量超过 5-7 个后，协作效率反而下降。通信开销的增长速度超过了并行带来的收益。类似 Brooks 定律。（来源：《多智能体协同》）
参考架构
用户请求 → 任务调度器（拆解、分配、监控）
↓
通信中间件（消息路由、序列化、容错）
↓
┌───────┬───────┬───────┐
Agent A Agent B Agent C
└───────┴───────┴───────┘
↓
┌───────┬───────┬───────┐
共享记忆 工具中心 评估引擎
└───────┴───────┴───────┘
评估四维框架
| 维度 | 指标 | 测量方法 | |------|------|---------| | 任务完成度 | 准确率 | 人工标注 + 自动检查 | | 协作效率 | 平均轮次、token 消耗 | 统计消息数和 token | | 鲁棒性 | 故障恢复率 | 模拟 Agent 故障 | | 可解释性 | 人类理解度 | 人工评分 |
安全风险
- Prompt 注入放大效应：一个 Agent 被注入，输出可能诱导下游 Agent
- 权限逃逸：某个 Agent 绕过自身限制，间接调用其他 Agent 权限
- 防护：输入/输出过滤 + 权限最小化 + 审计日志 + 熔断机制
五、LangChain 开发实践
核心组件
| 组件 | 功能 | 使用频率 | |------|------|---------| | Model I/O | Prompt Template + Chat Model + Output Parser | ★★★★★ | | Retrieval | Loader + Splitter + Embedding + Vector Store | RAG 必备 | | Memory | 会话记忆管理 | 看场景 | | Agent + Tools | 自主决策调用工具 | 高级应用标配 | | Callbacks | 事件钩子、日志追踪 | 生产环境必需 |
LCEL（LangChain Expression Language）
用 | 管道操作符把 Runnable 组件串成处理链：
chain = prompt | model | output_parser
关键特性：Runnable 统一接口（invoke/stream/batch）、RunnableParallel 并行、RunnableBranch 路由、RunnableWithFallbacks 回退。
生态全景
| 组件 | 功能 | 状态 | |------|------|------| | LangChain Core | 核心抽象和接口 | 稳定 | | LCEL | 声明式编排语言 | 主流写法 | | LangSmith | 追踪、评估、调试 | 商业产品 | | LangGraph | 有状态多 Agent 编排 | 快速发展 |
LangChain 解决的是"怎么调工具"，LangGraph 解决的是"怎么编排复杂流程"。两者不是替代关系，是互补关系。（来源：《AI Agent 开发》）
知识图谱实战
用 LLM 从非结构化文本抽取实体和关系，构建知识图谱，再通过 NL2Cypher 实现自然语言图谱问答。关键技术：Few-shot Prompt 实体抽取 + Neo4j 存储 + 自然语言转 Cypher 查询。
六、MCP 与 A2A 协议
MCP（Model Context Protocol）
Anthropic 推出的 AI 模型与外部数据源之间的标准化通信协议。核心：上下文段结构化表示 + metadata 标签语义 + 信息路由控制。
如果 MCP 是 Agent 与数据之间的"普通话"，那 A2A 就是 Agent 与 Agent 之间的"外交语言"。（来源：《AI Agent 开发》）
A2A（Agent-to-Agent）
智能体之间的标准化通信规范：
- Request-Response：点对点
- 广播与订阅：一对多
- 协商与竞争：多 Agent 竞争同一任务
七、AI 工程全流程
三层架构
┌─────────────────────────────────────────┐
│ 应用开发层（重点） │
│ 产品需求 → 选模型 → 提示工程 → 评估 │
│ RAG / Agent → 用户体验 → 反馈迭代 │
├─────────────────────────────────────────┤
│ 模型开发层（重点） │
│ 模型选择 → 微调（LoRA/DPO） │
│ 数据集工程 → 评估基准 │
├─────────────────────────────────────────┤
│ 基础设施层 │
│ GPU 集群 → 推理优化 → 部署运维 │
└─────────────────────────────────────────┘
决策框架
| 场景 | 推荐方案 | 原因 | |------|---------|------| | 简单问答 / 文本生成 | Prompt Engineering | 成本最低，迭代最快 | | 需要外部知识 | RAG | 减少幻觉，知识可更新 | | 需要调用工具 / 多步推理 | Agent + RAG | 扩展模型能力边界 | | 需要特定风格 / 格式 | 微调（LoRA） | Prompt 搞不定的才微调 | | 需要极致性能 / 低成本 | 微调小模型 + 推理优化 | 长期成本最优 |
微调不是万能药。在微调之前，先确认 prompt engineering 和 RAG 确实不够用。（来源：《AI工程》奇普萱）
评估体系
| 任务类型 | 推荐指标 | |---------|---------| | 分类 / 选择题 | Exact Match / 准确率 | | 翻译 | BLEU / COMET | | 摘要 | ROUGE / BERTScore | | 开放问答 | LLM-as-a-judge | | 总体质量 | 人工评估 + 分数分布 |
不要只看平均分，要看分数分布。两个模型平均分一样，但一个稳定一个方差大，在生产环境里表现会差很多。（来源：《AI工程》奇普萱）
八、私有化部署
模型选型决策
| 任务 | GPU 充足（≥24GB） | GPU 有限（≤16GB） | |------|-------------------|------------------| | 中文对话 | Qwen2.5-14B / ChatGLM4-9B | Qwen2.5-7B-INT4 | | 英文为主 | Llama3.1-8B / Mistral-7B | Phi-3-mini / Gemma-2-2B | | 代码生成 | DeepSeek-Coder / CodeLlama | — | | 多语言 | Qwen2.5 多语言版 | — |
先小后大：先用 7B 跑通全流程，再根据效果升级。不要一开始就上 72B。（来源：《构建私有化大模型应用系统》）
推理框架选型
| 框架 | 特点 | 适用 | |------|------|------| | Ollama | 一键部署，开箱即用 | 开发验证、快速原型 | | vLLM | PagedAttention，高吞吐 | 生产环境 | | llama.cpp | 纯 CPU 推理 | 边缘设备、无 GPU |
推荐路径：开发用 Ollama，生产用 vLLM。
部署架构
用户 → 前端(React/Gradio) → API 网关(FastAPI) → 推理服务(vLLM)
↓
向量数据库(Milvus)
↓
文档管理(对象存储)
监控指标
- GPU 利用率和显存占用（DCGM，不要用 nvidia-smi 轮询）
- 推理延迟 P50/P95/P99
- 请求吞吐量（QPS）
- Token 生成速度
- 错误率和超时率
九、软件工程 3.0
核心范式转变
SE 1.0 (1968-) SE 2.0 (2001-) SE 3.0 (2023-)
重文档流程 敏捷/DevOps AI 驱动/人机协同
瀑布模型/CMM CI/CD/云原生 ML-DevOps/自然语言编程
六大核心能力
| 能力 | 说明 | |------|------| | 提示工程 | CoT/ToT 技巧，模板设计 | | RAG | 用企业知识库增强大模型 | | 智能体 | 自主规划、执行、反思 | | 数据治理 | 清洗、增强、标注 | | 模型工程 | 微调、部署、评测 | | 安全治理 | 代码安全、隐私保护 |
实施三步走
自我评估（现状分析、差距识别）→ 局部试点（选痛点、3个月 MVP）→ 全面推广
程序员不会失业，但只会写代码的程序员会失业。未来工程师的角色是 AI 训练师和决策者。（来源：《软件工程3.0》）
十、Prompt Engineering 实用要点
核心策略
| 策略 | 说明 | 适用场景 | |------|------|---------| | 零样本 | 直接给指令 | 简单任务 | | 少样本 | 给几个示例 | 中等复杂度 | | Chain-of-Thought | 让模型"一步一步想" | 数学、逻辑推理 | | ReAct | 推理+行动交替 | Agent 核心 | | 角色设定 | "你是一个资深 XX 工程师" | 输出质量提升 |
提示词不是一次性的
好的 prompt 和好的代码一样，需要持续维护、A/B 测试、根据用户反馈迭代。
最好的 prompt 是用户不需要写的那个。Agent 的价值在于把复杂操作封装起来。（来源：《Building AI Agents》）
十一、Agent 能力层次模型
| 层次 | 能力 | 技术支撑 | |------|------|---------| | L0 | 文本理解和生成 | LLM 基础能力 | | L1 | 上下文感知 | Prompt Engineering | | L2 | 知识检索 | RAG 管道 | | L3 | 关系推理 | 知识图谱 | | L4 | 工具使用 | Function Calling | | L5 | 自主规划 | ReAct + 多 Agent | | L6 | 自我改进 | RL + 反馈循环 |
整理时间：2026-05-02 | 来源：8 本读书笔记精华提取