Agent 开发

Agent Loop · 上下文管理 · 工具调用 · AI 巡检落地

名词速查

首次阅读可跳过本表，直接看「场景问题」，遇到生词再回查。

本篇是Agent 范式与协议这一组名词的归属页——"Agent 有哪些搭法、它怎么调工具"这一组词在这里展开。运行时实现、多 Agent 协作、评测口径三组词归各自的深潜篇（见文末引用表）。

作为枢纽页，这张表刻意只收本篇自有名词，不把六篇深潜的词全列一遍——那些词走上面的枢纽导航表抵达更清楚。

本篇引用的其他上下文名词

本篇是枢纽，只给一句话定位与去处；这些词的完整解释（含类比与失效边界）在各自归属页：

场景问题

Agent 的最小闭环：Perception → Plan → Act → Reflect

         ┌────────────────────────────┐
         │  Prompt / Task / Context   │
         └──────────────┬─────────────┘
                        │
              ┌─────────▼─────────┐
              │   Reasoner (LLM)  │
              └─────┬───────┬─────┘
            plan?  │       │  need info?
              ┌────▼─┐   ┌─▼──────┐
              │ Act  │   │ Query  │
              │ Tool │   │ Memory │
              └───┬──┘   └───┬────┘
                  │          │
              ┌───▼──────────▼───┐
              │   Observation    │
              └─────────┬────────┘
                        │
              ┌─────────▼─────────┐
              │   Reflect / Loop  │
              └───────────────────┘

主流 Agent 架构范式

CodeAct vs Function Calling 的取舍：CodeAct 表达力强得多——一次输出就能表达"遍历这 20 个文件、对每个满足条件的调用 X"，用 tool call 要 20+ 轮。代价是必须有真沙箱（执行任意代码的攻击面远大于执行受限的 tool call），且失败模式从"参数错"变成"代码跑一半出错、副作用已部分发生"。判据：工具调用之间有复杂控制流 → CodeAct 划算；调用少且需要严格审计每一步 → Function Calling。

PlanAct 的价值在计划这个产物本身：计划落盘之后可以被人审、被复用、被 diff。它适合"执行有代价或不可逆"的场景（先让人批准计划再执行），而 ReAct 的隐式计划藏在推理里，没法审也没法复用。

Multi-Agent：五种拓扑与冲突消解（结论）

Multi-Agent 不是一种范式而是一个维度，它自己有五种拓扑。这里只给选型定位——各自什么时候该用、代价多大；「谁跟谁说话」这类机制定义与规模上限，见 Multi-Agent 系统 · 五种协作拓扑：

• Supervisor / 中心调度：默认选项。拆得出边界、收得回验收的活都用它，最常用，token O(N)。
• Pipeline / 流水线：工序顺序写死、每道工序交付什么很明确时首选，同为 O(N)。
• Group Chat / 群聊：只在「互相质疑」这件事本身值回票价时才用（方案评审、红蓝对抗），token O(N²)，最贵。
• Blackboard / 黑板：长任务、要共享大量结构化状态时用，状态区必须带版本号。
• Contract Net / 市场竞标：默认不用。竞标要 Agent 自报擅长什么，而这个自报拿不到客观校验。

结果不一致怎么处理（一句话结论）：先分类（事实 / 口径 / 时序 / 幻觉），再走四级有序阶梯——证据优先 → 置信度加权 → 第三方仲裁 Agent → 人工闸门，每级有明确进入判据。不用多数投票——两条独立的原因各自都足以否掉它，展开见深潜篇。还有一条时机要求：裁决要在主 Agent 装配上下文之前跑完，进它窗口的只能是裁决结果，不能是两份互斥的原始结论。

五种拓扑的规模上限与失效模式、三层通信机制（消息传递 / 黑板 / Handoff）、裁决阶梯每级的判据与代码骨架、MAS 五种特有失效、以及何时不该上 MAS 的三条否决判据——全部在 Multi-Agent 系统 展开，本页不重复。

实现方案

Tool Use / Function Calling

协议本质：LLM 输出结构化 JSON 声明"我要调用哪个工具、参数是什么"，Runtime 执行、把结果作为 tool_result 塞回上下文，模型继续推理。

• OpenAI: tool_calls（曾用 function_call）
• Anthropic: tool_use / tool_result 内容块
• Gemini: function_calls
• MCP (Model Context Protocol): 跨模型统一的工具协议，2024 起大厂共建

关键设计（工具四原则）：

• 工具幂等（同参多次调用结果相同）
• 工具参数校验 + 错误消息友好（模型能读懂错误自我修正）
• 工具返回大小截断（避免打爆 context）
• 工具副作用可回滚（危险操作前二次确认）

四原则之上，生产还需要危险动作三级分级（只读 / 可写可回滚 / 不可逆走人工闸门）、执行侧隔离（独立进程、硬超时、资源上限）、凭据句柄化（模型只见 conn 名，不见 DSN）。为什么白名单不够、为什么不能让模型自己判断危险 —— 见 运行时 · 工具沙箱与权限隔离。

打个比方：Agent Loop 就像新员工带 SOP 手册干活——每一步先想（Thought/Plan：这题是什么、下一步该干啥）、再翻手册决定用哪个工具（Act：调 search/db/write，参数按 schema 填）、看到结果再决定下一步（Observation → Reflect），旁边还有个 Planner 导师盯着别跑偏。工具幂等、参数校验、返回截断，就是 SOP 里写清"这个动作能重做几次、参数怎么填、别一次性把仓库搬回来"。类比失效边界：现实里新员工卡壳会举手问导师，Agent 卡壳却会幻觉出一个不存在的工具或参数名——它宁可编造一个 API 也不会说"我不会"；一旦幻觉调用被执行，可能出现无限循环、无效副作用或权限越界。所以生产 Agent 必须靠外部兜底：JSON Schema 强约束参数、工具白名单硬拦不存在的工具、同调用去重 + 最大轮数熔断 + token/时长/费用三重预算——不能指望它自觉停下。

上下文窗口管理：滑动窗口 + 压缩水位

问题：一个复杂任务的对话历史 + 工具输出，很快就撑爆 200k context。

四种主流做法（可组合使用）：

1. 朴素滑动窗口：只保留最近 N 轮 → 简单，但丢关键事实
2. 摘要压缩 (Summary)：把旧对话周期性压成摘要塞回 system prompt → 关键但对细节不友好
3. 语义分层 (Hierarchical Memory)：
   • 短期记忆：最近 N 轮原文
   • 工作记忆：本任务的摘要 + 关键事实（KV 抽取）
   • 长期记忆：向量库（历史相似任务）
4. 工具输出截断 + 惰性回读：工具结果先只返摘要 + 存全文到磁盘，模型需要时再 read_full(id)

关键事实抽取（AI 巡检系统落地经验）：

• 每 K 步做一次"pinning"——让模型自己列出必须记住的关键事实
• 关键事实以 key: value 格式压入 system prompt
• 滑动窗口只对"过程日志"生效，不动关键事实

下图：短期记忆是一个滑动窗口（紫框右移，划出窗外的旧对话被丢弃/压缩），但被 pin 的关键事实（绿色 📌）永不滑走；窗外内容沉淀进中期摘要，更久远的进长期向量库。

Prompt Engineering 的核心杠杆

• System prompt 定角色、能力边界、输出格式
• Few-shot 只给 3~5 个高质量示例，覆盖典型/边界/失败三类
• CoT (Chain-of-Thought)：思考链，先想再答
• Self-consistency：多次采样投票
• Structured output：JSON Schema / XML tag 强约束
• XML 分块 (Anthropic 推荐)：<task>、<context>、<examples>——模型解析更稳

为什么这么做

AI 巡检系统的滑动窗口设计（自研经验）

场景：巡检系统持续观察线上服务的日志 / 指标 / 告警，用 Agent 判断是否需要人工介入。

设计要点：

• 窗口分层：
  • Layer-1（10 分钟）：原始告警 & 核心指标，全量入 prompt
  • Layer-2（1 小时）：LLM 摘要 + 关键事实（服务名、错误码、责任团队）
  • Layer-3（1 天）：向量化历史事件用于相似性回溯
• 语义分析压缩：每 5 分钟触发一次压缩——summarize + extract_facts；产出 {time, service, symptom, root_cause_hypothesis, action}
• 失效恢复：Agent 每步都要写 current_focus 到独立 memory；崩溃后 replay 用 current_focus + Layer-2 摘要 快速恢复
• 护栏：涉及重启/回滚的动作必须走审批工具，不能自行执行

这三个时间参数为什么是 10 分钟 / 1 小时 / 1 天（跟着告警风暴聚集、值班升级决策、周期性对比三个业务判断周期走），以及巡检在游戏研发周期里的位置——见 AI 与游戏研发周期 · AI 巡检 Agent。

失败恢复三板斧

• 重试：工具超时/网络抖动，指数退避 + jitter
• 幂等：所有写操作用 idempotency_key；即使模型重试也不重复扣款/发货
• 护栏 (Guardrails)：白名单工具集、参数域约束、危险操作 human-in-the-loop、tokens/时长/费用三重预算

幂等键为什么必须带 task_id（只用参数指纹会让同玩家两次合法补偿撞成一个指纹 → 漏发）、三重预算的计量点在哪、熔断后为什么要优雅收尾返回部分结果 + resume_token 而不是抛异常 —— 见 运行时 · 并发、预算与幂等。

Agent 的评测方法

四种手段，各管一段：

• Golden Set（黄金集）：人工构造 100~500 个典型任务，跑回归、看成功率、步数、成本 —— 发布闸门
• 红队测试：对抗性 prompt / 恶意输入 / 边界数据；检查是否越权、是否 leak 敏感信息 —— 安全侧，详见 LLM 应用安全
• 离线回放：录制真实用户轨迹，改 prompt/模型后回放对比 —— 改动影响面评估
• A/B 影子流量：新 Agent 与旧 Agent 并跑，只对比不生效 —— 上线前最后一道

成功率怎么定义才不骗人（分母必须是全样本、超时与熔断要单独归桶）、轨迹为什么不能比参考路径相似度（合法路径不唯一，改判关键步里程碑）、span 树怎么埋、灰度回滚该看人工接管率而非成功率 —— 全部在 Agent 评测与线上运营 展开。

为什么别的选择不行

Agent 系统的十大真实坑

清单全列（这是本页的记忆锚点），每条的根因与修法细节在末列的深潜篇：

上下文压缩的边界事故

• 摘要漂移：多轮摘要后，关键约束（"用 Python 3.10"）在压缩过程丢失
• 滑动窗口误删指令：user 早期给的"必须遵守 XX"被踢出去后模型开始违反
• 向量检索误召：语义相近但事实相反的历史被错误召回，模型采用了

三种事故的共同点是都不会报错（只表现为"Agent 变笨了"），所以必须靠主动断言发现——检测手段与兜底见 运行时 · 三种失效。

主流 Agent 框架对比

沉淀结论

面试常见问题清单（按主题分类）

闭环与架构

• Q：Agent 的最小闭环是什么？ A：Perception → Plan → Act → Reflect 循环，模型自主决定下一步、观察结果再迭代。
• Q：ReAct 和 Plan-and-Execute 区别？ A：ReAct 每步现想现做（Thought→Action→Observation）；Plan-and-Execute 先出完整计划再逐步执行、中途可 replan，适合长任务。

工具调用

• Q：Function Calling 的协议本质？ A：LLM 输出结构化 JSON 声明"调哪个工具、参数是什么"，Runtime 执行后把 tool_result 塞回上下文继续推理；MCP 是跨模型统一的工具协议。
• Q：工具设计四原则？ A：幂等（同参多次结果一致）、参数校验 + 友好错误（模型能自我修正）、返回截断（别打爆 context）、副作用可回滚（危险操作二次确认）。

上下文与记忆

• Q：对话历史撑爆 200k context 怎么办？ A：分层记忆——短期留最近 N 轮原文、中期压成摘要 + pin 关键事实、长期进向量库；工具输出先返摘要、需要时再回读全文。
• Q：滑动窗口/摘要压缩的典型事故？ A：摘要漂移丢关键约束、滑窗误删早期指令、向量误召语义相近但事实相反的历史——所以关键事实要 pin 住不参与滑动。

可靠性与评测

• Q：Agent 生产化最容易坏在哪？ A：无限循环（同调用去重 + 最大轮数熔断）、工具输出爆炸（分页/摘要）、参数幻觉（JSON Schema 强校验）、成本失控（token 预算 + 熔断）、副作用不可控（白名单 + human-in-the-loop）。
• Q：Agent 怎么评测？ A：Golden Set 回归（成功率/步数/成本）+ 红队对抗测试 + 离线回放 + A/B 影子流量；Demo 跑通只是 20%，评测和护栏是剩下 80%。

记忆口诀

• 六件套：Prompt / Tools / Memory / Loop / Guardrails / Evaluation
• 最小闭环：Perception → Plan → Act → Reflect
• 工具四原则：幂等 / 校验+友好错误 / 返回截断 / 副作用可回滚
• 分层记忆：短期原文 / 中期摘要+pin关键事实 / 长期向量库
• 生产铁律：Demo 20% / 评测护栏 80% / 熔断+预算+白名单+Trace

内容来源

迁移自 guide/theme-agent-dev（综合整理）

综合整理：Anthropic / OpenAI / LangChain 官方文档、AI 巡检自研经验（2026-07；生态更新快，请以官方文档为准）

自测：合上资料能说清楚吗？

1. Agent 的最小闭环由哪四步构成？它和一次普通的 LLM 调用最大的区别在哪？

2. 工具（Tool Use）设计的四条原则是什么？分别防的是什么坑？

3. 对话历史撑爆 200k context，分层记忆是怎么解决的？关键事实为什么要单独 pin？

4. 对比 ReAct 和 Plan-and-Execute：各自思路、适用场景与短板？

5. 为什么说"Demo 跑通只是 20%"？生产化最容易坏在哪几处，各配什么护栏？