1.1 什么是 AI Agent
1.1.1 从 LLM 到 Agent
LLM，即 Large Language Model，大语言模型，本质上是一个基于上下文生成文本或结构化内容的模型。用户给它输入，它根据已有上下文生成输出。
最简单的 LLM 使用方式是：
用户输入问题
-> 模型生成回答
-> 用户看到回答
这种模式适合问答、写作、总结、翻译等任务，但它本身并不具备完整的“行动能力”。
Agent 则是在 LLM 外面增加了一套运行机制，使模型不仅能回答问题，还能：
- 判断任务目标
- 拆解任务步骤
- 选择合适工具
- 调用外部系统
- 读取工具结果
- 继续推理
- 在必要时重试
- 最终完成任务
可以把 Agent 理解为：
Agent = LLM + 目标 + 状态 + 工具 + 规划 + 执行 + 反馈 + 安全边界
LLM 是 Agent 的核心推理能力，但 Agent 不等于 LLM。
1.1.2 LLM、Chatbot、Workflow、Agent 的区别
| 类型 | 核心特点 | 是否能调用工具 | 是否有明确流程 | 是否具备自主决策 | 典型场景 |
|---|---|---|---|---|---|
| LLM | 根据上下文生成内容 | 否 | 否 | 否 | 问答、写作、总结 |
| Chatbot | 多轮对话界面 | 可选 | 通常较弱 | 较弱 | 客服、助手、咨询 |
| Workflow | 预定义流程自动化 | 可以 | 是 | 较弱 | 审批流、固定业务流程 |
| Agent | 根据目标动态规划和执行 | 是 | 可以动态变化 | 是 | 研究、代码、办公自动化、复杂任务执行 |
关键区别在于：
- Chatbot 关注对话体验
- Workflow 关注固定流程执行
- Agent 关注目标驱动的动态执行
例如，用户说：
帮我分析这个 PDF，总结重点，并生成一份待办清单。
普通 Chatbot 可能只能根据用户粘贴的文本回答。
Workflow 可以按照固定步骤执行：上传文件 -> 解析文件 -> 总结 -> 生成清单。
Agent 则可以根据实际情况动态判断：
- 文件是否需要 OCR
- 内容是否过长需要分块
- 是否需要先检索相关片段
- 是否需要调用任务管理工具
- 是否需要让用户确认生成的任务
- 如果解析失败是否需要换一种解析方式
这就是 Agent 与简单聊天机器人的区别。
1.1.3 Agent 为什么不是简单聊天机器人
简单聊天机器人通常只有以下能力：
接收消息 -> 调用模型 -> 返回文本
生产级 Agent 至少需要具备：
接收目标
-> 理解任务
-> 拆解步骤
-> 选择工具
-> 执行工具
-> 观察结果
-> 更新状态
-> 必要时继续执行
-> 输出最终结果
Agent 更接近一个“可以使用工具完成任务的智能执行系统”，而不只是一个“会说话的模型”。
判断一个系统是否更接近 Agent，可以看它是否具备以下特征：
- 是否能根据目标决定下一步做什么
- 是否能使用工具改变外部世界或读取外部数据
- 是否能维护任务状态
- 是否能根据工具结果调整后续行为
- 是否能处理失败和重试
- 是否有安全边界和权限控制
- 是否能被追踪、评测和复盘
如果一个系统只是把用户问题转发给模型，再把模型答案返回给用户，它更像 Chatbot，而不是生产级 Agent。
1.1.4 Agent 的典型应用场景
Agent 适合处理有目标、有步骤、需要工具、需要上下文的任务。
常见场景包括：
个人助理
- 整理日程
- 总结文件
- 生成待办事项
- 检索个人知识库
- 起草邮件或报告
研究助理
- 搜集资料
- 阅读网页或文档
- 提取观点
- 比较不同来源
- 生成研究报告
编程助理
- 阅读代码库
- 定位 bug
- 修改代码
- 运行测试
- 总结变更
企业知识库助手
- 回答内部制度问题
- 查询产品文档
- 引用知识来源
- 按权限隔离数据
- 记录问答日志
业务自动化 Agent
- 读取表格
- 调用业务 API
- 生成审批单
- 通知相关人员
- 记录执行结果
数据分析 Agent
- 理解分析目标
- 读取数据文件
- 执行统计分析
- 生成图表
- 输出结论
这些场景的共同特点是：任务往往不是一次模型调用就能完成，而是需要“多步骤执行 + 外部工具 + 状态管理”。
1.1.5 生产级 Agent 的基本要求
演示级 Agent 可以只追求“能跑起来”。
生产级 Agent 必须追求：
- 可控
- 可追踪
- 可恢复
- 可评测
- 可审计
- 可扩展
- 可部署
一个生产级 Agent 系统至少要回答以下问题：
- 用户是谁？他有权限访问哪些数据？
- Agent 调用了哪些工具？参数是什么？结果是什么？
- 哪些操作是高风险的？是否需要人工审批？
- Agent 的每一步是否有日志？能否回放？
- 模型调用消耗了多少 token？成本是多少？
- 如果工具失败，系统如何处理？
- 如果任务中断，是否可以恢复？
- 如果 Prompt 或工具改动，如何判断质量是否下降？
1.2 Agent 的核心组成
一个完整 Agent 通常由以下部分组成：
Model + Prompt + Tools + Memory + Planner + Executor + Guardrails + Evaluation
这些部分不是孤立存在的，而是在 Agent Runtime 中协同工作。
5.2.1 Model：模型能力边界
Model 是 Agent 的推理核心。它负责：
- 理解用户输入
- 生成计划
- 判断是否需要工具
- 生成工具参数
- 解释工具结果
- 输出最终回答
但模型不是万能的。模型有明显边界：
- 不知道用户私有数据，除非通过上下文或检索提供
- 不会真正执行外部操作，除非系统提供工具
- 可能产生幻觉
- 可能误解复杂指令
- 上下文窗口有限
- 输出格式可能不稳定
因此，Agent 工程不能只依赖“模型足够聪明”，而要通过工具、状态、校验、安全和评测来约束模型。
模型选型时通常需要考虑：
- 推理能力
- 工具调用能力
- 结构化输出能力
- 流式输出能力
- 上下文长度
- 延迟
- 成本
- 稳定性
- 供应商生态
1.2.2 Prompt：指令与上下文
Prompt 是 Agent 的行为说明书。它决定模型在当前任务中应该如何理解角色、目标、规则和输出格式。
常见 Prompt 类型包括：
System Prompt
用于定义 Agent 的身份、能力边界、安全规则和输出要求。
示例：
你是一个个人智能助理 Agent。你需要帮助用户完成资料整理、任务规划和知识库问答。
当需要外部信息时，你必须优先调用可用工具，而不是编造答案。
涉及文件写入、外部请求、代码执行等高风险操作时，必须等待用户审批。
Developer Prompt
用于描述开发者对 Agent 行为的约束，例如工具调用规则、格式要求、错误处理方式。
Tool Prompt
用于告诉模型某个工具能做什么、什么时候使用、参数如何填写、返回值如何理解。
Few-shot 示例
通过示例告诉模型“什么是好的输出”。
Prompt 工程的核心不是写一段漂亮的提示词，而是把 Agent 行为变得：
- 稳定
- 可解析
- 可测试
- 可迭代
- 可约束
1.2.3 Tools：工具调用
Tools 是 Agent 接触外部世界的方式。
没有工具的 Agent 只能“说”。 有工具的 Agent 才能“做”。
常见工具包括：
- 当前时间工具
- 计算器工具
- 搜索工具
- 文档检索工具
- 文件解析工具
- 数据库查询工具
- 代码执行工具
- 邮件发送工具
- 任务管理工具
- MCP 工具
一个工具通常需要定义：
工具名称
工具描述
参数 Schema
权限等级
执行函数
返回格式
错误格式
是否需要审批
示例工具定义：
{
"name": "calculator",
"description": "执行基础数学计算",
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "需要计算的数学表达式"
}
},
"required": ["expression"]
},
"risk_level": "low"
}
生产级工具系统不能只关注“能调用”，还必须关注：
- 参数校验
- 权限控制
- 审计日志
- 错误处理
- 超时控制
- 幂等性
- 人工审批
- 工具结果脱敏
1.2.4 Memory：记忆系统
Memory 让 Agent 不只是处理当前一句话，而是能够利用上下文和历史信息。
记忆可以分为两类：
短期记忆
通常指当前会话上下文，例如：
- 最近几轮消息
- 当前任务目标
- 已调用工具
- 工具返回结果
- 当前执行状态
短期记忆帮助 Agent 在一个任务中保持连贯。
长期记忆
通常指跨会话保存的信息，例如：
- 用户偏好
- 用户常用工具
- 历史任务摘要
- 常见项目背景
- 用户明确要求保存的信息
长期记忆帮助 Agent 实现个性化。
但记忆系统必须谨慎设计，因为它涉及隐私和安全：
- 什么信息可以记？
- 什么信息不能记？
- 是否需要用户授权？
- 用户能否查看、修改、删除记忆？
- 记忆是否可能被 Prompt Injection 污染？
1.2.5 Planner：任务规划
Planner 负责把用户目标拆解成可执行步骤。
例如用户输入：
帮我阅读这份行业报告，总结核心观点，并生成一个下周行动计划。
Planner 可能生成：
1. 解析用户上传的报告文件
2. 按章节提取关键内容
3. 总结行业趋势和关键观点
4. 将观点转化为行动建议
5. 生成下周任务清单
6. 输出最终总结
Planner 可以是显式的，也可以是隐式的。
隐式规划
模型不输出明确计划，而是在每一步内部决定下一步做什么。
显式规划
模型先输出结构化计划，然后系统按计划执行。
显式规划更适合需要可视化、审批和长任务恢复的场景。
生产级 Agent 中，Planner 需要考虑：
- 任务是否可完成
- 是否需要工具
- 是否涉及高风险操作
- 是否需要用户补充信息
- 是否需要拆成多个子任务
- 是否需要多个 Agent 协作
1.2.6 Executor：任务执行
Executor 负责执行 Planner 产生的步骤，尤其是工具调用。
Executor 需要处理：
- 调用哪个工具
- 参数是否合法
- 用户是否有权限
- 是否需要审批
- 工具是否执行成功
- 失败后是否重试
- 结果如何回传给模型
- 中间状态如何保存
可以把 Planner 和 Executor 的关系理解为：
Planner：决定要做什么
Executor：负责真的去做
在简单 Agent 中，Planner 和 Executor 可能都由同一个模型调用完成。
在复杂 Agent 中，它们可能被拆成不同节点，甚至不同 Agent。
1.2.7 Guardrails：安全边界
Guardrails 是 Agent 的安全防线。
Agent 能调用工具、读取数据、执行任务，因此必须有边界。否则它可能：
- 访问不该访问的数据
- 执行危险工具
- 被 Prompt Injection 诱导
- 泄露系统提示词或密钥
- 编造不存在的信息
- 生成不合规内容
- 无限制消耗 token 或调用外部 API
常见 Guardrails 包括：
输入侧 Guardrails
- 检查用户输入是否包含恶意指令
- 检查上传文件是否安全
- 检查 URL 是否允许访问
- 检查请求是否超出用户权限
工具侧 Guardrails
- 工具权限分级
- 高风险工具审批
- 参数白名单
- 超时限制
- 调用频率限制
- 沙箱隔离
输出侧 Guardrails
- 敏感信息过滤
- 输出格式校验
- 不确定时拒绝编造
- 引用来源校验
- 禁止泄露内部系统信息
一个核心原则是：
所有高风险工具都要权限和审批。
高风险工具包括但不限于：
- 文件写入
- 外部网络请求
- 代码执行
- 支付操作
- 邮件发送
- 删除数据
- 修改权限
1.2.8 Evaluation：效果评测
Agent 的输出具有不确定性，因此不能只靠人工感觉判断质量。
Evaluation 的目标是让 Agent 可以被持续改进。
评测对象包括：
- 模型回答质量
- 工具调用是否正确
- 参数生成是否正确
- RAG 检索是否准确
- 引用来源是否真实
- 多步骤任务是否完成
- 是否遵守安全规则
- 是否出现回归问题
常见评测方式包括：
单元测试
测试工具函数、API、Schema、权限逻辑。
Prompt 回归测试
固定一组输入，观察 Prompt 修改后输出是否变差。
RAG 评测
评估检索召回率、答案忠实度、引用准确性。
Agent 任务成功率评测
评估复杂任务是否真的完成。
LLM-as-judge
用另一个模型作为裁判，对答案进行评分。
人工标注
对关键任务进行人工审核，形成 Golden Dataset。
生产级 Agent 必须把 Evaluation 纳入开发流程，否则每次修改 Prompt、工具或模型都可能引入不可见的质量回退。
1.3 Agent 的基本运行模式
Agent 不是只有一种实现方式。不同任务适合不同运行模式。
1.3.1 ReAct 模式
ReAct 是 Reasoning + Acting 的组合。
它让模型在推理和行动之间循环：
Thought：我需要知道当前时间
Action：调用 get_current_time 工具
Observation：当前时间是 2026-05-26
Thought：我可以根据当前时间回答用户
Final Answer：现在是......
典型流程：
用户输入
-> 模型思考
-> 模型选择工具
-> 系统执行工具
-> 工具结果返回模型
-> 模型继续思考
-> 输出最终答案
ReAct 适合：
- 工具调用较少的任务
- 需要边想边查的任务
- 教学和理解 Agent Loop
- 快速构建最小 Agent
ReAct 的问题：
- 中间过程可能不稳定
- 复杂任务容易循环
- 对 Prompt 依赖较强
- 不适合复杂状态管理
1.3.2 Plan-and-Execute 模式
Plan-and-Execute 先制定计划，再执行计划。
用户目标
-> 生成计划
-> 执行步骤 1
-> 执行步骤 2
-> 执行步骤 3
-> 汇总结果
-> 最终回答
示例计划：
{
"goal": "总结报告并生成行动清单",
"steps": [
"解析报告文件",
"提取核心观点",
"归纳机会与风险",
"生成行动清单",
"输出最终总结"
]
}
适合场景：
- 多步骤任务
- 长任务
- 需要前端展示计划
- 需要人工审批
- 需要中断和恢复
优点：
- 更可控
- 更容易可视化
- 更容易记录状态
- 更适合生产系统
缺点：
- 初始计划可能不准确
- 执行过程中需要动态调整
- 计划与执行逻辑更复杂
后续引入 LangGraph 时，会把这种模式工程化为 Graph、Node、Edge 和 State。
1.3.3 Tool Calling 模式
Tool Calling 是现代 LLM API 常见能力。模型可以输出结构化工具调用请求，而不是自然语言描述。
简化流程：
用户：帮我算一下 128 * 56
模型：调用 calculator({ "expression": "128 * 56" })
系统：执行计算器工具
工具：返回 7168
模型：最终回答 128 * 56 = 7168
Tool Calling 的核心价值：
- 工具参数结构化
- 更容易校验
- 更容易执行
- 更容易记录日志
- 更适合与后端系统集成
但 Tool Calling 不等于完整 Agent。
Tool Calling 只是 Agent 的一个能力。完整 Agent 还需要状态、记忆、规划、权限、安全、评测等工程能力。
1.3.4 Workflow Agent 模式
Workflow Agent 把 Agent 的执行流程设计为明确的工作流或状态机。
例如：
开始
-> 理解任务
-> 检查权限
-> 生成计划
-> 执行工具
-> 是否需要审批？
-> 是：等待用户审批
-> 否：继续执行
-> 是否完成？
-> 否：继续下一步
-> 是：输出最终结果
Workflow Agent 适合生产系统，因为它具有：
- 明确状态
- 可恢复执行
- 可插入审批
- 可追踪节点
- 可处理失败
- 可进行回放
LangGraph 就非常适合构建这种状态化 Agent。
1.3.5 Multi-Agent 模式
Multi-Agent 是多个 Agent 协作完成一个复杂任务。
常见角色包括：
- Supervisor Agent：负责分配任务和汇总结果
- Researcher Agent：负责资料检索
- Planner Agent：负责计划制定
- Coder Agent：负责代码实现
- Reviewer Agent：负责检查质量
- Writer Agent：负责生成最终文档
典型结构：
用户任务
-> Supervisor Agent
-> Researcher Agent
-> Planner Agent
-> Writer Agent
-> Reviewer Agent
-> 汇总结果
-> 最终回答
Multi-Agent 适合：
- 复杂研究任务
- 长文档生成
- 软件开发协作
- 多角色审查
- 需要专业分工的任务
但 Multi-Agent 很容易复杂化：
- 成本上升
- 调用链变长
- 上下文管理困难
- Agent 之间可能冲突
- 调试难度增加
1.4 主流 Agent 框架对比
1.4.1 LangGraph
LangGraph 适合构建状态化、可恢复、可中断的 Agent 工作流。
核心概念：
- Graph
- Node
- Edge
- State
- Checkpoint
- Interrupt
- Streaming
适合场景：
- 多步骤 Agent
- 需要状态管理
- 需要人工审批
- 需要中断恢复
- 需要复杂流程控制
- 长任务执行
优势：
- 状态明确
- 流程可控
- 适合生产级编排
- 支持 Human-in-the-loop
- 支持 Durable Execution
需要注意：
- 抽象较多
- 需要设计状态结构
- 对初学者有一定门槛
1.4.2 OpenAI Agents SDK
OpenAI Agents SDK 是官方 Agent 开发工具，提供 Agent、Tools、Handoffs、Guardrails、Tracing 等能力。
适合场景：
- 快速构建基于 OpenAI 生态的 Agent
- 使用官方工具调用和追踪能力
- 构建多 Agent Handoff 流程
- 使用内置 Guardrails 能力
优势：
- 官方生态集成
- Agent 抽象清晰
- Tool 和 Handoff 支持完善
- Tracing 能力友好
需要注意：
- 与具体模型生态绑定较强
- 复杂状态流可能仍需要额外工程设计
1.4.3 Claude Agent SDK
Claude Agent SDK 适合构建基于 Claude 能力的 Agent 应用，尤其适合工具使用、上下文处理、代码任务和复杂推理类场景。
适合场景：
- 使用 Claude 构建定制 Agent
- 工具调用
- MCP 集成
- 复杂工程任务
- 构建可扩展 Agent Runtime
优势：
- 与 Claude 能力结合紧密
- 支持 Agent 相关工程抽象
- 适合与 MCP 生态结合
需要注意：
- 需要理解 SDK 的运行模型
- 需要结合实际项目设计状态、权限和日志
1.4.4 Vercel AI SDK
Vercel AI SDK 更偏向前端和全栈 AI 应用开发，尤其适合构建流式聊天体验、Tool Call UI 和前端 Agent 交互。
适合场景：
- Next.js AI 应用
- 流式输出
- Chat UI
- Tool Call 前端展示
- 全栈 TypeScript 项目
优势：
- 前端体验好
- Streaming 支持强
- 与 Next.js 结合自然
- 适合快速构建 AI Chat 产品
需要注意：
- 复杂后端权限、审计、任务系统仍需要单独设计
- 生产级 Agent Runtime 不应完全放在前端侧
1.4.5 CrewAI
CrewAI 偏向多 Agent 角色协作。它通过 Agent、Task、Crew 等概念组织多个角色完成任务。
适合场景：
- 多角色协作 Demo
- 研究报告生成
- 内容生产工作流
- 简化多 Agent 编排
优势：
- 多 Agent 概念直观
- 上手较快
- 适合演示角色分工
需要注意：
- 生产级状态管理、权限、安全和评测仍需要补齐
- 多 Agent 容易带来成本和调试复杂度
1.4.6 AutoGen
AutoGen 偏向多个 Agent 之间的对话式协作。
适合场景：
- Agent 之间相互讨论
- 研究型任务
- 编程协作实验
- 多智能体系统探索
优势：
- 多 Agent 对话机制强
- 适合实验复杂协作模式
需要注意：
- 对话链路可能较长
- 成本控制和稳定性需要额外设计
- 生产落地需要配套工程治理
1.4.7 LlamaIndex Agents
LlamaIndex 在数据连接、索引、RAG 和知识库方面能力较强，也提供 Agent 能力。
适合场景：
- 知识库问答
- 文档检索
- 数据连接
- RAG Agent
优势：
- RAG 生态丰富
- 数据连接器多
- 适合知识密集型 Agent
需要注意：
- 如果项目重点是复杂流程编排，可能需要结合其他工具
- 权限、审计、审批仍需要业务系统实现
1.5 MCP 与工具生态
1.5.1 MCP 是什么
MCP，全称 Model Context Protocol，是一种用于连接模型应用与外部工具、数据源和上下文的协议。
它可以理解为 Agent 世界里的“工具接入标准”。
在没有 MCP 之前，每个 Agent 应用都可能用自己的方式接入工具：
Agent A -> 自定义搜索 API
Agent B -> 自定义数据库工具
Agent C -> 自定义文件系统工具
这会导致：
- 工具无法复用
- 接入方式不统一
- 权限模型不一致
- 工具发现困难
- 维护成本高
MCP 试图用标准协议统一这个过程。
1.5.2 MCP Server 与 MCP Client
MCP 的基本结构：
Agent / AI App 作为 MCP Client
-> 连接 MCP Server
-> 发现工具、资源和提示词
-> 调用工具或读取资源
MCP Client
MCP Client 通常嵌入在 Agent 应用中，负责：
- 连接 MCP Server
- 获取工具列表
- 读取工具 Schema
- 发起工具调用
- 接收工具结果
- 将结果返回给 Agent
MCP Server
MCP Server 提供能力，负责暴露：
- Tools
- Resources
- Prompts
例如，一个文件系统 MCP Server 可以提供：
- 读取文件工具
- 搜索文件工具
- 文件资源列表
一个数据库 MCP Server 可以提供：
- 查询表结构
- 执行只读 SQL
- 获取数据资源
1.5.3 Tools、Resources、Prompts
MCP 中常见三类能力：
Tools
Tools 是可执行动作。
例如：
- search_files
- read_document
- query_database
- create_task
- send_email
Tools 通常有输入参数和返回结果。
Resources
Resources 是可读取资源。
例如：
- 文件内容
- 数据库表结构
- 项目配置
- 文档集合
Resources 更偏“上下文读取”，不一定执行动作。
Prompts
Prompts 是可复用提示模板。
例如：
- 代码审查 Prompt
- 报告总结 Prompt
- SQL 分析 Prompt
Prompts 可以帮助不同 Agent 应用复用同一套任务指令。
1.5.4 MCP 为什么适合 Agent 工具接入
MCP 对 Agent 有几个重要价值：
工具标准化
工具定义、参数、返回值可以通过标准协议暴露。
工具可发现
Agent 可以动态发现可用工具，而不是把所有工具写死在代码里。
工具可复用
同一个 MCP Server 可以被多个 Agent 应用使用。
生态可扩展
开发者可以为数据库、文件系统、浏览器、业务系统分别开发 MCP Server。
权限可治理
企业可以围绕 MCP Server 做统一权限控制、审计和策略管理。
1.5.5 MCP 与普通 HTTP API 的区别
MCP 和 HTTP API 并不是替代关系。
HTTP API 是通用接口协议。 MCP 是面向模型上下文和工具调用的协议。
| 对比项 | 普通 HTTP API | MCP |
|---|---|---|
| 目标 | 系统之间通用通信 | AI 应用接入工具和上下文 |
| 工具发现 | 通常需要手写文档或 SDK | 协议内支持工具发现 |
| Schema | OpenAPI 等方式描述 | 面向模型工具调用描述 |
| 资源模型 | 自定义 | Tools / Resources / Prompts |
| Agent 集成 | 需要手动适配 | 更适合 Agent 动态接入 |
| 使用方式 | 开发者调用 API | Agent/模型应用发现并调用工具 |
简单理解：
HTTP API 是底层通用能力，MCP 是面向 Agent 的工具接入层。
很多 MCP Server 内部仍然会调用 HTTP API，只是对 Agent 暴露为统一的 MCP 能力。
1.6 生产级 Agent 的工程要求
一个能演示的 Agent 和一个能上线的 Agent，差距主要在工程体系。
1.6.1 权限控制
Agent 可能访问用户私有数据，因此必须知道：
- 当前用户是谁
- 用户能访问哪些会话
- 用户能访问哪些文件
- 用户能调用哪些工具
- 用户是否有执行高风险操作的权限
权限控制不能只写在前端，也不能只依赖模型自觉遵守。
正确做法是：
- 后端校验用户身份
- 数据库查询按用户过滤
- 工具调用前做权限检查
- 高风险工具触发审批
- 所有权限失败写入日志
1.6.2 人工审批
Agent 可以自动执行低风险任务，但高风险操作必须引入 Human-in-the-loop。
需要审批的操作包括：
- 文件写入
- 文件删除
- 外部请求
- 邮件发送
- 代码执行
- 支付操作
- 修改权限
- 访问敏感数据
审批流程通常是：
Agent 准备调用高风险工具
-> 系统创建审批请求
-> 前端展示审批弹窗
-> 用户批准或拒绝
-> Agent 根据审批结果继续或终止
-> 审批记录写入审计日志
人工审批不是简单弹窗，而是生产级 Agent 的安全控制点。
1.6.3 工具审计
所有工具调用都应该被记录。
审计日志至少包含：
- 用户 ID
- 会话 ID
- Agent Run ID
- 工具名称
- 工具参数
- 工具结果摘要
- 调用状态
- 错误信息
- 审批状态
- 调用时间
工具审计的价值：
- 问题追踪
- 安全审查
- 成本分析
- 用户纠纷处理
- 合规要求
- Agent 行为复盘
1.6.4 日志与追踪
普通日志只能告诉我们“发生了什么”。
Tracing 可以告诉我们“整个调用链是怎样发生的”。
一次 Agent Run 可能包含：
用户消息
-> 模型调用 1
-> 工具调用 1
-> 模型调用 2
-> 工具调用 2
-> 审批等待
-> 工具调用 3
-> 模型调用 3
-> 最终回答
如果没有追踪系统，就很难判断：
- 哪一步失败
- 哪一步耗费最多 token
- 哪个工具返回异常
- 哪个 Prompt 导致错误
- 哪次修改引入回归
1.6.5 成本统计
Agent 会多次调用模型和工具，成本可能比普通聊天更高。
需要统计：
- 每次模型调用输入 token
- 每次模型调用输出 token
- 每次模型调用成本
- 每个 Agent Run 总成本
- 每个用户累计成本
- 每个工具调用成本
- 不同模型的成本分布
成本统计的作用：
- 控制用户配额
- 发现异常调用
- 优化模型路由
- 判断缓存是否有效
- 支撑商业化计费
1.6.6 失败恢复
Agent 任务可能失败：
- 模型超时
- 工具异常
- 网络错误
- 用户取消
- 审批拒绝
- Worker 崩溃
- 数据库连接失败
生产系统不能简单地让任务消失。
需要记录任务状态：
pending
running
waiting_approval
completed
failed
cancelled
retrying
还需要支持：
- 重试
- 取消
- 中断后恢复
- 查看失败原因
- 从 Checkpoint 继续执行
1.6.7 评测体系
没有评测体系的 Agent 很难稳定迭代。
因为 Agent 输出受以下因素影响：
- 模型版本
- Prompt 改动
- 工具描述改动
- 检索参数改动
- 文档内容变化
- 上下文压缩策略变化
每次改动都可能导致质量回退。
因此需要建立：
- 标准任务集
- Golden Dataset
- 工具测试
- Prompt 回归测试
- RAG 评测
- Agent 任务成功率评测
- LLM-as-judge
- 人工抽检
最终目标是：
每次修改 Agent 的 Prompt、工具、RAG 或运行逻辑后，都能通过评测判断质量是否下降。
2. 主线项目中的 Agent 系统架构
初版系统架构如下：
flowchart TD
User[用户] --> Web[Next.js 前端]
Web --> API[FastAPI 后端 API]
API --> DB[(PostgreSQL)]
API --> Redis[(Redis)]
API --> ObjectStorage[对象存储 / MinIO]
API --> AgentService[Agent 服务]
AgentService --> ModelClient[ModelClient]
ModelClient --> LLM[大模型 API]
AgentService --> ToolRegistry[工具注册表]
ToolRegistry --> BuiltinTools[内置工具]
ToolRegistry --> MCPClient[MCP Client]
MCPClient --> MCPServers[MCP Servers]
AgentService --> VectorDB[向量检索 / pgvector]
AgentService --> AuditLog[审计日志]
AgentService --> Trace[Tracing / Observability]
API --> Approval[审批系统]
Approval --> Web
这个架构中：
- 前端负责用户交互、聊天界面、工具调用展示、审批弹窗。
- 后端 API 负责用户、鉴权、会话、消息、文件、权限、审计。
- Agent 服务负责 Agent Loop、工具选择、工具执行、状态管理。
- ModelClient 负责统一封装模型调用。
- Tool Registry 负责工具注册、参数校验、权限等级和调用入口。
- MCP Client 负责连接外部 MCP Server。
- PostgreSQL 负责业务数据持久化。
- Redis 负责缓存、任务队列和运行状态辅助。
- 向量检索负责 RAG 知识库问答。
- 审批系统负责高风险工具调用的人类确认。
- Tracing 系统负责记录完整调用链。
3. 最小 Agent 运行流程
最小 Agent Loop 可以先不引入复杂框架。
基础流程如下：
sequenceDiagram
participant U as 用户
participant FE as 前端
participant API as 后端 API
participant A as Agent Runtime
participant M as 大模型
participant T as 工具系统
U->>FE: 输入任务
FE->>API: 发送消息
API->>A: 创建 Agent Run
A->>M: 发送上下文和工具定义
M-->>A: 返回工具调用请求或最终回答
alt 需要调用工具
A->>T: 执行工具
T-->>A: 返回工具结果
A->>M: 发送工具结果
M-->>A: 继续推理或最终回答
else 不需要工具
M-->>A: 返回最终回答
end
A->>API: 保存运行结果
API-->>FE: 流式返回结果
FE-->>U: 展示回答和执行过程
更简单的文本版：
用户输入
-> 后端创建 Agent Run
-> Agent 将用户输入和工具列表发给模型
-> 模型判断是否需要工具
-> 如果需要工具，Agent 执行工具
-> 工具结果返回模型
-> 模型继续推理
-> 输出最终答案
-> 后端保存消息、工具调用和运行状态
-> 前端展示回答和工具调用过程
4. 关键点
4.1 Agent 不是“套壳聊天”
如果一个应用只是：
用户输入 -> 调模型 -> 返回文本
它更像 Chatbot。
Agent 的关键是：
目标驱动 + 工具调用 + 状态管理 + 动态决策 + 安全边界
4.2 工具调用是 Agent 的分水岭
没有工具，模型只能生成内容。
有了工具，Agent 才能：
- 查询实时数据
- 读取私有文件
- 调用业务系统
- 执行计算
- 创建任务
- 操作外部资源
但工具越强，风险越高，所以必须有权限、审批和审计。
4.3 生产级 Agent 的难点在工程，而不只在模型
很多 Agent Demo 能跑，但难以上线，原因通常不是模型不够强，而是缺少：
- 用户系统
- 数据隔离
- 工具权限
- 审计日志
- 运行追踪
- 错误恢复
- 成本控制
- 自动评测
4.4 先简单，后复杂
不要一开始就做多 Agent、复杂 RAG、完整 MCP、长任务系统。
正确路线是：
最小 Agent Loop
-> Web Chat
-> Tool Agent
-> Knowledge Agent
-> Workflow Agent
-> MCP Agent
-> Production Agent
