Skip to content

第 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 / acceptancestr / list[str] / float / list[str]问题定义、知识资产、成本上限、验收标准
架构设计runtime / roles / protocol / storage / knowledgestr / dict[str, str] / str / str / list[str]Agent 框架、角色映射(键固定 human / agent,值填具体岗位)、通信协议、目录结构与存储底座、结构化知识
任务流planner / human_gates / flow_model / dispatch / uistr / 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 result

nx=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 已覆盖的身份与工具授权,共五项。

  1. 路径注入(增量):工作目录、输入目录、输出目录直接注入,不让 Agent 猜。
  2. 协议挂载(增量):消息格式、总线地址、回执规则挂到每个节点上。
  3. 交付契约(增量):输出格式、验收标准、失败时的回报方式。
  4. 身份(6.3.4 已覆盖):agent_id、角色名、所属项目,用于寻址和权限判断。
  5. 工具授权(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:主动取消。

状态只能沿定义的边迁移,表外的迁移一律拒绝。

从到触发条件
CREATEDPENDING进入队列、依赖已就绪
PENDINGRUNNING被调度器领取
RUNNINGSUCCEEDED节点执行成功,产物校验通过
RUNNINGFAILED节点执行失败
RUNNINGSUSPENDED命中人工节点,或等待外部事件
SUSPENDEDPENDING审批通过、驳回(带修改意见重跑当前节点)或外部事件到达,重新排期
SUSPENDEDFAILED超时按策略终止
FAILEDPENDING未超过重试次数,重新排期
PENDINGCANCELLED依赖任务永久失败(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 时代反而成了一种优势。我们的观察是,资深工程师最值钱的两样东西,是对失败模式的记忆和对边界的判断。这两样恰好是模型最难学到的,因为它们不在语料里,在后果里。

这也是我们愿意把这本书写完的原因:它不是一份宣言,更像一张施工图。读者不需要同意我们的判断,只需要能照着跑一遍。

文字 CC BY-NC-SA 4.0 | 代码 Apache-2.0