主题
第 3 章 Agent 技术原理与技术生态
第 2 章走完了四种入口的调用链。这一章往下挖一层:Agent 的能力从哪里来,工程层补了什么,落地时又该怎么选。3.1 先看底层演进:提示词、上下文、驾驭、循环、图五层工程如何一层层补上模型的缺口,以及 CPU 与 GPU 的分工;3.2 把这套结构拆成推理、记忆、上下文、工具四项能力,逐项看实现;3.3 转向技术生态,比较模型服务、向量库、协议与开源框架的选型边界;3.4 用一份可运行的代码手搓一个最小 Agent,把概念落到命令行。
3.1 Agent 底层演进和技术原理
握手、长连接、事件流都只是形式。能跑通一次,不等于知道它为什么能跑通,更不等于出了问题能修。
本节看演进与分工。Agent 的能力不是模型单独给的,模型只提供概率推理,其余部分都由工程层补齐,补的方式有先后,也有层次。四项能力的分项实现,留给 3.2。
理解这个层次,你才知道手上的问题该在哪一层解决。换模型不一定是答案,加一层约束往往更可控。
3.1.1 五大演进范式
过去三年,工程界为了让大语言模型稳定干活,在模型外面一层层加约束。社区后来给这些做法起了一串名字:prompt engineering、context engineering、harness engineering、loop engineering、graph engineering。
LangChain 在 2026 年 7 月 22 日的《3 Years of Graph Engineering with LangGraph》里,把这一串直接称为 buzzwords(流行词),并说最新的 graph engineering 是「这个周末」才冒出来的。话虽如此,这些叫法背后是真实的设计取舍:做法有三年,名字大多在 2025 至 2026 年才出现。
原文链接:https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph
本书把它们整理成五层结构,标题沿用「五大演进范式」的说法,下文简称五层工程。这个分层是本书的整理框架,不是学界统一的分类。
它们不是五个时代,而是层层包含的结构,外层管全局,内层管单点。越往里越靠近模型,越往外越靠近工程。
这张图要倒着读。从最里面的模型开始,一层层往外加控制。每加一层,都是为了补上一层的缺口,而不是推翻它。
3.1.1.1 提示词工程:单次指令的表达
2023 年是提示词(Prompt)工程的阶段。做法是把要求、示例、角色写进一段静态文本。思维链(Chain of Thought,CoT)、少样本提示(Few-shot prompting)、角色扮演,都是这一层的产物。
它解决的问题很具体:一次请求里,怎么让模型给出想要的表达。边界也很清楚,模型是无状态的概率推理机,单次请求装不下长链路任务。
Prompt 是起点。它能提高单次输出的命中率,但改变不了「一次就结束」这个前提。
3.1.1.2 上下文工程:资料的供给与取舍
静态 Prompt 很快撞上第二个问题。模型不知道你的私有资料,只能靠参数里的通识回答。上下文工程(Context Engineering)的做法,是在请求发出前动态组装资料。
检索增强生成(Retrieval-Augmented Generation,RAG)、向量数据库、上下文裁剪,都属于这一层。它解决的是信息供给,在有限的上下文窗口里放进最相关的内容,压掉无关的噪音。
难点不在检索,在取舍。放少了模型答不准,放多了注意力被稀释,Token 成本也上去了。这一层让模型懂了领域知识,但它仍然是一问一答,不会自己发起动作。
3.1.1.3 驾驭工程:受控的工具与权限
再往后,模型开始调 API、读文件、跑命令。能力扩大的同时,危险也跟着来了。驾驭工程(Harness Engineering)在模型外面包一层确定性代码。
沙箱、工具接口(Tool Interface)、参数校验、权限控制、护栏(Guardrails),都长在这一层。工具接口是模型与工具之间的契约,工具接入(Tool Integration)是把工具真正连进来的动作。模型只决定调哪个工具、传什么参数,真正的网络请求与文件写入由 CPU 端的代码执行。
这一层的关键词是边界。哪些目录能读,哪些命令能跑,失败了怎么回滚,都要在代码里写死。工具接入过去每家一套,模型上下文协议(Model Context Protocol,MCP)把接口标准化:MCP 服务端(MCP Server)实现一次,多个客户端复用。MCP 服务端提供工具、资源与 Prompt,客户端发起调用。
注意:MCP 服务端的工具描述会直接进入模型上下文,描述写得含糊会导致模型选错工具并传错参数。
有了手脚,模型能做的事多了一个量级(示意说法,不是测量值)。但每做完一步,仍要人来判断下一步做什么。工具与 MCP 的细节,见 3.2.4。
3.1.1.4 循环工程:单个循环的自我修正
第四层是循环工程(Loop Engineering),它把一部分判断权交出去。执行循环(Loop)把想一步、做一步、看结果串成回路。一个典型循环包含四个动作:计划(Plan)、行动(Act)、观察(Observe)、反思(Reflect)。
模型给出下一步动作,工具执行,结果回到上下文,模型据此修正。如此往复,直到满足退出条件。价值不在能重复,而在能用真实结果纠正自己。
报错、测试输出、编译结果,都是客观信号(外部可验证信号),比模型的自我评价可靠。代价是长链路会暴露三个问题:误差级联、死循环、自以为是的正确。这三者在 3.1.2 展开。
3.1.1.5 图工程:多个循环的编排
第五层是图工程(Graph Engineering),处理编排。单个循环再强,也管不了分支、并行和回溯。它的做法是把执行路径建模成状态图(StateGraph,一种带状态的有向图)。
LangChain 那篇 2026 年 7 月的总结里还说,图工程并不是新概念,只是这类做法最新才有的一个叫法。原文提到,「graph engineering」这个提法是「这个周末」才出现的。这并不矛盾:LangGraph 这个框架已经做了三年,名字是最近才有的。用工程约束替代模型的自由判断,是我们对这条线的理解,不是原文的结论。
五层到这里齐了,从内到外是提示词、上下文、驾驭、循环、图。图由哪些要素构成、它和循环怎么分工,留到 3.1.3 展开。
要强调的是叠加,不是取代。我们看到做得稳的产品,通常五层都在场,反例也有:不少聊天产品没有图工程,照样可交付。不同产品只是重心不同,聊天产品重提示词和上下文,编码 Agent 重驾驭和循环,多 Agent 平台重图工程。
演进的主线不只是约束变多,还有人的角色在退后。在我们看来,提示词阶段,人是执行者,一句话一句话地指挥。上下文阶段,人退成信息喂养者,负责挑资料。驾驭阶段,人是安全员,盯着工具别越界。循环阶段,人只定目标和退出条件。到了图工程,人更像架构师,画的是节点与边。
把五层放在一张表里:
| 层 | 解决什么 | 一句话例子 |
|---|---|---|
| 提示词工程 | 单次指令表达 | 把角色、示例写进 Prompt |
| 上下文工程 | 信息供给 | 检索相关文档再拼进窗口 |
| 驾驭工程 | 受控地使用工具 | 沙箱里执行命令并校验参数 |
| 循环工程 | 多步自我修正 | 测试失败后重写再跑 |
| 图工程 | 多循环编排 | 失败分支回滚到上一节点 |
3.1.2 循环工程:失效点、补法与模式库
五层里,前三层解决的是单次交互的边界,长链路的问题要到第四、五层才暴露。这一节和下一节只深挖这两层:3.1.2 看单个循环怎么失控、怎么补,3.1.3 看多个循环怎么编排。上下文与工具的工程细节,留给 3.2。
3.1.2.1 长链路的三个失效点
前三层解决的是单次交互:教模型听懂话,喂它资料,给它安全的工具。一旦任务变成几十步,问题就换了一种形态,错误不再孤立,而是沿着链路累积。
第一个失效点是误差级联。模型在第 5 步产生一个小的逻辑幻觉,第 20 步会被放大,第 50 步整个任务崩盘(步数是示意,不是实测数据)。这不是模型变笨了,是每一步都在拿上一步的输出当事实,误差没有地方被拦住。
第二个失效点是死循环(振荡)。模型修了 A 出现 B,改回 B 又出现 A,在两条错误路径之间来回振荡。几分钟内,几万个 Token(经验区间)烧光,任务还在原地。没有预算上限,循环通常不会停在正确的位置。
第三个失效点是自以为是的正确。模型缺少真实世界的反馈,喜欢在错误结果上坚持己见。它说「已完成」,但代码没编译,测试没跑,文件也没写进去,这是很常见的一类故障。
注意:循环没有轮次上限和退出条件时,模型会在两个错误分支之间反复重试,导致 Token 预算耗尽而任务仍未完成。
这三条都发生在单个循环内部。
3.1.2.2 四种补法
工程界给出的补法,都指向同一件事:把判断权从模型手里拿走一部分。3.1.1.4 说循环把判断权交出去,交出去的是下一步做什么;这里的补法拿走的是算不算数。补法一,生成器—验证器(generator-verifier)分离,写代码的模型不负责验收,另起一个角色专门挑错。
同一个模型既当运动员又当裁判,会放过自己写的明显缺陷。角色分开,视角才分得开。补法二,引入客观信号:模型说自己对了不算数,要看编译器、测试框架、类型检查器的退出码。
把真实的错误堆栈原样喂回去,比任何「请仔细检查」的提示都有效。补法三,建错误库。连续失败后,把失败原因与错误路径存进错误库(Error Library):这是本书对这类错误记忆的叫法。
下次遇到相似场景,先查已知雷区,避免在同一个位置再撞一次。反思式学习(Reflexion)走的是同一条思路,原文用语言化自我反思(verbal self-reflection)与情景记忆(episodic memory)来实现。
补法四,给循环装预算与轮次上限:每轮记录已用 Token 和剩余轮次,到线就退出,交回人工或降级。
四条补法覆盖三个失效点;其中死循环有两条,其余各一条。误差级联靠客观信号,每一步的产物由外部判定,不让错误悄悄传下去。死循环靠预算上限与错误库,前者强制停机,后者让模型避开已经撞过的位置。自以为是的正确靠生成器—验证器分离,写的人在验收环节没有投票权。
这四条值得默认配上。少一条,长任务里出问题的概率通常会明显上升,这是我们的经验判断,不是统计结论。
3.1.2.3 一个可运行的校验循环
下面这段代码只演示补法二。模型第一次给出的实现是错的,只有拿到真实断言失败后才改对。它的收敛条件不写在 Prompt 里,而是写在测试里。
python
# loop_verify.py — Python 3.10 及以上,仅用标准库
def model_generate(last_error: str | None) -> str:
if last_error is None:
return "def add(a, b):\n return a - b"
return "def add(a, b):\n return a + b"
def run_tests(src: str) -> str | None:
ns: dict = {}
exec(src, ns)
if ns["add"](2, 3) != 5:
return "断言失败: add(2, 3) 期望 5"
return None
error = None
for step in range(1, 4):
src = model_generate(error)
error = run_tests(src)
print(f"step={step} error={error!r}")
if error is None:
print("通过校验,退出循环")
break运行 python3 loop_verify.py,预期输出三行。前两行分别是第一次失败和第二次通过,第三行打印退出提示。
这段代码里,真正起作用的是 run_tests。它不经过模型,结果是确定的。循环的收敛条件也写在代码里,error is None 由测试决定,不由模型宣布。
把 model_generate 换成真实 API 调用,骨架不用改。至少还要补超时、重试和费用上限,这几件事同样写在代码里;流式解析、限流、密钥管理也要一并考虑。另外,exec(src, ns) 只是教学用的最小实现;生产环境应把待执行代码放进隔离的进程或容器,不要 exec 不可信代码。
3.1.2.4 五大类 20 种循环模式
示例只演示了一条补法。工程界在生产里积累的循环模式更多。本书按用途把常见的 20 种归纳为五大类,完整的 20 种清单见 4.1.3。
- 质量提升循环:生成、批评、重写,输出前卡住质量关。
- 记忆演化循环:反思与错误库,让系统记住失败。
- 规划与调整循环:计划、执行、重规划,环境变了就改路线。
- 探索与搜索循环:树搜索与辩论,用算力换解法。
- 系统自优化循环:Prompt 与工作流优化,依据运行指标改结构。
这些模式不是让你每个脚本都用。它们是处理长链路、高复杂度任务的工具箱。一些通用智能体面对开放的代码和命令行世界,会内置树搜索、多评审和动态重规划。
垂直应用不必照搬。挑两三种最契合的,比如生成与批评,再配一个错误库,把一条业务流跑稳就够了。模式选多了也有代价,每一层循环都要额外的模型调用,延迟和成本会一起上涨。
单个循环的模式再多,也解决不了循环之间的编排。这就是下一节图工程要处理的事。
3.1.3 图工程:循环的拓扑编排
3.1.3.1 单个循环的结构性限制
循环工程强在自主迭代。做错、看报错、修正、再做,这套动作在单点任务上很有效。但把它拉长到多阶段任务,单个循环会遇到三种结构性限制。第一条与 3.1.2.1 同源,是同一个死循环在控制结构上的表现;真正新增的是后两条。
一是死循环(振荡),3.1.2.1 已讲过,这里不再重复。二是上下文爆炸,跑十几轮之后,上下文里塞满失败堆栈,注意力被噪音污染。
三是不能并行,也不能回退。单个循环只能往前硬走,很难像人一样开三个分支试,不行就回滚。这三个问题单靠换更强的模型,通常解决不了。它们出在控制结构上,回滚、并行、单点预算这几件事,只能由结构给。
3.1.3.2 图的修补机制
先分工,再给写法。图工程的做法,是把不可控的大循环拆成一张有向图。节点是一个步骤,内部可以是一个轻量小循环。边是跳转条件,通常由工程代码判断,也可以交给模型路由,但落点仍是工程定义的有限选项:循环让模型决定节点内部怎么走,图让工程决定节点之间怎么连。
状态是显式对象,在节点之间传递,可存可查可回滚。分支用于并行探索,结果汇总后再合流。关键在局部小闭环,每个节点内部的循环只负责一件事。
比如把一段代码改到单测通过。小循环连续失败几次,条件边直接把它跳出去,进入降级分支。整个系统不会陪着它一起死循环。
状态显式化带来另一个好处。每一步的输入输出都可记录,失败时能定位到具体节点。这就是图工程和循环工程的分工。
3.1.3.3 条件边的写法
下面的例子用一个状态对象和一条条件边,演示预算耗尽后的降级路径。退出条件由代码判断,模型没有投票权。完整的节点与边怎么组织,见 3.1.3.2。
python
# graph_route.py — Python 3.10 及以上,仅用标准库
from dataclasses import dataclass
@dataclass
class State:
tries: int = 0
result: str = ""
def generate(state: State) -> str:
# 真实系统里这一步可以是模型调用:节点内部的动作用模型决定,节点之间的跳转仍由代码判断
state.tries += 1
# 成功阈值 3 故意高于预算 2:本例只走降级路径
return "ok" if state.tries >= 3 else "bad"
def verify(text: str) -> bool:
return text == "ok"
state = State()
while True:
state.result = generate(state)
if verify(state.result):
print(f"成功,用了 {state.tries} 次")
break
print(f"第 {state.tries} 次校验失败: {state.result}")
if state.tries >= 2:
print(f"降级,转人工,已试 {state.tries} 次")
break运行 python3 graph_route.py,输出三行。前两行是两次校验失败,第三行表示触发降级,任务交回人工。这里的 tries >= 2 就是一条条件边。
真实系统里,节点会更多。生成、审查、测试、合并各占一个节点,边上挂着重试预算和回滚逻辑。图越大,能表达的控制越多,能出错的地方也越多。
3.1.3.4 图的成本
图不是越复杂越好。节点数量一多,调试成本会非线性上升。一个十个节点的图,每个节点按两态算,状态组合是 2 的 10 次方,上千种,这还只是最保守的下界。出问题时,光定位在哪条边上就要花时间。
我们的经验是先画最小图。能三个节点解决,就不要画十个。只有当某个环节确实需要独立重试、独立回滚或并行探索时,才把它拆成节点。
3.1.4 CPU 与 GPU 的分工
3.1.4.1 两类执行主体
前面按功能分五层,换成执行主体看只有两类:确定性的代码和概率性的推理。主流部署里,确定性代码跑在 CPU 上,模型推理跑在 GPU 上,中间用结构化数据交换。
CPU 一侧负责硬控制:状态机、上下文的预算与裁剪、参数校验、权限、沙箱、死循环检测,都写在这里。GPU 一侧负责软推理:理解意图、拆解目标、归纳总结、生成文本、给出候选决策。
两者之间用结构化消息交换。工具调用(Tool Calling)是其中最常见的一类。参数是 JSON,结果是字符串或结构化对象。这个分工决定了系统能不能修:模型输出错了,代码层可以拦截、重试、降级。
3.1.4.2 一条判断标准
判断一个步骤该放哪一侧,有个简单标准:这一步是否必须百分之百正确。必须正确的,写成代码:扣款金额、文件路径、权限校验、退出条件。
需要判断的,交给模型。比如这段报错是什么意思,下一步该查哪个文件,用户到底想要什么。好的 Agent 架构,是用 CPU 的确定性去包容和纠正 GPU 的不确定性。
反过来做就会出问题。把权限判断交给模型,等于把门锁交给一个会临场发挥的保安。模型可以建议开哪扇门,钥匙必须留在代码手里。
到这里,3.1 讲完了演进与分工;下一节把这套结构拆成四项能力。
3.2 Agent 的四大核心能力
3.1 的五层工程回答控制流怎么组织,3.1.4 的 CPU/GPU 分工回答执行落在哪一侧。本节把这套结构拆成四项能力,逐项看工程上补了什么。
把范式落到应用上,需要四项能力同时到位:推理决定想得深不深,记忆决定忘不忘得掉,上下文(Context)决定一次能装下多少事,工具决定能不能真的动手。
这个划分是按「模型之外必须由工程补齐的环节」来的。模型只提供单步推理,其余三件事都要在模型外面解决,所以它是工程视角的划分,不排斥其他分法。
四项不是并列关系,而是一条链。任何一项短板都会让整条链路失效。断点常常不在显眼处:工具返回值被截断、摘要丢掉一条否定约束,都可能让后面几步全错,排查时容易被误导。
本节按三步讲每项能力。先看它解决什么问题,再看工程上怎么做,最后看常见怎么坏。关键环节给最小示例,不保证每段代码都能直接上线。以下经验与阈值来自我们若干个生产项目,数字只作量级参考。
3.2.1 推理引擎和推理方法
引擎选型
3.1 的五层工程解决怎么组织循环,循环里每一步都要调用一次模型。这一步的底座就是推理引擎(inference engine,也常被叫作推理服务框架),它决定单步能力的上限。
推理能力要解决的问题,是把单步上限和多步组织同时用足。前者靠引擎选型,后者靠推理方法,混着调就不知道该换模型,还是该改流程。
选型的第一个问题不是哪个推理引擎好用,而是要不要自己部署。先给判断:除了数据不能出内网、调用量极大且任务极窄这两类场景,我们建议直接调用云端模型 API。
自建路线在自有 GPU 上部署开源权重,能控数据、能微调,也能压延迟。代价是显存、运维和模型升级这三件事都要自己扛,具体部署与显存账见 3.3.2。
云端 API 把这三件事交给服务商,按 Token 付费,模型升级自动跟上。我们给新项目的默认建议是后者。长链路 Agent 动辄几十步调用,单步能力差一点,误差就会沿链路逐步累积。
一个 20 步的任务,单步成功率 95%,整体成功率只有 0.95²⁰ ≈ 35.85%。这个算术有三个前提:每步相互独立、失败后不重试、中间结果不做校验。它比任何选型争论都直接,结论也简单:要么提高单步成功率,要么用重试与校验兜底。
例外只有两类。一类是数据合规,模型不能出内网时,自建不是优化项,而是准入条件,没有商量余地。
另一类是极端成本。日均 Token 量稳定在高位、任务类型又足够窄时,专用小模型加自建集群才可能比云端便宜;量不稳定,这笔账就不成立。粗算方式是自建年固定成本除以云端单价,得到日 Token 阈值,日消耗稳定超过这条线,自建才划算。
路线定了,客户端代码几乎不用分叉。主流自建框架普遍提供 OpenAI 兼容接口,与云端 API 的差别通常在 base_url 和模型名;云端调用就是标准 OpenAI 客户端的默认用法,本节不再单独举例。
推理方法
有了引擎,第二个问题是怎样组织思考。推理方法不是模型自带的功能,而是提示词(Prompt)、解码参数与外部控制流的组合。
思维链(Chain of Thought,CoT)让模型先写推理过程再给答案。它在算术和多跳问答上稳定有效,代价是输出变长、延迟上升。
简单分类任务加 CoT 常常是净损失。判断依据是任务是否需要中间步骤,而不是看起来是否复杂。
别只看单步成本。自洽性(Self-Consistency)对同一问题采样多条推理链,再取多数答案,准确率会涨,但成本按采样数翻倍,适合答案可自动校验的场景。
思维树(Tree of Thoughts,ToT)把推理做成搜索树,每个节点展开多个候选并回溯。它适合有明确评估函数、解空间不大的问题。
分支因子为 b、深度为 d 时,调用次数约为 b 的 d 次方。这个数字决定了 ToT 只能用在验证便宜的场景,否则成本会先失控。
Plan-and-Solve 先出完整计划再逐步执行,适合步骤可预先分解的任务。计划错了后面全错,所以计划必须可修订,不能一次定死。
ReAct 把推理与工具调用交替进行,适合结果依赖外部环境的任务。它的前提是工具返回的观察值足够可靠,否则推理会被错误信号带偏。
工程上最容易犯的错,是把这些方法写进 Prompt,只加一句「请一步一步思考」。模型是否遵守全看运气,长链路里不能赌。
正确做法是把控制流放到代码里。模型只负责提出下一步动作,循环、校验和终止都由程序决定,失败时才有确定的兜底路径。
下面这段代码用 Plan-and-Solve 出计划,用 ReAct 逐步执行,并带最大步数熔断。
python
import json
import os
import sys
PLAN_PROMPT = '把任务拆成不超过 5 步,只输出 JSON:{"steps": ["步骤1", "步骤2"]}'
STEP_PROMPT = (
"当前步骤:__STEP__\n已完成:__HISTORY__\n"
'只输出 JSON:{"action": "finish", "answer": "..."} '
'或 {"action": "tool", "tool": "read_file", "args": {"path": "..."}}'
)
MOCK = [
'{"steps": ["读取 README.md 并统计 TODO 数量"]}',
'{"action": "tool", "tool": "read_file", "args": {"path": "README.md"}}',
'{"action": "finish", "answer": "共 3 处 TODO"}',
]
def call_llm(prompt: str) -> str:
if "--mock" in sys.argv:
return MOCK.pop(0)
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com",
)
resp = client.chat.completions.create(
model=os.environ.get("DEEPSEEK_MODEL", "deepseek-flash"),
messages=[{"role": "user", "content": prompt}],
temperature=0,
response_format={"type": "json_object"},
)
return resp.choices[0].message.content
def read_file(path: str) -> str:
if "--mock" in sys.argv:
return "# demo\nTODO: a\nTODO: b\nTODO: c\n"
with open(path, encoding="utf-8") as f:
return f.read()
TOOLS = {"read_file": read_file}
def run(task: str, max_steps: int = 8) -> str:
plan = json.loads(call_llm(PLAN_PROMPT + task))["steps"]
history = []
for step in plan:
for _ in range(max_steps):
prompt = STEP_PROMPT.replace("__STEP__", step).replace("__HISTORY__", str(history))
raw = call_llm(prompt)
act = json.loads(raw)
if act["action"] == "finish":
history.append(act["answer"])
break
name = act["tool"]
if name not in TOOLS:
history.append(f"工具不存在:{name}")
continue
history.append(str(TOOLS[name](**act["args"]))[:2000])
else:
raise RuntimeError(f"步骤超过 {max_steps} 次仍未完成:{step}")
return "\n".join(history)
if __name__ == "__main__":
print(run("统计 README 里的 TODO 数量"))运行方式有两种。有 API key 时走真实模型,没有时加 --mock 走内置应答,控制流可以脱离模型单独测试。示例的模型名以 DeepSeek 官方模型列表为准(api-docs.deepseek.com,查阅于 2026-11-03),可用环境变量 DEEPSEEK_MODEL 覆盖。response_format={"type": "json_object"} 需要服务端支持;不支持时删掉这一项,改靠提示词约束 JSON 输出。deepseek-reasoner 这类思考模型会忽略 temperature,普通对话模型仍然生效。
这一步能挡掉大部分集成阶段的低级错误。很多问题其实出在分发逻辑,而不是模型能力,先分离两者能省下大量排查时间。
注意:示例里
max_steps=8限制的是每个计划步骤最多调用 8 次,不是整条任务 8 步。生产环境这层熔断不能省:去掉它,模型反复调用同一个工具会让单步永久卡住,账单却一直在走。
还有一个隐蔽的失败模式,模型输出不是合法 JSON。概率不低,尤其在长上下文里,越复杂的工具参数越容易解析失败。
这段示例没有做这层防护,json.loads 一失败就整轮中断。生产环境要补一次重试:把解析错误回填进 Prompt 让模型改正,仍失败则降级为纯文本处理,不要在同一步无限重试。
温度也要按场景分开。工具参数生成用 0,创意写作再用 0.7 以上,一个 Agent 共用一组参数,会让两类任务都做不好。
总结这一节。引擎决定单步能力,方法决定多步组织,控制流必须由代码兜底。这三件事做到,推理这一环才算立住;但推理只处理当下这一步,Agent 还需要记住上一次做过什么。
3.2.2 记忆存储和检索
模型权重是静态的,前沿大模型训练一次要几个月,成本在千万到亿美元量级。它更新太慢,很难跟上业务变化,所以记忆必须放在模型外面。
这带来两个问题。一是权重的静态性,新知识只能靠外部写入;二是跨会话的连续性,上一次做过什么、定过什么,下一次必须还能拿到。
存储解决记得住,检索解决找得到,两件事不能混为一谈。它们的工程解法完全不同,混着做最后往往是两头都不达标。
中间件怎么选是另一个问题,见 3.3.3。本节只讲分层依据与最小演示。
3.2.2.1 Agent 的记忆存储
先看存储。按生命周期分层是最省钱的划分方式,分层依据不是技术栈,而是数据活多久、被读多少次。
工作记忆只服务当前会话,包括最近几轮对话和中间推理状态。它写入频繁、读取频繁、过期即弃,不适合放进持久化数据库。
Redis 适合这一层。单机 10 万级 QPS 是 redis-benchmark -t get -n 1000000 -P 16 在 8C16G 理想条件下的数量级,实际取决于硬件、pipeline 与命令类型。它带 TTL,可按 RDB/AOF 配置恢复,默认快照仍可能丢最近写入。代价是内存贵,不适合长期堆积。
单机小工具用 SQLite 就够,一个文件就能跑。它零运维,事务和索引都齐全,也是本地原型最省事的选择。
长期记忆跨会话保存用户偏好、任务结果和领域知识。它要求持久化和可查询,通常落在 MySQL、PostgreSQL 或向量库。
分层的关键不是用哪个数据库,而是明确哪类数据放哪层。放错层的代价是成本翻倍,或者关键信息随会话一起消失。
文本要能被语义检索,先要变成向量。这一步叫嵌入(Embedding),模型选择直接决定召回质量,换模型要重跑全量数据。
BAAI/bge-m3(正文简称 BGE-M3)是常用的开源选择,支持中英文,输出 1024 维向量。它同时提供稠密、稀疏和多向量三种表示:稠密走向量召回,稀疏走关键词或 BM25 路线,多向量用于重排或混合检索,适合中英双语、长文档和代码检索。
向量库存向量,同时存原文和元数据。元数据至少要有来源、时间和写入者,否则召回后无法判断可信度,也无法追责。
很多团队只存文本和向量,出了问题查不到出处。这是记忆系统(存储、检索与生命周期管理的整体能力)的典型设计缺陷,补数据的成本远高于一开始就存全。
结构上不需要复杂设计。一条记忆一行,正文、向量、时间三个字段就够跑通,来源与置信度按需再加。
sql
CREATE TABLE mem(
id INTEGER PRIMARY KEY,
text TEXT NOT NULL,
vec TEXT NOT NULL,
ts TEXT DEFAULT CURRENT_TIMESTAMP
);写入比检索简单:正文过一遍嵌入模型拿到向量,和原文一起落库。真正分叉的是检索,下一节展开。
3.2.2.2 Agent 的记忆检索
检索有三条路径,各有明确边界。选错路径,再好的模型也补不回来,因为召回阶段丢掉的证据,后面无法凭空生成。
稠密向量检索擅长模糊意图。用户问东西不想要了,它能召回退款政策,因为它比较的是语义而不是字面。
它的弱点是精确匹配。订单号、函数名、错误码这类字符,向量化后差异被抹平,召回经常落空,而且看不出为什么。
稀疏检索基于倒排索引,BM25 是代表。它对专有名词和编号极敏感,正好补上向量的短板,两类查询各有用武之地。
单路不够。常见做法是混合检索:两路各取前 50 条(经验值),用倒数排名融合(Reciprocal Rank Fusion,RRF)合并,避免单一路径漏召。
RRF 只依赖排名,不依赖分数尺度,实现简单。常数 k 取 60,来自 Cormack 等人 2009 年发表在 SIGIR 的论文,工程上直接照用即可。
合并之后再做重排。BAAI/bge-reranker-v2-m3(BGE Reranker)这类交叉编码器逐对打分,把真正相关的几条顶到前面,精度通常还能再提高一些。
重排很贵,只能作用在小候选集上。所以顺序不能反,先粗召再精排,颠倒过来成本会失控,延迟也压不住。
召回要宽,重排要严。
理论讲完,用一段最小代码把写入和召回跑通。它用 SQLite 存文本,用字符哈希生成向量,再按余弦相似度召回。
这段代码只依赖标准库,目的是把流程跑通。它不提供生产级语义能力,但接口和真实系统一致,替换实现即可升级。
python
import math
import sqlite3
import zlib
DIM = 256
def embed(text: str):
vec = [0.0] * DIM
for ch in text:
vec[zlib.crc32(ch.encode()) % DIM] += 1.0
norm = math.sqrt(sum(v * v for v in vec)) or 1.0
return [v / norm for v in vec]
def cosine(a, b):
return sum(x * y for x, y in zip(a, b))
class Memory:
def __init__(self, path=":memory:"):
self.db = sqlite3.connect(path)
self.db.execute(
"CREATE TABLE IF NOT EXISTS mem("
"id INTEGER PRIMARY KEY, text TEXT, vec TEXT, "
"ts TEXT DEFAULT CURRENT_TIMESTAMP)"
)
def add(self, text: str):
vec = ",".join(f"{v:.6f}" for v in embed(text))
self.db.execute("INSERT INTO mem(text, vec) VALUES (?, ?)", (text, vec))
self.db.commit()
def search(self, query: str, top_k: int = 3):
q = embed(query)
rows = self.db.execute("SELECT text, vec FROM mem").fetchall()
scored = []
for text, vec in rows:
v = [float(x) for x in vec.split(",")]
scored.append((cosine(q, v), text))
scored.sort(reverse=True)
return scored[:top_k]
if __name__ == "__main__":
m = Memory()
m.add("退款政策:签收后 7 天内可退,需保留包装")
m.add("发票申请:订单完成后 30 天内可开")
m.add("物流时效:江浙沪次日达")
for score, text in m.search("东西不想要了能退吗"):
print(f"{score:.3f} {text}")运行后可以看到,退款那条排在第一。字符哈希只能匹配字面重叠,换一个说法就失效,这正是语义模型要解决的问题。
生产环境把 embed 函数换成真实模型即可。用 FlagEmbedding 加载 BGE-M3,输出 1024 维向量,上层接口保持不变。
换模型时要注意维度必须与建表时一致。向量库通常会在写入时校验维度,不一致直接失败。本文这个 SQLite 示例把向量存成 TEXT,没有维度约束,写入不会失败。不过 zip 会按较短的一侧截断,余弦相似度算出来是错的,而且不报错。
3.2.2.3 记忆的故障与生命周期
记忆的故障分两组。一组出在写入与生命周期,一组出在检索与使用,表现都是答非所问,但根因不同,修法也完全不同。
先看写入侧,两种。第一种是切块不当:切块过大,一条记忆里混了三个主题,召回后模型抓不住重点;切块过小,上下文断裂,答案残缺。两种错都要靠调参平衡。
第二种是只增不删。记忆库(长期记忆的存储实体)会随写入量增长变成垃圾场,检索延迟持续上升,费用也跟着涨。对策是 TTL 加人工清理入口,别指望它自己变干净。
再看检索侧,也是两种。召回不重排,把 20 条噪音一股脑塞进上下文,既浪费 Token 又稀释注意力,回答质量反而下降。
记忆污染最危险。模型的一次错误结论被写入长期记忆,之后每次都被当成事实召回,错误会随时间自我强化。
它虽然种在写入,却每次都从检索里被捞出来,所以两边都要设防。对策是给记忆打上来源和置信度,低置信度的条目只作参考,不直接进入结论。
重要决策要能回溯到原始证据。没有出处的记忆,等于一条无法反驳的证词。
修完故障,记忆还要能自己变好,有两条机制值得实现。
第一条是错误库(Error Library)。把失败的调用、报错堆栈和错误决策单独归档,下次遇到相似场景优先读取,避免重复踩同一个坑。
第二条是压缩归纳。碎片记忆越积越多,检索精度会下降,后台需要定期把多条具体事件归纳成一条规则。
归纳要有版本,旧规则不能被直接覆盖。被替代时保留历史,否则错误结论会被永久固化,后来的人也无法判断它从哪来。
存储与检索解决知道过去。但即使检索准确,一次能放进模型的内容仍然有限,这就轮到上下文管理。
它决定模型每一步看见什么,也决定前两项能力的成果能否被用上。上下文放不进去的记忆,在实际推理中等于是不存在的。
3.2.3 上下文管理
大模型是无状态的,每次 API 调用都是一次独立推理。它不记得上一次说过什么,连续性完全靠外部程序重建。
Agent 之所以看起来有连续性,是因为程序在每次调用前重建了上下文。这件事听起来简单,做起来是长链路系统里最容易失控的一环。
多数长任务失败,根因都在这里。跑完第 5 步进入第 6 步时,程序没有把第 5 步的结果回填进上下文,模型就看不到它。
系统必须把任务目标、约束条件和历史结果重新打包。少放一项,模型就可能做出错误判断,而且错得很自信。到底哪些必须留,后面的摘要压缩给出三类。
步数越多,包越大。工具返回的日志、失败尝试和中间文件内容都会堆进来,很快就会逼近模型窗口的上限。
这时候不做裁剪,成本和质量会同时恶化。注意力机制对长上下文并非均匀分配,位置在中间的信息被利用的概率明显偏低。
这个现象在 Liu 等人的论文里被称为迷失在中间(Lost in the Middle),2024 年发表于 TACL。
它解释了为什么把整份文档塞进上下文,效果常常不如先检索再拼接。位置对了,信息才可能被用上。
第一层手段是裁剪,保留最近的 N 轮,丢弃更早的内容。它实现最简单,副作用也最明显,早期约束很容易被误删。
固定窗口对短会话够用,对长任务不友好。第 3 步定下的约束,到第 30 步可能仍然有效,删掉就会出事。
第二层是基于状态的动态过滤。写代码的 Agent 只需要当前文件内容和最近一次测试结果,早期报错日志可以整段删除。
第三层是摘要压缩。对话达到阈值时,调用一次便宜的小模型,把前几十轮归纳成一段进展摘要,腾出主要预算。
摘要要保留三类信息。已确认的事实、已否决的方案、仍然有效的约束,少一类后面就会返工,而且很难定位原因。
下面这段代码只演示第一层裁剪。动态过滤、摘要压缩,以及后面要讲的前缀缓存,都不在示例内。
python
def count_tokens(text: str) -> int:
try:
import tiktoken
return len(tiktoken.get_encoding("cl100k_base").encode(text))
except ImportError:
cjk = sum(1 for ch in text if "\u4e00" <= ch <= "\u9fff")
ascii_chars = sum(1 for ch in text if ord(ch) < 128)
others = len(text) - cjk - ascii_chars
return int((cjk + ascii_chars / 4 + others) * 1.1) + 1
class ContextBudget:
def __init__(self, limit: int = 8000, reserve: int = 1500):
self.limit = limit
self.reserve = reserve
def pack(self, system: str, history: list, question: str):
# 省略提示也要占额度,先按两位数轮数预留
head_cost = count_tokens("(前 00 轮已省略)")
budget = self.limit - self.reserve - count_tokens(question) - head_cost
kept, used = [], count_tokens(system)
for turn in reversed(history):
cost = count_tokens(turn)
if used + cost > budget:
break
kept.append(turn)
used += cost
dropped = len(history) - len(kept)
head = [f"(前 {dropped} 轮已省略)"] if dropped else []
return [system] + head + list(reversed(kept)) + [question]
if __name__ == "__main__":
system = "你是客服助手,只回答退款与发票问题。"
history = [f"第 {i} 轮:用户询问订单 {i} 的物流状态。" for i in range(1, 61)]
msgs = ContextBudget(limit=1200, reserve=200).pack(system, history, "我的订单能退吗")
print("保留消息数:", len(msgs))
print("估算 Token:", sum(count_tokens(m) for m in msgs))这段代码做三件事。给问题预留额度,从后往前装历史,丢弃的部分用一行提示标明,让模型知道有内容被省略。
逻辑不复杂,但能挡住一类常见的溢出错误。count_tokens 优先用 tiktoken,没安装时退回字符数估算。
这样脚本在任何环境都能跑,不会因为缺依赖中断。没有分词器(tokenizer)时按字符类型分开估:CJK 约 1 字 1 Token,ASCII 约 4 字符 1 Token,再乘 1.1 的安全系数。反过来,按 1.6 字符一个 Token 估算,对中英混排会低估约两成,不能当保守值用;具体偏差还随中英比例与 tokenizer 变化。
宁可多留余量,也不要线上因为估算偏差突然超限。上下文管理同时是成本问题,预算算法不同,账单会差一个数量级。
Transformer 的注意力计算随序列长度平方增长。上下文翻一倍,注意力计算量约变成四倍,延迟也会显著上升,长上下文从来不是免费的。
按 Token 计费的部分是线性的。但一次长任务有几十步调用,成本按步数相乘,单次便宜不等于整体便宜,要按任务算总账。
单次价格会骗人:假设每步输入 10 万 Token,单价每百万 Token 2 元,单步就是 0.2 元。30 步就是 6 元,这还没算输出和重试。
把输入压到 1 万 Token,同样的任务降到 0.6 元。这个差距在规模化之后非常直观,足以决定产品能不能跑通商业模型。
省钱的顺序是先删无用内容,再压缩摘要,最后才考虑换更便宜的模型。顺序反了,重试成本会抵消省下的钱:模型能力下降带来的差价,要按整条链路算,不能只看单次调用的价格标签。
另一条线:前缀缓存
它和前面三层不是同一个维度。前三层缩减内容,前缀缓存不改变内容,优化的是计费和延迟。
多数厂商对重复前缀提供折扣计费。把稳定的系统 Prompt(System Prompt)放在最前面,能省下可观的输入成本,长任务里尤其明显。
缓存命中的前提是前缀完全一致。在系统 Prompt 里插入时间戳或随机 ID,会让缓存全部失效,省下的钱又花回去。
上下文管理自身有两个失败模式,都不报错。它们只会让回答慢慢变差,等到用户投诉时,排查成本已经很高。
裁剪时把系统约束裁掉。模型不再知道自己不能做什么,越权操作和格式错误随之出现,而且看起来像是模型变笨了。
摘要时丢掉否定条件。「不要修改配置文件」这类约束一旦丢失,下一轮就会被当成可选项,破坏性操作可能直接执行。
另有一个相关的失败模式归工具侧:返回值不截断会把上下文直接撑爆,表现是报错而不是变笨,具体在 3.2.4 讲。
上下文决定模型每一步看到什么。但模型看到之后要能动手,就需要工具体系。
3.2.4 Agent 工具体系
到这里,Agent 已经能推理、能记忆、能看清当前局面。它还差最后一件东西,把手伸出去,改变外部世界。
没有工具,模型只能输出文字。有了工具,它才能读写文件、查询数据库、调用外部服务,把判断变成真实结果。
工具体系是 Agent 从会说到能做的分界线。这条线跨过去,系统才开始产生真实副作用,风险也随之上升。
工具是 CPU 与 GPU 之间的那道接口,3.1.4 讲过这条分界,这里不重复。落到工具体系,它的形态是固定的函数签名、类型校验和超时机制。
模型只负责决定调用哪个工具、传什么参数。真正的网络请求和磁盘写入由确定性代码执行,权限也在这一层收口。
这个分工让系统可以被审计。每一次调用都有入参、出参、耗时和错误码,出了问题能复现,也能追到具体环节。
工具接入常被说成两条路线,其实是两层,并不冲突。模型侧要一份调用格式,工具侧要一个接入协议,两层可以同时用。
模型侧是厂商原生的函数调用(Function Calling)。模型厂商在 API 里接受一份 JSON Schema,模型按 schema 返回结构化参数,这是调用格式;模型据此选中某个工具并触发它执行,则是工具调用。
工具侧是模型上下文协议(Model Context Protocol,MCP)。它由 Anthropic 在 2024 年 11 月提出,采用 JSON-RPC 2.0。
MCP 把工具、资源和 Prompt 抽象成服务端能力,这里的服务端称 MCP Server。Agent 作为客户端,可以动态发现并挂载多个服务端,不必为每个框架重写胶水代码。
服务端最终仍然通过工具调用被模型选中,所以 MCP 不是函数调用的替代品。它管的是工具怎么被共享,不是模型怎么开口。
判据看复用范围,不看能力。内部单体应用,工具数量在十个以内,函数调用更直接,schema 写在代码里,调用链短,调试简单。
跨团队、跨客户端、跨厂商共享时,才在函数调用之上加 MCP。同一个服务端可以被不同的 Agent 框架挂载,集成成本只付一次。
我们的判断是先用函数调用把业务流程跑通,需要被第二个客户端复用时再加 MCP。两层叠加,不是推倒重来。
一开始就上 MCP,会多出一层协议调试成本。收益在早期并不存在,团队却要先付出这部分调试成本,很容易拖慢第一版。
先看函数调用的最小结构。关键在参数定义,也就是 schema,描述要写清楚什么时候该用、参数长什么样,模型只能依据这些文字做判断。
python
TOOLS = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "按订单号查询物流状态。只读,可重复调用。",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单号,形如 SO20261103001",
}
},
"required": ["order_id"],
},
},
}]模型返回 tool_calls 后,程序按 name 分发到本地函数。结果作为 tool 角色消息回填,再请求下一轮,循环直到模型给出最终答案。
这个循环通常由 SDK 或框架封装。手写时要注意两点,参数必须校验,返回必须截断,否则一个脏数据就能拖垮整轮对话。
schema 里的 description 不是注释。它是模型判断何时调用工具的唯一依据,写得含糊,调用就会乱,而且很难通过 Prompt 补救。
本节只演示工具怎么定义、怎么以服务暴露。完整的发现、调用、回填循环,放到 3.4 手搓应用时一次跑通。
MCP 服务端可以用官方 Python SDK 写。FastMCP 把协议细节封装成装饰器,几十行就能跑,适合快速验证工具设计。
python
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("order-tools")
@mcp.tool()
def get_order_status(order_id: str) -> dict:
"""按订单号查询物流状态。只读,可重复调用。"""
return {"order_id": order_id, "status": "已发货", "carrier": "SF"}
if __name__ == "__main__":
mcp.run()环境是 Python 3.10 以上,安装命令为 pip install "mcp[cli]<2"。MCP Python SDK 的 2.x 版本据其 release notes 把 FastMCP 更名为 MCPServer,导入路径也随之变化,具体以官方 release notes 为准;本节锁定已验证的 1.x 路径。直接运行脚本会以标准输入输出作为传输层,不需要额外端口。
要在客户端挂载,把这段启动命令写进 MCP 配置即可。客户端会完成握手和工具发现,之后就能像本地函数一样调用。
函数签名和文档字符串会被自动转成 JSON Schema。所以类型标注不能省,它就是协议的一部分,写错会导致参数解析失败。
工具设计有五条经验规则。它们和协议无关,多数框架下都适用,但边界来自我们的实践,不是框架或协议强加的约束。
接口要窄,一个工具只做一件事;我们倾向于把参数控制在五个以内。贪多求全的接口,模型填错的概率会明显上升,校验逻辑也越写越复杂。
错误要结构化,返回 error_code 和 message 两个字段。只回一句 request failed,模型无法判断是参数错、权限错还是服务不可用,只能盲目重试。
写操作要幂等。网络超时后 Agent 会重试,非幂等接口会导致重复下单或重复扣款,这类损失会直接落在业务账上。
超时必须设置。一个卡住的工具调用会卡死整个循环,从外部还看不出卡在哪一步,排查要花几倍时间。
权限要最小化。查询工具不要给写权限,测试环境不要连生产库,一次误调用就可能导致数据泄漏或误删。
规则覆盖不到的故障还有两类,都在数据层面,往往上线后才暴露。
一类是返回值过大。一个不加限制的搜索接口,返回 40 KB 的 JSON(中英混排、含结构符号),大约就是 1 万到 1.5 万 Token。32K Token 的示例窗口下,这一下就占掉三分之一到一半;当前模型的上下文窗口更大,但要按实际值折算。预算紧的时候,一次调用就可能把它用完,重则直接超出窗口报错。
工具层要先做结构化裁剪,只返回模型需要的字段。这一步通常比加 Prompt 约束更有效,而且成本最低。
另一类是工具数量失控。按我们的经验,工具超过 20 个,就该考虑分组或二级路由:先让模型选类别,再选具体工具,单次决策空间小了,准确率会明显回升。工具越多越差,我们最大试过 80 个,那时模型在选型上就会犹豫,调用准确率下降,平均延迟也跟着上涨。
工具不是越多越好。
四节讲完,回到导语那句判断:四项能力是一条链,不是一张清单。任何一环松动,都会传到末端。
推理引擎决定上限,记忆决定连续性,上下文决定每一步看到什么,工具决定能不能落地。四者没有可以跳过的环节,只有先补哪一环的顺序问题。
四项能力都到位,Agent 才是一个能完成长任务的系统。下一节看支撑这四项能力的开源生态,以及它们各自的成熟度。
3.3 Agent 的技术开源生态
上一节把 Agent 拆成推理、记忆、上下文、工具四块能力,拆的时候清楚,装的时候麻烦。每一块能力落到代码,都要挑一个具体的开源件,还要让它们彼此接上。
生态不是一张选型清单,而是一条依赖链。下面按工程堆栈自下而上分五层技术栈(模型层、引擎层、记忆层、工具层、框架层),下层决定能力上限,上层决定落地速度。
图注:DSH 即 DeepSeek Harness。
本节面向三类读者:需要私有化或可控部署的;想先把链路跑通、再决定托管的;只用云端 API 的。第三类可以跳过 3.3.2 的部署步骤,只读该节的两张对比表,其余各层照常。
3.3.1 五层技术栈与依赖顺序
这五层的关系是单向的。模型层与引擎层提供算力与智力,记忆层提供状态,工具层把手脚接出去,框架层把整条链路串起来。
上下文管理不单独成层,它落在引擎层与框架层之间,由两边共同实现,3.2.3 已经展开。
真正锁死你的不是模型,是协议和状态。模型今天换 Qwen,明天换 DeepSeek,走云端 API 改一个 base_url 就能跑。
自建则要换权重、换 Tokenizer,并确认推理引擎支持这个架构。反过来,工具协议和记忆 schema 一旦上线,再换就要动全部工具定义和历史数据。
前者要重写每个工具的入参 schema,后者要做一次全量回填。
所以选型的顺序应该反过来。具体协议形态可以晚定,抽象层必须早留:工具接口与状态 schema 先与框架解耦,再定框架,最后才挑模型和推理引擎。
工具侧用哪种接入方式属实现细节,3.3.4 会再说。多数团队正好相反,先追最强的模型,最后被框架和协议绑住。
下文仍按图自下而上讲,是为了把依赖讲清;真正选型时请倒着走一遍。先定协议抽象层,契约变化最慢,返工成本最低。
生态的成熟度并不均匀:模型服务与引擎层已进入价格竞争,记忆层和工具层还在快速变化。选型时要把稳定的层和变化的层分开看。
这张图也可以当作技术评审的检查清单,分档结果见 3.3.6 的五层成熟度表。
3.3.2 模型与推理引擎的组合选择
第一层是模型层,第二层是引擎层。云端与自建的判断 3.2.1 已给过,本节补自建侧:这两层要一起看,模型权重、Tokenizer 与推理引擎版本必须对齐。
模型是发动机,推理引擎是变速箱,发动机再好,变速箱匹配不上,车也跑不起来。
截至 2026 年 11 月,在我们的项目经验里,中文场景下 Qwen 系列是稳妥的开源起点。它的工具调用格式规范,社区微调版本多,遇到问题容易搜到答案。
Llama 3.x 的社区最大,英文语料和评测最全;DeepSeek 开源系列的优势在推理性价比,适合预算紧、任务逻辑重的场景。
注意:模型权重、Tokenizer 与推理引擎版本不匹配,会导致服务启动报错,或者输出出现乱码。
推理引擎有两种用法,不要混用。本地原型用 Ollama,一条 ollama pull qwen2.5:7b 就能跑,适合验证提示词(Prompt)和工具调用格式。
它的默认并行数是 1,多个请求会排队,压测数据没有参考价值。
生产环境用 vLLM。它的 PagedAttention 把键值缓存(KV Cache)按页管理,连续批处理能把多路请求拼进同一轮计算。
同样一张卡,对比 HuggingFace Transformers 这类朴素部署,并发吞吐可高一个量级;同类引擎之间通常只差 2–4 倍。
这个数量级来自 vLLM 官方文档的架构说明与常见压测结果,具体倍数取决于上下文长度和批大小。
国产加速卡上,优先看 LMDeploy,它对昇腾等国产硬件的适配比 vLLM 早,量化工具链也完整。做结构化输出和高并发推理,可以看 SGLang。
候选不只这三个,横向放在一起更好判断。
| 引擎 | 定位 | 强项 | 代价 |
|---|---|---|---|
| vLLM | 通用生产引擎 | PagedAttention、连续批处理,并发吞吐最高 | 新硬件适配相对滞后 |
| LMDeploy | 国产卡与量化 | 昇腾等国产硬件适配早,量化工具链完整 | 文档中英双语,国际社区规模较小 |
| SGLang | 结构化输出与高并发 | RadixAttention 前缀复用、约束解码 | 生态较新,运维经验少 |
| TGI(Text Generation Inference) | Hugging Face 生态 | 与 HF 模型库衔接顺 | 与 HF 生态绑定较深 |
| Ollama | 本地原型 | 一条命令起服务,零配置 | 并发低,不适合压测与生产 |
在确定要自建的前提下,原型阶段不要搭推理集群:Ollama 够用,上了生产再换 vLLM。
两者都是 OpenAI 兼容接口,兼容范围是 chat.completions 子集,客户端骨架可以沿用;工具调用和结构化输出仍需各自验证。
这一条的前提 3.2.1 已经说过:多数项目先用云端,自建是少数派。只用云端 API 的读者,本节余下的部署部分可以跳过。
自建的部署细节放在本节。第一步不是微调,而是把推理服务跑通,vLLM 的安装与启动就三行:
bash
pip install "vllm==0.6.3"
vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000 \
--max-model-len 8192 --gpu-memory-utilization 0.90这段示例锁定 2024-11 基线(vLLM 0.6.3 / Qwen2.5-7B),仅为可复现。模型换成 Qwen3.5 系列时接口不变,权重名要跟着改。
服务起来后,客户端拿到的就是一个 OpenAI 兼容地址:
python
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")
resp = client.chat.completions.create(
model="Qwen/Qwen2.5-7B-Instruct",
messages=[{"role": "user", "content": "用一句话说明什么是 KV 缓存"}],
temperature=0,
)
print(resp.choices[0].message.content)引擎定了,还要看模型和引擎的配套关系。同一组权重在不同引擎上的支持程度不一样,选之前先查官方的支持矩阵。
下表的判定口径统一为「首选/可用」:官方文档明确列为支持、且给出适配说明的记「首选」,官方未明确承诺、但社区有可用实践的记「可用」。
没有验证过的组合不写进表里,也不做「不支持」的判断。
| 模型 | vLLM | LMDeploy | SGLang | 备注 |
|---|---|---|---|---|
| Qwen2.5 | 首选 | 可用(国产卡优先) | 可用(结构化输出) | 工具调用模板齐全,中文生态最全 |
| Llama 3.x | 首选 | 可用 | 可用 | 英文语料与评测最全 |
| DeepSeek 开源系列 | 可用 | 可用 | 可用 | 推理性价比高,需按官方模板配置 |
显存要按模型大小倒推。3.2.1 只给了云端与自建的判断,把显存账留到了这里,本节把账算完。
7B 模型 fp16 权重约 15GB,这是参数量乘 2 字节再加对齐开销。24GB 的卡按 --gpu-memory-utilization 0.90 算可用 21.6GB,扣掉权重还剩约 6.4GB。这点余量要同时装 KV Cache、激活值(activation)和并发请求。
KV Cache 可以按公式估:KV = 2 × 层数 × KV 头数 × head_dim × 2B × 序列长度 × 并发,公式中的序列长度即上下文长度。Qwen2.5-7B 是 28 层、4 个 KV 头、head_dim 128,8K 上下文长度下单请求约 0.45GB。四路并发约 1.8GB,6.4GB 的余量还撑得住。
真正吃紧的是长上下文和高并发叠加,或者换成 8 个 KV 头的模型(如 Llama-3-8B),后者单请求的 KV 直接翻倍到约 1GB。
所以 24GB 跑 7B 是「能跑、并发有限」,不是「刚好够用」:余量都在 KV Cache 上,上下文一长、并发一多就转不动。
跑 32B 就必须上量化或者换专业卡,fp16 权重约 64GB,一张消费级卡连加载都放不下。这一点在立项时就要算清楚。
3.3.3 记忆与检索中间件的分界
第三层解决状态。先按生命周期分三块(工作记忆、长期记忆、结构化状态),再说这三块怎么被一起检索。Agent 的记忆不是一个数据库能装下的。
工作记忆放当前会话的上下文和中间结果,Redis 合适;单机小项目用 SQLite 就够,省一个服务。机制见 3.2.2。
长期记忆放跨会话的偏好、历史任务和领域知识,向量库是主流选择。这里有个常见误区:数据量只有几十万条就选 Milvus,运维成本先被抬高一大截。
我们的建议是按数据量分界。百万条以内,PostgreSQL 加 pgvector 或者 Chroma 都能扛;Chroma 适合单机原型,装一个包就能用。百万到千万这一档,pgvector 要调索引参数(HNSW 的 m 与 ef_construction),或者用 Milvus 的单机轻量部署。
到了千万级以上,再考虑 Milvus 这样的分布式向量库。提前上重装备,运维成本会先把你拖住。
结构化状态放业务库。任务进度、审批节点、失败重试次数,这些字段用关系库查起来最直接。DuckDB 适合本地做数据分析和离线评测。
三块怎么被一起检索,机制在 3.2.2 已经展开,这里只补选型视角:混合检索的每一路都可以由独立的中间件承担。
BM25 交给 Elasticsearch 或 OpenSearch 这类搜索引擎,向量召回交给向量库,重排放在应用侧。
若走 PostgreSQL 一条路,它自带的全文检索是 tsvector/ts_rank,按词频与文档频率打分,不是 BM25。排序结果会有差异,调权重前要先分清。
分开部署的好处是每一路都能单独扩容和替换,代价是多一次网络往返,延迟预算要提前留出来。
选型时还有一笔隐性成本,常被笼统叫作「索引重建」,其实分两类。换 Embedding 模型或改切块策略,要重新向量化,数据全量过一遍模型,成本按数据量线性涨。
升级向量库版本、改索引类型,多数只是索引重建或数据迁移,通常不需要重算向量。两类成本差一个量级,评估时分开放。
数据量越大越要提前想:向量库要支持在线重建和双写切换,不要等到换模型那天才发现只能停服。
把三块合起来看,顺序是先定数据量和留存期,再定运维人手,最后才看功能清单。功能清单最容易比较,也最不重要:多数团队不是缺功能,是缺人维护。
3.3.4 工具协议与 MCP 的接入方式
第四层解决手和脚:工具体系负责模型能做什么。工具接入要分两层看。
模型侧的调用格式是函数调用(Function Calling),工具侧的接入协议是模型上下文协议(Model Context Protocol,MCP)。两者不是二选一,可以叠加。
函数调用决定模型怎么把意图表达成结构化参数,MCP 决定工具怎么被独立部署、发现和挂载。
定义、判据和最小服务端代码都在 3.2.4,本节不重复,只补生态视角与安全边界。
先看生态位。函数调用的工具跟着应用代码走,提供方就是应用自己,消费方也只有这一个应用,工具无法脱离代码被复用。
MCP 把工具封装成独立服务,由客户端动态发现和挂载。提供方可以是平台方、SaaS 厂商,也可以是团队内部的工具组;消费方是任何支持该协议的客户端。
同一个服务端被多个客户端挂载,集成成本只付一次。
MCP 的价值不在协议本身,在于它把工具从应用代码里拆了出来。
服务端只声明能力和执行;鉴权由客户端或网关发起并收口,服务端负责校验令牌(Token)。MCP 2025-06 规范已经把 OAuth 2.1 写进授权流程;限流、审计可以放在网关。
这条分工决定了生态的形态。工具市场可以只卖服务端,治理各自留在客户端;企业也可以自建一个内部工具网关,把权限、审计和配额收口在一处。
是否在函数调用之上再加 MCP,是后面的实现细节;工具接口先与框架解耦这条,3.3.1 已经说过。
安全边界是本节要补的另一半。工具一旦能碰文件系统和网络,风险就从模型输出转移到了真实副作用。
路径白名单是第一条。MCP 服务端(MCP Server)不做路径校验时,模型可以通过构造参数读取 /etc/passwd 这类敏感文件。
文件类工具必须限定根目录,参数先规范化再比较,符号链接和 .. 都要在解析后判断。
沙箱是工具层的另一半。模型生成的 Python 或 Shell 代码,不要直接在宿主机跑。Docker 容器隔离是最低要求:限制网络、挂载只读目录、设置超时。subprocess 加 seccomp 也能用,但要自己维护规则。
两条边界都落在服务端实现里:规范提出安全要求,但不提供实现,实现责任在服务端或网关。
这也是选 MCP 服务端时要看的:它有没有把白名单和沙箱做成默认项,而不是让调用方自己实现。
3.3.5 编排框架的取舍
第五层把前面四层串成一条可执行的链路。这一层的选择最多,也最容易选错。
LangGraph 适合有状态的长任务。它把流程写成显式的状态图,节点是函数,边是条件路由。好处是每一步都能落盘,中断后可以恢复。
坏处是图要先画清楚,探索期写起来慢。它的检查点(checkpoint)常用 MemorySaver,落在内存;生产环境要换成持久化 saver(PostgreSQL、SQLite、Redis 视规模而定),否则进程重启就丢状态。
AutoGen 适合多角色协作。它把 Agent 当成对话参与者,靠消息传递推进任务。上手快,适合做研究原型和评审类场景。
OpenClaw 适合长期运行的网关型 Agent。它管多渠道接入、会话状态和工具编排,定位是运行框架而不是算法库。要做一个常驻的数字员工,从它起步比从零写调度省事。
DeepSeek Harness(DSH)与 CrewAI 各有侧重。DSH 由 DeepSeek 官方开源,官方定位是插件化的 Agent harness(一切皆插件)。DSH 偏插件化运行时与工具编排,CrewAI 偏角色和任务编排。选之前先看它的抽象是否和你的业务结构对得上。
这里的五个框架只收本节实际验证过的最小集,不代表全部;未列出不代表不成熟。
下面的决策表按场景排列,选型时先对场景,再看项目:
| 场景 | 首选 | 理由 |
|---|---|---|
| 单人维护的单体应用 | 裸循环,不上框架 | 少一层抽象,调试链路最短 |
| 多角色协作原型 | AutoGen | 对话式推进,上手最快 |
| 长任务、要中断恢复 | LangGraph | 状态图可落盘,检查点能续跑 |
| 常驻多渠道网关 | OpenClaw | 渠道、会话、工具编排已内置 |
| 插件化运行时与工具编排 | DSH | 能力以插件挂载,工具路由是强项 |
| 角色与任务边界清晰 | CrewAI | 角色抽象和业务结构对得上 |
框架每加一层,调试链路就长一层。先把最小的执行循环裸写出来,跑通再接框架。反过来做,出问题时你分不清是模型、框架还是自己的逻辑。
注意:框架版本锁定不严,升级后状态 schema 不兼容,会导致历史会话无法恢复。
3.3.6 最小可跑的组合与项目索引
把五层接起来,最小的一套是 vLLM 加 Chroma 加 Redis。这一套只覆盖前三层,工具层按 3.3.4、框架层按 3.4 接入。验证链路先用 3.3.2 的 Ollama 版单机跑通:一条命令起服务,改 Prompt 和工具调用格式最快。
要并发、要接近生产的形态,再照下面这份 Compose 配置(docker-compose.yml)起。它在单机带一张 NVIDIA 显卡的 Linux 上可以直接用。
两种部署方式暴露的都是 OpenAI 兼容接口,3.4 的客户端骨架相同,换的只是 base_url。
yaml
services:
vllm:
image: vllm/vllm-openai:v0.6.3
command:
- "--model"
- "Qwen/Qwen2.5-7B-Instruct"
- "--served-model-name"
- "qwen"
- "--max-model-len"
- "8192"
ports:
- "8000:8000"
volumes:
- "~/.cache/huggingface:/root/.cache/huggingface"
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
chroma:
image: chromadb/chroma:0.5.20
ports:
- "8001:8000"
redis:
image: redis:8-alpine
ports:
- "6379:6379"这份 Compose 配置锁定 2024-11 基线(vLLM 0.6.3 / Qwen2.5-7B / Chroma 0.5.20),仅为可复现。Chroma 1.x 起 API 路径调整过,换新镜像要先对一遍官方迁移说明。
前置条件是 NVIDIA 驱动和 nvidia-container-toolkit,7B 模型用 fp16 加载,显存至少 24GB。--max-model-len 设成 8192,与 3.3.2 的启动参数和显存账保持同一口径;上下文长度越长,KV Cache 占用越高。
显存不够就换 4-bit 量化版本,但要重跑工具调用评测。
服务起来后,客户端只需要一个 OpenAI 兼容地址。
客户端代码在 3.3.2 已经给过,把 base_url 指向这份 Compose 配置暴露的 8000 端口,model 改成 served-model-name 里的 qwen 即可。Chroma 的连通性用 curl http://localhost:8001/api/v1/heartbeat 检查;/api/v1 是 0.5.x 的路径,1.x 起接口版本号变了,按镜像版本对照。
到这里,第一层和第二层通了,第三层也起了服务。工具层按 3.3.4 的安全边界接入,框架层留到 3.4,自己裸写。五层不必都上,缺哪层补哪层。
五层成熟度不在一个档位上。放在一起比一比,选型时才知道哪一层可以押注、哪一层要留退路。
| 层 | 成熟度 | 现状 | 选型建议 |
|---|---|---|---|
| 第一层 模型层 | 高 | 开源权重大约半年一代(经验判断),能力快速逼近闭源 | 不押单一模型,接口留抽象 |
| 第二层 引擎层 | 高,价格竞争充分 | 主流引擎接口趋同,OpenAI 兼容接口成默认 | 选兼容接口,随时可换 |
| 第三层 记忆层 | 中 | 向量库多而分散,能力边界靠工程补 | 按数据量选,别提前上分布式 |
| 第四层 工具层 | 低到中,变化最快 | MCP 仍在快速迭代,生态尚未成形 | 抽象层早留,具体协议晚定 |
| 第五层 框架层 | 中,淘汰率高 | 新框架几乎每年都出(经验判断),抽象差异大 | 先裸写循环,确有必要再接框架 |
最后把本节五层的代表项目汇总如下,只收有官方独立入口的。
生态认全了,接下来是接线。下一节用不到 200 行 Python,把模型、工具、循环和一个真实报错反馈接成能自己改代码的 Agent。
3.4 手搓一个 Agent 应用
3.1 到 3.3 节,我们把 Agent 拆成了三个切面:演进范式与 20 种(五大类)Loop 设计模式(完整清单见 4.1.3);推理、记忆、上下文、工具四大能力;五层开源生态。
拆得越细,越容易产生一种错觉:原理都懂了,动手应该不难。真正坐下写代码时才发现,处处是断点。
第一个问题就把人卡住:模型返回的是一段自然语言,程序怎么知道它想干什么,又怎么判断它干成了没有。
这两个问题不解决,Agent 就只是一个聊天窗口。
这一节只做一件事:用一个完整的例子,回答这两个问题。我们要手搓一个自愈型编程 Agent(Self-Healing Coding Agent),让它自己写代码、跑测试、读报错、再改一版。
选这个场景,与编程 Agent 是否热门无关。它有一个别处少见的优点:对错可以自动判定,而且在这个刻意缩小的问题上,判定成本极低。程序跑完,退出码加输出断言会共同给出答案。模型的自我感觉在这里没有市场。
3.4.1 场景设计:可自动判定的编程任务
日常开发里最耗神的不是写第一版代码,而是改。
改一版,跑一遍,报错,再改。每一轮都很短。
循环本身不难,难的是每一轮都要人重新读堆栈,重新判断问题出在哪一行。
这个循环有一个很适合自动化的结构。每一轮的输入是上一轮的错误,输出是一份新代码,终止条件由测试结果决定。换成 Agent 的语言,它就是前面讲过的 ReAct(Reasoning + Acting)加反思(Reflexion):ReAct 管步进,行动、观察;Reflexion 管错误回写,反思、再行动。
目标可以写得很朴素。给它一句需求,它调用模型生成 Python 代码,把代码写进临时目录,用独立子进程跑一遍。退出码为 0 且输出符合预期,就结束。否则把错误信息拼回上下文,让它再试一次。最多三轮(代码里的 MAX_STEPS,即轮次上限),超过就停。
这里有两个判断需要提前说清。
第一,终止条件不能只看退出码:一个空程序也能返回 0。它什么都没算,测试却显示通过,这种假通过比直接报错更危险。一个常见的错误示范,是让模型固定返回一句打印语句。程序必然以 0 退出,自愈循环一次都不会触发。本节因此加了输出断言,把跑通和算对分开。
这道断言不难写,却决定了整个 Agent 有没有意义。断言就是尺子。没有它,你造出来的只是一个会写文件的脚本。
注意:只以退出码判断成功,空实现或错误结果会被当成通过,会导致后续流程拿着错误产物继续执行,越走越偏。
第二,循环必须有硬上限:模型可能反复犯同一个错误,也可能在两版代码之间来回摇摆。两种情况下,轮次都会迅速耗尽。没有轮次上限,这个循环会一直烧 Token,直到账单提醒你。
3.4.2 四个零件:模型、工具、循环、反馈
把需求拆开看,这个 Agent 只有四个显式零件。它不是 3.2 节四项能力的直接映射。本节用到其中三项:推理对应模型调用,工具对应 subprocess,上下文对应 messages 的拼接。记忆缺席,因为单次任务不需要跨会话长期记忆;会话内的消息历史属于上下文,由 messages 承担。循环控制来自 3.1 的 Loop,反馈整理来自 3.1 的 Reflexion。三者的关系是:外层是 3.1 的 Loop,单轮「行动—观察」是 ReAct,错误回写是 Reflexion。
- 模型调用(
ask_llm、extract_code):负责生成代码。它读的是消息列表,不是一段拼好的字符串,历史轮次必须按角色保留,否则模型会忘记自己上一轮改过什么。 - 工具执行(
run_once):负责把代码跑起来。本节用subprocess启动一个子进程,拿到标准输出、标准错误和退出码。 - 循环控制(
check、run_agent):负责决定继续还是停止。三个条件参与判断,成功了停,轮次到顶了停,超时了也停。 - 反馈整理(
messages的追加):负责把失败翻译成下一轮的输入。错误堆栈要截断,只留尾部(截多少、为什么,见 3.4.5)。
四个零件里,最容易被低估的是反馈整理。
模型看不到你的终端,它只知道你在消息里写了什么。先喂对,再谈推理。
你把一整页安装日志贴进去,它就会去分析安装日志。你只贴最后 800 字符(约二十行)堆栈,它才会盯着真正的异常类型。输入决定输出,这条规律在 Agent 里比在任何地方都灵。
工具执行也有一个细节。进程隔离是底线。
它必须是子进程,不能是 exec()。子进程能拿到真实的退出码,崩溃了也只是子进程死掉,宿主进程不受影响(只隔离崩溃,不隔离权限与网络,见 3.4.5)。exec() 出错会污染宿主进程,还拿不到干净的结果。
这套结构还有一个隐含的第五个零件:轨迹(Trajectory)。每一轮的代码、输出、错误都要落盘,由 log() 写入。格式用 JSONL(JSON Lines),一行一轮,方便程序读取。没有轨迹,复盘只能靠猜;有了轨迹,至少能看清每一轮改了什么。归因仍需对照实验。
3.4.3 最小可运行实现与四处关键
运行环境是三样东西:Python 3.8 以上(本节在 3.10 上验证)、openai 包、一个兼容 OpenAI 协议的服务。没有现成兼容服务时,可直接用 DeepSeek:base_url 已指向 DeepSeek,改 model 即可。
bash
pip install openai
python healing_agent.py --mock # 不联网,先看修复成功
python healing_agent.py --mock-fail # 不联网,看三轮全失败后熔断
python healing_agent.py # 真实调用模型真实调用需要先在 shell 里设置 DEEPSEEK_API_KEY,代码只从环境变量读,不写进文件。这样代码可以进仓库,密钥不会跟着走。
模型名以 DeepSeek 官方模型列表为准(https://api-docs.deepseek.com/quick_start/pricing,查阅于 2026-11-03),示例用 deepseek-flash。若使用默认思考模式,temperature 不生效(见 https://api-docs.deepseek.com/guides/reasoning_model,查阅于 2026-11-03),代码里的 temperature=0.2 仅对非思考模式有意义。本节两条运行记录均来自 mock 剧本,真实调用路径未实测。
把下面代码保存为 healing_agent.py。为便于阅读,正文按职责拆成三段,拼起来是一个完整文件。
第一段解决「怎么问模型、怎么从回复里取出代码」:常量、系统提示词、模型调用、mock 剧本与代码抽取。
python
import json
import os
import re
import subprocess
import sys
import tempfile
from pathlib import Path
MAX_STEPS = 3
TIMEOUT = 10
EXPECT = [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
SYSTEM = "你是一个 Python 工程师。只输出一段可直接运行的 Python 代码,不要解释,不要加代码围栏。"
def ask_llm(messages):
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com",
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=messages,
temperature=0.2,
)
return resp.choices[0].message.content
# mock 剧本:复现 3.4.4 的修复与熔断两条路径
MOCK_PASS = [
"print(fib(10))",
"def fib(n):\n"
" a, b = 0, 1\n"
" out = []\n"
" for _ in range(n):\n"
" out.append(a)\n"
" a, b = b, a + b\n"
" return out\n\n"
"print(fib(10))",
]
MOCK_FAIL = [
"print(fib(10))",
"def fib(n):\n"
" return 0\n\n"
"print(fib(10))",
"print('still working')",
]
def next_reply(messages, mock):
if mock is None:
return ask_llm(messages)
if not mock:
return "print('mock 剧本已用尽')"
return mock.pop(0)
FENCE = "`" * 3
def extract_code(text):
text = text.strip()
if text.startswith(FENCE) and text.endswith(FENCE):
text = text[len(FENCE):-len(FENCE)]
text = re.sub(r"^(python)?\s*\n", "", text)
return text.strip()第二段解决「怎么把代码跑起来、怎么判定成功、怎么落轨迹」:run_once 负责执行,check 负责判定,log 负责写轨迹。
python
def run_once(code, workdir):
path = Path(workdir) / "solution.py"
path.write_text(code, encoding="utf-8")
try:
p = subprocess.run(
[sys.executable, str(path)],
capture_output=True,
text=True,
timeout=TIMEOUT,
cwd=workdir,
)
except subprocess.TimeoutExpired:
return {
"ok": False,
"timeout": True,
"out": "",
"err": f"运行超过 {TIMEOUT} 秒,已终止",
}
return {
"ok": p.returncode == 0,
"timeout": False,
"out": p.stdout.strip(),
"err": p.stderr.strip(),
}
def check(result):
if not result["ok"]:
return False, "进程非零退出:" + (result["err"] or "无错误输出")
nums = [int(x) for x in re.findall(r"\d+", result["out"])]
if nums != EXPECT:
return False, f"退出码为 0,但输出 {nums} 与预期 {EXPECT} 不符"
return True, ""
def log(step, code, result, ok):
row = {
"step": step,
"ok": ok,
"out": result["out"][-800:],
"err": result["err"][-800:],
"code": code,
}
with open("trajectory.jsonl", "a", encoding="utf-8") as f:
f.write(json.dumps(row, ensure_ascii=False) + "\n")第三段解决「谁来驱动这一切」:run_agent 串起循环、超时与熔断,末尾是命令行入口。
python
def run_agent(task, mock=None):
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": task},
]
for step in range(1, MAX_STEPS + 1):
reply = next_reply(messages, mock)
code = extract_code(reply)
with tempfile.TemporaryDirectory() as tmp:
result = run_once(code, tmp)
ok, why = check(result)
log(step, code, result, ok)
print(f"[step {step}] ok={ok} {why}".rstrip())
if ok:
return True
if result["timeout"]:
print("[终止] 单步运行超时,停止重试。")
return False
messages += [
{"role": "assistant", "content": reply},
{"role": "user", "content": f"第 {step} 轮失败,原因:{why}\n请修正后重新输出完整代码。"},
]
print(f"[熔断] {MAX_STEPS} 轮仍未通过,停止。")
return False
if __name__ == "__main__":
task = "写一个 Python 程序,打印斐波那契数列的前 10 项,从 0 开始。"
if "--mock" in sys.argv:
ok = run_agent(task, mock=list(MOCK_PASS))
elif "--mock-fail" in sys.argv:
ok = run_agent(task, mock=list(MOCK_FAIL))
else:
ok = run_agent(task)
sys.exit(0 if ok else 1)整份代码约一百五十行,真正决定成败的只有四处,正好对应 3.4.2 的四个零件。
系统提示词(System Prompt)与 extract_code 对应「模型调用」。系统提示词要求纯代码,是为了减少噪声;它管不住模型。
即便这样,模型仍可能加上解释,或者自己套一层代码围栏,输出格式不能指望一次就稳定。extract_code 因此保留了兜底正则,匹配不到再退回原文。双保险比只靠 Prompt 更稳。
run_once 对应「工具执行」。这里有三个参数,外加一个工作目录,都不能省。每一项缺了,后果各不相同。
capture_output 把两条流分开收,text 省掉手动解码,timeout 防止死循环。cwd=workdir 同样重要,它让相对路径的读写都落在临时目录里。
路径一乱,错误全是假的。
check 与 run_agent 的循环对应「循环控制」。check 负责定义什么叫成功,成功要能被验证。
数字列表必须与 EXPECT 完全一致,多一个少一个都算失败。这条断言适用于「脚本只打印结果」的场景;如果程序顺带打印了别的数字,re.findall 会把它们一并抓走,正确输出也会被判错。
messages 的拼接对应「反馈整理」,决定了模型能不能从错误里学习。失败的回复放进 assistant,错误说明放进 user,下一轮模型看到的就是一段真实发生的对话,而不是一句抽象的「请重试」。
3.4.4 运行记录:修复与熔断
用 --mock 跑一遍,剧本的第一轮故意给出一份调用未定义函数的代码。输出如下(mock 已验证,真实模型路径未实测)。
text
[step 1] ok=False 进程非零退出:Traceback (most recent call last):
File "/tmp/tmpn9h74g4v/solution.py", line 1, in <module>
print(fib(10))
NameError: name 'fib' is not defined
[step 2] ok=True第一轮的错误很典型:名字没定义。
子进程返回非零退出码,标准错误里有完整的堆栈,check 把它原样交给下一轮。
剧本的第二轮补上了函数定义,输出 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34],与预期一致,循环结束,整个过程没有人工介入,也没有额外的规则引擎。
trajectory.jsonl 会留下两行记录,一行失败,一行成功。失败比成功信息量大。把这两行放在一起看,能清楚看到剧本的两轮分别做了什么:第一轮写了什么,错在哪,第二轮改了什么。
堆栈是结构化程度最高的反馈之一。它有类型、有行号、有调用链,定位问题不需要额外解析。相比「结果不对」这种模糊评价,堆栈几乎等于一份免费的诊断报告。开篇说「判定成本极低」,具体形态就在这里:退出码给答案,堆栈给位置。
注意:轨迹里的
code字段会保存模型生成的完整代码,如果代码里带密钥或内网地址,轨迹文件会把它们一起落盘,导致密钥泄漏,必须在写入前做脱敏。
另一半也要看。换成 --mock-fail 再跑一遍,三轮都失败,循环会一直走到硬上限。
text
$ python healing_agent.py --mock-fail
[step 1] ok=False 进程非零退出:Traceback (most recent call last):
File "/tmp/tmp5c1r2w8q/solution.py", line 1, in <module>
print(fib(10))
NameError: name 'fib' is not defined
[step 2] ok=False 退出码为 0,但输出 [0] 与预期 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 不符
[step 3] ok=False 退出码为 0,但输出 [] 与预期 [0, 1, 1, 2, 3, 5, 8, 13, 21, 34] 不符
[熔断] 3 轮仍未通过,停止。第二轮退出码是 0,却只输出一个 0,这就是 3.4.1 说的假通过,被输出断言挡住了。第三轮干脆没有输出数字,同样被判失败。三轮走完,run_agent 打印 [熔断] 并返回 False。
这一段是硬上限的兑现:少了这道上限,同一个错误会被无限重试,Token 烧完才停。
在这个小任务上,DeepSeek 预期一次就能写对(未实测),看不到修复过程。这正是 --mock 存在的意义:它把修复与熔断两条路径固定下来,方便调试反馈逻辑和终止条件。
3.4.5 四个容易忽略的工程细节
第一,临时目录不是沙箱。
3.3 节第四层列出的 Docker 就是现成的隔离方案。本节先用标准库跑通最小版本。
tempfile.TemporaryDirectory() 只提供一个临时目录(用完自动清理),不隔离文件系统访问、权限、网络与进程。沙箱要单独做。
模型生成的代码在这个进程里能读环境变量,能访问内网,能删掉它有权限删的任何东西。
生产环境必须把执行器放进容器或独立的低权限用户,最好断网,把能碰到的范围压到最小。
注意:直接在主机的当前用户下执行模型生成的代码,一句
shutil.rmtree就能删掉没提交的代码和本机密钥,而且没有快照可回滚。
第二,错误信息要截断。
Python 的堆栈可以很长,尤其是框架调用链。整段拼回上下文,几轮之后就会挤掉任务描述,模型开始答非所问,任务本身反而被淹没。堆栈结构够好,唯一要做的加工是截断。
out 与 err 各保留尾部 800 字符,够定位异常,也不会失控。
第三,超时必须硬性终止。
timeout=10 必须保留,死循环的代码不会自己退出。run_once 捕获 TimeoutExpired 后返回 timeout=True,run_agent 见到这个标记就停止重试,不再把它当成普通的失败交给下一轮。不设超时,模型写出死循环时父进程会一直挂起,整个任务队列都会被卡住。
第四,轮次上限要配合成本预算(Token 预算)。
三轮是一个经验值,适合单文件、小函数。
任务变大以后,轮次要跟着调,同时要盯住 Token 消耗。本节的最小实现只有轮次上限,没有设总预算。真实项目里必须给每次运行设一个总预算,超预算直接终止;否则成本会先于轮次失控。
回到开篇的两个问题。程序怎么知道模型想干什么?系统提示词加 extract_code:把自由文本收成一段可执行代码。怎么判断它干成了没有?check 的输出断言:不看模型怎么说,只看进程输出了什么。
手搓这一遍,前面几节的概念都落了地。范式是骨架,能力是零件,生态是现成的替代品。你可以把这些零件换成 LangGraph 的图,换成 MCP 的工具,换成向量库的记忆,循环的形状不会变。
第四章换一个角度看同一件事:把真实世界里已经跑起来的 Agent 应用拆开,看它们在各自场景里怎么组织这套循环,又在哪里做了取舍。