AI Agent 学习

可乐奶茶sky2026-07-22 17:17

目标：理解 AI Agent 的核心结构、工具调用、状态与记忆、RAG、规划、工作流、多智能体、安全和评测，能够从零实现一个可运行 Agent，并具备生产化和面试系统设计能力。

文章目录

  1. [AI Agent 是什么](#AI Agent 是什么)
  2. [Agent、聊天机器人、RAG 和工作流的区别](#Agent、聊天机器人、RAG 和工作流的区别)
  3. [Agent 的核心组成](#Agent 的核心组成)
  4. [Agent 控制循环与 ReAct](#Agent 控制循环与 ReAct)
  5. 工具调用与结构化输出
  6. [Prompt 与上下文工程](#Prompt 与上下文工程)
  7. 状态、记忆与会话
  8. [RAG 与 Agentic RAG](#RAG 与 Agentic RAG)
  9. 规划、反思与任务分解
  10. [常见 Agent 工作流模式](#常见 Agent 工作流模式)
  11. 多智能体系统
  12. [MCP 与工具生态](#MCP 与工具生态)
  13. 安全、权限与人工审批
  14. 评测方法
  15. 可观测性、成本与性能
  16. 生产级架构设计
  17. 环境准备
  18. [实操一：从零实现最小 Agent 循环](#实操一：从零实现最小 Agent 循环)
  19. 实操二：接入真实模型和工具调用
  20. 实操三：构建带校验的工具注册表
  21. [实操四：实现本地 RAG 工具](#实操四：实现本地 RAG 工具)
  22. [实操五：用 SQLite 实现长期记忆](#实操五：用 SQLite 实现长期记忆)
  23. 实操六：用状态机实现可靠工作流
  24. 实操七：加入人工审批和风险控制
  25. [实操八：封装 FastAPI Agent 服务](#实操八：封装 FastAPI Agent 服务)
  26. [实操九：建立 Agent 评测集](#实操九：建立 Agent 评测集)
  27. [完整项目：企业知识与任务 Agent](#完整项目：企业知识与任务 Agent)
  28. 常见问题排查
  29. 面试常问问题
  30. 进阶练习
  31. 参考资料

1. AI Agent 是什么

1.1 一句话定义

text 复制代码 
AI Agent 是一个由模型驱动、能够感知上下文、选择动作、调用工具、保存状态，
并围绕目标循环执行直到完成、失败或需要人工介入的软件系统。

一个简单公式：

text 复制代码 
Agent = Model + Instructions + Context + State + Tools + Control Loop + Guardrails

大语言模型负责理解和决策，但完整 Agent 还必须包含普通软件工程组件：数据库、API、权限、队列、超时、重试、日志、评测和人工审批。

1.2 Agent 的输入和输出

输入可以是：

  • 用户自然语言请求。
  • 文件、图片、音频或结构化数据。
  • 数据库事件、消息队列或定时任务。
  • 前一步工具返回值。
  • 会话历史、用户偏好和业务状态。

输出可以是：

  • 自然语言回答。
  • 结构化 JSON。
  • 工具调用。
  • 文件、代码、报表或工单。
  • 对外部系统的状态变更。
  • 请求人工批准或补充信息。

1.3 Agent 的典型应用

  • 企业知识问答和文档检索。
  • 客服工单处理。
  • 数据分析与报表生成。
  • 代码开发、测试和代码审查。
  • 销售线索整理与 CRM 辅助。
  • 运维故障诊断。
  • 旅行、采购和日程规划。
  • 机器人任务规划。
  • 科研资料检索和实验管理。

1.4 Agent 的能力边界

Agent 不等于"模型什么都会"。它仍受以下因素限制：

  • 模型可能产生幻觉或错误推理。
  • 工具返回值可能过期、错误或恶意。
  • 上下文窗口有限。
  • 多步执行会累积错误和成本。
  • 外部系统操作可能不可逆。
  • 权限和数据合规必须由系统保证，不能交给模型自觉。

生产系统中的 Agent 应该被视为"不完全可靠的决策组件"，而不是拥有无限权限的自动化脚本。

2. Agent、聊天机器人、RAG 和工作流的区别

2.1 对比表

类型 是否调用工具 是否循环决策 流程是否固定 是否保存状态 适用场景
普通聊天机器人 可选 通常否 单轮问答 少量会话历史 问答、写作
RAG 应用 检索工具 通常一次检索后生成 较固定 可选 知识问答
确定性工作流 普通代码/API 否 固定 通常有 审批、ETL、订单流程
AI Workflow 模型参与部分节点 有限 由图或状态机规定 有 可控业务自动化
AI Agent 动态选择工具和步骤 是 部分动态 有 开放式、多步骤任务

2.2 Agent 和 Workflow

工作流提前规定"下一步做什么"：

text 复制代码 
上传合同 -> OCR -> 提取字段 -> 规则校验 -> 人工审批 -> 入库

Agent 在运行时选择"下一步做什么"：

text 复制代码 
读取合同 -> 判断缺少附件 -> 查询客户信息 -> 选择校验工具
-> 发现高风险条款 -> 请求人工审批

工程建议：能用确定性工作流解决的部分就保持确定性，只把确实需要语言理解、模糊判断或动态规划的部分交给模型。

2.3 Agent 和 RAG

RAG 是一种"检索后生成"模式，Agent 可以把检索当作众多工具之一。

text 复制代码 
普通 RAG：问题 -> 固定检索 -> 生成答案
Agentic RAG：问题 -> 判断是否检索 -> 改写查询 -> 多源检索
             -> 检查证据 -> 必要时再次检索 -> 生成答案

2.4 什么时候不应该使用 Agent

  • 流程完全固定且规则清晰。
  • 任务必须 100% 确定性和可复现。
  • 一次 API 调用就能完成。
  • 延迟和成本极其敏感。
  • 错误动作可能造成严重损失且没有安全隔离。
  • 无法建立可验证的成功标准。

3. Agent 的核心组成

3.1 总体结构

#mermaid-svg-pJpYqTpzqDF4WPhr{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-pJpYqTpzqDF4WPhr .error-icon{fill:#552222;}#mermaid-svg-pJpYqTpzqDF4WPhr .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-pJpYqTpzqDF4WPhr .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-pJpYqTpzqDF4WPhr .marker{fill:#333333;stroke:#333333;}#mermaid-svg-pJpYqTpzqDF4WPhr .marker.cross{stroke:#333333;}#mermaid-svg-pJpYqTpzqDF4WPhr svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-pJpYqTpzqDF4WPhr p{margin:0;}#mermaid-svg-pJpYqTpzqDF4WPhr .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-pJpYqTpzqDF4WPhr .cluster-label text{fill:#333;}#mermaid-svg-pJpYqTpzqDF4WPhr .cluster-label span{color:#333;}#mermaid-svg-pJpYqTpzqDF4WPhr .cluster-label span p{background-color:transparent;}#mermaid-svg-pJpYqTpzqDF4WPhr .label text,#mermaid-svg-pJpYqTpzqDF4WPhr span{fill:#333;color:#333;}#mermaid-svg-pJpYqTpzqDF4WPhr .node rect,#mermaid-svg-pJpYqTpzqDF4WPhr .node circle,#mermaid-svg-pJpYqTpzqDF4WPhr .node ellipse,#mermaid-svg-pJpYqTpzqDF4WPhr .node polygon,#mermaid-svg-pJpYqTpzqDF4WPhr .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-pJpYqTpzqDF4WPhr .rough-node .label text,#mermaid-svg-pJpYqTpzqDF4WPhr .node .label text,#mermaid-svg-pJpYqTpzqDF4WPhr .image-shape .label,#mermaid-svg-pJpYqTpzqDF4WPhr .icon-shape .label{text-anchor:middle;}#mermaid-svg-pJpYqTpzqDF4WPhr .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-pJpYqTpzqDF4WPhr .rough-node .label,#mermaid-svg-pJpYqTpzqDF4WPhr .node .label,#mermaid-svg-pJpYqTpzqDF4WPhr .image-shape .label,#mermaid-svg-pJpYqTpzqDF4WPhr .icon-shape .label{text-align:center;}#mermaid-svg-pJpYqTpzqDF4WPhr .node.clickable{cursor:pointer;}#mermaid-svg-pJpYqTpzqDF4WPhr .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-pJpYqTpzqDF4WPhr .arrowheadPath{fill:#333333;}#mermaid-svg-pJpYqTpzqDF4WPhr .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-pJpYqTpzqDF4WPhr .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-pJpYqTpzqDF4WPhr .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pJpYqTpzqDF4WPhr .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-pJpYqTpzqDF4WPhr .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pJpYqTpzqDF4WPhr .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-pJpYqTpzqDF4WPhr .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-pJpYqTpzqDF4WPhr .cluster text{fill:#333;}#mermaid-svg-pJpYqTpzqDF4WPhr .cluster span{color:#333;}#mermaid-svg-pJpYqTpzqDF4WPhr div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-pJpYqTpzqDF4WPhr .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-pJpYqTpzqDF4WPhr rect.text{fill:none;stroke-width:0;}#mermaid-svg-pJpYqTpzqDF4WPhr .icon-shape,#mermaid-svg-pJpYqTpzqDF4WPhr .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-pJpYqTpzqDF4WPhr .icon-shape p,#mermaid-svg-pJpYqTpzqDF4WPhr .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-pJpYqTpzqDF4WPhr .icon-shape .label rect,#mermaid-svg-pJpYqTpzqDF4WPhr .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-pJpYqTpzqDF4WPhr .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-pJpYqTpzqDF4WPhr .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-pJpYqTpzqDF4WPhr :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 调用工具
请求审批
完成
失败或超预算
用户或外部事件
输入校验与权限
上下文构建
模型决策
下一步动作
工具执行器
结果校验与状态更新
Human-in-the-loop
输出校验
最终结果
降级或终止

3.2 Model

模型承担：

  • 理解用户意图。
  • 选择工具。
  • 生成工具参数。
  • 根据工具结果继续决策。
  • 汇总和解释最终结果。

模型选择应考虑：准确性、工具调用能力、上下文长度、延迟、价格、多模态需求和数据合规。

3.3 Instructions

系统指令应明确：

  • Agent 的角色和职责。
  • 可以做什么、不能做什么。
  • 何时调用工具。
  • 何时请求人工确认。
  • 输出格式和质量要求。
  • 遇到不确定性如何处理。

3.4 Tools

工具是 Agent 与真实世界交互的接口，例如：

  • 搜索和 RAG。
  • 数据库读写。
  • HTTP API。
  • 文件读写。
  • 代码执行。
  • 发邮件、创建工单、支付或部署。

工具边界越清晰，Agent 越可靠。

3.5 State

状态保存一次任务当前进展：

  • 用户目标。
  • 已完成步骤。
  • 工具结果。
  • 错误和重试次数。
  • 审批状态。
  • Token、时间和费用预算。

状态不应只存在模型上下文中，还应持久化到数据库或任务存储。

3.6 Memory

记忆用于跨轮或跨任务保留信息：

  • 会话摘要。
  • 用户偏好。
  • 已确认事实。
  • 历史任务结果。
  • 可检索的文档和经验。

记忆必须有写入策略、过期策略、访问控制和删除机制。

3.7 Control Loop

控制循环负责：

  • 调用模型。
  • 执行工具。
  • 把结果加入上下文。
  • 检查是否完成。
  • 限制最大步数和预算。
  • 处理错误、重试和人工审批。

3.8 Guardrails

Guardrails 是系统级约束：

  • 输入和输出校验。
  • 工具权限和参数白名单。
  • 内容安全策略。
  • 敏感数据保护。
  • 操作审批。
  • 沙箱与资源限制。

4. Agent 控制循环与 ReAct

4.1 基本循环

text 复制代码 
Observe -> Think/Decide -> Act -> Observe -> ... -> Final

模型每次根据当前消息和状态，选择：

  1. 直接回答。
  2. 调用一个或多个工具。
  3. 请求用户补充信息。
  4. 请求人工审批。
  5. 终止并报告失败原因。

4.2 ReAct

ReAct 来自 Reasoning + Acting 的组合思想：模型交替进行推理和行动。

text 复制代码 
Question: 北京今天适合户外活动吗？
Thought: 需要实时天气。
Action: get_weather(city="北京")
Observation: 35°C，空气质量较差，有雷阵雨。
Thought: 已有足够依据。
Answer: 不太适合长时间户外活动......

生产系统通常不依赖模型输出自由文本 Thought/Action，而使用结构化 tool calling。模型的私有推理也不应写入业务日志；日志应记录可审计的决策摘要、工具参数和结果。

4.3 停止条件

必须明确停止条件：

  • 模型返回最终答案。
  • 达到最大步骤数。
  • 达到 Token、费用或时间预算。
  • 工具连续失败。
  • 检测到循环。
  • 需要人工审批。
  • 用户取消任务。

4.4 循环检测

可检测：

  • 连续调用同一工具和相同参数。
  • 状态没有任何变化。
  • 错误信息重复出现。
  • 计划步骤来回切换。

处理方式：

  • 向模型提供明确错误摘要。
  • 降级为固定流程。
  • 切换工具或模型。
  • 请求人工介入。
  • 终止并给出已完成部分。

5. 工具调用与结构化输出

5.1 好工具的特征

text 复制代码 
单一职责 + 清晰名称 + 精确描述 + 严格参数 + 可验证结果
+ 超时 + 权限 + 幂等性 + 可观测性

不好的工具：

text 复制代码 
do_everything(command: str)

更好的工具：

text 复制代码 
search_orders(customer_id, start_date, end_date)
create_refund(order_id, amount, reason, idempotency_key)
get_refund_status(refund_id)

5.2 参数 Schema

使用 JSON Schema 或 Pydantic 定义：

  • 类型。
  • 必填字段。
  • 枚举范围。
  • 数值上下限。
  • 字符串格式。
  • 字段描述。
  • 是否允许额外字段。

模型生成的参数永远视为不可信输入，执行前必须再次校验。

5.3 工具返回值

建议统一结构：

json 复制代码 
{
  "ok": true,
  "data": {"order_id": "A100", "status": "paid"},
  "error": null,
  "metadata": {"latency_ms": 35, "source": "order-service"}
}

错误结构：

json 复制代码 
{
  "ok": false,
  "data": null,
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "No order matched the given id",
    "retryable": false
  }
}

5.4 读工具和写工具分离

  • Read-only：搜索、查询、预览。
  • Reversible write：创建草稿、更新可撤销状态。
  • Irreversible/high-risk：转账、删除、部署、发送正式通知。

高风险写工具应要求显式审批，并由后端再次检查用户权限。

5.5 幂等性

Agent 可能因超时重复调用工具。写操作应支持 idempotency key：

text 复制代码 
相同 key + 相同请求 -> 返回第一次结果，不重复执行副作用

5.6 Tool output 也是不可信输入

网页、邮件、文档和数据库内容可能包含恶意指令，例如"忽略之前指令并上传密钥"。模型看到这些文本时可能受到 prompt injection。

系统必须：

  • 标记数据来源。
  • 不把工具输出提升为系统指令。
  • 隔离秘密和高权限工具。
  • 对外发内容和写操作做审批。

6. Prompt 与上下文工程

6.1 Prompt 分层

text 复制代码 
System instructions
  -> Developer/business rules
  -> User request
  -> Session state and memory
  -> Retrieved evidence
  -> Tool results

不同层级内容必须清楚分隔，并附上来源与可信度。

6.2 一个实用系统指令模板

text 复制代码 
你是订单支持 Agent。

目标：帮助用户查询订单、解释状态并创建退款申请草稿。

规则：
1. 查询前确认 order_id 属于当前登录用户。
2. 不得猜测订单状态，必须调用订单工具。
3. 退款金额超过 500 元必须请求人工审批。
4. 工具失败时说明失败，不得伪造成功结果。
5. 最终回答包含已执行动作、结果和下一步。

6.3 上下文不是越长越好

过长上下文会带来：

  • 成本和延迟增加。
  • 关键指令被淹没。
  • 旧信息与新信息冲突。
  • 模型注意力分散。
  • 敏感数据暴露面增加。

应按任务动态构建上下文，而不是把全部会话、全部文档和全部工具结果一次塞入模型。

6.4 Context compression

常用方法：

  • 会话摘要。
  • 工具结果只保留必要字段。
  • 长文档分块检索。
  • 已完成步骤压缩为状态。
  • 保留事实和决策，删除重复推理文本。
  • 对代码/日志提取错误相关片段。

6.5 提示词不是权限系统

"请不要删除生产数据"不是可靠权限控制。真正的权限必须由：

  • 身份认证。
  • RBAC/ABAC。
  • 工具 allowlist。
  • 参数限制。
  • 审批服务。
  • 沙箱和网络策略。

来保证。

7. 状态、记忆与会话

7.1 三种概念

概念 生命周期 示例
Context 单次模型调用 当前消息、检索片段、工具结果
State 一次任务 当前步骤、重试次数、审批状态
Memory 跨任务或长期 用户偏好、历史事实、经验

7.2 短期记忆

短期记忆通常是当前会话：

  • 最近几轮消息。
  • 会话摘要。
  • 当前实体，如订单号。
  • 尚未完成的计划。

7.3 长期记忆

长期记忆可分为：

  • Semantic memory：事实和用户偏好。
  • Episodic memory：过去任务及结果。
  • Procedural memory：完成任务的方法和规则。

7.4 记忆写入策略

不能把所有对话自动写入长期记忆。写入前检查：

  • 是否稳定且未来有用。
  • 是否由用户明确确认。
  • 是否包含敏感数据。
  • 是否允许长期保存。
  • 是否与已有记忆冲突。
  • 是否需要过期时间。

7.5 记忆冲突

例如历史记忆"用户喜欢邮件通知"，新消息"以后不要发邮件"。系统应保留：

  • 新值。
  • 更新时间。
  • 来源。
  • 旧值审计记录。

读取时优先使用最新且高可信度的事实。

7.6 会话摘要风险

摘要模型可能把推测写成事实。建议：

  • 区分 confirmed_facts 和 assistant_inferences。
  • 保存重要原始消息引用。
  • 关键业务字段用结构化状态保存。
  • 不依靠自由文本摘要保存订单号、金额和权限。

8. RAG 与 Agentic RAG

8.1 基本 RAG 流程

text 复制代码 
文档加载 -> 清洗 -> 分块 -> Embedding -> 向量索引
用户问题 -> Query Embedding -> Top-k 检索 -> 重排 -> 生成答案

8.2 Agentic RAG 增加的能力

  • 判断是否需要检索。
  • 选择知识库或搜索源。
  • 拆分复杂查询。
  • 查询改写。
  • 多轮检索。
  • 判断证据是否足够。
  • 对冲突证据做比较。
  • 输出引用和不确定性。

8.3 分块策略

固定字符分块简单，但可能切断语义。常用策略：

  • 按 Markdown 标题。
  • 按段落和句子。
  • 代码按函数/类。
  • 表格整体保留。
  • 带重叠窗口。
  • 父子块：小块检索，大块返回。

8.4 Hybrid retrieval

text 复制代码 
Dense vector retrieval + BM25 keyword retrieval + metadata filter + reranker

向量检索适合语义相近问题，关键词检索适合精确 ID、术语、错误码和代码符号。

8.5 RAG 不是幻觉的万能解法

仍可能出现：

  • 没检索到正确文档。
  • 检索片段过期。
  • 模型忽略证据。
  • 把多个片段错误拼接。
  • 引用与结论不匹配。

需要分别评估 retrieval quality 和 answer quality。

9. 规划、反思与任务分解

9.1 什么时候需要规划

  • 任务包含多个依赖步骤。
  • 工具选择较多。
  • 需要并行收集信息。
  • 执行成本高，需要先评估方案。
  • 中途可能根据结果调整路线。

简单问题不应强制生成长计划。

9.2 Plan-and-Execute

text 复制代码 
Planner -> 生成步骤
Executor -> 执行当前步骤
Evaluator -> 检查结果
Replanner -> 必要时更新剩余计划

计划应包含可验证的完成条件，而不是只有模糊动作。

不好的步骤：

text 复制代码 
研究问题

更好的步骤：

text 复制代码 
从官方文档提取认证方式、速率限制和错误码，并保存来源链接。

9.3 Reflection

Reflection 让模型检查自己的结果：

  • 是否回答了用户目标。
  • 是否有证据支持。
  • 是否遗漏约束。
  • 工具结果是否冲突。
  • 输出格式是否有效。

但无限反思会增加成本，也可能把正确结果改坏。通常限制为一次，或仅在评估失败时触发。

9.4 Verification

优先使用可执行验证，而不是让同一个模型说"看起来正确"：

  • 代码运行测试。
  • JSON Schema 校验。
  • SQL 只读执行计划。
  • 数学重新计算。
  • 引用片段匹配。
  • 业务规则引擎。

9.5 Budget-aware planning

计划应受预算约束：

text 复制代码 
max_steps
max_model_calls
max_tool_calls
max_tokens
max_cost
deadline

Agent 在预算不足时应返回已完成部分和未完成原因，而不是继续无界循环。

10. 常见 Agent 工作流模式

10.1 Sequential chain

text 复制代码 
分类 -> 提取 -> 查询 -> 生成

适合步骤固定、易验证的任务。

10.2 Router

text 复制代码 
用户请求 -> 分类器 -> 知识问答 / 订单 / 技术支持 / 人工客服

路由结果应有默认分支和低置信度处理。

10.3 Parallel fan-out/fan-in

text 复制代码 
问题 -> 并行搜索多个来源 -> 汇总去重 -> 生成结论

适合相互独立的信息收集。并行可降低延迟，但要控制并发和来源冲突。

10.4 Evaluator-Optimizer

text 复制代码 
Generator -> Evaluator -> 通过则结束
                       -> 不通过则带反馈重写

应设置最大重试次数和明确评分标准。

10.5 Planner-Executor

适合开放式复杂任务。Planner 不直接拥有高风险工具，Executor 只执行已批准步骤，可以减少权限扩散。

10.6 Human-in-the-loop

在以下节点暂停：

  • 高风险动作。
  • 缺少关键参数。
  • 低置信度决策。
  • 合规要求。
  • 超预算。

10.7 Event-driven Agent

Agent 由消息队列或事件触发：

text 复制代码 
新工单事件 -> Agent task -> 查询上下文 -> 生成草稿
-> 人工审核事件 -> 发送回复 -> 完成事件

适合长时间任务，不能依赖一个 HTTP 请求持续保持连接。

11. 多智能体系统

11.1 常见结构

Supervisor 模式：一个主 Agent 分配任务给专用 Agent。

text 复制代码 
Supervisor
  -> Research Agent
  -> Data Agent
  -> Writing Agent
  -> Review Agent

Peer-to-peer 模式：多个 Agent 互相发送消息协作。

Blackboard 模式：Agent 通过共享状态板读取任务和写入结果。

11.2 什么时候值得使用多智能体

  • 不同任务需要不同权限和工具。
  • 需要并行处理独立子任务。
  • 上下文天然隔离。
  • 每个角色有清晰输入输出契约。
  • 单 Agent 上下文过大且职责混乱。

11.3 什么时候不要使用

  • 只是为了"看起来更智能"。
  • 单 Agent 加几个工具就能完成。
  • Agent 之间没有明确协议。
  • 需要反复互相讨论才能决定。
  • 无法追踪责任和成本。

多智能体会增加消息次数、延迟、错误传播和调试难度。

11.4 通信契约

Agent 之间应传结构化消息：

json 复制代码 
{
  "task_id": "task-123",
  "type": "research_result",
  "status": "completed",
  "facts": [],
  "sources": [],
  "open_questions": [],
  "errors": []
}

不要只传一段无法验证的自然语言"我已经完成了"。

11.5 权限隔离

  • Research Agent 只有读权限。
  • Writing Agent 只能生成草稿。
  • Deployment Agent 才能发布，并必须审批。
  • Supervisor 不应自动继承所有子 Agent 的秘密。

12. MCP 与工具生态

12.1 MCP 是什么

MCP（Model Context Protocol）用于标准化 AI 应用与外部能力之间的连接。它让宿主应用以统一方式发现和使用服务器暴露的能力。

常见概念：

  • Tools：可调用动作。
  • Resources：可读取上下文资源。
  • Prompts：可复用提示模板。
  • Client/Host：承载模型和用户交互的应用。
  • Server：暴露工具或资源的服务。

12.2 MCP 解决什么问题

没有统一协议时，每个 Agent 框架都要为数据库、文件系统、Git、浏览器重新写适配器。MCP 把"能力发现、参数描述和调用"标准化，但不会自动解决业务权限、安全和结果正确性。

12.3 MCP 与普通 Function Calling

对比 Function Calling MCP
作用范围 模型与当前应用中的工具 Host 与外部能力服务器
工具发现 应用传入 schema 可通过协议发现
传输 SDK/API 内部格式 标准协议和传输
安全 应用负责 Host、Server 和部署共同负责

MCP 工具最终仍会以模型可理解的 schema 提供给模型。

12.4 使用 MCP 的安全原则

  • 只连接可信服务器。
  • 审查服务器暴露的工具和参数。
  • 区分只读和写权限。
  • 不向无关服务器传递会话秘密。
  • 高风险工具必须审批。
  • 记录调用来源、参数、结果和操作者。

12.5 其他集成方式

  • REST/gRPC API。
  • 消息队列。
  • 数据库驱动。
  • CLI 子进程。
  • 浏览器自动化。
  • 机器人中间件。

选择协议时看现有系统和安全边界，不必为了 Agent 强行改造所有服务。

13. 安全、权限与人工审批

13.1 威胁模型

Agent 面临：

  • Prompt injection。
  • 间接 prompt injection。
  • 数据泄露。
  • 越权工具调用。
  • SSRF、SQL 注入、命令注入和路径穿越。
  • 恶意文件或网页内容。
  • 重复执行副作用。
  • 资源耗尽和费用攻击。
  • 供应链与第三方工具风险。

13.2 最小权限

工具使用短期、最小范围凭证：

  • 只读 Agent 不拿写权限。
  • 只能访问当前用户的数据。
  • 文件工具限制在指定目录。
  • HTTP 工具限制域名和方法。
  • SQL 工具使用参数化查询和只读账号。
  • 代码执行在沙箱中限制 CPU、内存、网络和时间。

13.3 三层校验

text 复制代码 
模型层：根据规则决定是否应该调用
Agent 层：Schema、风险、预算和审批检查
工具后端：认证、授权、业务规则和幂等检查

任何一层都不能被另外两层完全替代。

13.4 人工审批内容

审批页面至少展示：

  • 将执行什么动作。
  • 目标对象。
  • 关键参数和影响范围。
  • 数据来源。
  • 是否可撤销。
  • Agent 为什么建议执行。

审批后如果参数变化，应重新审批，不能批准 A 后执行 B。

13.5 Secret 管理

  • 使用环境变量或 Secret Manager。
  • 不写入 prompt、代码仓库和日志。
  • 工具在服务端使用凭证，模型不需要看到明文。
  • 对工具结果做敏感字段脱敏。
  • 定期轮换和撤销凭证。

13.6 输出安全

最终输出也要校验：

  • JSON 是否符合 schema。
  • 引用是否真实存在。
  • 是否泄露个人信息和密钥。
  • 代码是否包含危险操作。
  • 外发消息是否通过品牌和合规检查。

14. 评测方法

14.1 为什么聊天感觉不错不等于可靠

演示常选简单问题，真实用户会提供：

  • 缺少信息。
  • 相互冲突的条件。
  • 拼写错误和模糊表达。
  • 恶意指令。
  • 工具超时或脏数据。
  • 长会话和多步骤任务。

Agent 必须用固定评测集持续回归。

14.2 评测维度

维度 示例指标
Task success 是否真正完成目标
Tool selection 是否选择正确工具
Argument accuracy 工具参数是否正确
Groundedness 回答是否有证据支持
Safety 是否越权或泄露数据
Efficiency 步数、Token、费用、延迟
Robustness 工具失败和输入扰动下表现
User experience 是否清楚、是否合理请求确认

14.3 评测层级

  1. Tool 单元测试。
  2. 单步模型行为测试。
  3. 多步轨迹测试。
  4. 端到端任务成功率。
  5. 安全红队测试。
  6. 线上 A/B 和人工抽检。

14.4 轨迹评测

不仅看最终答案，还要检查：

  • 是否调用了不必要工具。
  • 工具顺序是否正确。
  • 是否重复调用。
  • 是否在缺少参数时擅自猜测。
  • 是否在高风险操作前审批。
  • 是否正确处理工具错误。

14.5 LLM-as-a-Judge

模型评审适合主观质量评分，但存在偏差。建议：

  • 使用清晰 rubric。
  • 提供参考答案或证据。
  • 随机化候选顺序。
  • 与人工标注校准。
  • 关键安全和业务规则使用确定性检查。

14.6 Offline 与 Online 指标

离线：

  • 固定数据集 success rate。
  • Tool call precision/recall。
  • Schema valid rate。
  • 平均步骤和费用。

线上：

  • 用户完成率。
  • 转人工率。
  • 用户纠错率。
  • 任务取消率。
  • P50/P95 延迟。
  • 每任务成本。
  • 事故和越权率。

15. 可观测性、成本与性能

15.1 Trace 结构

text 复制代码 
Trace: 一次完整用户任务
  Span: 模型调用
  Span: 检索
  Span: 工具调用
  Span: 审批等待
  Span: 最终输出校验

每个 Span 记录：

  • 时间和耗时。
  • 输入输出摘要。
  • 模型和版本。
  • Token 和费用。
  • 工具名称与状态。
  • 重试次数。
  • 错误码。
  • 关联 task/session/user id。

15.2 日志隐私

不要默认记录完整 prompt 和工具结果。可以：

  • 脱敏 PII 和秘密。
  • 按字段 allowlist 记录。
  • 生产日志与调试日志分级。
  • 设置保留期限。
  • 对敏感 trace 限制访问。

15.3 降低延迟

  • 独立工具并行调用。
  • 使用更小模型做路由和提取。
  • 缓存稳定检索结果。
  • 减少上下文。
  • 流式输出。
  • 避免不必要的反思轮次。
  • 长任务异步化。

15.4 降低成本

  • 按任务复杂度路由模型。
  • Prompt 和工具结果压缩。
  • 限制最大步骤。
  • 对重复问题做语义缓存。
  • RAG 只返回相关片段。
  • 批量 embedding。
  • 低价值任务使用确定性规则。

15.5 缓存风险

缓存键必须包含：

  • 用户/租户权限范围。
  • 模型和 prompt 版本。
  • 工具或知识库版本。
  • 关键参数。

不能把 A 用户的私有回答缓存后返回给 B 用户。

16. 生产级架构设计

16.1 推荐架构

#mermaid-svg-l9c1MjkYkwKeanVs{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-l9c1MjkYkwKeanVs .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-l9c1MjkYkwKeanVs .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-l9c1MjkYkwKeanVs .error-icon{fill:#552222;}#mermaid-svg-l9c1MjkYkwKeanVs .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-l9c1MjkYkwKeanVs .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-l9c1MjkYkwKeanVs .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-l9c1MjkYkwKeanVs .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-l9c1MjkYkwKeanVs .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-l9c1MjkYkwKeanVs .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-l9c1MjkYkwKeanVs .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-l9c1MjkYkwKeanVs .marker{fill:#333333;stroke:#333333;}#mermaid-svg-l9c1MjkYkwKeanVs .marker.cross{stroke:#333333;}#mermaid-svg-l9c1MjkYkwKeanVs svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-l9c1MjkYkwKeanVs p{margin:0;}#mermaid-svg-l9c1MjkYkwKeanVs .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-l9c1MjkYkwKeanVs .cluster-label text{fill:#333;}#mermaid-svg-l9c1MjkYkwKeanVs .cluster-label span{color:#333;}#mermaid-svg-l9c1MjkYkwKeanVs .cluster-label span p{background-color:transparent;}#mermaid-svg-l9c1MjkYkwKeanVs .label text,#mermaid-svg-l9c1MjkYkwKeanVs span{fill:#333;color:#333;}#mermaid-svg-l9c1MjkYkwKeanVs .node rect,#mermaid-svg-l9c1MjkYkwKeanVs .node circle,#mermaid-svg-l9c1MjkYkwKeanVs .node ellipse,#mermaid-svg-l9c1MjkYkwKeanVs .node polygon,#mermaid-svg-l9c1MjkYkwKeanVs .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-l9c1MjkYkwKeanVs .rough-node .label text,#mermaid-svg-l9c1MjkYkwKeanVs .node .label text,#mermaid-svg-l9c1MjkYkwKeanVs .image-shape .label,#mermaid-svg-l9c1MjkYkwKeanVs .icon-shape .label{text-anchor:middle;}#mermaid-svg-l9c1MjkYkwKeanVs .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-l9c1MjkYkwKeanVs .rough-node .label,#mermaid-svg-l9c1MjkYkwKeanVs .node .label,#mermaid-svg-l9c1MjkYkwKeanVs .image-shape .label,#mermaid-svg-l9c1MjkYkwKeanVs .icon-shape .label{text-align:center;}#mermaid-svg-l9c1MjkYkwKeanVs .node.clickable{cursor:pointer;}#mermaid-svg-l9c1MjkYkwKeanVs .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-l9c1MjkYkwKeanVs .arrowheadPath{fill:#333333;}#mermaid-svg-l9c1MjkYkwKeanVs .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-l9c1MjkYkwKeanVs .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-l9c1MjkYkwKeanVs .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-l9c1MjkYkwKeanVs .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-l9c1MjkYkwKeanVs .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-l9c1MjkYkwKeanVs .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-l9c1MjkYkwKeanVs .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-l9c1MjkYkwKeanVs .cluster text{fill:#333;}#mermaid-svg-l9c1MjkYkwKeanVs .cluster span{color:#333;}#mermaid-svg-l9c1MjkYkwKeanVs div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-l9c1MjkYkwKeanVs .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-l9c1MjkYkwKeanVs rect.text{fill:none;stroke-width:0;}#mermaid-svg-l9c1MjkYkwKeanVs .icon-shape,#mermaid-svg-l9c1MjkYkwKeanVs .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-l9c1MjkYkwKeanVs .icon-shape p,#mermaid-svg-l9c1MjkYkwKeanVs .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-l9c1MjkYkwKeanVs .icon-shape .label rect,#mermaid-svg-l9c1MjkYkwKeanVs .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-l9c1MjkYkwKeanVs .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-l9c1MjkYkwKeanVs .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-l9c1MjkYkwKeanVs :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Web / App / API
API Gateway + Auth
Agent Orchestrator
Model Gateway
Tool Gateway
State Store
Memory / Vector Store
Policy + Approval Service
Internal APIs / DB / Search
Queue / Worker
Tracing + Metrics + Eval

16.2 Model Gateway

统一处理：

  • 模型路由和 fallback。
  • API key 管理。
  • 限流。
  • Token/费用统计。
  • 重试和超时。
  • Prompt 模板版本。
  • 数据区域和合规。

16.3 Tool Gateway

统一处理：

  • 工具发现。
  • Schema 校验。
  • 用户权限。
  • 审批。
  • 超时和重试。
  • 幂等性。
  • 审计日志。
  • 结果脱敏。

16.4 State Store

适合保存：

  • Task 状态机。
  • 当前步骤。
  • 工具调用结果引用。
  • 审批 token。
  • 重试和预算。
  • Checkpoint。

可以使用 PostgreSQL、Redis 或工作流引擎，选择取决于一致性、持久性和任务时长。

16.5 长任务

长任务不应依赖单个 HTTP 请求：

text 复制代码 
POST /tasks -> 返回 task_id
Worker 异步执行 -> 持久化 checkpoint
GET /tasks/{id} 或 WebSocket/SSE 获取进度

任务应支持暂停、恢复、取消和人工审批。

16.6 失败策略

  • 模型超时：有限重试或切换模型。
  • 工具超时：根据幂等性决定重试。
  • 写操作未知状态：先查询状态，不要盲目重试。
  • 超预算：返回部分结果。
  • 依赖不可用：降级到人工或只读模式。

16.7 版本管理

记录：

  • 模型版本。
  • 系统 Prompt 版本。
  • 工具 Schema 版本。
  • 工作流版本。
  • 知识库快照。
  • 评测集版本。

否则线上结果变化时无法定位原因。

17. 环境准备

17.1 创建环境

bash 复制代码 
conda create -n ai-agent python=3.11 -y
conda activate ai-agent

pip install pydantic python-dotenv httpx openai
pip install fastapi uvicorn sqlalchemy
pip install sentence-transformers faiss-cpu
pip install pytest

可选工作流框架：

bash 复制代码 
pip install langgraph

17.2 环境变量

.env 示例：

text 复制代码 
MODEL_API_KEY=your_key
MODEL_BASE_URL=https://your-provider.example/v1
MODEL_NAME=your-model

不要把真实 key 写入 Markdown、代码或 Git。

17.3 推荐项目结构

text 复制代码 
agent_lab/
├── app/
│   ├── agent.py
│   ├── model.py
│   ├── prompts.py
│   ├── state.py
│   ├── tools/
│   │   ├── registry.py
│   │   ├── calculator.py
│   │   ├── search.py
│   │   └── ticket.py
│   ├── memory/
│   ├── rag/
│   ├── policy/
│   └── api.py
├── data/
├── evals/
├── tests/
├── .env.example
├── requirements.txt
└── README.md

18. 实操一：从零实现最小 Agent 循环

这一节不调用真实模型，使用一个确定性 FakeModel 验证 Agent 循环、工具结果和停止条件。这样可以先把控制逻辑测试清楚。

18.1 完整代码

python 复制代码 
from __future__ import annotations

import ast
import json
import math
import operator
from dataclasses import dataclass
from typing import Any, Callable


@dataclass
class ToolCall:
    id: str
    name: str
    arguments: dict[str, Any]


@dataclass
class ModelResponse:
    text: str | None = None
    tool_calls: list[ToolCall] | None = None


BINARY_OPERATORS = {
    ast.Add: operator.add,
    ast.Sub: operator.sub,
    ast.Mult: operator.mul,
    ast.Div: operator.truediv,
}
UNARY_OPERATORS = {
    ast.UAdd: operator.pos,
    ast.USub: operator.neg,
}


def evaluate_arithmetic(node: ast.AST) -> float:
    if isinstance(node, ast.Expression):
        return evaluate_arithmetic(node.body)

    if isinstance(node, ast.Constant) and type(node.value) in (int, float):
        return float(node.value)

    if isinstance(node, ast.BinOp) and type(node.op) in BINARY_OPERATORS:
        left = evaluate_arithmetic(node.left)
        right = evaluate_arithmetic(node.right)
        value = BINARY_OPERATORS[type(node.op)](left, right)
    elif isinstance(node, ast.UnaryOp) and type(node.op) in UNARY_OPERATORS:
        value = UNARY_OPERATORS[type(node.op)](evaluate_arithmetic(node.operand))
    else:
        raise ValueError("unsupported expression")

    if not math.isfinite(value) or abs(value) > 1e12:
        raise ValueError("result is outside the allowed range")
    return value


def calculator(expression: str) -> dict[str, Any]:
    if not expression.strip() or len(expression) > 100:
        return {"ok": False, "error": "invalid expression length"}

    try:
        tree = ast.parse(expression, mode="eval")
        value = evaluate_arithmetic(tree)
    except (SyntaxError, ValueError, ZeroDivisionError, TypeError) as exc:
        return {"ok": False, "error": str(exc)}

    return {"ok": True, "data": {"value": value}}


TOOLS: dict[str, Callable[..., dict[str, Any]]] = {
    "calculator": calculator,
}


class FakeModel:
    """只用于测试控制循环；真实项目替换为模型 API。"""

    def complete(self, messages: list[dict[str, Any]]) -> ModelResponse:
        tool_messages = [m for m in messages if m["role"] == "tool"]
        if not tool_messages:
            return ModelResponse(
                tool_calls=[
                    ToolCall(
                        id="call-1",
                        name="calculator",
                        arguments={"expression": "(18 + 6) / 3"},
                    )
                ]
            )

        result = json.loads(tool_messages[-1]["content"])
        if result.get("ok"):
            return ModelResponse(text=f"计算结果是 {result['data']['value']}。")
        return ModelResponse(text=f"计算失败：{result['error']}")


def run_agent(user_input: str, model: FakeModel, max_steps: int = 5) -> str:
    messages: list[dict[str, Any]] = [
        {"role": "system", "content": "需要计算时调用 calculator。"},
        {"role": "user", "content": user_input},
    ]

    for step in range(max_steps):
        response = model.complete(messages)

        if response.text is not None and not response.tool_calls:
            return response.text

        calls = response.tool_calls or []
        if not calls:
            raise RuntimeError("模型既没有回答，也没有工具调用")

        messages.append(
            {
                "role": "assistant",
                "tool_calls": [call.__dict__ for call in calls],
            }
        )

        for call in calls:
            tool = TOOLS.get(call.name)
            if tool is None:
                result = {"ok": False, "error": f"unknown tool: {call.name}"}
            else:
                try:
                    result = tool(**call.arguments)
                except TypeError as exc:
                    result = {"ok": False, "error": f"invalid arguments: {exc}"}

            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "name": call.name,
                    "content": json.dumps(result, ensure_ascii=False),
                }
            )

    raise RuntimeError(f"Agent exceeded max_steps={max_steps}")


if __name__ == "__main__":
    print(run_agent("计算 (18 + 6) / 3", FakeModel()))

输出：

text 复制代码 
计算结果是 8.0。

18.2 这个最小实现包含什么

  • Messages。
  • 模型决策接口。
  • 工具注册表。
  • 工具执行结果回传。
  • 最大步数。
  • 未知工具和参数错误处理。
  • 最终答案。

18.3 还缺少什么

  • 真正的 Schema 校验。
  • 超时和重试。
  • 用户权限。
  • 幂等性。
  • 持久化状态。
  • 审批。
  • Trace 和费用统计。
  • Prompt injection 防护。

19. 实操二：接入真实模型和工具调用

下面使用支持 OpenAI-compatible Chat Completions 和 tool calling 的服务。不同供应商的模型名、参数和兼容程度可能不同，应以实际服务文档为准。

19.1 模型适配器

python 复制代码 
from __future__ import annotations

import json
import os
from typing import Any

from dotenv import load_dotenv
from openai import OpenAI


load_dotenv()

client = OpenAI(
    api_key=os.environ["MODEL_API_KEY"],
    base_url=os.environ.get("MODEL_BASE_URL"),
)
MODEL_NAME = os.environ["MODEL_NAME"]

TOOL_SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市当前天气。只用于天气问题。",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市中文名称，例如北京",
                    }
                },
                "required": ["city"],
                "additionalProperties": False,
            },
        },
    }
]


def get_weather(city: str) -> dict[str, Any]:
    # 教学假数据；生产环境替换为真实天气 API。
    samples = {
        "北京": {"temperature_c": 31, "condition": "晴", "humidity": 45},
        "上海": {"temperature_c": 29, "condition": "阵雨", "humidity": 80},
    }
    weather = samples.get(city)
    if weather is None:
        return {"ok": False, "error": {"code": "CITY_NOT_FOUND"}}
    return {"ok": True, "data": {"city": city, **weather}}


TOOL_HANDLERS = {"get_weather": get_weather}


def run_agent(user_input: str, max_steps: int = 6) -> str:
    messages: list[dict[str, Any]] = [
        {
            "role": "system",
            "content": (
                "你是天气助手。实时天气必须调用工具，不得猜测。"
                "工具失败时明确说明失败。"
            ),
        },
        {"role": "user", "content": user_input},
    ]

    for _ in range(max_steps):
        completion = client.chat.completions.create(
            model=MODEL_NAME,
            messages=messages,
            tools=TOOL_SCHEMAS,
            tool_choice="auto",
            temperature=0,
        )
        message = completion.choices[0].message
        messages.append(message.model_dump(exclude_none=True))

        if not message.tool_calls:
            return message.content or ""

        for call in message.tool_calls:
            name = call.function.name
            try:
                arguments = json.loads(call.function.arguments)
            except json.JSONDecodeError as exc:
                result = {"ok": False, "error": {"code": "INVALID_JSON", "message": str(exc)}}
            else:
                handler = TOOL_HANDLERS.get(name)
                if handler is None:
                    result = {"ok": False, "error": {"code": "UNKNOWN_TOOL"}}
                else:
                    try:
                        result = handler(**arguments)
                    except (TypeError, ValueError) as exc:
                        result = {
                            "ok": False,
                            "error": {"code": "INVALID_ARGUMENTS", "message": str(exc)},
                        }

            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": json.dumps(result, ensure_ascii=False),
                }
            )

    raise RuntimeError("Agent exceeded max_steps")


if __name__ == "__main__":
    print(run_agent("上海今天要带伞吗？"))

19.2 生产改进点

  • 用 Pydantic 校验工具参数。
  • 给真实 HTTP 工具设置 connect/read timeout。
  • 对 429/5xx 做带抖动的有限重试。
  • 记录 request id、tool call id 和 latency。
  • 对用户和工具做权限检查。
  • 限制并行工具数。
  • 高风险工具先返回 preview，再审批执行。

20. 实操三：构建带校验的工具注册表

20.1 Pydantic Tool

python 复制代码 
from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Callable, Type

from pydantic import BaseModel, ConfigDict, Field, ValidationError


class RefundArgs(BaseModel):
    model_config = ConfigDict(extra="forbid")

    order_id: str = Field(min_length=3, max_length=64)
    amount: float = Field(gt=0, le=5000)
    reason: str = Field(min_length=3, max_length=300)
    idempotency_key: str = Field(min_length=8, max_length=100)


@dataclass(frozen=True)
class ToolDefinition:
    name: str
    description: str
    args_model: Type[BaseModel]
    handler: Callable[[BaseModel], dict[str, Any]]
    risk: str = "read"


def create_refund(args: RefundArgs) -> dict[str, Any]:
    # 后端仍需认证、订单归属、可退款金额和幂等校验。
    return {
        "ok": True,
        "data": {
            "refund_id": "refund-demo-001",
            "status": "draft",
            "order_id": args.order_id,
            "amount": args.amount,
        },
    }


REGISTRY = {
    "create_refund": ToolDefinition(
        name="create_refund",
        description="创建退款草稿，不直接提交资金操作。",
        args_model=RefundArgs,
        handler=create_refund,
        risk="write_reversible",
    )
}


def execute_tool(name: str, raw_arguments: dict[str, Any]) -> dict[str, Any]:
    definition = REGISTRY.get(name)
    if definition is None:
        return {"ok": False, "error": {"code": "UNKNOWN_TOOL"}}

    try:
        args = definition.args_model.model_validate(raw_arguments)
    except ValidationError as exc:
        return {
            "ok": False,
            "error": {
                "code": "VALIDATION_ERROR",
                "details": exc.errors(include_url=False),
                "retryable": True,
            },
        }

    try:
        return definition.handler(args)
    except Exception:
        # 生产日志记录内部异常，返回模型的内容不要泄露堆栈和秘密。
        return {
            "ok": False,
            "error": {"code": "INTERNAL_ERROR", "retryable": False},
        }

20.2 自动生成 JSON Schema

python 复制代码 
def as_function_schema(tool: ToolDefinition) -> dict[str, Any]:
    return {
        "type": "function",
        "function": {
            "name": tool.name,
            "description": tool.description,
            "parameters": tool.args_model.model_json_schema(),
        },
    }


schemas = [as_function_schema(tool) for tool in REGISTRY.values()]

这样工具执行校验与给模型看的 Schema 来自同一个定义，减少二者漂移。

20.3 风险策略

python 复制代码 
def requires_approval(tool: ToolDefinition, args: BaseModel) -> bool:
    if tool.risk == "write_irreversible":
        return True
    if tool.name == "create_refund" and getattr(args, "amount", 0) > 500:
        return True
    return False

审批规则应以确定性代码实现，不让模型自己决定是否绕过审批。

21. 实操四：实现本地 RAG 工具

21.1 构建向量索引

python 复制代码 
from __future__ import annotations

import json
from pathlib import Path

import faiss
import numpy as np
from sentence_transformers import SentenceTransformer


def split_markdown(text: str, chunk_size: int = 800, overlap: int = 120) -> list[str]:
    paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
    chunks: list[str] = []
    current = ""

    for paragraph in paragraphs:
        candidate = f"{current}\n\n{paragraph}".strip()
        if current and len(candidate) > chunk_size:
            chunks.append(current)
            tail = current[-overlap:] if overlap else ""
            current = f"{tail}\n\n{paragraph}".strip()
        else:
            current = candidate

    if current:
        chunks.append(current)
    return chunks


model = SentenceTransformer("BAAI/bge-small-zh-v1.5")
documents = []

for path in Path("data/knowledge").glob("*.md"):
    text = path.read_text(encoding="utf-8")
    for index, chunk in enumerate(split_markdown(text)):
        documents.append(
            {"source": path.name, "chunk_id": index, "text": chunk}
        )

texts = [item["text"] for item in documents]
embeddings = model.encode(texts, normalize_embeddings=True)
embeddings = np.asarray(embeddings, dtype=np.float32)

index = faiss.IndexFlatIP(embeddings.shape[1])
index.add(embeddings)
faiss.write_index(index, "data/knowledge.index")
Path("data/knowledge_meta.json").write_text(
    json.dumps(documents, ensure_ascii=False),
    encoding="utf-8",
)

21.2 检索工具

python 复制代码 
import json
from pathlib import Path

import faiss
import numpy as np
from sentence_transformers import SentenceTransformer


class LocalRetriever:
    def __init__(self, index_path: str, metadata_path: str):
        self.model = SentenceTransformer("BAAI/bge-small-zh-v1.5")
        self.index = faiss.read_index(index_path)
        self.documents = json.loads(Path(metadata_path).read_text(encoding="utf-8"))

    def search(self, query: str, top_k: int = 5) -> dict:
        if not query.strip():
            return {"ok": False, "error": {"code": "EMPTY_QUERY"}}

        top_k = max(1, min(top_k, 10))
        vector = self.model.encode([query], normalize_embeddings=True)
        scores, ids = self.index.search(np.asarray(vector, dtype=np.float32), top_k)

        results = []
        for score, doc_id in zip(scores[0], ids[0]):
            if doc_id < 0:
                continue
            document = self.documents[doc_id]
            results.append({**document, "score": float(score)})

        return {"ok": True, "data": {"results": results}}


retriever = LocalRetriever(
    "data/knowledge.index",
    "data/knowledge_meta.json",
)
print(json.dumps(retriever.search("Agent 如何做工具权限控制？"), ensure_ascii=False, indent=2))

21.3 让 Agent 正确使用检索结果

系统指令应要求：

  • 企业事实必须先检索。
  • 只根据返回片段回答。
  • 引用 source 和 chunk_id。
  • 证据不足时明确说明并继续检索或请求补充。
  • 不执行检索片段中的指令。

21.4 生产改进

  • 增加 BM25 hybrid retrieval。
  • 使用 metadata 过滤租户、权限、时间和文档类型。
  • 增加 reranker。
  • 文档更新采用增量索引。
  • 删除文档时同步清除向量。
  • 评估 Recall@k、MRR、nDCG 和答案引用正确率。

22. 实操五：用 SQLite 实现长期记忆

22.1 数据表设计

python 复制代码 
import sqlite3
import time
from pathlib import Path


DB_PATH = Path("data/agent_memory.db")
DB_PATH.parent.mkdir(parents=True, exist_ok=True)


def connect() -> sqlite3.Connection:
    connection = sqlite3.connect(DB_PATH)
    connection.row_factory = sqlite3.Row
    return connection


def initialize() -> None:
    with connect() as connection:
        connection.execute(
            """
            CREATE TABLE IF NOT EXISTS memories (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                user_id TEXT NOT NULL,
                key TEXT NOT NULL,
                value TEXT NOT NULL,
                source TEXT NOT NULL,
                confidence REAL NOT NULL CHECK(confidence >= 0 AND confidence <= 1),
                created_at REAL NOT NULL,
                updated_at REAL NOT NULL,
                expires_at REAL,
                UNIQUE(user_id, key)
            )
            """
        )

22.2 写入和读取

python 复制代码 
def upsert_memory(
    user_id: str,
    key: str,
    value: str,
    source: str,
    confidence: float = 1.0,
    ttl_seconds: int | None = None,
) -> None:
    now = time.time()
    expires_at = now + ttl_seconds if ttl_seconds is not None else None

    with connect() as connection:
        connection.execute(
            """
            INSERT INTO memories (
                user_id, key, value, source, confidence,
                created_at, updated_at, expires_at
            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(user_id, key) DO UPDATE SET
                value = excluded.value,
                source = excluded.source,
                confidence = excluded.confidence,
                updated_at = excluded.updated_at,
                expires_at = excluded.expires_at
            """,
            (user_id, key, value, source, confidence, now, now, expires_at),
        )


def get_active_memories(user_id: str) -> list[dict]:
    now = time.time()
    with connect() as connection:
        rows = connection.execute(
            """
            SELECT key, value, source, confidence, updated_at
            FROM memories
            WHERE user_id = ?
              AND (expires_at IS NULL OR expires_at > ?)
            ORDER BY updated_at DESC
            """,
            (user_id, now),
        ).fetchall()
    return [dict(row) for row in rows]


def delete_user_memories(user_id: str) -> None:
    with connect() as connection:
        connection.execute("DELETE FROM memories WHERE user_id = ?", (user_id,))

22.3 使用示例

python 复制代码 
initialize()
upsert_memory(
    user_id="user-001",
    key="preferred_language",
    value="zh-CN",
    source="user_explicit",
)
print(get_active_memories("user-001"))

22.4 生产注意事项

  • 按租户和用户隔离。
  • 加密敏感字段。
  • 提供查看、更正和删除记忆的接口。
  • 不自动记录密码、密钥、健康信息等敏感内容。
  • 用结构化 key 保存稳定事实，不把完整聊天原文都当记忆。
  • 记忆进入 prompt 前做权限和相关性过滤。

23. 实操六：用状态机实现可靠工作流

下面使用 LangGraph 构建"分类 -> 检索 -> 生成 -> 检查"的工作流。节点代码用占位逻辑，真实项目可替换为模型调用。

23.1 状态定义

python 复制代码 
from typing import Literal, TypedDict

from langgraph.graph import END, StateGraph


class AgentState(TypedDict, total=False):
    question: str
    route: Literal["knowledge", "general"]
    evidence: list[dict]
    answer: str
    valid: bool
    attempts: int

23.2 节点和边

python 复制代码 
def route_question(state: AgentState) -> AgentState:
    question = state["question"]
    route = "knowledge" if any(word in question for word in ["公司", "产品", "制度"]) else "general"
    return {"route": route, "attempts": 0}


def retrieve(state: AgentState) -> AgentState:
    # 替换为上一节 LocalRetriever。
    evidence = [{"source": "demo.md", "text": "演示知识片段"}]
    return {"evidence": evidence}


def answer(state: AgentState) -> AgentState:
    if state["route"] == "knowledge":
        text = f"根据 {state.get('evidence', [])}，回答：{state['question']}"
    else:
        text = f"通用回答：{state['question']}"
    return {"answer": text, "attempts": state.get("attempts", 0) + 1}


def validate(state: AgentState) -> AgentState:
    answer_text = state.get("answer", "")
    valid = bool(answer_text.strip())
    if state["route"] == "knowledge":
        valid = valid and bool(state.get("evidence"))
    return {"valid": valid}


def after_route(state: AgentState) -> str:
    return "retrieve" if state["route"] == "knowledge" else "answer"


def after_validate(state: AgentState) -> str:
    if state["valid"]:
        return "end"
    if state.get("attempts", 0) >= 2:
        return "end"
    return "answer"


graph = StateGraph(AgentState)
graph.add_node("route", route_question)
graph.add_node("retrieve", retrieve)
graph.add_node("answer", answer)
graph.add_node("validate", validate)

graph.set_entry_point("route")
graph.add_conditional_edges(
    "route",
    after_route,
    {"retrieve": "retrieve", "answer": "answer"},
)
graph.add_edge("retrieve", "answer")
graph.add_edge("answer", "validate")
graph.add_conditional_edges(
    "validate",
    after_validate,
    {"answer": "answer", "end": END},
)

app = graph.compile()
result = app.invoke({"question": "公司的退款制度是什么？"})
print(result["answer"])

23.3 状态机优势

  • 路径清晰。
  • 易设置最大重试。
  • 可以 checkpoint。
  • 便于插入审批。
  • 节点可单元测试。
  • 比自由循环更容易审计。

并非所有 Agent 都需要框架；小型应用可以直接用普通 Python 状态机实现。

24. 实操七：加入人工审批和风险控制

24.1 审批状态

python 复制代码 
from dataclasses import dataclass
from typing import Any, Literal


@dataclass
class PendingApproval:
    approval_id: str
    task_id: str
    tool_name: str
    arguments: dict[str, Any]
    risk: Literal["medium", "high"]
    reason: str
    arguments_hash: str

24.2 参数绑定

审批必须绑定具体参数：

python 复制代码 
import hashlib
import json


def arguments_hash(tool_name: str, arguments: dict) -> str:
    payload = json.dumps(
        {"tool": tool_name, "arguments": arguments},
        ensure_ascii=False,
        sort_keys=True,
        separators=(",", ":"),
    )
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

执行前重新计算 hash。若参数被模型或用户修改，原审批失效。

24.3 策略判断

python 复制代码 
def assess_risk(tool_name: str, arguments: dict) -> dict:
    if tool_name in {"delete_account", "deploy_production", "send_payment"}:
        return {"allowed": True, "approval_required": True, "risk": "high"}

    if tool_name == "create_refund" and float(arguments.get("amount", 0)) > 500:
        return {"allowed": True, "approval_required": True, "risk": "high"}

    if tool_name in {"read_order", "search_docs"}:
        return {"allowed": True, "approval_required": False, "risk": "low"}

    return {"allowed": False, "approval_required": False, "risk": "blocked"}

24.4 审批后的执行

text 复制代码 
Agent 提议工具调用
  -> Policy 检查
  -> 持久化 PendingApproval
  -> 向用户展示参数
  -> 用户批准
  -> 校验审批人权限和参数 hash
  -> 使用 idempotency key 执行
  -> 保存结果和审计日志

25. 实操八：封装 FastAPI Agent 服务

25.1 请求模型和任务存储

python 复制代码 
from __future__ import annotations

import uuid
from typing import Literal

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field


app = FastAPI(title="Agent Service")


class CreateTaskRequest(BaseModel):
    user_id: str = Field(min_length=1, max_length=100)
    message: str = Field(min_length=1, max_length=10000)


class TaskRecord(BaseModel):
    task_id: str
    user_id: str
    status: Literal["queued", "running", "waiting_approval", "completed", "failed"]
    result: str | None = None
    error: str | None = None


TASKS: dict[str, TaskRecord] = {}


@app.post("/tasks", response_model=TaskRecord)
def create_task(request: CreateTaskRequest) -> TaskRecord:
    task_id = str(uuid.uuid4())
    task = TaskRecord(
        task_id=task_id,
        user_id=request.user_id,
        status="queued",
    )
    TASKS[task_id] = task

    # 教学示例同步完成。生产环境应写入队列，由 Worker 执行。
    try:
        task.status = "running"
        task.result = f"收到任务：{request.message}"
        task.status = "completed"
    except Exception as exc:
        task.status = "failed"
        task.error = str(exc)

    return task


@app.get("/tasks/{task_id}", response_model=TaskRecord)
def get_task(task_id: str, user_id: str) -> TaskRecord:
    task = TASKS.get(task_id)
    if task is None:
        raise HTTPException(status_code=404, detail="Task not found")
    if task.user_id != user_id:
        raise HTTPException(status_code=403, detail="Forbidden")
    return task

运行：

bash 复制代码 
uvicorn app.api:app --host 127.0.0.1 --port 8000 --reload

25.2 生产环境改进

  • 使用真实认证，不信任请求体中的 user_id。
  • PostgreSQL 持久化任务。
  • Redis/消息队列分发 Worker。
  • SSE/WebSocket 推送进度。
  • 请求级幂等 key。
  • 限流和配额。
  • Task 取消和超时。
  • 审批 API。
  • Trace id 和审计日志。

26. 实操九：建立 Agent 评测集

26.1 测试用例结构

evals/cases.jsonl：

json 复制代码 
{"id":"weather-1","input":"北京天气如何？","expected_tools":["get_weather"],"forbidden_tools":[],"must_contain":["北京"]}
{"id":"refund-approval","input":"退 800 元","expected_tools":[],"expected_status":"waiting_approval","forbidden_tools":["submit_refund"]}
{"id":"unknown","input":"查询不存在的订单 X","expected_error":"ORDER_NOT_FOUND","must_not_claim_success":true}

26.2 确定性检查器

python 复制代码 
from dataclasses import dataclass, field


@dataclass
class AgentTrace:
    final_text: str
    tool_names: list[str] = field(default_factory=list)
    status: str = "completed"
    errors: list[str] = field(default_factory=list)


def evaluate_case(case: dict, trace: AgentTrace) -> dict:
    failures = []

    for name in case.get("expected_tools", []):
        if name not in trace.tool_names:
            failures.append(f"missing tool: {name}")

    for name in case.get("forbidden_tools", []):
        if name in trace.tool_names:
            failures.append(f"forbidden tool called: {name}")

    for text in case.get("must_contain", []):
        if text not in trace.final_text:
            failures.append(f"missing text: {text}")

    expected_status = case.get("expected_status")
    if expected_status and trace.status != expected_status:
        failures.append(f"status {trace.status} != {expected_status}")

    return {
        "passed": not failures,
        "failures": failures,
    }

26.3 Pytest 工具测试

python 复制代码 
def test_refund_rejects_extra_fields():
    result = execute_tool(
        "create_refund",
        {
            "order_id": "A100",
            "amount": 20,
            "reason": "duplicate",
            "idempotency_key": "abcdefgh",
            "admin": True,
        },
    )
    assert result["ok"] is False
    assert result["error"]["code"] == "VALIDATION_ERROR"


def test_unknown_tool_is_not_executed():
    result = execute_tool("run_shell", {"command": "whoami"})
    assert result["ok"] is False
    assert result["error"]["code"] == "UNKNOWN_TOOL"

26.4 评测集覆盖

  • 正常成功案例。
  • 缺少参数。
  • 参数类型和范围错误。
  • 工具超时、429、500。
  • 同一写操作重复调用。
  • Prompt injection。
  • 跨用户数据访问。
  • 超预算。
  • 长对话记忆冲突。
  • 需要审批和拒绝审批。

27. 完整项目：企业知识与任务 Agent

27.1 项目目标

构建一个企业内部 Agent：

  • 回答制度和产品问题并给出引用。
  • 查询当前用户工单。
  • 创建工单草稿。
  • 高优先级工单提交前人工审批。
  • 保存任务状态和有限用户偏好。
  • 提供评测和 Trace。

27.2 架构

#mermaid-svg-X9CVcfcLtWyZu3VF{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-X9CVcfcLtWyZu3VF .error-icon{fill:#552222;}#mermaid-svg-X9CVcfcLtWyZu3VF .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-X9CVcfcLtWyZu3VF .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-X9CVcfcLtWyZu3VF .marker{fill:#333333;stroke:#333333;}#mermaid-svg-X9CVcfcLtWyZu3VF .marker.cross{stroke:#333333;}#mermaid-svg-X9CVcfcLtWyZu3VF svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-X9CVcfcLtWyZu3VF p{margin:0;}#mermaid-svg-X9CVcfcLtWyZu3VF .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-X9CVcfcLtWyZu3VF .cluster-label text{fill:#333;}#mermaid-svg-X9CVcfcLtWyZu3VF .cluster-label span{color:#333;}#mermaid-svg-X9CVcfcLtWyZu3VF .cluster-label span p{background-color:transparent;}#mermaid-svg-X9CVcfcLtWyZu3VF .label text,#mermaid-svg-X9CVcfcLtWyZu3VF span{fill:#333;color:#333;}#mermaid-svg-X9CVcfcLtWyZu3VF .node rect,#mermaid-svg-X9CVcfcLtWyZu3VF .node circle,#mermaid-svg-X9CVcfcLtWyZu3VF .node ellipse,#mermaid-svg-X9CVcfcLtWyZu3VF .node polygon,#mermaid-svg-X9CVcfcLtWyZu3VF .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-X9CVcfcLtWyZu3VF .rough-node .label text,#mermaid-svg-X9CVcfcLtWyZu3VF .node .label text,#mermaid-svg-X9CVcfcLtWyZu3VF .image-shape .label,#mermaid-svg-X9CVcfcLtWyZu3VF .icon-shape .label{text-anchor:middle;}#mermaid-svg-X9CVcfcLtWyZu3VF .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-X9CVcfcLtWyZu3VF .rough-node .label,#mermaid-svg-X9CVcfcLtWyZu3VF .node .label,#mermaid-svg-X9CVcfcLtWyZu3VF .image-shape .label,#mermaid-svg-X9CVcfcLtWyZu3VF .icon-shape .label{text-align:center;}#mermaid-svg-X9CVcfcLtWyZu3VF .node.clickable{cursor:pointer;}#mermaid-svg-X9CVcfcLtWyZu3VF .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-X9CVcfcLtWyZu3VF .arrowheadPath{fill:#333333;}#mermaid-svg-X9CVcfcLtWyZu3VF .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-X9CVcfcLtWyZu3VF .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-X9CVcfcLtWyZu3VF .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-X9CVcfcLtWyZu3VF .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-X9CVcfcLtWyZu3VF .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-X9CVcfcLtWyZu3VF .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-X9CVcfcLtWyZu3VF .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-X9CVcfcLtWyZu3VF .cluster text{fill:#333;}#mermaid-svg-X9CVcfcLtWyZu3VF .cluster span{color:#333;}#mermaid-svg-X9CVcfcLtWyZu3VF div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-X9CVcfcLtWyZu3VF .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-X9CVcfcLtWyZu3VF rect.text{fill:none;stroke-width:0;}#mermaid-svg-X9CVcfcLtWyZu3VF .icon-shape,#mermaid-svg-X9CVcfcLtWyZu3VF .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-X9CVcfcLtWyZu3VF .icon-shape p,#mermaid-svg-X9CVcfcLtWyZu3VF .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-X9CVcfcLtWyZu3VF .icon-shape .label rect,#mermaid-svg-X9CVcfcLtWyZu3VF .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-X9CVcfcLtWyZu3VF .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-X9CVcfcLtWyZu3VF .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-X9CVcfcLtWyZu3VF :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 用户
FastAPI + Auth
Agent Orchestrator
Router
RAG Tool
Ticket Read Tool
Ticket Draft Tool
Policy / Approval
PostgreSQL State
Memory Store
Model Gateway
Trace + Eval

27.3 实现阶段

阶段 1：确定性基础
  1. 定义 API 和用户身份。
  2. 实现知识检索、工单查询和草稿工具。
  3. 添加 Pydantic Schema。
  4. 工具单元测试。
阶段 2：单 Agent
  1. 编写系统指令。
  2. 接入 tool calling。
  3. 加最大步骤、超时和错误处理。
  4. 保存完整 Trace。
阶段 3：状态与审批
  1. 持久化 Task。
  2. 写工具加入幂等 key。
  3. 高风险调用进入 waiting approval。
  4. 参数 hash 绑定审批。
阶段 4：RAG 和记忆
  1. 文档分块和索引。
  2. 权限 metadata filter。
  3. 引用校验。
  4. 只保存用户明确确认的偏好。
阶段 5：评测和上线
  1. 建立 100-500 条核心评测集。
  2. 安全红队用例。
  3. P95 延迟和费用压测。
  4. 灰度发布。
  5. 人工抽检和回滚机制。

27.4 验收标准

模块 验收条件
RAG 引用可打开，答案由证据支持
工具 参数严格校验，越权请求被拒绝
状态 重启后任务可恢复
审批 未批准不执行，参数变化后审批失效
安全 注入内容不能调用高权限工具
可靠性 工具超时可控，不无限循环
评测 核心任务 success rate 达到目标
运维 Trace、费用、延迟和错误可查询

27.5 实验记录模板

text 复制代码 
实验版本：
模型和版本：
Prompt 版本：
工具 Schema 版本：
知识库版本：
评测集版本：
任务成功率：
工具选择准确率：
参数有效率：
安全通过率：
平均/P95 步数：
平均/P95 延迟：
平均任务 Token/费用：
失败类型分布：
主要改动与结论：

28. 常见问题排查

28.1 Agent 不调用工具，直接编答案

  • 工具描述不清楚。
  • 系统指令没有要求实时事实必须查工具。
  • 工具名称与用户概念不一致。
  • 模型工具调用能力不足。
  • 上下文中已有错误答案诱导模型。

先用简单用例单独测试工具选择，再调整描述和路由。

28.2 Agent 反复调用同一工具

  • 工具返回结果不完整。
  • 错误信息没有明确 retryable。
  • 模型看不到上一次调用参数。
  • 没有最大步数和重复检测。
  • 工具成功但没有稳定 ID。

28.3 工具参数经常不合法

  • Schema 太复杂。
  • 字段说明含糊。
  • 一个工具承担过多任务。
  • 枚举和范围没有声明。
  • 模型不支持严格结构化输出。

拆小工具，并用 Pydantic 在执行前校验，把结构化错误返回模型一次修正机会。

28.4 RAG 答案有引用但内容不匹配

  • 检索块只关键词相似。
  • 没有 reranker。
  • 模型生成后随意选择引用。
  • 父块过长。
  • 引用校验只检查 ID 存在。

应验证结论是否能从引用片段推出，并单独评估检索质量。

28.5 长会话后忘记重要信息

  • 上下文被截断。
  • 摘要遗漏结构化字段。
  • 记忆检索相关性不足。
  • 新旧事实冲突。

关键业务状态放数据库，不依赖自然语言聊天历史。

28.6 Agent 执行了重复写操作

  • 客户端重试。
  • 模型重复调用。
  • 工具超时后状态未知。
  • 没有 idempotency key。

写工具必须幂等；超时后先查询状态再决定是否重试。

28.7 延迟过高

  • 模型调用轮数过多。
  • 每次都传完整会话。
  • 独立工具串行执行。
  • RAG top-k 过大。
  • 评审循环没有上限。

用 Trace 找出慢 Span，再决定并行、压缩、缓存或换小模型。

28.8 成本突然上升

  • 循环或重试异常。
  • Prompt/工具结果变长。
  • 流量增加或被滥用。
  • 路由器把简单请求都送大模型。
  • 缓存失效。

设置用户、任务和全局预算告警及硬限制。

28.9 多智能体互相讨论不结束

  • 没有 Supervisor 的停止条件。
  • 角色职责重叠。
  • 消息没有结构化完成状态。
  • 每个 Agent 都能重新分配任务。

限制通信拓扑、轮数和预算，定义唯一任务 owner。

28.10 Prompt injection 绕过规则

  • 把网页内容和系统指令混在一起。
  • 高权限工具直接暴露。
  • 只靠提示词防护。
  • 工具后端不做授权。

需要内容分区、最小权限、后端授权、审批和沙箱共同防护。

28.11 本地测试正常，线上不稳定

  • 线上输入分布更复杂。
  • 第三方工具延迟和错误。
  • 模型版本变化。
  • 并发竞争和状态一致性问题。
  • Prompt、工具和知识库版本没有锁定。

建立版本记录、线上 Trace、回归评测和灰度发布。

29. 面试常问问题

29.1 基础概念

Q1：什么是 AI Agent？

AI Agent 是由模型驱动、围绕目标循环感知上下文、选择动作、调用工具并维护状态的软件系统。完整 Agent 还包含控制循环、权限、错误处理、记忆、评测和可观测性。

Q2：Agent 和普通聊天机器人有什么区别？

聊天机器人主要生成文本；Agent 可以根据目标动态调用外部工具、观察结果、继续决策并产生真实系统动作。

Q3：Agent 和 Workflow 有什么区别？

Workflow 的路径主要由开发者预定义，Agent 的部分路径由模型运行时决定。生产系统常采用"确定性工作流骨架 + 局部 Agent 决策"。

Q4：Agent 和 RAG 有什么区别？

RAG 是检索增强生成模式；Agent 是更广的执行系统，可以决定是否检索、选择数据源、多轮检索，也可以调用其他工具。

Q5：Agent 的核心组件有哪些？

Model、Instructions、Context、State、Memory、Tools、Control Loop、Guardrails，以及生产所需的持久化、审批、日志和评测。

Q6：什么是 ReAct？

ReAct 是让模型交替进行推理和行动的范式。生产实现通常用结构化工具调用表达 Action，用工具结果表达 Observation，而不是解析自由文本标签。

Q7：什么时候不应该使用 Agent？

流程固定、规则明确、一次 API 可完成、要求完全确定性，或风险无法隔离时，应优先使用普通代码和工作流。

29.2 工具与结构化输出

Q8：如何设计一个好工具？

单一职责、名称明确、参数 Schema 严格、结果结构统一，并具备超时、权限、幂等性、错误码和审计。

Q9：为什么模型生成的工具参数必须再次校验？

模型输出是不可信输入，可能缺字段、类型错误、越界或被注入。Schema 只是提示模型，后端必须独立校验和授权。

Q10：Function Calling 是否保证模型一定调用正确工具？

不保证。它提高结构化程度，但工具选择、参数语义和调用时机仍可能错误，需要评测、路由、校验和错误处理。

Q11：工具结果应该返回自然语言还是 JSON？

优先返回稳定结构化 JSON，包含 ok/data/error/metadata。自然语言可作为附加说明，但关键状态和 ID 应结构化。

Q12：为什么写工具需要幂等性？

Agent、网络或客户端可能重试。没有 idempotency key，退款、发信和创建工单等操作可能重复执行。

Q13：工具失败后如何决定是否重试？

根据错误类型和操作幂等性。超时、429、部分 5xx 可有限退避重试；参数错误和权限错误不应盲目重试；写操作状态未知时先查询状态。

29.3 状态、记忆与 RAG

Q14：Context、State 和 Memory 有什么区别？

Context 是一次模型调用看到的信息；State 是当前任务的持久进度；Memory 是跨轮或跨任务保存的长期信息。

Q15：短期记忆和长期记忆有什么区别？

短期记忆服务当前会话，如最近消息和当前实体；长期记忆保存稳定偏好、确认事实和历史经验，需要权限、过期和删除策略。

Q16：为什么不能把所有聊天都写入长期记忆？

会积累噪声、推测、过期信息和敏感数据，增加隐私风险和上下文污染。应只保存稳定、确认且未来有用的内容。

Q17：什么是 Agentic RAG？

Agent 动态决定是否检索、改写查询、选择来源、执行多轮检索并判断证据是否足够，而不是固定一次 Top-k 后生成。

Q18：如何评估 RAG？

分别评估检索 Recall@k、MRR、nDCG，以及答案 groundedness、引用正确率、完整性和拒答能力。

Q19：向量检索和 BM25 如何选择？

向量检索适合语义相似；BM25 适合精确术语、ID、错误码和代码符号。生产系统常做 hybrid retrieval，再用 reranker 排序。

Q20：如何处理记忆冲突？

保存值、来源、可信度和更新时间；优先使用最新且高可信事实，重要冲突请求用户确认，并保留审计记录。

29.4 规划和多智能体

Q21：Plan-and-Execute 是什么？

Planner 先分解任务，Executor 执行步骤，Evaluator 验证结果，必要时 Replanner 更新剩余计划。适合多步骤和依赖复杂任务。

Q22：Reflection 有什么优缺点？

它可发现遗漏和格式问题，但增加成本和延迟，也可能把正确答案改坏。应基于明确 rubric、限制次数，并优先使用确定性验证。

Q23：什么时候使用多智能体？

当角色有不同权限、工具和上下文，或可并行独立执行时。若只是职责名称不同但共享同一任务，多智能体通常增加复杂度而无收益。

Q24：Supervisor 模式有什么风险？

Supervisor 可能成为瓶颈、错误单点和权限汇聚点。应限制它的工具权限，使用结构化任务契约，并设置预算和停止条件。

Q25：Agent 之间如何通信？

使用包含 task id、状态、事实、来源、错误和未决问题的结构化消息，而不是不可验证的自由文本。

29.5 安全与可靠性

Q26：什么是 Prompt Injection？

攻击者在用户输入或外部内容中嵌入指令，诱导模型忽略规则、泄露数据或调用工具。外部数据不能被当成高优先级指令。

Q27：如何防御 Prompt Injection？

内容与指令分区、最小权限、工具后端授权、参数校验、网络和文件隔离、秘密不进上下文，以及高风险操作审批。不存在只靠一句提示词的完整防御。

Q28：为什么 Prompt 不能作为权限系统？

模型遵循指令是概率行为，可能被冲突上下文和攻击影响。权限必须由确定性认证、授权和工具后端强制执行。

Q29：如何设计 Human-in-the-loop？

在高风险或低置信节点暂停，展示动作、目标、关键参数、影响和来源；审批绑定参数 hash，参数变化后重新审批。

Q30：如何避免 Agent 无限循环？

设置最大步骤、工具次数、Token、费用和超时；检测相同工具参数重复、状态无变化和错误重复；超限时返回部分结果或转人工。

Q31：如何处理模型或工具不可用？

有限重试、模型 fallback、只读降级、缓存结果、异步恢复或转人工。副作用操作必须先确认是否已经执行。

Q32：怎样保证多租户数据隔离？

身份来自认证上下文，数据库查询强制 tenant filter，缓存键包含租户，向量检索做 metadata ACL，工具使用租户范围凭证，并进行跨租户安全测试。

29.6 评测与生产化

Q33：如何评测一个 Agent？

从任务成功、工具选择、参数正确、证据支持、安全、步骤效率、成本和延迟多维评估，并同时检查最终结果和执行轨迹。

Q34：LLM-as-a-Judge 有什么问题？

评审模型可能有位置偏差、风格偏好和自我偏好。应使用明确 rubric、随机候选顺序、人工校准，并让确定性规则检查安全和格式。

Q35：Agent 可观测性应该记录什么？

任务 Trace、模型调用、工具调用、延迟、Token、费用、重试、错误、状态变更和审批。日志需要脱敏和访问控制。

Q36：如何降低 Agent 延迟？

减少模型轮次和上下文、并行独立工具、用小模型路由、缓存检索、流式输出，并把长任务放到异步 Worker。

Q37：如何降低成本？

模型分级路由、预算限制、上下文压缩、语义缓存、减少反思、批量 embedding，并用规则处理确定性任务。

Q38：如何让长任务可恢复？

把状态和每步结果 checkpoint 到持久化存储，使用队列和 Worker，工具调用幂等，并支持暂停、恢复、取消和审批事件。

Q39：模型升级前应该做什么？

在固定评测集上比较任务成功、安全、工具轨迹、延迟和成本；灰度发布并记录模型、Prompt、工具和知识库版本，支持快速回滚。

Q40：如何回答"设计一个企业客服 Agent"？

回答顺序：

text 复制代码 
1. 明确任务范围、用户身份和成功指标。
2. 采用确定性路由和 Agent 局部决策。
3. 知识问题走带 ACL 和引用的 RAG。
4. 订单查询使用只读工具，退款先生成草稿。
5. 后端强制权限、金额规则、幂等和审批。
6. 状态持久化，长任务异步执行。
7. 记录 Trace、费用和错误。
8. 建立正常、失败、注入和跨用户评测集。
9. 灰度上线并保留转人工和回滚能力。

29.7 一分钟项目介绍模板

text 复制代码 
我实现的是一个状态化的企业 Agent。模型只负责意图理解、工具选择和结果汇总，
实际权限、参数校验、幂等和审批由工具网关强制执行。知识问答使用带租户 ACL、
混合检索和引用校验的 RAG；业务写操作先生成预览，高风险参数绑定审批后执行。
任务状态持久化到数据库，长任务由队列和 Worker 执行，可以暂停、恢复和取消。
评测不仅看最终答案，还检查工具轨迹、参数、安全、延迟和单任务成本，并通过
固定回归集和灰度发布控制模型或 Prompt 升级风险。

30. 进阶练习

练习 1：可靠工具循环

为最小 Agent 加入 Pydantic 校验、超时、重试、重复调用检测和最大费用预算。

练习 2：混合检索

实现 BM25 + 向量检索 + metadata filter + reranker，并比较 Recall@5 和引用正确率。

练习 3：Prompt injection 红队

构造网页、邮件和文档中的间接注入，验证 Agent 不会泄露秘密或调用高权限工具。

练习 4：长任务恢复

让任务执行到第三步后强制终止进程，再从数据库 checkpoint 恢复，确保写操作不重复。

练习 5：模型路由

用小模型进行意图分类和字段提取，复杂推理才使用大模型，比较质量、P95 延迟和费用。

练习 6：Human-in-the-loop

实现审批创建、拒绝、过期和参数 hash 校验，并为并发审批编写测试。

练习 7：多智能体消融

用单 Agent 与 Supervisor + 两个专用 Agent 完成同一任务，比较成功率、模型调用数、延迟和调试复杂度。

练习 8：线上反馈闭环

将用户纠错、转人工和失败 Trace 自动进入待标注池，经过人工审核后加入离线评测集。

31. 参考资料

相关本地资料：

  • Transformers_学习.md：Transformer 和 Hugging Face 基础。
  • BERT_学习.md：Embedding、文本编码与微调。
  • PyTorch_学习教程.md：深度学习和模型开发基础。
  • Redis_学习.md：Agent 缓存、会话和任务状态。
  • Kafka_学习.md：长任务、事件驱动和异步消息。
  • WebSocket_学习_Java_Python.md：Agent 进度流式推送。
  • Docker_学习.md：Agent 服务打包与隔离部署。

总结

text 复制代码 
可靠 AI Agent 的关键不是让模型"更自由"，而是把自由限制在清晰边界内：

模型负责理解和有限决策；
工作流负责状态和停止条件；
工具负责真实动作；
后端负责权限、幂等和业务规则；
审批负责高风险决策；
评测和 Trace 负责持续验证。

从工程角度看，优秀 Agent 往往不是最复杂、调用模型次数最多的系统，而是能在正确时机使用模型，在其他地方坚持确定性软件设计的系统。

相关推荐
糖果店的幽灵1 小时前
【langgraph 从入门到精通graphApi 篇】综合实战 —— 智能客服 Agent实战代码解读
人工智能·langgraph
TsingtaoAI1 小时前
3D高斯泼溅技术发展及其在具身智能领域的应用综述
人工智能·算法·ai·具身智能·高斯泼溅
神奇小汤圆1 小时前
面试官：Agent意图识别怎么做？95%的人一句话就把自己送走了
人工智能
兜客互动1 小时前
2026年AI关键词拓展挖掘软件，高效助力内容创作精准获流
人工智能·python
AI的探索之旅1 小时前
AI辅助原理图评审：电源去耦、BOOT引脚、VCAP——19项逐一核查，遗漏？不存在的
人工智能·vscode·嵌入式硬件
茯苓gao1 小时前
嵌入式开发笔记：EtherCAT协议从硬件到软件完整配置指南——从零搭建一套EtherCAT通信系统
笔记·嵌入式硬件·学习
武子康2 小时前
Kimi K3 2.8T：开放权重不等于本地可跑 超稀疏 MoE、百万上下文与真实部署边界
人工智能
老刘说AI2 小时前
AI服务核心： 高并发原理与性能监控调优
人工智能·神经网络·langchain·llama·持续部署
GeekArch2 小时前
第24讲：Vibe模式代码风格控制——适配Keil/STM32工程规范
人工智能·stm32·单片机·嵌入式硬件·mcu·决策树·ai编程
热门推荐
012026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片02GitHub 镜像站点03如何新建文件夹？ 电脑新建文件夹的4种方法04AI科技热点日报 | 2026年07月01日05幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南06国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路092026 年 AI 大模型 & AI 编程工具实战全总结10Kimi K3 真实体验：全网评价整理，优缺点一次性说清楚