知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# 优秀 Agent 架构的核心原则 > 导读:本文从"为什么很多 Agent 在 Demo 里惊艳、一上生产就崩"这个具体痛点出发,把优秀 Agent 架构的五条核心原则、四种主流架构模式、以及"什么场景选什么架构"的决策依据讲透,最后给出工程实践与踩坑。适合正在把 LLM(Large Language Model,大语言模型)应用从原型推向生产、或正在准备 Agent 架构相关面试的同学。  *图:Agent 的分层架构——接口、编排、工具、记忆与模型* ## 一、先建立全局认知 ### Q:Agent 项目失败,最常见的根因是什么? A:结论先行——绝大多数失败跟"模型不够聪明"无关,而是架构没有提前把五类确定性的工程问题接住:工具选择失焦、上下文失忆、单点错误放大、控制流失控、线上不可观测。把这五类问题翻译成工程语言,就是工具设计、上下文管理、容错设计、控制流设计、可观测性这五个模块。 原文归纳的失败原因排行(按出现频率归纳,非严格统计)如下:  *图:Agent 失败原因排行:五种现象对应五类根因* ```text 失败原因排行: 1. 工具太多,LLM 选不准 → 工具设计问题 2. 上下文越来越长,LLM 开始"忘事" → 上下文管理问题 3. 一个步骤出错,整个任务崩溃 → 容错设计问题 4. 无限循环或跑偏,停不下来 → 控制流问题 5. 生产环境出问题,不知道哪里错了 → 可观测性问题 ``` 关键点解读:这张清单最大的价值是给出了"排查顺序"。线上 Agent 出问题,先看工具是否过多导致选错,再看上下文是否被塞爆,然后看错误是否被放大,再确认控制流是否有边界。可观测性必须第一天就建,否则前面四步你根本看不到。所谓"好架构",本质就是提前把这些坑填上。 这里先明确一个术语:Agent(智能体)指由 LLM 做决策、可以调用工具、多步迭代直至完成目标的程序。它与"单次问答"最大的区别是——它有循环、有外部副作用、有中间状态,所以很多在纯 Prompt 场景下不存在的问题,在 Agent 场景下会集中爆发。 ### Q:这五类问题分别对应哪五条架构原则? A:结论先行——一对一映射:工具选不准对应"最小化 LLM 决策负担";上下文失忆对应"状态显式化";单点错误放大对应"失败是常态、设计要容错";控制流失控对应"控制流要可预测";线上黑盒对应"可观测性优先"。 | 失败现象 | 根因 | 对应原则 | 主要手段 | |---|---|---|---| | 工具选错、参数传错 | 单次决策选项过多 | 最小化 LLM 决策负担 | 工具分层、动态加载、描述精简 | | 忘记约束、重复劳动 | 关键信息只活在对话历史里 | 状态显式化 | 结构化状态对象、中间结果外置 | | 一步失败全盘失败 | 没有重试/降级/恢复 | 失败是常态,容错设计 | 重试、检查点、幂等、降级 | | 死循环、跑偏、停不下来 | 终止条件交给 LLM 自由决定 | 控制流要可预测 | 工具白名单、迭代上限、超时 | | 线上无法定位 | 决策过程不透明、无记录 | 可观测性优先 | 追踪、结构化日志、指标、告警 | 关键点解读:这五条不是"五选一",而是一个整体。可以先落地前三、四条(收益最大、改造成本最低),但可观测性必须同步开始,否则后面所有优化都无法度量。 ### Q:这里说的"架构"到底指什么?选个好框架是不是就够了? A:结论先行——不是。架构指的是"确定性代码与 LLM 之间的职责边界怎么划":哪些事必须由代码保证(状态、重试、终止、权限),哪些事交给 LLM 自由决定(在约束范围内选路径)。框架只是实现手段,边界划错了,换任何框架都一样崩。 一句话记住这条分界线:**不要让 LLM 做它不擅长的事(记住所有状态、处理所有错误、判断什么时候停),把这些交给代码。** ### Q:是不是所有任务都值得做成 Agent? A:结论先行——不是。当任务步骤固定、分支明确、无需临场判断时,用普通代码或固定工作流(Workflow)比 Agent 更可靠、更便宜、更好调试。Agent 的价值只在"路径无法预先枚举"的场景里才能兑现。 ```text 适合做成 Agent: 路径不确定,需要根据中间结果决定下一步 需要调用多种外部工具并串联 自然语言输入输出,无法预先定义全部分支 更适合用固定工作流 / 普通代码: 步骤固定、顺序确定(ETL、报表生成) 规则明确、可穷举(审批流、状态流转) 对延迟和成本极敏感、且容错空间小 ``` 关键点解读:这是最容易被忽视的第一道架构取舍。Agent 引入了 LLM 的随机性与额外成本,如果任务本身是确定性的,你就等于"花钱买不确定性"。反过来,很多团队把本该 Agent 化的开放任务硬编码成 if/else 工作流,结果规则越堆越多、越改越脆。判据是"分支能否穷举",而不是"看起来高不高级"。 ### Q:一个 Agent 架构好不好,用什么指标衡量? A:结论先行——看四个维度:任务成功率、平均步骤数、单任务成本、失败可定位率。前三个衡量效果,第四个决定"能否持续优化"。 | 指标 | 含义 | 架构含义 | |---|---|---| | 任务成功率 | 端到端完成的占比 | 容错与边界设计是否到位 | | 平均步骤数 | 完成任务的迭代次数 | 决策负担是否过重、是否绕路 | | 单任务成本 | Token 与工具调用折算 | 上下文与工具体系是否臃肿 | | 失败可定位率 | 失败能被追踪还原的比例 | 可观测性是否真正落地 | 关键点解读:注意"平均步骤数"这个指标常被忽略。步骤数异常偏高,往往不是模型笨,而是状态没显式化导致重复劳动。指标之间要一起看:只盯成功率,会诱导你把重试次数拉得很大,结果成本飙升、延迟恶化。 ## 二、五条核心原则 ### Q:为什么"最小化 LLM 决策负担"要排在第一位? A:结论先行——因为 LLM 的决策质量随选项数量单调下降,工具越多,Prompt 越长、注意力越分散,选错工具和传错参数的概率越高。这是所有 Agent 问题的"上游",上游错了,下游的重试和容错只是在替它擦屁股。 原文给出的经验性观察(示意量级,非官方基准,务必以你自己的场景实测为准): ```text 工具数量 vs 选择准确率(经验性示意): 3 个工具 → 准确率约 95% 10 个工具 → 准确率约 80% 20 个工具 → 准确率约 60% 原因:LLM 需要在 Prompt 中理解所有工具的描述, 工具越多,上下文越长,注意力越分散。 ``` 三条落地手段: ```text 1. 工具分组:不要把所有工具一次性给 LLM → 根据任务类型动态加载相关工具 → 每次决策暴露的工具数量控制在 5~8 个 2. 工具描述精简:每个工具的描述控制在 2~3 句话 → 说清楚"做什么"和"什么时候用" → 不要写使用示例(浪费 Token) 3. 工具命名语义化:名字本身就能说明用途 ✗ tool_1, execute, process ✓ search_web, query_database, send_email ``` 关键点解读:注意"5~8 个工具"是经验区间,不是硬阈值。它的架构含义是——**把"选择空间的大小"当成一个可调的架构参数**,而不是把所有能力堆在一个 Agent 上就完事。替代方案是"多 Agent 分工",代价是通信开销和协调复杂度上升(后续文章会专门展开)。 ### Q:为什么状态必须显式化?丢失的到底是什么? A:结论先行——因为状态只活在 LLM 上下文里时,它既不可持久化、也不可从中间恢复,且上下文一长就会被截断。显式状态把"当前任务、已完成步骤、中间结果、待办事项"变成可读写的普通数据结构,从而获得三件事:可持久化、可从检查点恢复、可被程序断言和校验。 ```text 隐式状态(差): 所有信息都在对话历史里 LLM 自己"记住"当前进行到哪一步 → 上下文一长就容易出错 → 无法从中间恢复 显式状态(好): 用数据结构明确记录: 当前任务是什么 已完成了哪些步骤 中间结果是什么 还需要做什么 → 状态可以持久化 → 出错后可以从检查点恢复 ``` 下面是一个可直接借鉴的显式状态结构设计: ```python # 显式状态设计示例 from typing import TypedDict, List, Optional from enum import Enum class TaskStatus(Enum): PENDING = "pending" IN_PROGRESS = "in_progress" COMPLETED = "completed" FAILED = "failed" class AgentState(TypedDict): # 任务信息 task_id: str original_goal: str current_step: int # 执行状态 status: TaskStatus plan: List[str] # 任务计划 completed_steps: List[str] # 已完成的步骤 intermediate_results: dict # 中间结果 # 对话历史(控制长度) messages: List[dict] message_count: int # 错误信息 error_count: int last_error: Optional[str] ``` 关键点解读:这个结构把"任务事实"(original_goal / plan / completed_steps / intermediate_results)与"对话表现"(messages)彻底分开。前者是唯一事实源,后者只是可裁剪的展示层。架构取舍在于:显式状态要你提前定义字段,比"全塞进 messages"多写代码,但换来了断点续跑与可断言性——生产环境这笔交易几乎总是划算的。 ### Q:控制流怎样才算"可预测"? A:结论先行——把"可以做什么、什么时候停、出错怎么办"这三件事从 LLM 手里收回到代码里,只把"在约束内选哪条路径"留给 LLM。 ```text 完全自由(危险): LLM 决定一切:做什么、怎么做、什么时候停 → 容易跑偏,难以调试 结构化控制(安全): 开发者定义:可以做什么(工具白名单) 什么时候停(终止条件) 出错怎么办(错误处理) LLM 决定:在约束范围内选择最优路径 ```  *图:外层是确定性边界,内层是 LLM 的自由度* ```text 好的控制流设计——外层是确定的边界,内层是 LLM 的自由度: ┌─────────────────────────────────────────┐ │ 开发者控制的部分(确定性) │ │ ┌─────────────────────────────────┐ │ │ │ LLM 决策的部分(灵活性) │ │ │ │ 在这个范围内,LLM 可以自由选择 │ │ │ └─────────────────────────────────┘ │ │ │ │ 最大迭代次数:10 │ │ 超时时间:60s │ │ 允许的工具:[search, calculate, write] │ │ 禁止的操作:[delete, send_email] │ └─────────────────────────────────────────┘ ``` 关键点解读:这张图是本文最重要的一张图——**边界由代码给定,路径由 LLM 选择**。边界一旦缺失,LLM 就会用"看起来很合理"的方式继续跑,比如反复调用同一个工具、或者自己去"执行"一个并不存在的删除动作。注意这里的数字(10 次、60 秒)只是示意值,具体上限要按你的任务实测确定。  *图:Agent 控制流边界* ### Q:为什么说"失败是常态",容错必须设计在第一版里? A:结论先行——因为 LLM 调用与外部工具调用本身都有不可忽略的失败率,而多步任务的整体成功率是各步成功率的连乘,会随步骤数指数衰减。容错不是"以后再加",而是"不加就大概率跑不完"。 ```text 经验性失败率量级(示意,需以实际监控数据为准): LLM 调用失败率:约 1%(网络、限流、模型错误) 工具调用失败率:约 5%(API 超时、参数错误、权限问题) 10 步任务,每步 95% 成功率: 整体成功率 = 0.95^10 ≈ 60% 所以: 每个步骤都要有错误处理 关键步骤要有重试机制 整体任务要有降级方案 ``` 关键点解读:真正致命的不是"某一步失败",而是"失败没有分层处理"。把错误分成"可重试""可修复""致命"三类分别处理,比统一 try/except 有效得多(第 04 篇会给出完整实现)。架构取舍上,重试会放大对下游服务的压力,所以必须配合指数退避与上限。 ### Q:可观测性为什么强调"第一天就要建"? A:结论先行——因为 Agent 的问题极难复现,如果不从一开始就记录,你甚至连"这次失败时模型看到了什么"都还原不出来。可观测性不是运维收尾工作,它是调试 Agent 的唯一入口。 ```text Agent 的问题很难复现: LLM 的输出有随机性 工具调用依赖外部状态 多步骤的错误可能在很后面才暴露 所以从一开始就要记录: 每一步的输入和输出 工具调用的参数和结果 LLM 的思考过程(Thought) Token 消耗 每步的耗时 ``` 关键点解读:这些记录同时也是成本与性能优化的数据源。也就是说,可观测性投入一次,回报覆盖"调试 + 优化 + 告警"三条线。 ### Q:这五条原则分别有哪些替代方案?代价是什么? A:结论先行——每条原则都有一个"更省事但更脆"的替代方案;面试里能说清代价,比背出原则本身更有价值。 | 原则 | 备选做法 | 代价 / 边界 | |---|---|---| | 最小化决策负担 | 一次暴露全部工具 | 上手快,但选错率随工具数上升;仅适合工具少且语义不重叠 | | 状态显式化 | 用全量对话历史当状态 | 实现简单,但不可恢复、约束会失效;仅适合单轮短任务 | | 控制流可预测 | 完全让 LLM 决定终止 | 灵活,但易死循环;仅适合探索性、无副作用的场景 | | 容错设计 | 不做重试,失败即报错 | 简单,但多步任务成功率指数衰减;仅适合幂等且极短的任务 | | 可观测性优先 | 出问题再加日志 | 前期省事,但线上问题无法复现;几乎没有正当理由 | 关键点解读:把"代价"写清楚,才能真正做出取舍。例如"完全让 LLM 决定终止"在某些探索型任务里是合理的,因为副作用可控;但一旦涉及写操作,终止条件必须由代码兜底。**判据可以归纳为两个问题:有没有副作用?分支能否枚举?** ## 三、四种架构模式对比 ### Q:常见的 Agent 架构模式有哪几种?各自适合什么场景? A:结论先行——四种:简单循环、计划-执行、状态机、多 Agent 协作。它们不是递进替代关系,而是面向不同复杂度与可靠性要求的四档配置。 **模式一:简单循环(适合简单任务)**  *图:简单循环 Agent:模型与工具交替的单环结构* ```text 用户输入 → LLM 思考 → 工具调用 → 观察 → 循环 → 输出 优点:简单,快速上手 缺点:复杂任务容易失控,难以调试 适用:单一目标、步骤少(< 5 步)的任务 ``` **模式二:计划-执行(适合复杂任务)** ```text 用户输入 → 规划 Agent(生成计划)→ 执行 Agent(逐步执行)→ 输出 优点:有全局视角,步骤清晰 缺点:初始计划可能不准,需要动态调整 适用:多步骤、有明确子任务的复杂任务 ``` **模式三:状态机(适合生产环境)** ```text 用 LangGraph 等框架把 Agent 建模为状态机 每个状态有明确的转移条件 出错时可以回滚到上一个检查点 优点:可控、可调试、可恢复 缺点:设计复杂,需要提前想清楚所有状态 适用:生产环境、高可靠性要求的场景 ``` **模式四:多 Agent 协作(适合大型任务)** ```text Orchestrator(协调者)→ 分发任务给多个专家 Agent → 汇总结果 优点:并行执行,专业分工 缺点:通信开销大,协调复杂 适用:可以并行的大型任务 ``` 关键点解读:把这四种模式放一起对比,取舍就非常清楚: | 模式 | 核心代价 | 主要收益 | 典型适用 | |---|---|---|---| | 简单循环 | 无全局计划、易失控 | 实现成本最低 | 单一目标、< 5 步 | | 计划-执行 | 计划可能失真,要留重规划入口 | 全局视角、步骤清晰 | 多步骤、有子任务 | | 状态机 | 需提前穷举状态与转移 | 可控、可调试、可恢复 | 生产、高可靠 | | 多 Agent | 通信与协调开销大 | 并行、专业分工 | 可并行的大型任务 | 注意"计划-执行"和"状态机"经常组合使用:用状态机承载控制流,其中某个状态内部再跑一个小型计划-执行循环。这是生产里最常见的形态。 ## 四、架构选择与演进 ### Q:拿到一个具体任务,怎么决定用哪种架构? A:结论先行——用一个三层判断的决策树:先看复杂度,再看能否并行,最后看可靠性要求。  *图:三步判断:按复杂度、并行性、可靠性选架构* ```text 任务复杂度? 简单(1~3 步)→ 简单循环 复杂(> 5 步)→ 继续判断 任务是否可以并行? 可以 → 多 Agent 协作 不可以 → 继续判断 对可靠性要求高吗? 高(生产环境)→ 状态机(LangGraph) 一般(原型/内部工具)→ 计划-执行 ``` 关键点解读:这个决策树是"从简到繁"的收敛顺序,默认答案是"能简单就简单"。因为每往上一档,可控性都是下降的:简单循环你永远知道它在哪一步;多 Agent 你连"此刻谁在等谁"都要额外画图。 ### Q:从原型走向生产,架构一般怎么演进? A:结论先行——典型路径是"简单循环起步 → 加显式状态与容错 → 抽成状态机 → 按需拆多 Agent",每一步都由指标触发,而不是由架构偏好触发。 ```text 阶段 1:简单循环 + 可观测性 目标:跑通链路,拿到成功率基线 升级触发:步骤经常超过 5 且开始失控 阶段 2:计划-执行 + 显式状态 目标:把全局计划与中间结果外置 升级触发:需要断点续跑、需要人工确认 阶段 3:状态机(如 LangGraph) 目标:控制流可枚举、可回滚 升级触发:出现可并行的独立子任务 阶段 4:多 Agent 协作 目标:并行 + 专业分工 升级触发:无(这已是当前主流分层里的上限) ``` 关键点解读:注意每一阶段是"叠加"而不是"替换"——状态机里仍然有显式状态,多 Agent 里每个 Agent 仍然是状态机。常见误区是直接跳到阶段 4,结果在没有基线和可观测性的前提下调试多 Agent,成本极高且无从下手。 ## 五、工程实践与踩坑 ### Q:落地这五条原则时,最容易踩的坑有哪些? A:结论先行——四类高频坑:一步到位上多 Agent、把状态塞进 Prompt、只做重试不做幂等、可观测性上线后才补。 ```text 坑 1:一开始就上多 Agent 表现:为了"看起来专业"拆出 5 个 Agent 代价:通信开销、协调复杂、调试成本成倍上升 建议:单 Agent 跑通并量化成功率后,再按需拆分 坑 2:把状态塞进对话历史 表现:中间结果、计划、约束全在 messages 里 代价:上下文膨胀、约束被"推到中间"后失效 建议:状态与消息分离,消息只留摘要 坑 3:只做重试,不做幂等 表现:超时后重试,结果写了两遍 代价:重复下单、重复发信、数据脏 建议:写操作必须先有幂等键(第 04 篇) 坑 4:可观测性后补 表现:出问题才发现没有 Trace 代价:无法复现,只能靠猜 建议:第一版就记录每步输入输出与 Token ``` 关键点解读:这四个坑有一个共同结构——**都是"用 LLM 的能力去弥补工程缺失"**。而架构原则的核心恰恰相反:用代码的确定性,去替代 LLM 的不确定性。 ### Q:如何验证架构确实"扛得住"? A:结论先行——三条可执行的自检:边界可枚举、状态可重建、失败可定位。满足这三条,架构基本合格。 ```text 自检 1:边界可枚举 能否一句话说出"LLM 能做什么、不能做什么"? 能否列出最大迭代次数与超时时间? 自检 2:状态可重建 任意时刻从检查点恢复,任务能否继续跑完? 已完成步骤是否可被程序读取,而不依赖 LLM 记忆? 自检 3:失败可定位 任取一次失败任务,能否还原每步的输入输出? 能否区分是"模型选错"还是"工具失败"? ``` ### Q:这些原则在成本与性能上有什么代价?该怎么权衡? A:结论先行——显式状态、幂等、重试、全量追踪都会增加存储与调用开销;正确做法是先测量基线,再逐项优化,而不是一开始就为"极致省钱"牺牲可靠性。所有成本与性能结论都必须在自己的真实流量下实测,不要照搬他人的量级。  *图:可靠性手段的代价清单:存储、缓存与下游压力* ```text 代价清单(定性): 显式状态 + 检查点 → 需要持久化存储,写放大 幂等缓存 → 需要缓存层,存在过期与一致性设计 重试 → 放大下游压力,需退避与上限 全量追踪 → 日志/存储成本上升,需采样 工具精简 → 需维护"任务类型 → 工具集"的映射 ``` 关键点解读:可靠性与成本天然对立。经验顺序是——先用可观测性量化基线(成功率、步骤数、Token),再对"最贵且最无效"的环节动手(通常是过长的上下文与重复工具调用),最后才考虑缩容重试次数或降低追踪粒度。任何"能省多少"的说法,都应以你自己的实测为准。 ### Q:如果在团队里推不动这些改造,怎么讲清楚投入产出? A:结论先行——用"失败成本"而不是"架构先进性"来论证:把线上失败任务按五类根因归因,算出每类占比与人工兜底成本,改造优先级自然浮现。 ```text 归因方法: 1. 拉取一段时间内失败 / 重试的任务 2. 按五类根因打标:工具选错 / 上下文失忆 / 错误放大 / 控制流失控 / 不可定位 3. 统计占比,并估算每类的人工干预成本 4. 优先改造"占比最高且改造成本最低"的一类 ``` 关键点解读:这套方法的副产品是"可观测性必须先有"——没有打标数据,归因无从谈起。所以在最早期,即使其他改造暂缓,追踪与日志也应当先落地。 ### Q:常见追问——"你的 Agent 怎么保证不会无限循环?" A:结论先行——三层兜底:代码层的迭代上限、时间层的超时、语义层的进展检测(无进展即终止)。 ```text 三层兜底(从硬约束到软约束): 1. 迭代上限:硬编码 max_iterations,超出即终止并返回当前结果 2. 超时:单步超时 + 整任务超时,防止"慢而不停" 3. 进展检测:对比相邻步骤的状态,若连续 N 步状态无变化即判定卡死 → 触发终止或切换到降级策略 ``` 关键点解读:只靠迭代上限不够——10 步也可能已经烧掉大量 Token;只靠超时也不够——慢速的无效循环同样浪费。三层叠加才能同时约束"步数、时间、有效性"这三个维度。 ## 小结 - 五条原则:最小化 LLM 决策负担、状态显式化、控制流可预测、失败是常态要容错、可观测性优先。 - 一句话:**好的 Agent 架构 = 最小化 LLM 决策负担 + 显式状态管理 + 可预测控制流 + 容错设计 + 可观测性。** - 核心分工:不要让 LLM 做它不擅长的事(记住所有状态、处理所有错误、判断何时停止),把这些交给代码。 - 四种模式按复杂度排序:简单循环 → 计划-执行 → 状态机 → 多 Agent;默认从最简单的开始,按需升级。 - 架构不是选框架,而是划"确定性代码与 LLM"的职责边界。 ## 思考题 1. 如果把工具从 20 个压到 8 个会降低单步错误率,但可能让某些任务无法完成。你会如何在"决策负担"与"能力覆盖"之间取舍?有没有第三种方案? 2. 显式状态要求你提前定义字段。面对一个尚不明确的任务类型,你会先定义哪些"最小必备字段",以保证后续可扩展? 3. "控制流可预测"与"LLM 自主规划"在本质上是矛盾的。请举一个你认为应该把控制权交给 LLM 的具体场景,并说明边界应如何设置。 4. 假设每步成功率 95%,一个 20 步任务的整体成功率大约是多少?如果允许其中 3 步失败后重试一次,结果会如何变化(给出估算思路即可)? 5. 可观测性要求在第一步就记录大量信息,这会带来存储与隐私成本。你会如何设计"记录粒度"来平衡调试需求与成本?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入