主题
第 6 章 Agent 架构设计
在开启本章之前,我们首先需要划定一个清晰的边界:本书从这一章开始,只谈论 Agent 的“应用设计与落地交付”,而不去纠缠大模型底层的训练与基础算法。
放在今天,底层的技术栈已经足够成熟,各大开源和商业生态日新月异,甚至 AI 自身已经具备了辅助人类编写和迭代代码的能力。对于绝大多数超级个体与企业而言,盲目去自己搞底层大模型无异于缘木求鱼。
然而,当我们把视线转向应用层时,却常常陷入一种集体迷思:各类炫酷的宣传和 Demo 让人眼花缭乱,给人的直观感觉仿佛 Agent 已经无所不能。但真正上手实操时,大家往往会遭遇当头一棒——“一看就会,一用就废”。
网上的文章拿来一跑,要么是运行环境百般报错,要么是输出结果南辕北辙,要么是跑了几个长链条后 Token 费用直接超标爆炸。
为什么会出现这种“能力很强、交付很弱”的怪圈?答案很简单:因为很多人误以为只要有了大模型,就可以抛弃软件工程。
事实上,Agent 的本质依然是一个复杂的现代软件。只要是软件,它的需求分析、系统架构设计、开发测试、异常熔断与最终调试,就一个环节也少不了。本章,我们就将剥离营销泡沫,聚焦于工程落地本质,系统性地为你拆解——如何进行一个真正能打、稳定交付的 Agent 应用架构设计。
6.1 Agent 应用架构设计的必要性
本章开篇给了一个结论:Agent 的本质仍是软件。结论好懂,但它不能自动回答一个更尖锐的问题:既然模型越来越强,架构设计会不会被模型取代?
这个疑问每隔几个月就会冒出来一次,理由看起来也充分:模型已经能自己写代码、自己拆任务、自己检查结果。
我们的判断是:不会。模型变强,改变的是架构的写法,不是架构的必要性。
本节给出两条理由,外加一层代价。先看 Agent 为什么仍是软件。再看架构为什么仍是意图的桥梁。不写架构会在交付时付出什么代价,放到 6.1.2 的案例里兑现。
6.1.1 Agent 应用依然没有脱离软件的本质范畴
先看变化:相比确定性代码,Agent 确实带来了两处改变。它们常被误读成「不再需要软件工程」。
改变之一:软件开始生成软件
传统程序的大部分能力边界在编译期就定了,能做什么、不能做什么,代码里写得清清楚楚。
Agent 不一样,它可以在运行时写脚本、改配置、造工具,再用这些工具解决下一步的问题。
让它处理一批 CSV,它发现分隔符不统一,会先写一个清洗脚本,再继续。这段脚本不在你的代码库里,是它临时造的。
这确实是新能力,但它没有取消工程约束,只是把约束从「写代码时」挪到了「允许它写什么代码」上。
能读哪些目录、能调用哪些命令、生成的脚本要不要人工确认(人在回路),这些问题模型不会替你回答。
改变之二:感知与推理能力上移
传统软件的输入通常是结构化数据,少一个字段就解析失败。
Agent 能直接读自然语言、日志、截图,甚至一段录音,入口变宽了,这是好事。
代价是输入的边界变模糊了。用户说「把上周的账对一下」,哪一周、对到什么口径、差异多大算异常,这些都没有写在字符串里。
模型会猜。猜对了是运气,猜错了是事故。架构要做的,是把这些猜测变成显式的参数与校验规则。
没有改变:输入、加工、输出
剥掉这两项能力,Agent 剩下的仍是一个信息系统:输入是比特,输出也是比特,中间是加工。
三条会议记录进去,一份周报出来。模型负责理解与组织,系统负责传递、存储、校验与重试。
这三段一段都不能省。省掉输入校验,脏数据会一路传到输出;省掉输出校验,错误会静默落盘;省掉重试,一次抖动就让任务停在半路,得人来接。
未变的约束:边界、状态与成本
既然仍是软件,传统工程的三类约束就仍然成立。而且在 Agent 场景里,它们更贵。
- 边界:模型不知道你所在公司的报销上限,也不知道哪些客户数据不能出内网。工具白名单、目录权限、数据脱敏,只能由架构给定。
- 状态:模型调用本身是无状态的。长任务跑到第 12 步断了,第 13 步从哪里接,靠的是系统侧的检查点(checkpoint),而不是模型记忆。模型记忆有损,不可校验。
- 成本:传统软件按服务器小时算钱,Agent 按 Token 数乘步数算钱。一个 20 步的任务,每步新增输入(不计历史上下文)8000 Token、输出 1000 Token,一次跑完就是 18 万 Token(8000×20 + 1000×20)。这是量级示例,不计价。失败后整体重跑三次(合计四遍),账单就是四倍。工具调用失败还会带来重复推理与上下文回放:每一步重跑,前面的对话都要重新送进模型,输入侧的 Token 再算一遍。没有 Token 预算上限的循环,可以把一次任务烧成一场事故。
把三类约束放在一起看,会发现它们都不是模型能力问题,而是系统设计问题。模型可以更聪明,但它不会主动给自己设预算,也不会在断点处保存状态。
所以,Agent 改变的是软件的形态,不是软件的性质。形态变了,架构要跟着变;性质没变,架构不能不要。
6.1.2 架构设计是向 Agent 传递人类意图的不可省略的桥梁
再说第二条理由。就算承认 Agent 是软件,仍有一个误解:把需求写清楚,模型就能自己长出架构。
这句话在 Demo 里成立,在交付里不成立。
原因在于自然语言天然有歧义。你说「整理得专业一点」,十个人有十种理解,模型还有第十一种。
把这份周报任务原样交给一个没有架构的 Agent,常见的结局是这样:
- 输出是一段话,不是结构化数据,下游报表系统接不了。
- 三条记录被压成一句「支付修复」,丢掉了「重复扣款」这个关键信息。
- 模型补了一句「整体顺利」,但没有任何数据支撑。
连跑三次,可能得到三种格式。这不是模型不努力,是它不知道什么叫「完成」。
这种失败在 Demo 里看不出来,因为演示的人会挑一次成功的结果。到了生产环境,同样的提示词(Prompt)每天要跑几百次,格式抖动就会被放大成故障。
架构的作用,就是把「什么叫完成」写成模型能执行、系统能验收的东西。具体是四件事。
- 角色:谁在做,对谁负责,不能做什么。
- 输出契约(Output Contract):输出什么结构,哪些字段必填,类型是什么,为空怎么办。
- 流程:分几步,每步的输入输出是什么,哪一步需要人工确认。
- 边界:Token 预算多少,失败重试几次,超限之后是停、是降级,还是转人工。
四件事里,最容易被忽略的是流程这一条。项目里更常见的情况,是把流程写在文档里,却没有把它写进代码,结果每一步靠人记,人一忙就乱。
流程要落成三步:生成候选、按输出契约与 Token 预算校验、人工确认后写盘。校验不通过就回到第一步重试。哪一步停、谁来确认,必须写在代码里,而不是留给口头约定。
这四件事写下来,才构成一份可执行的意图;写在文档里叫设计,落进代码里才叫架构。
超级个体和小团队更需要架构。大团队可以用人力补位,每个环节配一个人值守,出错有人接住;小团队没有这个余量,只能让系统自己兜住。
下面这段脚本按输出契约、重试、Token 预算和流程跑同一个任务。示例先判预算再校验契约,重试上限写死为 1 次(共 2 次尝试)。
环境是 Python 3.10 及以上,只用标准库,不需要 API Key。脚本里的模型是写死的假模型,只为让例子能离线运行。真实模型的输出抖动,比这更随机。
python
"""demo_flow.py:输出契约、重试、Token 预算、人工确认与执行轨迹。
Python 3.10+,仅标准库。
"""
import json
import sys
from pathlib import Path
RECORDS = ["周一:登录联调", "周三:修复支付回调重复扣款", "周五:运营后台培训"]
TOKEN_LIMIT, ITEM_KEYS = 1500, {"day", "work", "status"}
def call_model(prompt: str, attempt: int) -> tuple[str, int]:
"""假模型:第 1 次返回自由文本,第 2 次返回合法 JSON。"""
if attempt == 1:
return "本周完成了登录联调、支付修复和运营培训,整体顺利。", 580
rows = [("周一", "登录模块联调"), ("周三", "支付回调重复扣款修复"), ("周五", "运营后台培训")]
items = [{"day": d, "work": w, "status": "done"} for d, w in rows]
return json.dumps({"week": "2026-W45", "items": items}, ensure_ascii=False), 860
def validate(text: str) -> dict:
data = json.loads(text)
if not isinstance(data, dict) or not isinstance(data.get("week"), str):
raise ValueError("week 字段缺失")
items = data.get("items")
if not isinstance(items, list) or not items:
raise ValueError("items 必须是非空列表")
if not all(isinstance(x, dict) and ITEM_KEYS.issubset(x) for x in items):
raise ValueError("条目字段不全")
return data
def save_trace(trace: list) -> None:
"""执行轨迹落盘:成功、中止、异常三条路径都要留证据。"""
Path("trace.jsonl").write_text("\n".join(map(json.dumps, trace)) + "\n", encoding="utf-8")
def main() -> None:
prompt = "把下面的会议记录整理成周报:\n" + "\n".join(RECORDS)
trace, used = [], 0
try:
for attempt in (1, 2):
text, tokens = call_model(prompt, attempt)
used += tokens
trace.append({"attempt": attempt, "tokens": tokens})
if used > TOKEN_LIMIT:
raise RuntimeError(f"Token 预算超限:{used} > {TOKEN_LIMIT}")
try:
data = validate(text)
except ValueError as exc:
trace.append({"attempt": attempt, "error": str(exc)})
continue
written = "非交互环境,跳过确认,写出"
if sys.stdin.isatty():
if input("[流程] 生成周报后是否继续?(y/N) ").strip().lower() != "y":
trace.append({"step": "confirm", "result": "human_stop"})
return
written = "确认后写出"
Path("weekly.json").write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"[flow] 第 {attempt} 次通过校验,{written} weekly.json")
return
raise RuntimeError("流程中止:校验失败或人工未确认")
finally:
save_trace(trace)
if __name__ == "__main__":
main()运行结果:
bash
$ python3 demo_flow.py < /dev/null
[flow] 第 2 次通过校验,非交互环境,跳过确认,写出 weekly.json
$ python3 demo_flow.py # 有终端时先问 y/N
[流程] 生成周报后是否继续?(y/N) y
[flow] 第 2 次通过校验,确认后写出 weekly.json两次调用用的是同一个假模型,差别在脚本这层壳。第 1 次返回的自由文本被 validate 挡下,json.loads 抛异常;脚本没有把它写进正式文件,而是记进执行轨迹(Trace),转入下一次尝试。
第 2 次通过校验,确认点放行后写出 weekly.json,字段齐全,下游可以直接消费。整个过程输出侧用了 1440 Token,没有超过 1500 的 Token 预算。本节预算只约束输出侧,输入另计。
确认点只在有终端时生效;管道或 CI 下应按无人值守流程处理。
注意:没有输出契约时,下游要么解析报错,要么把自由文本当字段写进库;两种都要人收尾。
这段代码没有让模型变得更聪明。它做的是三件事:定义什么算合格,决定失败之后怎么办,留下可复查的证据。有人会说,加这层壳不就是多写代码吗,模型迟早能自己生成。这个判断只对了一半。
模型能生成校验函数,但哪些字段必填、为空怎么办,只能由人给。这就是架构的位置。它不生产智能,它生产确定性。
模型变强之后,这三件事会变轻,但不会消失:模型能自己写 JSON、自己重试、自己解释失败,契约、预算与责任仍然要人给。
能力越强,越需要有人告诉它边界在哪;这不是对模型的不信任,是对交付的负责。
文档会过期,代码里的约束不会:校验函数还在,预算还在,检查点还在,系统就还能按原来的边界运行。反过来,我们的经验是文档写得很全、代码里一条校验也没有。
一份输出契约、一个预算上限、一份检查点,写起来不过几十行,省下的是整晚的排查。
回到开头的疑问:模型变强,架构不会消失,因为架构管的是模型管不到的部分。
能力强决定上限,架构稳决定下限。Agent 给了我们很高的上限,但交付看的是下限。下一节给出架构设计的整体套路。
6.2 Agent 应用架构设计模式
6.1 论证了架构设计的必要性。本节回答另一个问题:按什么套路设计。
很多团队在这里会走向两个极端。一种是直接把微服务、分层架构原样搬过来。另一种是干脆不设计,先写一段提示词(Prompt)跑起来。
这两种做法都会付出代价。前者在集成阶段暴露,后者在成本和稳定性上暴露。
我们的判断是:Agent 应用的架构设计模式,不是一套重新发明的模式。它借用了软件工程里常见的分段习惯(业务分析、架构设计、任务流),在 Agent 场景下重新排布了重心。
本节只给骨架,具体做法留给 6.3 到 6.5 三节展开。
6.2.1 模式的重心:从划分模块到约束不确定性
传统软件架构的核心工作,是把系统划分成职责清晰的模块。输入确定,输出确定,模块之间的契约可以用接口和类型写死。
同步 RPC(远程过程调用)与分层契约被照搬。问题出在契约的前提。上层把模型的输出当作确定值,下游按字段类型校验,一次格式漂移就整链失败;重试被当成幂等操作,实际每次重试都可能重复计费。
分层也会被穿透:Agent 拿着工具权限直接调用底层接口,所谓边界只剩文档上的一行。
Agent 应用多出两个变量。第一个是推理过程不确定,同一个输入可能走出不同路径。第二个是工具会动态增加,Agent 可以在运行时生成脚本,或者调用新的 Skill。
我们认为,这两个变量不会因为模型升级而消失,反而会随着工具数量增加而放大,也会随着业务链路变长而放大。所以架构要解决的不是某一次推理的对错,而是整条链路在异常输入和工具故障下的可控性。
这两个变量决定了架构重心必须前移,但模块怎么划分依然重要。更关键的问题是:哪些环节必须确定、哪些环节允许不确定、边界画在哪?
一条可以直接使用的判据是:凡是会花钱、会写入数据、会对外发请求的动作,都交给确定性代码执行,Agent 只负责给出参数和判断。
反过来,理解意图、归纳信息、生成草稿这类工作可以交给模型,它们错了可以重来,代价可控。
注意:让 Agent 直接执行写库或付款动作,会导致错误无法回滚,账目和业务状态也会错乱。
这条判据看起来简单,真正落地时会牵出一整条工程链路。它的作用是先画边界,再谈实现。参数怎么校验,失败怎么重试,重试几次后转人工。这些都属于架构问题。不属于 Prompt 问题。
把重试逻辑写进系统提示词(System Prompt)。这是常见的错误做法。模型每次重试的方式往往都不一样。问题会被暂时掩盖,最后在账单和故障记录上暴露。代价会迟到。
以报销审批为例。发票识别和摘要生成可以交给模型,金额校验、审批流和付款必须由代码完成。识别错了,人工改一张票即可,损失可控。付款错了,追回成本远高于一次人工复核,还可能影响供应商关系。
6.2.2 三段式:业务分析、架构设计、任务流
我们把这条链路拆成三个连续的动作。每一段都有明确的产出物和退出条件。
- 业务分析:回答值不值得做、边界在哪里。产出物是问题定义、知识资产盘点、成本上限、验收标准和岗位映射与审批节点(拆岗定义见 6.3.4,架构侧映射见 6.4.7)。
- 架构设计:回答系统长什么样。产出物是 Agent 框架选型、人与 Agent 的角色映射、通信协议、目录结构、存储底座和结构化知识(这是最小面,完整八根支柱见 6.4)。
- 任务规划与执行流程(下称任务流):回答一次任务怎么跑完。产出物是计划拆解方式、人在回路(Human-in-the-Loop)节点、调度载体(
dispatch)和人机界面。
三段的退出条件必须写死。三段有先后,顺序不能反。业务分析没有验收标准,不进入架构设计。架构设计没有角色映射,不进入任务流。任务流没有人在回路节点,不上线。
每段只设一道跨段门禁,其余产出物段内自检,不构成进入下一段的条件。
三段之间不是瀑布式的单向传递。业务分析改了验收标准,架构设计就要调整存储和成本策略。架构设计换了 Agent 框架,任务流的调度载体也要跟着换。
任务流在压测中暴露的问题,还会反过来修正业务分析和架构设计的假设。这个循环通常会跑很多轮,直到三段的假设彼此对齐为止。
举个具体的例子。业务分析最初要求单份合同审阅不超过 3 分钟,架构设计选了本地小模型。压测发现小模型漏检率过高,任务流只能增加一次人工复核。复核一加,3 分钟的目标就守不住了。
最后还是回到业务分析,把验收标准改成 5 分钟,同时把高风险合同单独分流。
这里最容易犯的错误,是把三段做成三份互不相关的文档,文档写完,项目照旧失控。
原因不复杂:文档描述意图,机器执行约束。意图会随时间漂移,只有约束才会被机器稳定执行。
所以三段式的每一段都要落成可检查的东西。验收标准要能写成测试用例,角色映射要能写成配置,流程模型用状态机或 DAG(有向无环图),调度载体取队列(queue)或直调(direct):批量任务通常用队列,单机或单进程部署用直调。
6.2.3 三个反模式
在进入代码之前,先看三个常见反模式(Anti-Pattern)。它们分别对应三段式的缺失,顺序也按三段式排列。
- 提示词堆叠(Prompt 堆叠):所有规则都塞进系统提示词,改一处影响全部。这是业务分析缺失的表现,因为没人说清哪些规则真正需要。
- 无状态重跑:失败后从头再来,已经完成的步骤全部作废。这是架构设计缺失的表现,状态没有地方存放。
- 全自动长链:从接收任务到交付结果,中间没有人工检查点。这是任务流缺失的表现,错误会在末端放大。
提示词堆叠的典型症状,是系统提示词越来越长,没人敢删任何一句。无状态重跑的典型症状,是账单随重试次数线性上涨。全自动长链的典型症状,是演示时很顺,一旦遇到异常输入就卡死。
这三个反模式的共同点,是拿局部手段去补结构缺口:Prompt、重跑、自动化,都只能把问题推迟到更贵的地方暴露。
判断一个团队是否真的在做架构,看它有没有留下可执行的约束。只有文档没有约束,说明架构还停留在讨论阶段。
6.2.4 可校验的架构契约
下面把三段式的产出物固化成一个数据结构。程序在启动前做一次校验,关键项缺失返回错误。先定契约,再写实现。运行环境是 Python 3.10 及以上,只使用标准库。
6.2.4.1 契约字段
| 段 | 字段 | 类型 | 含义 |
|---|---|---|---|
| 业务分析 | problem / assets / budget_cny / acceptance | str / list[str] / float / list[str] | 问题定义、知识资产、成本上限、验收标准 |
| 架构设计 | runtime / roles / protocol / storage / knowledge | str / dict[str, str] / str / str / list[str] | Agent 框架、角色映射(键固定 human / agent,值填具体岗位)、通信协议、目录结构与存储底座、结构化知识 |
| 任务流 | planner / human_gates / flow_model / dispatch / ui | str / list[str] / str / str / str | 计划拆解、人在回路节点、流程模型、调度载体、人机界面 |
flow_model 取 state_machine 或 dag,回答「流程怎么建模」;dispatch 取 queue 或 direct,回答「任务怎么派发」。两者是两个维度,不要合成一个字段。
AgentAppContract 含 business / architecture / flow 三个属性,分别对应上表三行,各字段名即属性名。dataclass 定义按字段表直译,这里只留核心校验。
python
def validate(app) -> list[str]:
errors: list[str] = []
if not app.business.acceptance:
errors.append("业务分析缺少验收标准")
if app.business.budget_cny <= 0:
errors.append("业务分析缺少成本上限")
if not {"human", "agent"} <= set(app.architecture.roles):
errors.append("角色映射必须至少包含 human 与 agent")
if not app.flow.human_gates:
errors.append("任务流缺少人在回路节点")
if app.flow.flow_model not in {"state_machine", "dag"}:
errors.append("流程模型必须是 state_machine 或 dag")
if app.flow.dispatch not in {"queue", "direct"}:
errors.append("调度载体必须是 queue 或 direct")
return errors题注:上面只保留核心校验,完整 dataclass 定义见 6.2.4.1 字段表。
以合同审阅助手为例:验收标准取「漏检率低于 3%」「单份审阅时间低于 5 分钟」(示例取值,与 6.3 案例目标一致),高风险合同由人在回路节点暂停分流;flow_model 取 state_machine,dispatch 取 queue。校验通过时返回空列表。
6.2.4.2 校验的边界
这段校验的价值很具体。它把口头约定变成了启动自检。角色映射少了一方,校验失败;验收标准为空,校验失败;flow_model 写了不存在的类型,同样失败。
它也可以接进 CI(持续集成):每次修改架构,校验过了才谈上线;架构评审同样可以直接看校验结果和字段取值,不必逐页翻文档。
需要说明边界:这份契约只能检查结构是否齐全,不能检查结构是否合理。成本上限填了 2000 元,不代表这笔钱真的够用。人在回路节点写了三个,不代表位置正确。角色映射写了两方。但职责可能重叠;验收标准写了三条。但可能互相矛盾。
这些只能靠评审和试运行判断。
另外两点。第一,本契约只覆盖单应用的最小角色面,多 Agent 拓扑见 6.4.7。第二,这五个架构字段是 6.4 八根支柱的最小检查面,清单见 6.4 开篇。knowledge 对应 6.4.4 与 6.4.6;6.4.4 的介质转换工具选型、6.4.5 人类专家接口、6.4.8 能力提取,是契约之外的增量。
6.2.5 与后续内容的关系
接下来的三节,会分别展开这三段的具体做法。
阅读顺序上,我们建议先读 6.3,再读 6.4,最后读 6.5。这个顺序和实际项目的首次推进顺序一致。也和三段式的依赖关系一致。执行阶段的回环见 6.2.2。
三节读的时候,各自盯住前面列出的产出物。三节读完之后,再回头重读本节的三段式。读者应该能把它还原成一张属于自己的架构图。
如果本节只留一句话,那就是:Agent 应用的架构设计,本质上是在给不确定性划定边界。边界之内交给模型,边界之外交给代码。
6.3 业务分析
6.2 把 Agent 应用的落地拆成三步:业务分析、架构设计、任务规划与执行流程。 本节讲第一步。它看起来最不像技术活,却最容易埋下返工的种子。
传统软件的需求分析,产出是一张功能清单。 谁能登录、点哪个按钮、数据写到哪张表,写清楚就能开工。 Agent 应用不行:它的输入是自然语言,输出带概率,同一句话跑三遍可能给出三种答案。
所以业务分析要回答四个问题:这门生意怎么运转,手里有什么知识,投入产出划不划算,人站在哪个位置。 每个问题各占一小节,我们用一个贯穿案例对照着讲:某工程公司想用 Agent 做投标文件(标书)初审。
这家公司近三年累计收到六千余份标书,其中两千份已数字化,本书按每年两千份的稳态量算账。
法务和商务各出三个人看,一份平均四十分钟,六人同时看,按墙钟(wall-clock)总耗时计;漏检率约百分之八。
数字是项目方给的,后面每一步都用它算账。
四小节合起来的交付物是一份业务蓝图:业务定位、知识资产清单、单位经济模型与预算约束、岗位映射与审批节点。 这份蓝图怎么交到下一节,见 6.3.4.3。
6.3.1 梳理业务本质
梳理业务本质,是第一件事:先把大模型的光环放一边,不要问它能做什么,要问这门生意原来怎么运转。 运转方式清楚了,Agent 该插在哪一段,自然就清楚了。 具体拆成四个动作:问定位、定模式、看介质、写契约。 第一个动作内部再分四问,其余三个动作各解决一件事。
6.3.1.1 问定位:四问核心
第一问,解决什么问题:要找到最痛的那一段,而不是笼统地说提高效率。 标书初审的痛点是漏检和耗时,漏检一次可能直接废标,耗时长了投标窗口就压不住。 这两个痛点都能量化,也都能验收。
第二问,替代哪段流程:只替代一段,不要一上来替代整条链路。 标书项目里,Agent 做资格条款核对、格式检查与缺件识别,法务终审仍然由人做。 真正的理由是责任要有人担:技术做得到,不代表能把这些环节交出去,留在人手里,项目才推得动。
第三问,提升多少效率:目标要写成可验收的数字。 至少要三个数字:时间、质量与人力,缺一个都不算完整目标。 具体数值见 6.3.3,那里要拿它们算账。
第四问,占据什么位置:人机协同有三档,先看清再选。
- 副驾驶(Copilot):Agent 只给建议,人做全部决定。
- 人在回路(Human-in-the-Loop,HITL):Agent 执行,关键节点由人审批。
- 全自动(Full-Auto):Agent 全自动执行,人只看日志。
档位选错,后果很直接:标书漏检会导致废标,所以标书项目只能停在第二档。
涉及资金支付、对外发布、数据删除等操作,默认人在回路。分级表与判断理由见 6.3.4.2。这条判断不因模型变强而改变:模型越强,错误越隐蔽,人的复核越不能省。
6.3.1.2 四大交互模式
模式决定架构骨架。先认模式,再谈框架。 模式说做什么,档位说人管多少,两者不是同一个问题。
- 问答模式(QA):围绕知识库做检索与回答,架构重点在切片、召回与引用。
- 生成模式(Generation):按格式产出新内容,架构重点在模板、约束与校验。
- 分析模式(Analysis):从大量材料里提炼结论,架构重点在批次、聚合与证据定位。
- 操作模式(Action):调用外部系统执行动作,架构重点在权限、幂等与审计。
四种模式不是互斥的,但一个项目要有一个主模式。 主模式决定大部分的架构工作,辅助模式挂在旁边。 标书初审的主模式是分析,辅以问答:它要读两百页 PDF,找出缺件、错项与越界条款,再把结论交给法务。
如果把主模式误判成问答,架构就会退化成一个聊天框,既读不完长文档,也定位不到条款。
判断方法很简单,看交付物:是一段回答就是问答,是一份新文档就是生成,是一张结论表就是分析,是一次系统状态变更就是操作。 交付物一旦认错,后面的目录结构与任务编排也会跟着错。
6.3.1.3 输入介质与预处理
介质决定预处理链路,也决定成本上限。
- 文本(Text):PDF、Word、Markdown、JSON、日志。
- 语音(Voice):会议录音、客服通话。
- 图片(Image):截图、扫描件、图纸。
- 视频(Video):演示片、监控画面。
标书基本都是扫描 PDF,这一类输入不能直接丢给模型。 扫描件要先过 OCR,再把版面还原成段落与表格。 我们在项目里用 300 dpi 重新扫描,低于这个值,表格竖线容易断,金额列会错位。
注意:扫描件不做 OCR 直接送进模型,会导致表格错行,金额与工期字段读错。
介质组合要提前写清楚:是纯文本,还是图片加文本的混合输入,决定了后面要不要接视觉模型,也决定了单份成本。 一份两百页的扫描标书,OCR 加版面还原通常要几十秒到几分钟,这个时间要算进端到端延迟,不能只算模型推理。
6.3.1.4 数据契约
介质管输入,契约管输出。契约是一份双方共同认可的格式约定,写清楚字段、类型与取值范围。 没有契约,模型今天返回三段话,明天返回一张表,下游解析就会失败。
下面这份 JSON Schema 就是标书初审的输出契约。
json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["file_id", "verdict", "risks"],
"properties": {
"file_id": {"type": "string"},
"verdict": {"enum": ["pass", "review", "reject"]},
"risks": {
"type": "array",
"items": {
"type": "object",
"required": ["clause", "level", "evidence"],
"properties": {
"clause": {"type": "string"},
"level": {"enum": ["high", "medium", "low"]},
"evidence": {"type": "string"}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}这里有三处关键约定。 第一,verdict 只有三档:pass、review、reject。 review 表示要人看,reject 表示硬性不合格,下游系统只认这三档,不接受自由文本。
第二,risks 里每条都要带 clause 与 evidence,clause 是条款号,evidence 是原文位置与摘录。 没有证据的风险项一律丢弃,这是防幻觉最省事的一招。
第三,顶层与 risks 每条都写 additionalProperties: false,多出来的字段一律判不合规。
把上面这份 Schema 存成 bid_schema.json,校验代码只读它,不抄第二遍字段。 运行环境是 Python 3.10 以上,先装依赖:pip install jsonschema。
python
import json
from jsonschema import validate
schema = json.load(open("bid_schema.json", encoding="utf-8"))
payload = json.load(open("result.json", encoding="utf-8"))
validate(instance=payload, schema=schema) # 不合规会抛 ValidationError校验通过时什么都不输出;不合规时直接报出字段路径与原因。
注意:若漏写
additionalProperties: false,模型多返回的字段会通过校验,入库时可能因多一列被拒绝。
失败语义也属于契约。模型超时、OCR 失败、条款找不到,各自该怎么办,都要在业务分析阶段定好。 业务分析不写代码细节,但要写清楚出错时系统应该表现成什么样。
6.3.2 盘点现有知识资产
第二件事,盘家底。Agent 的推理能力再强,也替代不了领域知识。 很多项目上线即瘫痪,问题往往出在知识供给:该给的知识没给,或者给的方式不对。
知识资产不只是数据库里的表:制度、SOP、历史案例、专家经验、系统日志,都算。 盘的时候分两类:已数字化的,和没数字化的。
6.3.2.1 两类知识
已数字化的知识,躺在硬盘、网盘、数据库与工单系统里。 它们并不缺,问题是散、旧、格式乱。 未数字化的知识,在老专家脑子里,在车间的设备状态里,在纸质档案柜里。 对 Agent 来说,这部分等于不存在。
6.3.2.2 把隐性知识与物理状态变成可读数据
先看标书项目的家底:已数字化两千份,另有评标细则与近三年废标记录;未数字化的部分包括八位评标专家的判断习惯,比如哪些条款看起来合规、其实要重点看,后者才是真正的壁垒。这八位专家是历史标注资源,不在六人初审组内。
专家脑子里的东西,要靠人来挖。 方法不复杂,但很费工:选样本、做访谈、让专家标注,再把标注归纳成规则。
标书项目做了三个月;三个月是阶段跨度,八位专家并非全职投入。 这八位专家每人标注二十份历史标书,标出哪里会废标、哪里可以放过。 从这一百六十份标注中归纳出六十三条否决条款,写成结构化的检查项。
这一步没有捷径:模型不能替专家说出他自己都没写下来的判断。 我们能做的是把访谈问题设计好,把标注界面做轻,让专家愿意多标一轮。
物理世界的知识,靠采集设备转成比特。 高拍仪、3D 扫描与传感器读数,都是同一类工作:把实体状态映射成模型能读的数据。 采集精度要提前定,精度不够,后面再好的模型也补不回来。
6.3.2.3 静态与动态
已数字化的知识,还要再分一层:静态知识变化慢,制度、SOP 与评标细则一年改一次。 这类知识清洗一遍,切成块,灌进检索库就行。
动态知识变化快,中标结果、黑名单、供应商资质与市场价格每天都在变。 这类知识必须有更新频率与同步通道。 没有更新机制的知识库,三个月后就会给出过时答案,而且错得很自信。
我们的做法是给每类知识标三个字段:来源、更新周期与责任人。 黑名单每天同步一次,资质每周一次,评标细则随发文更新。 任何一个字段为空,这条知识就不允许进库。
6.3.2.4 配套工具
知识要流动,得有工具。
- 提取工具:从文档与对话里抽实体与关系。
- 校验工具:让专家改错、补充与驳回。
- 交互工具:让专家在日常工作里顺手补一条经验。
- 映射工具:把结构化知识转成提示词(Prompt)、检索索引或 MCP 服务端(MCP Server)。
盘点做到最后,要落到一张清单上:写清每条知识在哪、什么格式、多久更新、谁来负责。 这张清单直接决定知识库怎么建(见 6.4)。
盘点时最常犯的错,是把『文件已归档』当成『知识已就绪』。 文件在,不等于可检索、可引用、可更新。
6.3.3 经济性评估与预算约束
第三件事,算账。 本节最常被跳过,也最容易出事。 市面上有一种说法:『部署 Agent 就能少花钱、多办事』。这话只说了一半。 Agent 要花算力、要花人力、要花维护成本,没有免费劳动力这回事。
6.3.3.1 收益的三本账
第一本,时间:单份处理时间缩短多少,要用贯穿案例的基线折算成分钟数,这是最硬的一笔收益。
第二本,直接成本:API 费用、渲染算力与存储,要和原来的外包费、软件许可费对着算。 第三本,人力与隐性损耗:人力不只是工资,还包括管理、沟通与返工。 Agent 能吃掉重复劳动,但吃不掉协调成本。
三本账定的是结构,标书项目的数字统一在 6.3.3.3 算一遍。
6.3.3.2 两个边界
算完收益,还要算边界,边界决定预期,也决定组织怎么配。
第一个边界,人力底线:Agent 不能替代所有环节。 总有节点需要人签字、担责、处理例外。 十个人的团队,优化后可能还剩两个做复核;业务翻倍,人可能要加到四个。 这不是线性替代,而是比例替代。 把这个底线想清楚,才不会对裁员幅度产生错误预期。
第二个边界,时间与产能:算力堆得再多,也快不过串行环节。 OCR 要时间,外部接口要响应,法务要签字,这些步骤不能被 Agent 加速。
阿姆达尔定律说得很清楚:系统加速比受串行部分限制。 一条一百小时的流程,如果串行部分占五十小时,理论上限就是两倍。 先找出串行段,再谈提速目标。
6.3.3.3 单位经济模型
算账之前,先把目标落成三个数字,并注明来源:单份初审从四十分钟降到八分钟(四十分钟为项目方给定的基线,八分钟为目标值),漏检率从百分之八降到百分之三以下(百分之八为试点实测基线,百分之三为目标值),人工只复核被标记的百分之二十(项目方给定)。
三个数字分别对应时间、质量与人力,进入单位经济模型时各有落点:省下的分钟数与 API 单价决定单份收益,复核比例决定人力成本,漏检率是验收指标、不进成本模型。
时间账按墙钟口径计,只把串行等待的时间折成人力成本。
如果按六人同时投入的工时口径算,单份节省折合 3.2 人时,净收益约 380 元,回本约 79 份;本节采用更保守的墙钟口径,回本 496 份。
把账算成代码。这比写在 PPT 上可靠。 下面这段脚本不依赖第三方库,把单份 API 成本、月成本、年成本与回本份数一次算清。 价格是示例值,换成你手上的供应商报价再跑。
python
# 运行环境:Python 3.10+,无第三方依赖
def per_case_cost(in_tokens, out_tokens, price_in, price_out, calls=1.0):
return (in_tokens * price_in + out_tokens * price_out) * calls
def break_even_units(fixed_cost, margin_per_unit):
if margin_per_unit <= 0:
return None
return fixed_cost / margin_per_unit
# 示例价格:输入 2 元/百万 Token,输出 8 元/百万 Token
in_tokens = 100_000 # 200 页 OCR 文本约 10 万 Token
calls = 1.3 # 1 次主调用 + 0.3 次重试/多段
api_cost = per_case_cost(in_tokens, 1_500, 2.0 / 1e6, 8.0 / 1e6, calls=calls)
# 案例口径:2000 份/年
monthly = api_cost * 2_000 / 12
yearly = api_cost * 2_000
print(f"单份 API 成本 {api_cost:.4f} 元,月成本 {monthly:.2f} 元,年成本 {yearly:.2f} 元")
fixed_cost = 30_000 # 一次性投入示例假设值:开发 1.5 万 + 设备与 OCR 5 千 + 专家标注 1 万
saved_minutes = 32 # 单份节省 32 分钟
hourly_rate = 120 # 综合人力成本,元/小时
review_cost = 0.20 * 8 / 60 * 120 # 两成送复核,每份 8 分钟
margin = saved_minutes / 60 * hourly_rate - api_cost - review_cost
print(f"单份净收益(仅 API+复核){margin:.2f} 元,回本需 {break_even_units(fixed_cost, margin):.0f} 份")输出是:
text
单份 API 成本 0.2756 元,月成本 45.93 元,年成本 551.20 元
单份净收益(仅 API+复核)60.52 元,回本需 496 份四百九十六份。按每年两千份的稳态量算,不到三个月回本。
这里的净收益只扣了 API 与复核两项,渲染、存储与维护成本未计入,实际回本份数会比这个数字高。 在 3 万元一次性投入的假设下,这个结果说明项目值得做。 红线的位置可以倒推:按每年两千份、五年回本算,一次性投入超过约 60 万元就不成立,那就该重新设计范围,而不是硬上。
6.3.3.4 一个反面案例
有一个流传很广的教训,值得单独说。 一位从业者的家人买了 AI 生成短视频的教程,用 Agent 批量做视频发到平台。 链路是通的:选题、文案、剪辑与发布全自动,也确实拿到了流量分成。 但盘点这本账时,问题暴露了:买 Token 与渲染算力花了一百元,最终流量收益九毛钱。
这不是技术问题,而是商业模型不成立。 全人类的注意力是有限的。 按八十亿人、每人每天看十小时算,全球每天的注意力池是八百亿小时。
AI 把内容生产成本压到接近零。下面的供给量是量级假设,不是实测数据:按每天一万亿小时计(乐观下限,折合每人每天 125 小时),全球每天八百亿小时的注意力,摊到每小时内容上只有 0.08 小时,也就是 4.8 分钟。 一条三分钟的视频,期望被看到的时长是 3×60×0.08=14.4 秒。 若供给按三倍计(每天三万亿小时),折算下来只剩约 5 秒;供给每翻一倍,期望时长就减半,这条规律与三倍假设互不替代。
结论很直接。 如果一个 Agent 项目只是在高效地生产没人看的东西,效率越高,亏得越快。 技术可行不等于商业可行,业务分析阶段必须把这句话摆在桌面上。
把这个教训翻译成工程参数,就是一条预算约束:注意力是稀缺资源,产出先要证明有人要,才值得投算力。 落到设计上,每个任务都要有 Token 上限与成本上限;超限时不加预算,直接降级:缩短输出、减少批次,或者直接转人工。 这一条直接接上 6.3.3.5 的五类参数。
6.3.3.5 目标写进预算
算完账,结论要落成硬约束。
- 单任务 Token 上限。
- 日成本上限。
- 失败重试上限。
- 人工复核比例。
- 熔断条件。
这些上限不是财务指标,而是架构参数。 它们会直接落进 6.4 的超时设置、重试策略与监控告警里。 业务分析不产出这些约束,架构设计就只能拍脑袋。
6.3.4 人员角色与组织架构
第四件事,安排人。 市场上常见的说法是 Agent 会取代整个部门,真实的工程实践不是这样。 Agent 改变分工,并不取消分工。 组织还在,只是有些岗位从人换成了 Agent,有些岗位从执行变成了复核。
6.3.4.1 先按碳基团队拆岗
做法很朴素。先假设这件事完全由人做,再问需要哪些岗位。 不要一上来就想 Agent,先想人,再想映射。
标书项目拆成三个组。
- 知识工程组:收集历史标书、清洗、切片、维护检索库。
- Agent 开发组:写 Prompt、接 OCR、做校验、接业务系统。
- 运维与风控组:盯任务状态、看成本、处理异常、做审计。
每个岗位写三样东西:职责、输入与产出。 职责是边界,输入是依赖,产出是验收标准。 这三样写不清,映射到 Agent 就会变成一个什么都干、什么都干不好的万能助手。
6.3.4.2 映射的三条规范
碳基(人)与硅基(Agent)的差别要先认。 人执行慢,但有常识、有默契、会主动发现问题。 Agent 执行快,但没有默认默契,不会猜你的意思,也不会自己发现这份标书该盖骑缝章。
第一条,显性契约:人与人之间说『整理一下文档』,默认包含排版、纠错与目录对齐。 Agent 不理解这个默认。 所以角色定义要写清三件事:你是谁,你不能做什么,什么算做完。 角色定义第三条,什么算做完,最重要:没有完成标准,Agent 会一直在差不多的状态里打转。
第二条,知识切片:人入职后会自己观察、自己学,Agent 不会。 它的全部世界就是你给它的上下文。 所以每个角色只给它这个岗位需要的资料。 把全公司的文档塞给每一个 Agent,注意力会被稀释,关键信息会被淹没。
第三条,授权边界:Agent 执行快,错误也放大得快。 哪些动作可以全自动,哪些必须人批,要按后果分级。
| 动作类型 | 例子 | 档位 | 附加要求 |
|---|---|---|---|
| 只读操作 | 检索、摘要、分类 | Full-Auto | 留日志 |
| 写内部系统 | 建单、改状态、写库 | Human-in-the-Loop | 留日志、可回滚 |
| 对外发布 | 公告、标书提交 | Human-in-the-Loop | 双人复核 |
| 资金支付 | 付款、报销 | Human-in-the-Loop | 双人复核 |
| 数据删除 | 清库、销号 | Human-in-the-Loop | 双人复核 |
后面遇到分级,直接回这张表查。
这三条来自传统权限模型的移植,是必然结果,并非可选建议。 Agent 越像员工,越需要岗位说明书与权限表。
6.3.4.3 把责任写进流程
人在回路不只是加一个确认按钮。分级的判断标准见 6.3.4.2,这里只写落地三件事:谁签、看什么、超时怎么办。
标书项目里,高风险条款必须法务签。 签之前,系统把证据定位到页码与段落,法务只看这几页。 超过四小时未签,任务挂起并通知主管,不默认通过。
注意:若设为审批超时默认通过,会导致高风险条款无人复核,直接进入投标。
四小节做完,业务分析才算有了交付物。
一份业务蓝图,包含四块:业务定位与量化目标(数字见 6.3.3)、知识资产清单、单位经济模型与预算约束、岗位映射与审批节点。 这四块交给 6.4,架构设计才有输入。 没有这份蓝图,架构讨论会变成框架偏好之争,谁也说服不了谁。
6.4 架构设计
架构设计是软件工程里最不显眼的一步,代码还没写,它先把系统边界划好。系统平稳运行时没人提它,出了事故才知道这一步值多少钱。
Agent 应用没有削弱架构的价值,模型越强,架构反而越重要。原因不复杂:模型输出是概率的,系统交付必须是确定的,中间那层确定性只能由架构提供。
在 Agent 应用里,架构是人和 Agent 之间的一份契约。它划系统边界,约束调用链,规定消息格式,指定数据落点,把人的意图翻译成机器能稳定执行的结构。
契约一旦含糊,模型就会在长链条里不断猜。猜错一次,后面十步都建在错误前提上,最后表现为幻觉、跑偏、重复劳动和账单上涨。
6.3 结尾交给架构四块业务蓝图:目标、预算、知识清单、岗位与审批。这四块不是背景材料。它们直接变成架构约束,分别落到验收标准、选型上限、知识预置与组织映射,具体落点见各节。
本节按八根支柱拆解 Agent 应用的架构设计。顺序是框架、协议、目录与存储、知识数字化、人类专家接口、知识预置、组织映射和能力提取。
架构文档不需要写得很长,但必须能回答四个问题:边界在哪,谁调用谁,数据放哪,失败怎么办。四个问题答不上来,代码写得再熟,系统也只是一个演示。读者可以把这八根支柱当成一份检查清单,逐项对照自己的系统。
四个问题不是另一套框架,它们与八根支柱是同一套东西的两种问法,对照关系如下:
- 边界在哪:6.4.1 框架选型与 6.4.7 组织映射,划系统边界与责任边界。
- 谁调用谁:6.4.2 通信协议与 6.4.7.2 组织拓扑,给调用关系与回执路径。
- 数据放哪:6.4.3 目录与存储、6.4.4 知识数字化、6.4.6 知识预置。
- 失败怎么办:6.4.2.4 幂等与重试、死信队列,6.4.5.3 超时策略,6.4.8.2 退出条件。
6.2.4 的五个契约字段(runtime、roles、protocol、storage、knowledge)依次对应 6.4.1、6.4.7、6.4.2、6.4.3,以及 6.4.4 与 6.4.6。6.4.5、6.4.8 以及介质转换工具选型,是本节相对 6.2 契约的三项增量。
6.4.1 Agent 框架的选择
框架在软件史上是工业化的标志。Struts 和 Spring 把 Java Web 从手写 Servlet 里拉出来,Vue 和 React 把前端从 DOM 操作里拉出来。一个领域出现稳定框架,说明这类问题已经有人踩过足够多的坑。
Agent 开发也在走同一条路。底层有大语言模型(Large Language Model,LLM)API、上下文(Context)管理、工具调用和状态持久化,全部从零写等于放弃现成的工程积累。
架构师的第一个决定,是选一条技术路线,而不是选一个品牌。
选框架先做一次小验证,不要只看文档。用真实任务跑一轮,记录工具调用成功率、单次耗时和失败恢复方式,这三项比功能列表更能说明问题。
我们建议先用一周左右做技术验证(经验值),看框架能不能跑通,再决定是否投入长期建设。业务需求本身的可交付验证一般要两周左右,见 6.4.1.2。
6.4.1.1 三条可选路径
第一条是托管型公用平台,代表有 Coze、Dify 云服务、OpenAI GPTs 以及各类低代码 Agent 平台。
它的优势是快。注册、拖拽、发布,半小时左右能做出一个能用的 demo(原型,不是可交付系统)。基础设施、扩容和监控都由平台负责,推荐用于个人验证和轻量工具。
代价有三个。数据要出内网,定制受平台能力限制,迁移时配置和历史记录不一定带得走。对内部数据和长期业务,这三条都要提前算清楚。
第二条是开源自建,代表有 Dify 私有化部署、OpenClaw、LangGraph、CrewAI 和 AutoGen。其中 AutoGen 已进入维护模式,微软把新项目导向 Microsoft Agent Framework(2025 年 10 月公告),新项目选型前先看这个信号。
这条路我们推荐用于大多数企业场景。数据留在自己的机器上,代码和配置可改,工具链可以接内部系统。代价是要有人会部署和运维,版本升级也要自己安排。
Dify 同时出现在两条路上并不矛盾:云服务与私有化部署是同一产品的两种交付形态。
第三条是完全自研。基于原生 API,用 Python、Go 或 Node.js 写一个轻量调度引擎。
它适合两类场景。一是资源受限的边缘设备,通用框架太胖。二是业务模型极其特殊,现成框架的抽象反而碍事。
代价是状态持久化、重试、熔断和上下文裁剪这些底层问题,全部要自己解决。团队没有相应工程能力时,自研会变成一个长期负债。
主流项目的官方地址:Coze(coze.cn)、Dify(dify.ai;开源版 github.com/langgenius/dify)、LangGraph(github.com/langchain-ai/langgraph)、CrewAI(github.com/crewAIInc/crewAI)、AutoGen(github.com/microsoft/autogen)、OpenClaw(github.com/openclaw/openclaw)。
框架版本要锁死,升级前先在隔离环境跑回归。Agent 框架迭代很快,接口改名或行为变化会直接打断线上任务,锁版本是最便宜的保险。
6.4.1.2 场景对位
选型不看流行度,看约束。
- 场景 A:个人验证或轻量工具。优先托管平台,目标是两周内验证需求,不是建长期系统。
- 场景 B:企业核心业务、敏感数据、多 Agent 协同。优先开源自建,数据边界和扩展性比上线速度重要。
- 场景 C:嵌入式、边缘设备、极高并发。优先自研轻量引擎,通用框架的运行时开销在这里不可接受。
还有一个常被忽略的判据:退出成本。选之前先问一句,如果明年要换,配置、提示词(Prompt)、知识库、调用日志和权限关系能不能导出;哪一项导不出来,哪一项就会成为下一次迁移的阻力。
成本上限也在这一步定:托管平台按调用量计费,自建要算人力与机器,先算清这笔账,再选路线。
6.4.1.3 排除性检查清单
动手之前过一遍五个问题,任何一个问题的答案如果不可接受,就直接排除对应路线。
一、数据能不能出内网。不能,就排除托管平台。
二、任务是否要跑几小时甚至跨天。是,就看框架有没有检查点(checkpoint)。按 LangGraph 官方文档的 Persistence 一节,检查点用于保存图状态,中断后可以恢复。
三、是否要接内部数据库和业务系统。要,就确认模型上下文协议(Model Context Protocol,MCP)或 HTTP 工具的接入成本。
四、团队有没有容器和运维能力。没有,私有化的维护成本会超过收益。
五、出问题时能不能定位。看框架是否暴露调用链、Token 消耗,以及工具入参和出参。这五个问题没有标准答案,但每一个都能帮我们排除一类错误选项。
注意:托管平台如果没有导出接口,迁移时历史会话和知识库无法带走,业务会卡在旧平台上。
框架定完,系统有了地基,下一个问题是节点之间怎么说话。
6.4.2 通信协议的设置
多 Agent 系统本质上是分布式系统。每个 Agent 是一个程序节点,节点之间靠消息协作,而不是靠共享内存。
框架一般自带传输层,可能是 Pub/Sub、HTTP、WebSocket,也可能是进程内事件队列。传输层解决比特怎么到,解决不了消息长什么样。
上层格式必须提前定死。否则 A 发一段自然语言,B 按自己的理解解析,出错时双方都觉得自己没错。我们在做多 Agent 项目时,一般先把信封格式定下来,再写业务代码。
协议还要考虑版本兼容。信封里带 schema_version,接收方遇到不认识的版本可以拒绝并回执,而不是按旧字段硬解析,最后把数据写坏。
6.4.2.1 三条硬约束
第一条是结构化契约。消息体用 JSON Schema 或 Protocol Buffers 定义,字段名、类型、必填项和枚举值都写清楚。YAML 只作书写载体,不提供校验能力,校验交给 JSON Schema 或 Protocol Buffers(Protobuf)。
不要在全局通信里传自由文本。自由文本可以放在 payload 的某个字段里,但信封必须是结构化的。
第二条是自包含。每条消息都要带足元数据,让接收方不用回查全库就知道三件事:谁发的,为什么发,要它做什么。
第三条是传输模式与任务时长匹配。同步调用适合短任务,异步消息适合长任务。超过几十秒量级的步骤不要占着连接等,改成事件通知,否则一次超时会把整条链拖死。
6.4.2.2 消息信封
一份可用的信封至少包含五组字段,下面给出完整示例。
json
{
"header": {
"schema_version": "1.0",
"message_id": "msg_20261031_001",
"trace_id": "trace_task_8892",
"task_id": "task_chapter6_review",
"timestamp_ms": 1793404800000,
"idempotency_key": "review_ch6_8892_01"
},
"addressing": {
"sender": {"agent_id": "agent_writer_01", "role": "ContentGenerator"},
"receiver": {"agent_id": "agent_reviewer_02", "role": "QualityChecker"}
},
"control": {
"message_type": "REQUEST",
"action": "REVIEW_DOCUMENT",
"priority": "HIGH",
"deadline_ms": 600000
},
"payload": {
"content_ref": "file_id_9901",
"format": "markdown",
"schema": "review_request"
},
"context": {
"working_directory": "/workspace/project_root/03_working/agent_writer_01/",
"previous_state": "DRAFT_COMPLETED",
"locale": "zh-CN"
}
}信封里的时间字段统一用毫秒(timestamp_ms、deadline_ms),不要混用秒与毫秒。
版本只由 schema_version 承载,它标的是协议版本;payload.schema 只写载荷模式的名字,如 review_request,两者分工不同。idempotency_key 是发送方为业务动作生成的去重标识,deadline_ms 是接收方必须在此毫秒数内完成的时间预算。
正文不要塞进信封。大文件传引用,例如 content_ref 指向对象存储或共享目录,消息体只放指针和摘要。
消息体超过几 MB 量级时,总线延迟和重试成本都会明显上升。把大对象放到对象存储,消息里只留引用、校验值与过期时间,接收方按需拉取。
6.4.2.3 每个字段防什么故障
身份与角色防投错。没有唯一的 agent_id,消息可能落到同名角色上,处理结果就进了别人的任务。
任务号(task_id)与追踪号(trace_id)防查不清。任务号把多轮消息归到同一件事,追踪号把跨 Agent 的整条链串起来。日志、耗时和 Token 消耗都挂在追踪号上。
消息类型与动作防误解。REQUEST 是要对方干活,RESPONSE 是回报结果,BROADCAST 是通知状态,HUMAN_INTERRUPT 是人介入,HANDOFF 是岗位交接(扩展类型,定义见 6.4.7.3)。
类型不清,接收方可能把通知当成任务又执行一遍。
路由防死循环。A 发给 B,B 回执给 A,A 再把回执当新任务发给 B,环就形成了。规则要写死:回执不再触发回执。
载荷防解析失败。字段类型、必填项和最大长度都要约束,JSON 解析失败要有明确错误码,不能静默降级。
上下文防环境错位。工作目录、状态机位置和数据版本都要带上,接收方在错误目录里执行,产物会写丢。
6.4.2.4 幂等与重试
网络传输通常是至少一次,不是恰好一次,同一消息可能到达两次。
如果接收方没有去重,重复消息会触发重复执行。查一次没事,写文件会多一份,下单会多一笔。
做法很直接。发送方为每个业务动作生成稳定的幂等键(idempotency_key),接收方为它维护一条去重记录,锁与结果各占一个键。
重复请求进来,直接返回上次结果,不再执行。
下面是一段可运行的最小实现。运行前需要本机有 Redis 服务,并安装 Python 的 redis 包:pip install redis。
python
import json
import redis
r = redis.Redis(decode_responses=True)
def handle_once(key: str, fn):
lock_key = f"idem:{key}"
result_key = f"result:{key}"
if not r.set(lock_key, "1", nx=True, ex=86400):
raw = r.get(result_key)
if raw is None:
return "PENDING"
return json.loads(raw)
try:
result = fn()
except Exception:
r.delete(lock_key) # 失败释放锁,允许重试
raise
r.set(result_key, json.dumps(result), ex=86400)
return resultnx=True 保证只有一个请求能拿到锁,ex=86400 让去重记录一天后自动过期。结果先序列化成 JSON 再存,读取时再反序列化,dict、字符串和空串都能安全往返。判空用 is None,不用 or,否则空串会被误判成「处理中」。幂等键必须由动作内容决定,不能用随机数,否则重试会生成新键,去重失效。
重复请求在首个请求完成前到达时,会拿到 PENDING,调用方应稍后重试,不能把它当成成功结果。
还要设死信队列。连续失败的消息不能无限重投,超过次数就落到死信队列,等人处理。
注意:只带
message_id而不做去重记录,网络重试会导致同一任务被执行两次;涉及写文件或下单时,会产出重复文件或重复扣款。
协议定完,消息格式和重试规则定了,下一个问题是消息里提到的文件放在哪。
6.4.3 统一目录与存储架构
多数团队把注意力放在工具上,忽略了产物落在哪。Agent 跑完一轮,报告、日志和中间文件散在十几个路径里,下一个人找不到。
统一目录解决可寻址,统一存储解决可管理。这两件事没做好,多 Agent 协同很快就会变成互相覆盖。读者如果只记一条,那就是路径必须由系统注入。
6.4.3.1 目录规范
一套够用的目录树如下。
text
/workspace/project_root/
├── 01_inputs/ 原始输入,只读
├── 02_knowledge/ 预置知识库,只读
├── 03_working/ Agent 中间产物
│ ├── agent_researcher/
│ └── agent_coder/
├── 04_outputs/ 最终交付物
├── 05_logs_and_traces/ 日志与链路追踪
└── 06_runtime_knowledge/ 运行演进库,可读可写,审核后合并入 02五条规则。
- 路径由系统注入。Agent 的环境变量或配置里直接给绝对路径,不让它猜。
- 输入和知识库只读。任何写入都拒绝,防止误改原始资料。
- 工作区按 Agent 隔离。A 的临时文件不放到 B 的目录。
- 输出目录统一。文件名带任务号和时间,便于追溯和清理。
- 生命周期分级。临时文件设保留期,交付物长期保存,日志按周归档。没有清理规则的目录,半年左右就会变成垃圾场。
命名规范要能排序。建议用日期、任务号、版本和描述四段,例如 20261103_task8892_v2_report.md,按文件名排序就是时间顺序。
6.4.3.2 四类存储
文件存储放代码、文档、多媒体和配置。本地文件系统适合单机,对象存储适合多机和备份,关键是命名规范和目录归属。
关系型数据库(下称关系库)放任务状态、Agent 名册、权限和业务流水。轻量场景可用 SQLite,多机并发用 MySQL 或 PostgreSQL。分析、报表类查询可以另用 DuckDB,它是列式的联机分析处理(OLAP)库,单写者模型,不适合在线事务。表结构要先设计,不要等 Agent 自己建表。
向量数据库(下称向量库)放知识切片和语义索引。Chroma、Qdrant、Milvus 和 pgvector 都可以。设计要点是切片大小、重叠率、Embedding 模型版本,以及按知识域分集合。
缓存放上下文、锁、临时变量和计数器。Redis 是常见选择,每条缓存都要设生存时间(TTL)。没有过期时间的缓存,最后都会变成脏数据。
选择存储时先看一致性要求,而不是看技术热度。任务状态丢了可以重跑,交付物丢了不可恢复,两者不该放在同一个可靠性等级上。预算也在这一步落地:对象存储按量计费、向量库按规模计费,先算数据增长曲线,再定用哪一类。
6.4.3.3 访问接口
不要让 Agent 用自然语言拼 SQL。模型生成的 SQL 可能漏 where 条件,也可能带上 drop table。
正确做法是封装。把查询、写入和检索做成 MCP 工具或内部 API,参数要做校验,表名走白名单。
写入接口还要有审计。谁在什么时候改了哪一行,要能查出来,否则出问题只能猜。
存储访问权限只讲一条:账号只读或最小权限,写入走封装接口。完整的权限模型与层级放在 6.4.7,这里不重复。
注意:把数据库账号和密码写进提示词或明文配置,一旦日志被导出,凭据会随上下文一起泄漏;应改用只读账号加 MCP 封装。
6.4.3.4 存储运维
表结构变更要走迁移脚本,不要手工改线上库。每次迁移带版本号和回滚脚本,Agent 读到的 Schema 才能和代码保持一致。
备份策略按数据等级分开。任务状态每天备份一次一般够用(按可容忍的丢失量定),交付物和知识库要异地保存,恢复演练至少每季度做一次(示例值,按合规要求调整),否则备份只是心理安慰。
数据底座稳了,接下来要解决知识从哪来。
6.4.4 知识数字化的工具
未数字化、未转写、也未接入多模态的介质,对 Agent 不可见、不可检索。
所以知识数字化不是可选项,它是 Agent 能不能干活的前置条件。没有数字化,模型只能凭已有数据推断,推出来的东西看起来合理,实际不可用。
本节只讲介质转换:把非数字形态变成可计算的数据。知识入库之后如何分库、如何审核升级,统一放在 6.4.6.2,本节不重复。
动手做工具之前,先盘一遍知识资产。哪些在文档里,哪些在系统里,哪些只在人脑里,各有多大体量,决定先做光学字符识别(OCR)还是先做访谈。我们建议先做小样本验证,再批量转换。
6.4.4.1 介质转换与索引
第一类工具处理非结构化介质。OCR 负责图片和扫描件,语音转写负责会议录音,视觉解析负责图表和界面截图。输出要尽量结构化,至少带页码或时间戳,方便回查。
OCR 结果要带置信度,低于阈值的字段进入人工复核队列;票据和合同里的数字按金额分级抽检。字符错一位就可能让整份报表失去意义。
隐性知识(专家脑子里的判断规则)不在这里处理,提取方法见 6.4.5.1。
第二类工具处理切片与索引。长文档按语义切块,生成向量,写入向量库。切片要保留标题路径,否则检索出来的片段没有上下文。
一组经验值是每块 500 到 800 汉字,重叠 10% 到 15%,再按实际检索命中率调整。切片太大检索不准,太小会丢上下文。
Embedding 模型升级会让旧向量失效。换模型前先建新集合并双写一段时间,等检索评测通过后再切换,否则历史知识会突然搜不到。
知识可以被转成数据了,但关键判断还在人脑里,下一步是把人接进系统。
6.4.5 人类专家的接口
有一个事实常被忽略:模型只能在已数字化的数据上计算。
商业世界里最值钱的知识,往往没被数字化。它们在专家的直觉里,在例外处理的习惯里,在十年的现场经验里。
对这些知识,模型只能猜,猜的结果就是幻觉。所以架构里必须有人类专家接口,它不是聊天窗口,而是三条结构化通道。读者可以把这三条通道理解成三个不同频率的通道。
6.4.5.1 三条通道
第一条是知识提取。把专家口述的经验变成规则文档、JSON 或工具契约,形式可以是结构化表单,也可以是带引导问题的对话。
第二条是知识判别。专家不写知识,只做裁判,系统抽样送审,专家打分、纠错、标记时效,通过的内容才进预置知识库。
第三条是结果批判。高风险动作执行前,把中间结果推给专家,专家给通过、打回或修改意见,Agent 按意见修正。
频率轴要写清楚:知识提取是低频、一次性;知识判别是中频、抽样;结果批判是高频、按抽检规则送审。高频不等于全量:一次评审按十分钟计,日均 50 单就是 8 小时以上,相当于一个全职专家岗,因此要设抽检比例或每日送审上限。三条通道共用一套结构化落库格式,但触发频率和专家负担完全不同。
三条通道的共同点是结构化。每次交互都要落库,带任务号、结论、理由和时间,方便追溯和统计。
升级路径要写成手册。什么条件需要请专家、找谁、多久必须响应、无人响应怎么办,这四条写清楚,值班的人才知道下一步做什么。
专家时间是最贵的资源,接口要尽量减少专家的操作。能自动填的字段不要让人填,能批量判的不要逐条问,一次评审控制在十分钟以内。
6.4.5.2 连续性与实时性
多数项目把专家参与做成一次性访谈,上线前聊两小时,上线后就不管了,这样的知识很快过期。
接口要支持连续补充。专家在日常工作里发现新规则,能随时补一条,下一轮任务就生效,规则要版本化,旧版本可回滚。
接口还要支持实时干预。Agent 卡住、重试超限或置信度低于阈值时,系统要能主动叫人,而不是等任务失败后再复盘。
规则版本要和任务记录绑定。回看一次失败任务时,要能知道当时用的是哪一版规则,否则复盘只能靠记忆。
6.4.5.3 工程参数
这三个参数必须提前定,它们都是人类专家接口的参数;控制节点的实现见 6.5.2.2。
- 置信度阈值:低于阈值的输出不允许直接交付,必须送审或重跑,阈值按业务定,合同和财务场景要比内部摘要高。
- 审批分级:低风险自动通过,中风险抽检,高风险全审,分级依据是金额、影响范围和可逆性。这三档与 6.3.4.2 的分级表一一对应:低:Full-Auto;中:Human-in-the-Loop 抽检;高:Human-in-the-Loop 全审 + 双人复核。
- 超时策略:审批超时不能默认通过,应挂起或拒绝,并记录未审原因。
三个参数要靠反馈统计校准。通过率、打回原因和平均处理时长,能看出阈值定得是否合理,也能发现 Agent 反复犯的同类错误。
注意:超时策略的参数取值只有挂起和拒绝两种。默认放行不是可选项,等于把最危险的决策交给计时器(工程实现见 6.5.2.2)。
人接进来了,知识也要有入口和出口。
6.4.6 知识预置与流转
把文档塞进向量库,不等于知识预置。检索不准、上下文过载和新旧知识冲突,都是常见结果。
知识数字化(介质转换)已在 6.4.4 讲过,本节只讲预置与流转:知识怎么进来、怎么出去、怎么更新。我们一般把知识分成规范、案例和术语三层,分别控制注入长度。
6.4.6.1 通道
统一走 MCP 或 Skill。MCP Server 把向量库、关系库和文件存储封装成标准服务,Agent 不需要知道底层是哪种数据库,只按协议调用。
Skill 定义什么时候查、怎么查、查多少。没有这层规则,Agent 要么跳过检索凭印象回答,要么每句话都查一遍。
6.4.6.2 输入向与输出向
知识分两个库。预置知识库(下称预置库)放人类确认过的 SOP、规范和标准,对 Agent 只读;运行演进库(下称运行库)放 Agent 执行中的笔记、调试经验和失败记录,可读可写。
分开的理由是:Agent 会总结出错误经验,若允许它直接写预置库,一条错误结论就会变成下一轮的标准答案。运行库的经验要经过审核才能进预置库,合并前先灰度,出问题能退回旧版本。
输入向解决启动时的领域无知。Agent 初始化时,把行业规范、业务 SOP、数据库 Schema 和术语表按需注入。
注入要控制长度,按三层分开处理:规范只取与任务相关的条款,案例按相似度取一两条,术语表整表注入。先检索,再裁剪,最后放进上下文。
检索效果要定期评测。准备一组真实问题,标注标准答案,测命中率和引用准确率,模型或切分策略一改就重跑,否则退化不会被发现。
输出向解决的是经验流失问题,只记四项增量:来源、置信度、过期时间、适用条件。Agent 在任务中总结出的新经验,写入运行库时就带上这四项。
知识卡片可以加一个字段:适用条件。没有适用条件的经验,换个场景就是错的。
新旧知识冲突时,以版本号和生效时间为准,不要靠检索排序判断。冲突记录要保留,方便回查是哪次更新覆盖了旧结论。
6.4.6.3 专职知识 Agent
主业务 Agent 不该同时负责整理知识。上下文被撑爆、注意力被分散、成本上升这三条论证放在 6.4.8,这里只讲角色拆分。
可以拆两个角色。知识查询 Agent 只做检索,它理解主 Agent 的意图,做多路召回和重排,把最相关的几段送回主 Agent。
知识整理 Agent 在后台跑,它监听任务日志和运行库,做去重、打标和归纳,提交审核。这两个角色的组织归属与权限见 6.4.7。
一个可用的检索流程是:召回 20 条,重排后取满至 2000 Token 上限(约 3 到 4 条,按 1 个汉字约 1 Token 粗估),具体数值按模型窗口和业务调。以上都是经验值,不是硬标准。
知识要标有效期。行业规范、产品价格和内部流程都会变,过期知识比没有知识更危险,因为它看起来仍然可信。
注意:把整本手册直接塞进系统提示词(System Prompt),无关章节会占满上下文,关键规则反而被稀释,模型容易漏掉约束;应按任务检索并限制注入长度。
知识和人都就位了,接下来把组织映射到 Agent。
6.4.7 人员与组织到 Agent 的映射
有一种常见误解:模型够强,一个 Agent 就能覆盖所有岗位。
在简单任务里也许成立,在工业系统里一定失败。需求、开发、测试和运维的责任边界,不会因为换了执行者就消失。读者在画拓扑图时,先把派发关系画出来,再补回执和升级路径。
6.4.7.1 个人映射
6.3.4.2 已经给出三条规范:显性契约、知识切片、授权边界;按人类团队的实际岗位拆岗,方法见 6.3.4.1。架构层补三项增量,加上 6.3.4 已覆盖的身份与工具授权,共五项。
- 路径注入(增量):工作目录、输入目录、输出目录直接注入,不让 Agent 猜。
- 协议挂载(增量):消息格式、总线地址、回执规则挂到每个节点上。
- 交付契约(增量):输出格式、验收标准、失败时的回报方式。
- 身份(6.3.4 已覆盖):
agent_id、角色名、所属项目,用于寻址和权限判断。 - 工具授权(6.3.4 已覆盖):按岗位授权,后端 Agent 给数据库查询和编译工具,不给支付接口。
工具是授权清单,不等于常驻上下文,常驻与挂载的分界见 6.4.8.2。
五项缺一项,Agent 就会在某个环节自由发挥。
角色名不要写成万能头衔。写清楚这个 Agent 负责什么、不负责什么,边界越具体,越不容易在交接处出现空档。
6.4.7.2 组织映射
组织映射解决多节点协同。在 6.3.4 之上,架构层补四项:组织拓扑、共享与私有、分层、权限复核。
项目组结构要映射出来。知识组、开发组、测试组和运维组,映射成协作拓扑,谁向谁派任务,谁给谁回执,要画出来。
共享与私有要分开。全局知识库跨组共享,项目草稿区组内可见,个人工作区只对自己开放。最小必要原则见 6.3.4.2,这里不再重复解释。
权限要定期复核。项目结束后收回临时授权,人员变动时同步调整 Agent 权限,长期不用的账号直接停用,别等出事再查。
组织规模变大后,拓扑要分层。组内靠共享目录协作,组间靠任务号交接,跨层调用走统一网关,避免任意两个 Agent 直接相连。
6.4.7.3 交接协议
交接就是 6.4.2.2 消息信封的一个子类型。任务号、输入引用、截止时间都已在信封里,本节只定义增量。
增量只有一个字段:acceptance_criteria,写清什么算完成、谁来判、判不过怎么办。
一份最小交接单就是信封加这个字段。例如 message_type 用 HANDOFF,payload.content_ref 指向交付物,acceptance_criteria 写「三项指标全部达标,由测试 Agent 判定,不达标退回派发方」。
交接失败要有回退。接收方拒收或超时,任务回到派发方,不能悬空。
注意:把生产库写权限直接挂给编码 Agent,一次错误的迁移脚本就会导致线上数据错乱;应只给测试库写权限,生产变更走审批。
组织搭好了,最后一步是能力怎么装进去。
6.4.8 人员能力的提取与映射
一个常见的错误是把员工的所有技能、SOP 和历史规则,全部塞进同一个系统提示词。
理由通常是上下文够大,但上下文大不代表注意力够用。
后果有两个。角色冲突,前端规范和后端规范互相干扰;成本上升,每次调用都为用不到的规则付费。我们在配置 Agent 时,优先保证身份和输出契约稳定,再谈能力扩展。
6.4.8.1 提取三步
第一步是解构。跟岗位专家一起,把任务拆成输入、判断、动作和输出,重点是判断规则,尤其是例外。
第二步是转 SOP。把直觉写成步骤,把步骤写成可检查的条件,模糊的词要换成可验证的标准。
第三步是封装。高频且确定性强的操作,写成 Skill 内的脚本文件或 MCP 工具,不要让模型每次自由发挥。
Skill 的粒度按任务定,不按代码行数定。一个 Skill 解决一类可验收的任务,输入输出清楚,能被单独测试,这样的粒度才适合挂载。
6.4.8.2 静态身份与动态挂载
Agent 的常驻身份要精简,只留三项:身份与协议、工作目录、输出契约。
专业能力按需挂载。调度器根据当前任务类型,把对应的 Skill 和工具加载进上下文,任务结束就卸载。
例如同一个 Agent 在前端阶段加载组件规范,在测试阶段换成测试框架和代码扫描工具,两套规范不同时在场,冲突随之减少。
每次挂载都要有退出条件。任务完成、超时或连续失败,都要卸载并清理上下文,否则残留的 Skill 会在下一个任务里继续影响判断。
Token 账也好算。常驻 20000 Token 与 2000 Token 相比,单次成本差一个数量级,调用量越大,差距越明显。
动态挂载的实现不复杂。把 Skill 写成独立目录,每个目录带一份 SKILL.md 说明用途和触发条件,调度器只加载与当前任务匹配的目录。
还有配置治理。每次调整 Agent 配置,都要留一份可回滚的版本。系统提示词、工具授权和挂载的 Skill 一起纳入版本管理,出问题能在几分钟内退回去。
注意:把全部岗位手册常驻在系统提示词里,每次调用都要为用不到的规则付费,导致单次成本成倍上升;上下文越长,关键指令的注意力占比越低。
八根支柱到这里就齐了。
框架打地基,协议定节点怎么说话,目录与存储定产物落在哪,知识数字化定 Agent 能看到什么。人类专家接口解决不懂时找谁,知识预置解决经验能不能复用,人员与组织映射解决谁负责什么,能力提取解决每个 Agent 带多少东西上场。
回到开场的四问:边界在哪、谁调用谁、数据放哪、失败怎么办,四个问题都已作答。
这八根支柱不是清单打卡,它们互相约束。举个具体的联动:协议从同步改成异步,目录就要加消息归档和死信队列,存储就要加消息表,权限就要加消费组。一处改,三处跟着改,这才是架构而不是拼装。
本节可以当架构评审的检查表用,逐项打勾。
6.5 会用到本节的三项产物:
- 6.4.2 的消息信封是任务规划的输入输出格式。
- 6.4.3 的目录与状态存储是步骤落盘的地方。
- 6.4.5.3 的人类专家接口参数是流程里审批节点的配置来源。
架构定完,下一步是把目标拆成可执行的步骤,这是 6.5 要处理的问题。
6.5 任务规划与执行流程
6.4 把架构的八根支柱画完了,本节接着把目标变成可执行的步骤。
第一次用 Agent 的开发者,常常会有同一个直觉:模型已经会思考,把目标丢给它就行。这个直觉在 Demo 里成立,在工程里不成立。
我们做过一组对照:模型、温度和任务描述都固定,连续跑 10 次,通常会拿到 10 份不同的计划。有时步骤顺序不同,有时漏掉一步,有时执行到一半又绕回起点。
大语言模型(Large Language Model,LLM,下文简称大模型)的输出是概率采样,不是确定性函数。把流程交给它自由发挥,等于把稳定性交给随机数。
严肃业务的要求恰好相反:确定性、可复现、可审计。同一个输入,今天和明天要得到同样的结果,出了问题要能回放到具体哪一步。
这两件事,靠提示词(Prompt)叮嘱是做不到的。所以,Agent 应用必须在模型之外再建一层骨架,也就是本节要讲的任务规划与执行流程(Task Planning & Execution Flow)。
这层骨架负责把目标拆成任务,把任务放进状态机,把状态写进数据库,再按依赖关系一步步推进。模型只负责每个节点里的判断,流程本身不归模型管。
接下来的五节,分别回答五个问题:任务怎么拆,人在哪里介入,任务之间怎么调用,用什么工具调度,界面怎么让人看懂。
6.5.1 任务拆解和计划的定制
拆解的目的不是把任务变多,而是把不确定性关进小盒子。一个任务越大,模型需要同时照顾的约束就越多。
约束一多,注意力就分散,分散到一定程度,模型开始漏条件、编字段、重复劳动。这不是模型能力不够,是任务边界没划清。
拆解之后还要回答三个问题:切成多大(6.5.1.1)、切开之后怎么管(6.5.1.2)、任务之间怎么连(6.5.1.3)。失败处理作为最后一道防线,单独放在 6.5.1.4。
6.5.1.1 单一职责与上下文隔离
上下文窗口(Context Window)是 Agent 的工作内存,也是最贵的资源。一份 60 页的采购合同,正文约 4 万字(按 1 字≈1 Token 估算,约 4 万 Token),附件另约 4 万 Token,合计约 8 万 Token。
把整份合同塞进一次推理,模型要同时完成版面还原、条款定位、金额计算和格式转换。这四件事互相干扰,任何一件出错,整份结果都要重来。
更麻烦的是长上下文本身的衰减。论文《Lost in the Middle》做过一组实验:关键信息放在上下文开头或结尾时,模型召回率较高;放在中间时,召回率明显下降。
这是长上下文场景下的结论;把它外推到多节点任务链,是我们的推论。我们的做法是按动作切分,一个任务只做一件事。
parse_contract:只做版面还原,输出纯文本和页码索引。extract_terms:只抽 6 个字段,输出 JSON。check_schema:只校验类型、范围和必填项,不修改内容。write_crm:只负责写入客户关系管理(CRM)系统,不做任何推断。
这里有一个前提:parse_contract 走 OCR 与版面解析,不调模型;只有后三个节点调模型,每个节点约 4000–10000 Token,合计约 1.2 万–3 万,文中按 2.5 万估。
切分之后,每个节点只需要加载与自己相关的材料。extract_terms 看不到写入逻辑,write_crm 也不需要理解合同条款。
上下文从 8 万 Token 降到 4000–10000 Token,单次推理的成本和出错面同时下降。这笔账在大批量任务里非常直观。
按每天处理 200 份合同计算,两种做法的分母都是「每份合同」。不切分时,3 个调模型的节点各读一遍整份合同,每节点最多 8 万 Token,单份合计约 24 万;切分后,3 个节点合计约 2.5 万。前者约为后者的 10 倍,一天省下的不是一点电费,而是可以把预算放到更难的字段上。成本账还有一项:在支持前缀缓存的推理服务上,同一段前缀反复提交时,键值缓存(KV Cache)可以省掉一部分计算。把稳定不变的部分放在前面、变化的部分放在后面,命中率会高很多。
单一职责不是把函数写短,而是把判断边界划清。一个节点如果需要综合三类以上业务规则才能给出结果,通常还可以继续拆。拆到每个节点都能用一句话说清输入和输出,边界才算稳定。
上下文隔离还有一层含义:上游只向下游传结构化产物,不传中间推理。模型在节点里说了什么、试了什么、否定了什么,都属于过程垃圾。
下游真正需要的是字段和文件地址。把整段对话历史传给下一个节点,等于把噪声一起传过去,Token 花了两遍,注意力还被稀释。
注意:把上游的完整对话历史直接塞给下游节点,历史里的错误假设会被下游当成事实继承,导致错误在整条链上放大。
6.5.1.2 任务的全生命周期状态机
拆完的任务不能散落在内存里,每一个任务都要有身份、有状态、有负责人。
我们要求任务表至少记录六类信息。身份包括任务编号、父任务和所属计划;责任包括谁发起、谁执行、结果回给谁;状态记录当前生命周期阶段。
另外三类是尝试次数与失败原因、产物引用(对象存储地址 + 哈希)、超时时间与下一次唤醒时间。字段不多,但缺一项,排查时就会卡住。
状态本身要收敛,不能随便加,我们用七个状态:
CREATED:已创建,尚未进入队列。PENDING:已排期,等待依赖完成。RUNNING:执行中。SUSPENDED:挂起,等待人工或外部事件。SUCCEEDED:执行成功,产物已校验。FAILED:执行失败,等待重试或人工处理。CANCELLED:主动取消。
状态只能沿定义的边迁移,表外的迁移一律拒绝。
| 从 | 到 | 触发条件 |
|---|---|---|
CREATED | PENDING | 进入队列、依赖已就绪 |
PENDING | RUNNING | 被调度器领取 |
RUNNING | SUCCEEDED | 节点执行成功,产物校验通过 |
RUNNING | FAILED | 节点执行失败 |
RUNNING | SUSPENDED | 命中人工节点,或等待外部事件 |
SUSPENDED | PENDING | 审批通过、驳回(带修改意见重跑当前节点)或外部事件到达,重新排期 |
SUSPENDED | FAILED | 超时按策略终止 |
FAILED | PENDING | 未超过重试次数,重新排期 |
PENDING | CANCELLED | 依赖任务永久失败(BLOCKED),写事件记录 |
| 任意非终态 | CANCELLED | 主动取消,或重试耗尽后人工终止 |
不允许从 FAILED 直接跳到 SUCCEEDED,也不允许跳过 RUNNING 直接写结果。跳状态看起来省事,实际会把审计记录弄断。
这七个状态只描述任务的生命周期。另有一条与之正交的投递轴(投递/确认轴):sent(已发出)、delivered(已送达)、read(接收方已读并校验)。生命周期回答“任务走到哪一步”,投递轴回答“消息有没有被真正接收并看懂”。两条轴各记各的,不能互相替代。6.5.5.2 的任务时间线会把两条轴混排,那里的 DISPATCHED、READ 属于投递轴,不在这七个状态里。
每次迁移都写一条事件记录:谁改的、什么时候改的、从什么状态到什么状态、依据是什么。这张事件表比任务表更重要。
并发更新的问题也要在状态机里解决。两个调度器同时抢同一个任务时,用版本号做乐观锁,更新语句同时带上旧状态和旧版本(WHERE status = 旧状态 AND version = 旧版本),只有一行受影响才算抢到。抢不到的一方重新读取,不要强行覆盖。
锁的粒度按任务算,不要按整张计划表算,否则一个慢任务会挡住同计划里的其他节点。抢锁失败的一方进入 PENDING,等下一次扫描再试,不要原地自旋。
任务表回答“现在是什么”,事件表回答“为什么会这样”。线上排查时,后者用得更频繁。
状态机的价值在故障时体现。正常路径下,它看起来只是多写了几行状态判断;一旦进程被杀,能不能从表里恢复,差别立刻出来。
完成之后还有一次读确认:SUCCEEDED 只说明产物已校验,不说明下游看懂了。读确认是交付确认,单独记在投递轴上,详见 6.5.3.4。
6.5.1.3 基于 DAG 的任务依赖与流程设计
任务之间的关系,要写成图,不要写成自然语言。自然语言适合描述意图,不适合做调度。
调度器需要知道谁必须在谁之前,需要判断有没有环,需要计算哪些节点可以并行。这些事只有有向无环图(Directed Acyclic Graph,DAG)能直接表达。
一个合同处理流程可以画成这样。
执行前先做拓扑排序,有环就拒绝执行,不做任何补救。环通常意味着需求没想清楚,让程序硬跑只会把问题拖到运行时。
节点失败时只重试当前节点,不要让整条链从头再来。重跑全链的代价不只是 Token,还有副作用:邮件可能发两遍,数据可能写两次。
长流程还要有检查点:每完成一个节点就把产物引用写进任务表,进程重启后从最后一个成功节点继续,而不是从根节点重放。
DAG 这一层只做四件事:把依赖画成图、执行前拓扑排序、失败只重试当前节点、每步写检查点。退避、幂等、补偿这些可靠性手段属于另一层,放到 6.5.1.4。
下面这段代码是调度器的骨架,只保留状态、依赖和拓扑推进。
python
# Python 3.10+,只用标准库
from dataclasses import dataclass, field
from enum import Enum
from typing import Callable
class State(Enum):
CREATED = "CREATED"
PENDING = "PENDING"
RUNNING = "RUNNING"
SUCCEEDED = "SUCCEEDED"
FAILED = "FAILED"
CANCELLED = "CANCELLED"
# 骨架聚焦调度,示例省略 SUSPENDED;完整版见 6.5.2.3
@dataclass
class Task:
name: str
run: Callable[["Context"], str]
deps: list[str] = field(default_factory=list)
state: State = State.CREATED
output: str | None = None
@dataclass
class Context:
data: dict[str, str] = field(default_factory=dict)
def execute(tasks: dict[str, Task], ctx: Context) -> None:
done = {n for n, t in tasks.items() if t.state is State.SUCCEEDED}
while len(done) < len(tasks):
ready = [t for t in tasks.values()
if t.state in (State.CREATED, State.PENDING)
and set(t.deps) <= done]
if not ready:
raise RuntimeError("存在循环依赖或永久阻塞")
print("就绪批次", [t.name for t in ready])
for task in ready:
task.state = State.RUNNING
task.output = task.run(ctx)
ctx.data[task.name] = task.output
task.state = State.SUCCEEDED
done.add(task.name)
def parse_contract(ctx: Context) -> str:
return "合同正文:付款周期 30 天,金额 80 万元"
def extract_terms(ctx: Context) -> str:
text = ctx.data["parse_contract"]
return "金额=800000; 付款周期=30"
tasks = {
"parse_contract": Task("parse_contract", parse_contract),
"extract_terms": Task("extract_terms", extract_terms, deps=["parse_contract"]),
}
ctx = Context()
execute(tasks, ctx)
print(ctx.data["extract_terms"])运行环境是 Python 3.10 及以上,不需要安装第三方包。保存为 dag_demo.py,执行 python3 dag_demo.py 即可看到输出。
读者可以改 deps 做两个小实验:把 extract_terms 的依赖清空,输出从两批并成一批;把 parse_contract 的依赖改成 ["extract_terms"],会形成环,execute 立刻抛「存在循环依赖或永久阻塞」。这比看架构图更直观。
这段代码刻意保持很小,要证明的只有一件事:调度逻辑可以独立于模型存在。run 函数里调模型、调数据库还是调外部 API,调度器都不关心。
调度器只认状态、依赖和产物,把这三样管住,模型换版本、换供应商,流程都不用重写。骨架为聚焦调度,省略了 SUSPENDED 与人工节点;完整版(含挂起、重试、审批恢复)见 6.5.2.3 的综合示例。
6.5.1.4 失败处理与幂等边界
节点失败后的可靠性手段,多数在 6.4.2.4 已经讲过,这里只补 DAG 层面的边界,不重复协议层的实现。
重试要退避,不要立刻重放:第一次失败等两秒,第二次等四秒,第三次不再重试,直接抛错交给上层转人工(经验值,按业务调整)。节点失败先记 FAILED 并写失败原因;未超过重试次数,立即转 PENDING 并写入下一次执行时间 next_retry_at。退避期间任务状态是 PENDING,由调度器到点再唤醒。
重试必须配幂等键,去重表的做法见 6.4.2.4。DAG 这一层要保证的是:同一个节点重跑,用的必须是同一个 idempotency_key,不能每次重试生成新键,否则去重形同虚设。
没有幂等,重试就是放大器,一个偶发超时,会被放大成三条重复订单。
有些副作用无法回滚,比如已经发出的短信。这类节点要配补偿动作,或者放到流程最后,减少中途失败的概率。
并行也不是越多越好:并行节点共享下游资源时,要限流。10 个节点同时写同一个库,锁等待会把并行变成互相拖累。
超过重试次数,任务进入 FAILED,交给人工,不要无限重试;无限重试会把一个明确的错误变成一堆重复日志,还会拖住整个队列。
拆解、状态机、DAG 三件事做完,机器侧的流程就立住了;失败处理只是给这条链补上最后一道防线。但还有一类节点,机器不能自己决定。这就是下一节要讲的人在回路。
6.5.2 人在回路的控制节点
全自动跑到底,在 Demo 里是卖点,在生产里是风险。付款、合同用印、生产发布、对外承诺,这些动作的共同点是:错了要有人负责。
模型可以给建议,但不能承担后果,责任和权限必须留在人这一侧。所以,人在回路(Human-in-the-Loop,HITL)不是可选项,是架构的一部分。
6.4.5 已经从专家接口的角度讲过三条通道、审批分级和超时策略,本节不重复那些政策,只讲任务流这一侧的工程问题:控制节点(人工节点或外部事件等待)怎么挂起、怎么恢复、怎么留痕。后文按最常见的情况,统一称人工节点。
6.5.2.1 为什么必须在设计期预留
6.4.5 回答了“为什么要有专家接口”,这里补一个工程视角的理由:预留的成本远低于补装。
第一批需求里,系统通常没有人工审批。任务流引擎被写成一条直线:创建、执行、结束。
三个月后,业务方提出“金额超过 50 万的单子要人看一眼再放行”。这时候改动的不只是一个判断。异步通信要改,上下文要能保存,进程重启后要能恢复,界面要能展示待办。
原来那条直线得拆掉重写,返工范围会从一个人工节点扩散到整个调度层。
差别往往就在这里:第一次做 Agent 的工程师按当前需求画最短路径,做过生产系统的工程师会先问一句,哪些节点将来一定要人签字。答案一旦明确,接口第一天就留出来。
另一层原因是合规:审计要的不是“系统说它批准了”,而是“谁在什么时间、看了什么材料、基于什么理由批准”。这条记录必须由系统生成,不能靠聊天记录补。
6.5.2.2 控制节点的工程实现
一个人工节点,本质上是一个可以挂起和恢复的状态机节点。审批分级、超时不得默认通过等政策层规定见 6.4.5.3,这里只列任务流特有的五条机制。
挂起要落库,不能靠
sleep。 用sleep等审批会占住进程,机器重启就丢。正确做法是把任务状态写成SUSPENDED,把上下文快照和产物引用写进表,然后释放执行资源。与此同时,待办消息要带够信息:任务编号、业务摘要、关键字段、风险提示和截止时间。只发一句“有个任务待审批”,审批人还得自己去找上下文,通过率会很低。上下文快照单独存。 快照只保恢复所需的最小状态:上游产物引用、已完成节点、当前变量;产物本身留在对象存储,快照里只放地址和哈希,避免和产物版本脱节。
审批记录要结构化。 不要只存一个“同意”,一份完整的审批记录包含七项:
| 字段 | 作用 |
|---|---|
| 任务编号 | 把审批挂回具体任务 |
| 审批人 | 谁签的字 |
| 审批时间 | 什么时候签的 |
| 决定 | 通过 / 驳回 / 退回修改 |
| 理由 | 为什么这么判 |
| 被修改字段 | 驳回时指明改哪里,下游不用猜 |
| 材料版本 | 确认审批人看到的是哪一版材料 |
材料版本常被漏掉,导致事后无法确认审批人看到的是不是最终稿。
恢复前要重新校验。 挂起期间,上游数据可能已经变了。恢复时先比对产物引用里的哈希,再决定是继续还是重跑当前节点。
代理人机制要写进配置。 审批人休假时,任务不能一直挂着,要按预设规则转给备份人员。代理人变更要留记录,否则责任链会断在假期里。
另有四条属于落地约束,不改变机制结构:
- 阈值规则要写进配置,不要写进 Prompt。Prompt 里的“金额较大时需要人工确认”,模型每次理解都可能不同;配置里的
amount > 500000只有一个含义。分级标准本身按 6.4.5.3 执行。 - 高风险场景可以加双人复核,两个审批人必须都通过,任务才恢复。一个人的误判,不至于直接落到生产。
- 超时前要分级提醒。距离截止还有两小时提醒一次,剩三十分钟再提醒一次,超时后转给上级,而不是静默失败。
- 人工节点不宜过多,每个节点都会增加等待时间。只在高风险、不可逆、对外生效的环节设卡,其余环节用抽样复核;卡子越多,业务越容易绕过系统走线下。
注意:把超时交给计时器自动放行,最危险的决策就变成了“没人反对即通过”。我们在一个夜间批量对账项目里见过这种亏:三笔高风险写入在无人值守时被放行,第二天只能靠回滚脚本补救,其中一笔已经同步给了外部系统。
6.5.2.3 综合示例:状态机、DAG 与人工挂起
下面这段完整代码把状态机、DAG 和人工挂起放在一起,可以直接运行。6.5.1.3 的骨架只演示调度,这里补上挂起与恢复。
python
# Python 3.10+,只用标准库
from dataclasses import dataclass, field
from enum import Enum
from typing import Callable
class State(Enum):
CREATED = "CREATED"
PENDING = "PENDING"
RUNNING = "RUNNING"
SUSPENDED = "SUSPENDED"
SUCCEEDED = "SUCCEEDED"
FAILED = "FAILED"
CANCELLED = "CANCELLED"
@dataclass
class Task:
name: str
run: Callable[["Context"], str]
deps: list[str] = field(default_factory=list)
retries: int = 2
need_human: bool = False
state: State = State.CREATED
output: str | None = None
attempt: int = 0
next_retry_at: str | None = None
@dataclass
class Context:
data: dict[str, str] = field(default_factory=dict)
approvals: set[str] = field(default_factory=set)
def execute(tasks: dict[str, Task], ctx: Context) -> None:
done = {n for n, t in tasks.items() if t.state is State.SUCCEEDED}
max_steps = 100 * max(1, len(tasks))
steps = 0
while len(done) < len(tasks):
steps += 1
if steps > max_steps:
raise RuntimeError("调度超过最大步数,可能存在永久阻塞")
ready = [
t for t in tasks.values()
if t.state in (State.CREATED, State.PENDING)
and set(t.deps) <= done
]
if not ready:
waiting = [t.name for t in tasks.values() if t.state is State.SUSPENDED]
if waiting:
print("流程挂起,等待审批:", ", ".join(waiting))
return
raise RuntimeError("存在循环依赖或永久阻塞")
for task in ready:
# 挂起:人工节点先落库,等待审批注入
if task.need_human and task.name not in ctx.approvals:
task.state = State.SUSPENDED
continue
task.state = State.RUNNING
for attempt in range(task.retries + 1):
if attempt:
task.attempt = attempt
task.next_retry_at = f"now+{2 ** attempt}s"
print(" 计划重试时间", task.next_retry_at)
task.state = State.PENDING # 退避期停在 PENDING
task.state = State.RUNNING # 演示不等待,真实系统由调度器到点唤醒
try:
task.output = task.run(ctx)
ctx.data[task.name] = task.output
task.state = State.SUCCEEDED
done.add(task.name)
break
except Exception as exc:
task.state = State.FAILED
print(f"第 {attempt + 1} 次失败 {task.name}: {exc}")
else:
raise RuntimeError(f"任务最终失败:{task.name}")
print("全部任务完成")
def parse_contract(ctx: Context) -> str:
return "合同正文:付款周期 30 天,金额 80 万元"
def extract_terms(ctx: Context) -> str:
text = ctx.data["parse_contract"]
assert "金额" in text, "缺少金额字段"
return "金额=800000; 付款周期=30"
def check_schema(ctx: Context) -> str:
terms = ctx.data["extract_terms"]
assert "金额=" in terms and "付款周期=" in terms, "字段不完整"
return terms
def write_crm(ctx: Context) -> str:
return f"已写入 CRM:{ctx.data['check_schema']}"
def resume(task: Task) -> None:
# 审批通过或驳回都回到 PENDING;驳回不加入 approvals,带修改意见重跑当前节点
if task.state is not State.SUSPENDED:
raise ValueError(f"{task.name} 当前不是 SUSPENDED")
task.state = State.PENDING
print("审批通过,恢复执行", task.name)
tasks = {
"parse_contract": Task("parse_contract", parse_contract),
"extract_terms": Task("extract_terms", extract_terms, deps=["parse_contract"]),
"check_schema": Task("check_schema", check_schema, deps=["extract_terms"]),
"write_crm": Task("write_crm", write_crm, deps=["check_schema"], need_human=True),
}
ctx = Context()
execute(tasks, ctx) # write_crm 挂起
# 审批注入:把审批结果写回上下文
ctx.approvals.add("write_crm") # 模拟审批通过
resume(tasks["write_crm"]) # SUSPENDED → PENDING
# 断点恢复:从已完成的节点继续
execute(tasks, ctx) # 从断点继续
print(ctx.data["write_crm"])运行环境同样是 Python 3.10 及以上,不需要安装第三方包。保存为 dag_hitl.py,执行 python3 dag_hitl.py,会依次看到挂起提示、恢复执行和最终写入结果。把 check_schema 改成直接 raise ValueError,输出里的重试时间依次是 now+2s、now+4s,第三次失败后抛 任务最终失败:check_schema,由上层转人工。
这个示例把三条线接在了一起:DAG 决定谁先谁后,状态机决定能不能往下走,need_human 决定哪一步要停下来等人。
人把关的位置定了,任务在节点之间怎么传,还需要一套确定的规范。
6.5.3 任务调用的接口设计:强类型参数与语义模板的渲染映射
任务拆好之后,下一个问题是:上游怎么把任务交给下游。偷懒的做法很常见:直接拼一段自然语言。
“请把 ID 为 ABCD 的数据提取出来,放到项目编号 12345678 的库里,然后同步到生产环境。”这句话人能看懂,模型也能看懂,但每次都要重新写。
更麻烦的是,参数藏在句子里,模型需要自己找。项目编号少一位、数据 ID 多一个字母,模型未必发现,发现了也未必按同样的方式处理。
正确的做法,是把任务调用当成接口来设计。接口的输入是数据,不是句子。
6.5.3.1 三层解耦
本节定的是 payload.instruction 的生成方式;信封本身仍按 6.4.2 结构化,自由文本只出现在这个字段里,不放全局通信。
一个任务调用可以拆成三层。
text
(1) 结构化入参 Schema
project_id: "12345678"
data_item_id: "ABCD"
target_action: "SYNC_TO_PROD"
│
▼
(2) 固定语义模板
"请从数据源 [$data_item_id] 提取最新业务快照,
同步至项目 [$project_id] 的存储库,
目标环境为 $target_action。"
│
▼
(3) 渲染与发送引擎
校验参数 → 替换占位符 → 生成最终指令 → 投递第一层是数据结构,每个任务都要有一份入参定义,字段名、类型、必填、取值范围都写清楚,调用方只填数据,不写句子。
第二层是语义模板,模板由架构师维护,经过测试,措辞固定。模板里只留占位符,不允许调用方改结构。
第三层是渲染引擎,它先校验参数,再替换占位符,最后检查生成结果的长度和关键字段,确认无误后才投递。
模板不要追求通用:一个模板服务一个任务,比一个模板适配 10 个任务更好维护。通用模板最后通常会长满条件分支。
三层的边界到这里就定完了,下一节给一个可以跑的最小实现。
6.5.3.2 一个可运行的实现
下面这段代码用 Python 标准库实现三层结构。
python
# Python 3.10+,只用标准库
import re
from dataclasses import dataclass
from string import Template
@dataclass
class SyncTaskInput:
project_id: str
data_item_id: str
target_action: str
def validate(self) -> None:
if not re.fullmatch(r"[0-9]{8}", self.project_id):
raise ValueError("project_id 必须是 8 位数字")
if not re.fullmatch(r"[A-Za-z]{4}", self.data_item_id):
raise ValueError("data_item_id 必须是 4 位字母")
allowed = {"SYNC_TO_PROD", "SYNC_TO_TEST"}
if self.target_action not in allowed:
raise ValueError(f"target_action 必须是 {allowed} 之一")
TEMPLATE_V1 = Template(
"请从数据源 [$data_item_id] 提取最新业务快照,"
"同步至项目 [$project_id] 的存储库,"
"目标环境为 $target_action。"
)
def render(payload: SyncTaskInput) -> str:
payload.validate()
text = TEMPLATE_V1.substitute(
project_id=payload.project_id,
data_item_id=payload.data_item_id,
target_action=payload.target_action,
)
if len(text) > 500:
raise ValueError("渲染结果超过 500 字,请检查模板")
return text
print(render(SyncTaskInput("12345678", "ABCD", "SYNC_TO_PROD")))运行环境同样是 Python 3.10 及以上。执行后会输出一条固定格式的指令,参数位置和措辞都不随调用方变化。
这段代码的重点不在语法,在边界:validate 负责数据类型,TEMPLATE_V1 负责语义,render 负责组装。三层各管一件事,改一层不影响另外两层。
6.5.3.3 接口化带来的三个结果
- 调用方不用再写长 Prompt。 人填表单、上游系统传 JSON,都是确定性输入。
- 参数错误提前暴露。 字段少了、格式错了,在
validate就被拦住,不会等到模型输出一段看起来合理但字段错位的结果。 - Prompt 可以独立迭代。 措辞、示例、输出格式都能改,只要模板变量不变,业务代码不动。
6.5.3.4 调用确认:从“送达”到“听懂”
接口把指令发出去,只完成了投递;上游发指令、下游回结果,消息送达不等于下游看懂。
下游必须先做 Schema 校验,确认字段齐全、类型正确、范围合法,然后回一条确认。没有确认,上游的投递状态最多停在“已送达”,不能算“已完成”。
这条规则听起来繁琐,却能挡住三类常见脏数据:字段缺失、数值错位、格式漂移。字段少一个、金额多了两位、日期从 YYYY-MM-DD 变成时间戳,都会在确认环节暴露。
读确认不能只回一个布尔值,最好把校验结果一起带回来,下游返回解析到的字段数量和失败字段名。确认消息本身也要落表,避免只存在消息队列里,队列一清就查不到。
等到写进数据库再发现,清理成本高一个量级。读者如果维护过数据同步链路,应该对这个顺序不陌生。
6.5.3.5 接口演进与错误处理
模板要版本化:TEMPLATE_V1 改成 TEMPLATE_V2 时,旧接口继续可用。等所有调用方迁移完,再下线旧版本。这样 Prompt 优化不会变成全系统停机。
字段只增不改是接口演进的底线。新字段给默认值,旧调用方不传也能跑;删除字段要先标记废弃,等调用方迁移完再移除。
模板上线前要跑固定用例,同一组参数连续渲染 100 次,输出必须完全一致。换一组边界参数,校验必须按预期报错,不能把错误留到模型那一层。
渲染失败要返回结构化错误码,不要只抛一句异常。调用方需要知道是参数错、模板错,还是下游不可用,这三种情况的处理方式完全不同。
错误码要分层,参数错误返回 400,权限错误返回 403,下游不可用返回 503,调用方据此决定重试还是终止。把错误都包装成 500,会让调用方失去判断依据。
6.5.3.6 模板的安全边界
这里有一个安全边界要单独说。
注意:把用户输入直接拼进模板而不做转义,输入里的指令性文本会被模型当成任务执行,导致越权调用工具或泄露上下文。
模板渲染只能填数据,不能填指令。用户输入要先做白名单校验,再放进占位符。对高风险动作,模板里要明确写死允许的工具列表,不能由输入决定。
读者可以把 6.5.1.3 的调度器骨架和 6.5.3.2 的渲染实现放在一起看:一个负责什么时候跑,一个负责跑什么,职责不重叠。
任务拆好了,接口也定了,接下来要选一个东西把任务管起来。
6.5.4 任务计划工具的选择和应用:从口头承诺到标准化调度
先约定三个与调度有关的词:调度系统指这套能力的集合;调度层指它在架构里的位置;调度中心指部署实例,核心是任务表与队列。
多数团队一开始会直接用 Agent 框架自带的规划功能。
LangChain、LangGraph、AutoGen、CrewAI 都能做一定程度的任务编排。Demo 阶段够用,生产阶段要看清边界。
6.5.4.1 框架自带调度的四个盲区
- 链路不可见。 任务在框架内部被消化,外部系统看不到它派给了哪个 Agent、落在哪个会话、现在跑到哪一步。
- 确认机制缺失。 发送成功不等于对方读到,多数开源框架默认只有消息投递,没有读确认;上游以为完成了,下游其实没解析。
- 断点不可恢复。 多数框架默认把状态放在进程内存里,要恢复得自行接入外部存储,例如 LangGraph 的 checkpointer;进程一挂,整条链从头再来,长任务尤其致命。
- 跨主机不可调度。 多数开源框架默认不带跨主机调度,单进程实例管不了多台机器上的 Agent。任务量一上来只能加机器,加完却没有统一的队列和状态表。
这四条不是框架的缺陷,是定位不同。框架解决的是怎么让模型调工具,不是怎么让 100 个任务在 10 台机器上可审计地跑完。
我们的判断是:单机、单团队、短流程,用框架自带调度更轻。多项目、多主机、要审计、要人工节点,必须把调度提到框架外面,做成独立服务。
6.5.4.2 一个调度系统至少要有什么
八项核心能力:
- 持久化任务表。任务、状态、负责人、产物、时限都落库,进程重启不丢。
- 状态机与事件表。当前状态可查,历史迁移可回放。
- 队列与超时看门狗。任务进队列,超时自动唤醒或告警。
- 幂等键。重试不会产生重复副作用。
- 读确认。发出、送达、已读三个状态分开记,机制见 6.5.3.4。
- 人工节点。挂起、通知、审批、恢复串成一条可恢复的链路。
- 项目隔离。普通成员跨项目互不可见,全局角色按权限可见。
- 审计日志。谁在什么时候做了什么,能导出。
这八项里,最容易被省略的是读确认和幂等。它们不产生新功能,只在出问题时救场。但没有它们,系统在故障面前没有还手之力。
除此之外还有三条部署约束:
- 队列上限。生产速度长期高于消费速度时,任务会堆在队列里,延迟越来越大。超过阈值就拒绝新任务,让上游看见压力,而不是悄悄堆积。
- 多主机独立。任务表和队列必须独立于任何一台执行机,执行机可以挂,调度中心不能跟着挂。时钟统一用数据库时间或网络时间协议(NTP),不用各自主机的本地时间,几秒时间差就会让超时判断互相矛盾。
- 优先级。付款、对账这类有截止时间的任务走前面的通道,报表生成可以往后放。没有优先级时,一个批量任务能把所有实时任务堵在队列里。
6.5.4.3 Agentgeex 的落地方式
我们在 Agentgeex(仓库名 agentgeex)项目里采用的就是外部调度这条路。Agentgeex 是本书团队自研的 Agent 任务调度与项目管理平台,它不负责模型推理,只负责把任务管清楚。
一次任务派发会生成一条执行记录,记录里有任务编号、发起方、执行方、会话、超时时间和指令正文。任务结束后,执行方回写结果和总结。
调度层做三件事:第一,按状态推进,该唤醒的唤醒,该告警的告警。第二,按依赖串联,计划里的步骤通过前置和后置关系连成链,前置没完成,后置不会启动。第三,按项目隔离,每个项目有自己的成员、任务和会话,跨项目调用要被拒绝。
第一件事的执行者是看门狗,它不是定时重启,只做三件事:发现超时、发出提醒、按策略推进。重启进程是最后手段,不是默认动作。人工不盯着,流程也能往前走。
看门狗的扫描间隔要和任务时长匹配,短任务用三十秒,长任务用五分钟,间隔太密会空转,太疏会延迟发现故障。扫描本身要轻量,只查索引字段,不加载完整指令。
这套结构带来的直接变化是:任务不再是“口头承诺”,而是表里的一行记录。谁派的、谁接的、跑到哪、卡了多久,都能查。
工具选型的判断标准,不是功能列表长短,而是出故障时能不能定位。能在五分钟内回答“卡在哪个节点、谁负责、上次心跳什么时候”,这套工具就合格。
读者在选型时,可以拿一条真实故障去试,看看这套工具能不能在五分钟内给出定位。
回答不了,功能再多也只是演示,任务管理工具的价值在事故现场才真正体现。
后端把任务管住之后,人还需要一个入口去看它、批它、追溯它,这就是下一节的界面。
6.5.5 人机界面的设计和开发:区分框架界面与企业级应用界面
最后一个环节是界面,先澄清一个常见混淆:Agent 框架自带的界面,不等于企业级 Agent 应用的界面。
Dify、Coze、OpenClaw 控制台这类工具都有前端,但按各自的公开文档和默认配置,服务对象主要是开发者和单次任务。打开界面,看到的通常是一个会话框、一段回答、几个工具调用;编排型产品则是一张工作流画布。
它们不理解项目、角色、权限,也不保存完整的任务审计。企业要的不是聊天窗口,是一个能管住多个项目、多个 Agent、多个任务的控制台。
6.5.5.1 四层功能结构
一个可用的企业级控制台,可以按四层组织。
| 层 | 放什么 | 职责 |
|---|---|---|
| 组织层 | 项目、项目组 | 资源隔离的第一边界,管人和权限 |
| 资源层 | Agent、会话 | 按项目挂载,展示角色、模型、技能(Skill)与任务上下文 |
| 执行层 | 任务、快捷指令 | 看拆解结构、执行轨迹、耗时和状态;填表单触发任务 |
| 治理层 | 技能库、审计 | 管理可复用技能的版本与发布范围;全量事件检索 |
组织层没定对,后面的权限和审计都会漏。一个企业同时跑五个 Agent 项目,数据、Agent、任务都不能混,这一层是它们唯一的公共边界。
后三层各有一个易错点。资源层的会话要能恢复现场,不能只剩一条消息流;执行层的快捷指令应直接复用 6.5.3 的强类型接口,而不是另写一套表单;治理层的技能库要有版本与发布范围,审计要能按任务、Agent、时间检索。
这四层里,执行层使用频率最高,治理层价值最大。不少团队把执行层做得很好看,治理层只有一个日志列表。真出问题时,能救命的恰恰是治理层。
审批界面要展示差异,而不是整份文档。人只需要看这次改动涉及的三个字段,审批速度会快很多,漏看概率也低。
控制台的第一屏应该回答今天有什么需要处理,而不是展示模型有多聪明。待审批数量、失败任务数量、平均耗时,这三个数字比任何演示动画都有用。
权限要落到按钮级:谁能看任务、谁能派任务、谁能审批、谁能改配置,都要在后端校验。前端隐藏按钮只是提示,不是权限。
6.5.5.2 审计要回答四个问题
企业级界面和调试界面的分水岭,是能不能回答四个问题。谁发起了这个任务,任务投给了哪个 Agent 的哪个会话,每一步的状态和产物是什么,接收方有没有真正读取并校验结果。
四个问题都能回答,界面才具备治理能力。只能展示最终回答,那就还是聊天工具。
任务详情页应该是时间线,不是一段文本。
text
09:12:03 CREATED 运营张三 创建任务
09:12:04 DISPATCHED 投递至 agent_sales 的会话 102
09:12:31 RUNNING 开始执行
09:18:22 SUCCEEDED 产出 3 个文件,Schema 校验通过
09:19:05 READ 下游 agent_crm 确认接收时间线里的 DISPATCHED 就是投递轴的 sent(已投递);PENDING 与投递同时发生,图中省略。
这条时间线能直接回答“卡在哪”。如果 DISPATCHED 之后一直没有 RUNNING,问题在投递或唤醒。
如果 RUNNING 超时,问题在执行节点。如果 SUCCEEDED 之后没有 READ,问题在下游。排查路径一下子从猜测变成了定位。
时间线里混着两条轴:CREATED、RUNNING、SUCCEEDED 属于任务生命周期,DISPATCHED、READ 属于投递轴。两条轴各记各的,见 6.5.1.2。
任务详情页还要支持导出,审计人员不一定有系统账号,导出 PDF 或 CSV 后才能在离线环境核对。导出内容要包含事件时间线和产物引用,不能只有一张结果截图。
界面不是装饰,是治理入口:业务人员通过它发起任务,管理者通过它发现问题,审计通过它还原过程。
把界面当成聊天框的附属品,前面四节做的拆解、状态机、接口和调度,在最后一公里都会失效。
6.5.5.3 看板与性能
审计之外,界面还要能推动日常工作。看板要按状态分组,不要按时间倒序堆一张长表。待审批、执行中、失败待处理,这三个分组比 100 条日志更能推动工作。
审计日志要独立存储,保留时间按合规要求定。任务表可以归档,审计记录不能跟着删。
任务列表超过 1 万条时,必须分页和按状态过滤,不能一次全查。列表页只查摘要字段,详情页再加载指令正文和产物,接口响应时间才压得住。
到这里,6.5 的五节就走完了:拆解与计划把任务变小(含状态机与 DAG),人工节点把风险控住,接口把调用变确定,调度工具把整条链管起来,界面把过程变得可看。
下一节我们回到更根本的问题:这些设计背后,Agent 应用的软件工程本质到底是什么。
6.6 总结与感言:Agent 应用的软件工程本质与架构思维
本章值得多花一点篇幅收尾。它是全书方法论的落点,需要一个从“怎么造”回到“为什么这样造”的收束。
6.1、6.2 打了地基(必要性、设计模式),6.3—6.5 是主体,讲业务怎么拆、架构的八根支柱、任务怎么规划、怎么执行、怎么留痕。把这三块拼起来,其实只回答了一个问题:Agent 应用到底该按什么方式造。
我们的答案不是“让模型更强”,而是“让系统更确定”。
本节说三件事。第一,Agent 应用为什么仍然受软件工程约束。第二,程序员这个职业在变什么、不变什么。第三,架构思维在 AI 时代为什么更值钱。
6.6.1 Agent 再智能,其本质依然是软件
6.1 已经从“输入、加工、输出”的角度论证过一遍。这里换个更直接的办法:看它在生产环境里是怎么坏的。
过去两年,我们在若干 Agent 项目里见过、也修过故障。下面的分类来自这些观察,是归纳,不是统计。6.2.3 说的结构缺失,落到生产环境就是这些样子。
| 故障现象 | 对应的工程问题 | 缺了它会怎样 |
|---|---|---|
| 模型把金额字段填成字符串,没有一处拦得住 | 接口契约:工具的 JSON Schema 与参数校验 | 脏数据直接落库,下游对账全乱 |
| 长任务跑到中后段,上下文被压缩,Agent 忘了最初的目标 | 状态机:任务的全生命周期 | 任务卡死没人知道,重复派发也没人拦 |
| 工具调用超时后自动重试,同一笔退款执行了两次 | 事务与补偿:幂等键与回滚动作 | 一次重试就是一笔重复扣款 |
| 两个子 Agent 同时写同一个文件,后写的覆盖先写的 | 并发控制:写锁与唯一键(用于去重) | 并发写入互相覆盖,谁最后写完谁说了算 |
| 出错之后,说不清是哪一步、哪次工具调用出的问题 | 日志与链路追踪(Trace):执行记录与调用链 | 出错只能靠猜,现场无法重建 |
| 一个任务跑完,账单比预期高出几十倍 | 资源配额:Token 预算、步数上限和超时 | 成本不可预测,约束要写进代码而不是提示词(Prompt)里 |
| Agent 调用了不该它调用的工具,读到了别的项目的数据 | 权限模型:工具白名单与项目隔离 | 一次提示词注入就能越界 |
| 模型升级后,原来稳定的流程开始胡说 | 回归测试:固定用例回放 | 换模型等于重新赌博 |
这几类问题有一个共同点:没有一类是因为“模型不够聪明”。
这些故障的处置手段,全部是传统软件工程手段。老问题换了一件衣服又回来了,逐条对下来,几乎没有剩下什么新东西。
这些故障的处置动作,绝大部分并不发生在模型侧。加一层参数校验、加一个唯一键、加一条超时规则,问题往往就消失了。处置本身并不难,难的是在设计阶段就预判到它会这样坏。
所以“用确定性架构治理概率性 AI”不是一句口号。它是安全工程里最普通的一条原则:把模型的输出当成不可信输入来处理。所有外部输入都要校验,所有副作用都要可重试且幂等,或至少可补偿,所有状态都要可恢复。
模型只是换了一个更难预测的输入源,原则没有变。
模型还有一个传统输入源没有的特点:它不是确定性函数。同样的输入,temperature 大于 0 时输出会变;即使把 temperature 设成 0,模型版本一升级,行为也可能变。这意味着“上次跑通了”不能作为“这次也能跑通”的证据。
所以在 Agent 架构里,有一条分工要提前定死:模型负责判断,代码负责裁决。模型可以建议给用户退款,但是否真的退、退多少、退给谁,由代码按规则判定。
举个很小的例子。你在 Prompt 里写“单笔退款不要超过 5000 元”,模型绝大多数时候会遵守。偶尔一次,它可能因为上下文里多了一段用户诉苦而心软。而在代码里写 if amount > 5000: reject(),每一次都会拦住。
看一段代码就明白了。
python
# Python 3.10+,无第三方依赖:sqlite3 存幂等键,Decimal 存金额
import sqlite3
from dataclasses import dataclass
from decimal import Decimal, InvalidOperation
MAX_AMOUNT = Decimal("5000.00")
DOWNSTREAM_CALLS = 0
@dataclass
class Refund:
order_id: str
amount: Decimal
def parse_refund(raw: dict) -> Refund:
order_id = raw.get("order_id")
amount = raw.get("amount")
if not isinstance(order_id, str) or not order_id.startswith("ORD-"):
raise ValueError(f"order_id 非法: {order_id!r}")
try:
value = Decimal(str(amount))
except (InvalidOperation, TypeError):
raise ValueError(f"amount 不是合法数字: {amount!r}")
if not (Decimal("0") < value <= MAX_AMOUNT):
raise ValueError(f"amount 越界: {amount!r}")
return Refund(order_id, value.quantize(Decimal("0.01")))
def call_downstream(r: Refund) -> str:
global DOWNSTREAM_CALLS
DOWNSTREAM_CALLS += 1
return f"refunded {r.amount} for {r.order_id}"
def refund(conn: sqlite3.Connection, idem_key: str, raw: dict) -> str:
row = conn.execute(
"SELECT result FROM refunds WHERE idem_key = ?", (idem_key,)
).fetchone()
if row is not None:
return f"{row[0]}(命中幂等记录,未调用下游)"
r = parse_refund(raw)
result = call_downstream(r)
conn.execute(
"INSERT INTO refunds (idem_key, result) VALUES (?, ?)", (idem_key, result)
)
conn.commit()
return result
def main() -> None:
conn = sqlite3.connect("refund.db")
conn.execute(
"CREATE TABLE IF NOT EXISTS refunds "
"(idem_key TEXT PRIMARY KEY, result TEXT NOT NULL)"
)
print(refund(conn, "req-001", {"order_id": "ORD-9", "amount": "99.00"}))
print(refund(conn, "req-001", {"order_id": "ORD-9", "amount": "99.00"}))
try:
refund(conn, "req-002", {"order_id": "ORD-9", "amount": "-1"})
except ValueError as e:
print("已拦截:", e)
print("下游调用次数:", DOWNSTREAM_CALLS)
if __name__ == "__main__":
main()保存为 refund_guard.py,用 python3 refund_guard.py 运行,输出是:
text
refunded 99.00 for ORD-9
refunded 99.00 for ORD-9(命中幂等记录,未调用下游)
已拦截: amount 越界: '-1'
下游调用次数: 1两次调用的结果一致,第二次没有碰下游,下游只被调用了一次。幂等键落在 sqlite 里,把进程重启再跑一遍,两次都会命中幂等记录,下游调用次数为 0。
这段代码没有一行是在让模型更聪明。它只做三件事:类型校验、范围校验、幂等。这三件事在几十年前的银行核心系统里就已经是常规做法。
Agent 应用能不能上线,往往就取决于这些不性感的代码有没有写。模型决定的是系统上限,架构决定的是系统下限。上限可以很高,但决定一个系统能不能用的,是下限。
6.6.2 硅基浪潮下,程序员与架构思维的重构
既然下限由架构决定,下一个问题自然落到人身上:架构由谁定。
这两年“程序员要消失”的说法反复出现。我们的判断很明确:消失的是“把需求翻译成语法”的岗位,不是“把模糊业务拆成确定边界”的能力。本节说的“重构”,指的是能力结构从“实现力”转向“判断力”,不是职业的消失。
先看哪些工作确实在消失。
- 记住某个库的函数签名。
- 手写增删改查。
- 写重复的胶水代码。
- 调 CSS 让按钮往左挪两个像素。
这些工作的共同点是:输入明确、输出可验证、做错了代价低。恰好是模型最擅长的区间。
再看哪些工作没有消失。
- 判断这个需求该不该做。
- 判断这个模块该不该拆。
- 判断失败的时候怎么退。
- 判断谁有权限看、谁有权限改。
这些工作的共同点是:输入模糊、没有标准答案、做错了代价高。模型可以给你五个方案,但它不承担后果。也就是说,经验的价值在上升。
代码变便宜之后,变贵的是“决定写什么”和“决定不写什么”。
本章 6.4 的八根支柱就是例子。让 Agent 生成一个能跑的 demo,可能只需要一段 Prompt。但 demo 要上线,这八根支柱里每一个都对应一个必须由人拍板的决定,这里只挑其中五项:框架怎么选、协议字段怎么定、目录怎么分层、知识库怎么隔离、人员能力的提取与映射(6.4.8)。
这些决定没有一个是模型能替你拍板的。
这些选择不是技术题,而是责任题。
有人会说,等模型再强一点,这些也能自动做。我们的看法是:即使未来 Agent 能写完所有代码,审计、数据路由、安全隔离、契约调用这些东西依然存在。因为它们本质上不是编程,是责任分配。
代码可以自动生成,但责任无法自动生成。
这里要把适用边界说清楚。如果你的需求只是写一个一次性脚本,跑完就扔,那确实不需要架构。Agent 足够用。
但只要系统要长期运行、要多人接手、要动钱或者要接受合规检查,架构判断就绕不过去。这不是立场问题,是成本问题。省下的设计时间,后面会以数倍的维护时间还回来。
如果要把“架构思维”拆成可以练习的动作,我们的总结是四件事:划边界、定契约、设状态、留痕迹。
- 划边界:哪些事归这个 Agent,哪些事不归。边界不清,Agent 就会越权或者互相打架。
- 定契约:输入输出长什么样,字段类型、取值范围、失败语义。契约不清,模型只能猜。
- 设状态:任务走到哪一步、失败了停在哪、重试从哪开始。状态不清,一次失败就会变成一团乱麻。
- 留痕迹:谁发起、谁执行、谁确认、耗时多少。痕迹不清,出了问题只能重建现场。
这四件事不需要高深的算法,但需要有人对结果负责。它们就是 6.2.4 那张契约字段表要检查的这四项:边界、契约、状态、痕迹,逐项落成字段。这也是为什么我们一直说,Agent 应用的核心竞争力不在模型,在架构。
架构思维不是一种气质,而是一组可以检查的动作。你可以拿一张纸,把系统的边界、契约、状态、痕迹各写一页。写不满一页的地方,通常就是后面最容易出问题的部分。
6.6.3 效能飞跃与架构师的“黄金时代”
前面讲的是分工怎么变,这里说成本结构怎么变。真正变化的,是每件事的执行成本。
过去,一个架构师的想法受限于三件事:打字速度、调试时间、平台适配。设计再漂亮,落地还是要一行行写。一个人想在一个月内交付一套跨平台系统,基本不现实。
现在,只要架构足够清晰,实现这一段可以并行铺开。
效能放大有三个前提,缺一个都会变成返工。
- 任务可拆。拆到单一职责、上下文能隔离,否则 Agent 之间互相污染。
- 验收可判。每个子任务有明确的完成标准,否则交回来的东西没法判断对错。
- 失败可退。出错能回滚、能重跑、能定位,否则一次错误会滚成一串错误。
这三条不成立的时候,Agent 带来的不是效率。就像一个没有审校机制的实习生,写得越多,技术债越多。
这三个前提听起来像常识,其实在 6.5.1.1(单一职责、上下文隔离)、6.5.1.4(失败处理与幂等边界)、6.5.2(人在回路)里都出现过。
任务拆到多细、验收标准由谁签字、失败后回滚到哪个版本,这些都要在开工前落到纸面。等 Agent 跑起来再讨论,返工就已经发生了。
反过来说,如果这三条都成立,一个人确实可以推进过去需要一个团队才能推进的工程量。本章本身就是按这三条跑出来的:拆分写作、按轮审校、保留全部中间版本。
所以“黄金时代”这个说法,有它的前提:三个前提成立,它才是黄金时代;不成立,放大的只是返工。
对能定架构、能判验收、能兜后果的人,AI 确实是放大器。对只会接需求、等着别人给方案的人,AI 更像替代品。
AI 放大的是人的判断。判断对了,它帮你把正确的事做快;判断错了,它帮你把错误的事做大。方向由人定,速度由机器给。
小结到这里。剩下的几句,是感言。
年龄在 AI 时代反而成了一种优势。我们的观察是,资深工程师最值钱的两样东西,是对失败模式的记忆和对边界的判断。这两样恰好是模型最难学到的,因为它们不在语料里,在后果里。
这也是我们愿意把这本书写完的原因:它不是一份宣言,更像一张施工图。读者不需要同意我们的判断,只需要能照着跑一遍。