从粗放第一代智能体 单轮一问一答无状态多步任务直接抓瞎 + 工具说明硬塞 prompt 用正则 if-else 硬解析自由文本措辞一变就崩 + 无记忆每轮从白纸开始记不住任何上下文 + 无规划埋头乱做复杂任务一团乱 + 单 agent 光杆司令塞满所有角色和几十个工具样样稀松 + 跑起来就是黑盒关键操作无法叫停 + 死循环反复重试 token 像流水一样烧 + 整个执行黑盒出事查不到想了啥调了啥 + 自由文本输出下游靠正则抠格式一变就崩 → 2026 现代 AI Agent 工程体系 ReAct 推理-行动-观察循环多步任务自主迭代 + 标准化 function calling 与 MCP 结构化工具调用 + 短期记忆加长期向量检索分层记忆 + planning 先分解子任务再执行 + multi-agent 多智能体 supervisor 分工协作 + human-in-the-loop 关键动作前人工审批 + 循环上限加预算控制加 guardrails 护栏兜底 + 全链路 tracing 每步可查 + 结构化输出加 schema 校验 + 上下文压缩按需检索记忆 87 天战役复盘:47 套工程修法 + 7 个 P0 复盘 + 6 条工程哲学

我们是一支 13 人的 AI Agent(智能体)工程团队,过去一年里在线上跑着一套"第一代"的智能体系统——说是智能体,其实更像一个套了层壳的单轮问答机器人。它的毛病在我们把它推上生产、扛真实业务量之后一个接一个地暴露:它本质上是单轮、无状态的,用户问一句它答一句、一轮结束上下文就丢光,根本没有"先想一步、再做一步、看了结果再想下一步"的推理与行动循环,稍微复杂一点、需要多步才能完成的任务它就抓瞎;它调用外部工具(查数据库、调接口)的方式极其原始——把所有工具的说明一股脑硬塞进 prompt 里,然后用一堆正则和 if-else 去硬解析模型吐出来的自然语言、试图从里面抠出"它想调哪个工具、参数是什么",模型措辞稍微一变解析就崩;它没有任何记忆,每次对话都从一张白纸开始、记不住用户三轮前说过的话、更记不住上周的偏好;它是个光杆司令、一个 agent 啥都想干、没有分工没有规划、面对复杂任务直接埋头乱做;它一旦跑起来就是个黑盒、没人能介入、没法在关键操作前叫停审批;它会陷入死循环、一个工具调用失败就反复重试同一步、把 token 像流水一样烧掉而我们浑然不觉;它整个执行过程不可观测,出了问题我们连"它到底想了什么、调了哪些工具、在哪一步跑偏的"都无从查起。这套系统能演示、却扛不住真实业务,每一次线上故障复盘,结论都指向同一句话:我们缺的不是一个更聪明的模型,而是一整套让智能体真正可控、可靠、可观测的工程体系。

我们花了 87 天,把这套粗放的第一代智能体,系统性地重构成了 2026 年的现代 AI Agent 工程体系。这不是简单地换个更强的大模型,而是一次从"单轮问答、硬解析工具、无记忆无规划、黑盒不可控"到"ReAct 推理行动循环、标准化工具调用、分层记忆、任务规划、多智能体编排、人在回路、护栏兜底、全链路可观测"的范式跃迁。下面这张表,是我们这次智能体现代化战役里十个关键战场的"重构前 → 重构后"全景对比。

这套体系不是一蹴而就的,而是 13 个人在 87 天里、在一套天天还在服务真实用户的智能体系统上,一个能力一个能力地补、一个失控点一个失控点地堵、一条链路一条链路地接上观测,啃下来的。最终我们沉淀了 47 套工程修法、7 个 P0 事故复盘和 6 条工程哲学。下面从十个战场逐一复盘。

一、执行范式:从单轮问答到 ReAct 推理-行动-观察循环

第一仗,也是整场战役的地基,就是把智能体从"单轮问答机"改造成一个会"想一步、做一步、看结果、再想下一步"的推理-行动循环。古早时代我们的 agent 是单轮、无状态的:接到用户的问题,一次性地让大模型生成一个回答,完事——可现实里大量任务根本不是一问一答能解决的,比如"查一下张三这个月的订单总额、如果超过一万就给他发张优惠券",这需要先调订单接口查数据、看到结果再决定要不要调发券接口,是一个"行动→观察结果→再决策"的多步过程,而我们那个单轮 agent 面对这种任务要么瞎编一个答案、要么直接卡死。现代做法是采用 ReAct(Reasoning + Acting)范式:让 agent 在一个循环里反复地"推理(thought:我现在该干什么)→行动(action:调用某个工具)→观察(observation:拿到工具返回的结果)",每一轮都把上一轮的观察结果纳入下一轮的推理,如此迭代直到任务完成。下面是执行范式的对比:

# 重构前:单轮无状态,一次性生成回答,多步任务直接抓瞎
# def agent(question: str) -> str:
#     return llm.complete(f"回答用户问题:{question}")  # 一锤子买卖
# agent("查张三本月订单总额,超一万就发券")              # 无法查库、无法决策,只能瞎编

# 重构后:ReAct 循环,推理→行动→观察反复迭代,多步任务自主完成
def react_agent(task: str, tools: dict, max_steps: int = 10) -> str:
    history = [{"role": "user", "content": task}]
    for step in range(max_steps):                         # 循环上限兜底,见第七仗
        decision = llm.decide(history, tools)             # 推理:该思考还是该调工具
        if decision.is_final:                             # 任务完成,返回最终答案
            return decision.answer
        # 行动:调用模型选定的工具
        result = tools[decision.tool](**decision.args)    # observation
        history.append({"role": "tool", "name": decision.tool, "content": result})
        # 下一轮推理会带着这次的 observation,逐步逼近目标
    raise RuntimeError("超过最大步数仍未完成")             # 防失控,不无限循环

执行范式让我们从"单轮无状态一问一答、一次性生成回答、面对需要多步行动和决策的复杂任务直接抓瞎只能瞎编或卡死"进化到了"ReAct 推理-行动-观察循环、每轮把上一轮观察纳入下一轮推理、反复迭代直到任务完成":过去我们的智能体本质上就是一个单轮的问答函数,把用户的问题丢给大模型、一次性地拿回一个回答就结束了,它脑子里没有"这件事要分几步做、做完一步看看结果再决定下一步"的概念,可真实业务里绝大多数有价值的任务都是多步的——要先查个数据、根据查到的结果再判断、再决定调用下一个工具——这种需要"行动、观察、再决策"反复交替的活,单轮 agent 根本无从下手,要么强行一次性瞎编一个看似合理实则错误的答案、要么干脆卡死;现在我们采用了 ReAct 这一智能体的核心范式,让 agent 运行在一个循环里:每一轮它先做推理(想清楚当前这一步到底该做什么),然后采取行动(调用一个具体的工具去执行),再获得观察(拿到这个工具返回的真实结果),关键在于每一轮的观察结果都会被纳入下一轮推理的上下文里,于是 agent 能像人解决问题一样、根据每一步的实际反馈动态地调整后续的计划、一步一步地逼近最终目标,直到它判断任务已经完成才跳出循环给出答案。我们的纪律是"一切非平凡任务走 ReAct 循环而非单轮、每轮推理与行动分离、observation 必须真实回填进上下文、循环必须设最大步数上限防失控"。执行范式的本质认知是:大模型单次生成的本质是"基于当前已知信息一次性地给出最可能的输出",它没有与环境交互、获取新信息、再据此修正的能力,而现实任务的复杂性恰恰在于"很多关键信息要在执行过程中边做边获取、后续的决策高度依赖前面步骤的真实结果"——用单轮问答去解多步任务,等于要求一个人闭着眼睛、不许中途睁眼看一下、就把一件需要边看边做的事一口气做完;ReAct 的智慧是给智能体装上"行动-观察-再推理"的反馈闭环,让它能够主动调用工具去和真实世界交互、把每一步的真实结果作为下一步决策的依据,从而把大模型从一个"一次性的回答生成器"升级成一个"能在与环境的反复交互中逐步完成复杂任务的自主体",这是一切真正智能体的起点。

二、工具调用:从正则硬解析自然语言到标准化 function calling

第二仗,是把智能体调用外部工具的方式从极其脆弱的"硬解析"升级成稳健的"结构化函数调用"。古早时代我们让 agent 用工具的方式简直是刀耕火种:把所有工具的名字、用途、参数说明用自然语言一股脑写进 prompt,然后祈祷模型在回答里以某种我们约定的格式(比如"调用工具:查订单(用户=张三)")把它想调的工具和参数表达出来,我们再写一大堆正则表达式和 if-else 去解析模型这段自然语言、试图把工具名和参数抠出来——可大模型的输出是自由文本、措辞和格式随时会变,今天它写"调用工具:查订单"、明天可能写成"我需要查一下订单"或"call check_order",我们的正则解析三天两头崩、抠出来的参数也经常缺胳膊少腿。现代做法是用大模型原生支持的 function calling(函数调用 / 工具调用)能力:我们用结构化的 JSON Schema 把每个工具的名字、参数、类型清清楚楚地声明给模型,模型则直接以结构化的、保证格式正确的方式返回"我要调用哪个函数、参数是这些"(而非自由文本),我们拿到的是可以直接解析执行的结构化数据,彻底告别正则;更进一步,我们用 MCP(Model Context Protocol)这类标准协议来统一描述和接入工具。下面是工具调用的对比:

# 重构前:工具说明硬塞 prompt,正则 if-else 硬解析自由文本,措辞一变就崩
# prompt = "你有这些工具:查订单(用户名)、发券(用户名)。需要时请说'调用工具:xxx(参数)'"
# resp = llm.complete(prompt + task)
# m = re.search(r"调用工具:(\w+)\((.+?)\)", resp)   # 模型换个措辞正则就抓瞎
# if m: tool_name, arg = m.group(1), m.group(2)       # 参数还得自己再切分,缺参就崩

# 重构后:用 JSON Schema 声明工具,模型原生 function calling 返回结构化调用
tools = [{
    "type": "function",
    "function": {
        "name": "query_order",
        "description": "查询某用户本月订单总额",
        "parameters": {                                   # 结构化 schema,参数类型明确
            "type": "object",
            "properties": {"user": {"type": "string"}},
            "required": ["user"],
        },
    },
}]
resp = llm.chat(messages, tools=tools)                    # 模型原生支持工具调用
for call in resp.tool_calls:                              # 直接拿到结构化调用,无需正则
    args = json.loads(call.function.arguments)            # 参数已是合法 JSON
    result = registry[call.function.name](**args)         # 按名分发执行,稳定可靠

工具调用让我们从"工具说明用自然语言硬塞进 prompt、靠正则和 if-else 去解析模型吐出的自由文本来抠工具名和参数、模型措辞或格式稍变解析就崩参数还经常缺失"进化到了"用 JSON Schema 结构化声明每个工具的名字参数类型、模型原生 function calling 直接返回保证格式正确的结构化调用、拿到即可解析执行彻底告别正则、用 MCP 标准协议统一接入工具":过去我们让智能体使用工具的方式脆弱得令人头疼——把工具的清单和用法用大白话写在 prompt 里,然后指望模型在它的自由文本回答里按我们口头约定的某种格式把"想调哪个工具、传什么参数"说出来,我们再用一堆正则表达式去模型这段措辞千变万化的自然语言里大海捞针般地抠出工具名和参数,可大模型生成的本就是不受严格约束的自由文本、它今天这么说明天那么说、多一个字少一个标点我们的正则就匹配失败,即便匹配上了抠出来的参数也常常格式不对或缺斤少两,导致工具调用这个智能体最核心的能力三天两头出故障;现在我们用上了主流大模型都原生支持的 function calling 能力,把每一个工具都用 JSON Schema 这种结构化的方式精确地声明给模型——工具叫什么、有哪些参数、每个参数是什么类型、哪些是必填,清清楚楚,模型在需要用工具时不再吐自由文本、而是直接以一种结构化的、由模型服务端保证格式合法的形式返回"我要调用名为 query_order 的函数、参数是 {user: 张三}",我们拿到的就是可以直接 json.loads 解析、按函数名分发执行的干净结构化数据,正则解析这种脆弱环节被整个删除了,更进一步我们还引入了 MCP 这类标准协议来统一地描述、发现和接入各种工具,让工具的接入也标准化、可复用。我们的纪律是"一切工具调用走原生 function calling 严禁正则解析自由文本、工具一律用 JSON Schema 声明参数和类型、工具执行前校验参数、优先用 MCP 标准协议接入工具便于复用、工具要幂等且有超时和错误处理"。工具调用的本质认知是:让大模型去使用工具,核心难题在于如何在"模型生成的是概率性的自由文本"和"工具执行需要的是确定性的结构化指令"这两者之间架起一座可靠的桥——用正则去解析自由文本,是在试图从不确定性里硬凑确定性,注定脆弱;function calling 的智慧是把这座桥的建造责任从我们的正则代码挪到了模型本身和它的服务端,让模型被训练和约束成能够直接输出符合我们声明的 schema 的结构化工具调用、由服务端保证其格式合法,从而把工具调用从一个靠运气的字符串解析问题、变成了一个稳定可靠的结构化数据交换问题,这是智能体能够稳定、可靠地与外部世界交互、真正具备"动手能力"的根本前提。

这十个战场不是孤立的,它们彼此咬合、层层递进,共同构成了从单轮问答机到现代自主智能体的完整跃迁。下面这张图,勾勒出我们这套 AI Agent 工程体系里一个任务从进入、规划、在 ReAct 循环中调用工具与记忆、经护栏与人工审批、到全程被可观测系统记录的全景脉络:

三、记忆系统:从每轮白纸开始到短期记忆加长期向量检索

第三仗,是给智能体装上记忆。古早时代我们的 agent 是彻底失忆的:每一次对话、甚至每一轮交互都从一张白纸开始,记不住用户三轮前说过的话、记不住这次会话里已经查到的中间结果、更记不住这个用户上周表达过的偏好,导致它要么反复问用户已经说过的信息、要么在多轮任务里前言不搭后语。现代做法是构建分层的记忆系统:短期记忆(working memory)保存当前这次会话的上下文(对话历史、本次已获得的中间结果),让 agent 在一次任务的多轮交互里保持连贯;长期记忆(long-term memory)则把跨会话需要持久记住的东西(用户偏好、历史事实、过往交互)存进向量数据库,需要时通过语义检索(把当前情境向量化、去向量库里召回最相关的记忆片段)按需取回、注入上下文。下面是记忆系统的对比:

# 重构前:无记忆,每轮从白纸开始,记不住任何上下文
# def chat(msg: str) -> str:
#     return llm.complete(msg)   # 只有当前这一句,前面说的、用户偏好,全忘光

# 重构后:短期记忆保会话连贯 + 长期记忆向量检索按需召回
class Memory:
    def __init__(self, vec_db):
        self.short_term: list = []        # 短期:本次会话的对话历史 + 中间结果
        self.vec_db = vec_db              # 长期:向量库,跨会话持久记忆

    def remember(self, text: str):
        self.short_term.append(text)
        self.vec_db.upsert(embed(text), text)        # 同时写入长期向量记忆

    def build_context(self, query: str, k: int = 5) -> list:
        # 长期记忆:语义检索召回最相关的 k 条历史记忆
        recalled = self.vec_db.search(embed(query), top_k=k)
        # 短期记忆 + 召回的长期记忆,一起组成喂给模型的上下文
        return self.short_term[-10:] + [r.text for r in recalled]
        # ↑ 短期保连贯、长期按需取,既不失忆也不无脑全塞(见第十仗上下文管理)

记忆系统让我们从"彻底失忆每轮从白纸开始、记不住几轮前说的话和本次的中间结果、更记不住用户跨会话的偏好、反复追问已知信息或前言不搭后语"进化到了"分层记忆:短期记忆保存本次会话上下文让多轮交互连贯、长期记忆把跨会话要记住的存进向量库需要时语义检索按需召回注入":过去我们的智能体最反直觉的一点就是它没有任何记忆——不仅跨会话记不住,甚至在同一次任务的多轮交互里都常常丢失上下文,每次调用大模型都只带着当前这一句话、把之前的对话和已经查到的中间结果全忘干净,结果就是它会反复地问用户一些早就回答过的问题、会在一个需要好几轮才能完成的任务中途突然忘了自己在干什么、会对一个老用户表现得像从没见过他一样完全不记得他的偏好,体验和可靠性都大打折扣;现在我们给它构建了分层的记忆系统,把记忆明确地分成两层来管理:短期记忆(也叫工作记忆)负责保存当前这一次会话的即时上下文——这一轮之前的对话历史、本次任务执行过程中已经从各个工具拿到的中间结果——确保 agent 在一次多轮任务里始终清楚地知道前因后果、保持连贯;长期记忆则负责那些需要跨越会话长期记住的信息——用户的偏好设定、过往交互中沉淀的事实、历史的重要结论——我们把这些信息向量化之后存进向量数据库,在每次需要时,把当前的情境(比如用户当前的提问)也向量化、拿去向量库里做语义相似度检索、召回与当前最相关的若干条历史记忆,再把它们注入到喂给模型的上下文里,做到既不会失忆、又不会把所有历史无脑地全塞进去撑爆上下文。我们的纪律是"记忆分短期与长期两层管理、短期保会话连贯、长期入向量库靠语义检索按需召回、召回 top_k 受控并按相关度排序、敏感记忆脱敏存储、过期记忆定期清理"。记忆系统的本质认知是:大模型本身是无状态的——它每次推理只看你这一次喂给它的上下文、不会自动记住任何跨调用的信息,所谓"智能体的记忆"完全是我们在模型之外用工程手段构建出来的,而记忆工程的核心矛盾在于"模型的上下文窗口是有限且昂贵的"和"需要记住的信息是海量且持续增长的"之间的冲突——既不能什么都不记(失忆),也不能什么都往上下文里塞(爆窗口、烧 token、且无关信息会干扰模型);分层记忆的智慧是用短期记忆解决"一次任务内的连贯性"、用长期记忆加语义检索解决"跨会话的海量信息按需取用"——把无限增长的长期记忆放在外部的向量库里、只在每次真正需要时通过语义检索精准地召回与当前最相关的那一小部分注入上下文,从而在有限的上下文窗口里实现了一个事实上无限、且高度相关的记忆,这是让智能体从"金鱼记忆"变成"有连续人格和经验积累的助手"的关键能力。

四、任务规划:从埋头乱做到 planning 先分解再执行

第四仗,是让智能体在动手之前先学会"规划"。古早时代我们的 agent 面对一个复杂任务时是没有规划意识的——它不会先把大任务拆解成有序的子任务、想清楚先做什么后做什么、哪些有依赖关系,而是接到任务就一头扎进去、走一步看一步地埋头乱做,结果在复杂任务上经常步骤错乱、漏掉关键环节、或者在死胡同里打转,因为它缺乏对整个任务的全局视野和路径规划。现代做法是引入 planning(规划)环节:在真正执行之前,先让大模型对任务做一次分解——把一个复杂的大目标拆成一系列更小、更明确、有先后依赖关系的子任务,形成一个计划(plan),然后再按这个计划有条不紊地逐个执行子任务,执行过程中如果发现计划不对还可以重新规划(re-planning)。常见的有先规划后执行的 Plan-and-Execute 模式。下面是任务规划的对比:

# 重构前:无规划,接到复杂任务一头扎进去走一步看一步,步骤错乱漏环节
# def do_task(task: str):
#     return react_loop(task)   # 没有全局视野,复杂任务里打转、漏步、卡死

# 重构后:Plan-and-Execute,先让模型把大任务分解成有序子任务,再逐个执行
def plan_and_execute(task: str) -> str:
    # 第一步:规划——把复杂任务分解成有序、明确、带依赖的子任务列表
    plan: list[str] = llm.plan(
        f"把这个任务分解成有序的子任务步骤:{task}"
    )  # 例:["查用户本月订单总额", "判断是否>1万", "若是则调发券接口", "汇总回复"]

    results = []
    for i, subtask in enumerate(plan):                  # 按计划有条不紊逐个执行
        ctx = "\n".join(results)                        # 带上已完成子任务的结果
        r = react_loop(f"{subtask}\n已知:{ctx}")        # 每个子任务用 ReAct 执行
        results.append(f"步骤{i+1}({subtask})结果:{r}")
        if llm.should_replan(plan, results):            # 发现计划不对就重新规划
            plan = llm.replan(task, results)
    return llm.summarize(task, results)                 # 汇总所有子任务结果

任务规划让我们从"没有规划意识、接到复杂任务就一头扎进去走一步看一步地埋头乱做、缺乏全局视野导致步骤错乱漏掉关键环节或在死胡同里打转"进化到了"执行前先做 planning 把大目标分解成有序明确带依赖的子任务形成计划、再按计划有条不紊逐个执行、执行中发现计划不对可重新规划":过去我们的智能体是个十足的"莽夫",面对一个稍微复杂、需要好几个步骤才能完成的任务,它没有任何"先谋而后动"的意识——不会停下来先想想这件事到底该分成哪几步、这几步谁先谁后、哪一步依赖哪一步的结果,而是接到任务就立刻埋头开干、纯粹走一步看一步,这种缺乏全局规划的执行方式在简单任务上还能凑合、一到复杂任务上就原形毕露:它会把步骤的顺序搞乱、会漏掉某个关键但不那么显眼的环节、会因为没想清楚整体路径而在某个死胡同里反复打转,因为它始终只盯着眼前这一步、从未对整个任务有过通盘的考量;现在我们在 agent 真正动手之前加入了一个明确的 planning 环节,先让大模型对接到的任务做一次分解——运用它的推理能力把一个庞大、笼统的目标拆解成一系列粒度更小、描述更明确、并且标清了先后依赖关系的子任务、形成一份清晰的执行计划,然后 agent 再严格地按照这份计划一个子任务接一个子任务地有条不紊执行、每个子任务执行时还能带上前面已完成步骤的结果作为上下文,而且这个规划不是一锤定音的,在执行过程中一旦发现实际情况和原计划有出入、原计划走不通了,agent 可以基于已有的进展重新规划、动态调整后续的步骤。我们的纪律是"复杂任务必须先 planning 分解再执行严禁莽撞直接做、子任务要明确且标注依赖关系、执行中允许并鼓励基于新信息 re-planning、计划本身要可被人审阅(关键计划走人工确认)"。任务规划的本质认知是:大模型的单步推理虽然强,但它的"注意力"在面对一个庞大复杂的任务时容易陷入局部、只见树木不见森林,缺乏对完成整个任务所需路径的通盘把握——这正是它在复杂任务上步骤错乱、丢三落四的根源;planning 的智慧是把"思考整体路径"和"执行具体步骤"这两件认知负荷很不一样的事情显式地分离开来——先用一次专门的规划调用让模型站在全局视角把复杂任务分解成一张清晰的、有序的、可执行的子任务地图,再让模型在执行每个具体子任务时只需聚焦于那一小步,从而既保证了整体路径的合理性、又降低了每一步的复杂度,同时保留了根据执行反馈动态重规划的弹性,这是让智能体能够稳健地驾驭复杂、多步、长程任务的关键能力,也是从"反应式"智能体迈向"深思熟虑式"智能体的分水岭。

五、多智能体编排:从单 agent 光杆司令到 supervisor 分工协作

第五仗,是把一个什么都干的单 agent,拆成多个各有专长、分工协作的智能体团队。古早时代我们就一个 agent 包打天下:它的 prompt 里塞满了各种角色的职责、各种工具的说明、各种任务的处理逻辑,既要当客服又要查数据还要做分析、工具列表长达几十个,结果是这个 agent 又臃肿又分裂、面对每个具体任务时都被一大堆无关的工具和指令干扰、表现样样稀松,而且这个巨型 prompt 改起来牵一发动全身、加个新能力就可能弄坏旧能力。现代做法是采用 multi-agent(多智能体)架构:把不同的职责拆分给多个专门的 agent——比如一个查询 agent 专门负责取数、一个分析 agent 专门负责分析、一个写作 agent 专门负责生成回复,每个 agent 只配它自己那一小撮相关的工具和精炼的指令、各司其职、术业有专攻,再由一个 supervisor(主管 / 协调者)agent 负责理解总任务、把子任务分派给合适的专家 agent、协调它们之间的协作和信息传递。下面是多智能体编排的对比:

# 重构前:单 agent 包打天下,prompt 塞满所有角色/工具/逻辑,臃肿分裂样样稀松
# mega_agent = Agent(
#     prompt="你是客服+数据分析师+文案,你有这40个工具...",  # 又臃肿又分裂
#     tools=all_40_tools,                                    # 每个任务都被无关工具干扰
# )

# 重构后:multi-agent,职责拆给专门 agent,supervisor 分派协调
query_agent   = Agent(role="数据查询专家", tools=[query_order, query_user])   # 只管取数
analyst_agent = Agent(role="数据分析专家", tools=[compute, compare])          # 只管分析
writer_agent  = Agent(role="文案专家",     tools=[])                          # 只管写回复

class Supervisor:                                          # 主管:理解总任务、分派、协调
    def __init__(self, workers: dict):
        self.workers = workers
    def run(self, task: str) -> str:
        plan = llm.plan(task)                              # 规划(见第四仗)
        ctx = []
        for sub in plan:
            who = llm.route(sub, self.workers.keys())      # 路由:这个子任务派给哪个专家
            r = self.workers[who].run(sub, context=ctx)    # 专家 agent 执行
            ctx.append(r)                                  # 结果传递给后续协作
        return self.workers["writer"].run("汇总成回复", context=ctx)

sup = Supervisor({"query": query_agent, "analyst": analyst_agent, "writer": writer_agent})

多智能体编排让我们从"单个 agent 包打天下、prompt 里塞满所有角色职责和几十个工具说明、又臃肿又分裂每个任务都被无关工具和指令干扰样样稀松、巨型 prompt 牵一发动全身加新能力就弄坏旧能力"进化到了"multi-agent 架构把不同职责拆给多个各有专长的专门 agent、每个只配自己相关的少量工具和精炼指令各司其职、再由 supervisor 主管理解总任务分派子任务给合适专家并协调协作":过去我们把所有的事情都压在一个 agent 身上,它的系统提示词里堆砌着客服、数据分析师、文案等好几个完全不同角色的职责描述,挂载着几十个五花八门的工具,既要应对用户的咨询、又要去数据库取数、还要对数据做分析、最后还得把结果写成漂亮的回复,这种"全能选手"的设计在实践中彻底失败了——这个 agent 因为要兼顾太多互不相关的职责而变得又臃肿又精神分裂,它在处理任何一个具体任务时,都要在一大堆与当前任务毫不相干的工具和指令的干扰下做判断,注意力被严重稀释、结果样样都做但样样都做不精,而且那个塞满一切的巨型 prompt 已经复杂到牵一发而动全身、我们想给它加一个新能力或改一处指令、都可能莫名其妙地把它原本好好的某个旧能力给弄坏;现在我们改用多智能体架构,把这一个全能 agent 拆分成了一个各有专长、分工明确的智能体团队——查询 agent 只负责数据查询、只挂载取数相关的少数几个工具、prompt 只讲怎么查数;分析 agent 只负责数据分析、只配分析工具;写作 agent 只负责把结果组织成回复,每个专家 agent 都因为职责单一、工具精简、指令聚焦而在自己的领域内表现得又专又稳,然后我们用一个 supervisor 主管 agent 站在更高层,负责理解用户的总任务、(配合规划)把它分解并把每个子任务精准地路由分派给最合适的那个专家 agent、协调专家之间的执行顺序和信息传递、最后汇总成交付,整个系统像一个分工协作的专家团队而非一个疲于奔命的全才。我们的纪律是"职责复杂的系统拆成多个单一职责的专家 agent 严禁单 agent 包打天下、每个 agent 工具最小化指令聚焦、用 supervisor 做任务分派与协调、agent 间通过明确的接口传递结构化信息、避免 agent 数量过度膨胀按真实职责边界拆分"。多智能体编排的本质认知是:一个 agent 的能力和可靠性与它所承担职责的聚焦程度成正比、与它所面对的无关干扰成反比——把太多不同的职责、太多的工具、太多的指令堆在一个 agent 上,本质上是在不断稀释它的注意力、扩大它的出错面、并让它的 prompt 复杂到不可维护,这和软件工程里"上帝类"反模式是同一个道理;多智能体的智慧是把"单一职责原则"和"分而治之"从代码层面上升到智能体层面——让每个 agent 都小而专、只在自己擅长的窄域里凭借精简聚焦的配置发挥出最佳水平,再用一个负责编排协调的 supervisor 把这些专家的能力组合起来去完成单个 agent 无力胜任的复杂任务,从而用"专家团队的协作"取代"全才的疲于奔命",这是让智能体系统在面对真实世界的复杂职责时既能力强又可维护、可扩展的架构基石。

六、人在回路:从黑盒跑飞到 human-in-the-loop 关键操作审批

第六仗,是给智能体的自主权装上一道人工的闸门。古早时代我们的 agent 一旦启动就是个彻底的黑盒、全自动地一路跑到底,这在它只是查查数据、读读信息时还好,可一旦它被赋予了能"动手改变世界"的工具——比如发优惠券、退款、删数据、发邮件、改配置——全自动就变成了悬在头顶的利剑:模型一旦判断失误、或者被用户的话术带偏,它会毫不犹豫地、不可逆地执行一个危险操作,而我们事先没有任何机会拦住它、事后也只能收拾残局。现代做法是引入 human-in-the-loop(人在回路):识别出那些高风险、不可逆、影响重大的关键操作,在 agent 真正执行它们之前强制暂停、把"我打算执行这个操作、参数是这些"清晰地呈报给人类、等待人工审批,人点了确认才执行、点了拒绝或修改就按人的意思来,把人类的判断作为关键决策点上的最后一道防线。人在回路让我们从"agent 启动就是黑盒全自动一路跑到底、被赋予发券退款删数据等能改变世界的工具后一旦判断失误或被话术带偏就毫不犹豫不可逆地执行危险操作而我们事先拦不住事后只能收拾残局"进化到了"识别高风险不可逆的关键操作、在执行前强制暂停把意图和参数呈报人类等待审批、人确认才执行拒绝或修改就按人意来、把人的判断作为关键决策点的最后防线":过去我们的智能体在设计上追求的是全自动、是越少人工干预越好,于是它一启动就像一辆没有刹车、没有方向盘干预的自动驾驶车一路狂奔到底,这在它只做只读操作时风险尚可控,可当我们为了让它真正有用而给它装上那些能实实在在改变现实世界状态的工具之后——能给用户发钱(优惠券)、能退款、能删除数据、能以公司名义发出邮件、能修改线上配置——这种全自动就从"高效"变成了"高危",因为大模型终究是概率性的、会判断失误、会产生幻觉、会被用户精心构造的话术诱导,而一旦它在某个时刻错误地决定要执行一个这样的高危操作,它会像执行任何普通步骤一样干脆利落地、不可逆地把它做掉,我们这些守在屏幕后的人事先完全没有被告知、没有机会喊停,等发现时损失已经造成、只能疲于补救;现在我们引入了人在回路机制,把 agent 可能执行的操作按风险分级、精准识别出其中那些高风险、不可逆、一旦做错影响重大的关键操作,在 agent 的执行流程走到这些操作的前一刻强制把它暂停下来、把"我现在打算调用这个工具去做这件事、具体参数是这些"完整清晰地呈现给负责的人类、然后停在那里等待人工的审批,只有当人看过并点击确认之后 agent 才会真正执行这一步,如果人觉得不妥点了拒绝、或者修改了参数,agent 就服从人的决定,我们把人类的判断力作为悬在所有高危操作之上的最后一道、也是最可靠的一道防线。我们的纪律是"高风险不可逆操作(涉钱/删数据/对外发送/改配置)一律强制人工审批严禁全自动、审批时完整呈报意图与参数、低风险只读操作可全自动、审批动作本身要可追溯留痕、紧急情况有全局熔断开关"。人在回路的本质认知是:智能体的自主性是一把双刃剑——自主性越高它越有用、但一旦出错造成的破坏也越大越不可控,而大模型基于概率生成、会犯错会被诱导这一根本特性,意味着我们永远无法保证一个全自动的智能体不会在某个时刻做出灾难性的错误决定;human-in-the-loop 的智慧是不去追求"完全消除人工"这个既不现实也不安全的目标、而是精准地在"风险最高、最不可逆"的那几个关键决策点上把人重新请回到决策回路里,让智能体在绝大多数低风险环节保持高效的全自动、同时在少数高危环节接受人类判断这道闸门的把关,从而在"自动化的效率"和"不可逆操作的安全"之间取得务实的平衡,这是任何被赋予了真实世界行动能力的智能体在投入生产时必须配备的安全机制——能力越大,越需要在关键处留一个人。

七、护栏与预算:从死循环烧钱到循环上限与 guardrails 兜底

第七仗,是给智能体套上一圈防止它失控的"护栏"。古早时代我们的 agent 在自主运行时缺乏任何失控防护,最典型的灾难就是死循环:一个工具调用失败了,它判断"那我再试一次"、于是反复重试同一个注定失败的步骤、或者在两三个步骤之间来回打转出不来,而每一轮循环都是一次真金白银的大模型调用、token 像拧开的水龙头一样哗哗地烧,我们却因为缺乏监控而浑然不觉、直到月底账单或某次偶然查看才发现它已经空转了成千上万轮、烧掉了大笔费用;除了死循环,它还可能输出有害内容、调用工具时传入危险参数、试图越权访问。现代做法是建立多层护栏(guardrails):用最大循环步数和最大 token / 费用预算给每次任务设硬性上限、一旦触顶立即强制终止,用输入输出的内容护栏过滤有害或越界的内容,用工具调用的参数校验和权限控制防止危险或越权操作,给每个工具调用设超时。护栏与预算让我们从"自主运行缺乏任何失控防护、工具失败就反复重试同一步或在几步间来回打转陷入死循环、每轮都是一次大模型调用 token 哗哗烧而我们因无监控浑然不觉直到账单出来才发现空转了成千上万轮烧掉大笔钱、还可能输出有害内容或传危险参数越权"进化到了"多层 guardrails:用最大循环步数和 token/费用预算设硬上限触顶即强制终止、用输入输出内容护栏过滤有害越界、用参数校验和权限控制防危险越权操作、给工具调用设超时":过去我们的智能体在放手让它自主运行时几乎是在裸奔、没有任何防止它失控的安全机制,其中最经典也最烧钱的翻车就是陷入死循环——它在执行过程中遇到一个失败的工具调用,基于"再试试也许就成了"的朴素判断决定重试,可如果那个调用是因为某种确定性的原因(参数错了、接口下线了)注定失败的,它就会一遍又一遍地重试这个永远不会成功的步骤,或者在 A 步骤的结果让它想做 B、B 的结果又让它想回头做 A 这样的两三个步骤之间无限地来回横跳,而这里最致命的是:智能体的每一轮循环背后都是一次实实在在的、要花钱的大模型 API 调用,死循环意味着 token 和费用以失控的速度持续燃烧,偏偏我们当时又没有对它的运行做任何监控和限额,于是它可能已经在后台空转了成千上万轮、悄无声息地烧掉了一大笔钱,而我们要等到月底收到天价账单、或者某次碰巧打开后台才骇然发现;除了烧钱的死循环,裸奔的 agent 还可能生成有害的、不当的输出内容,可能在调用工具时传入具有破坏性的参数,可能试图去访问它本不该有权限碰的资源;现在我们给智能体套上了一圈多层次的护栏:首先是最硬的资源护栏——给每一次任务的执行设定一个最大循环步数的上限和一个最大 token 消耗或费用的预算,agent 的循环一旦撞到这两条天花板就被立即强制终止、绝不允许无限地跑下去无限地烧,把死循环烧钱的风险从根上锁死;其次是内容护栏——在数据流入和流出 agent 的两端都架设内容过滤,拦截有害的、越界的、违规的内容;再次是操作护栏——在每次工具调用前对参数做严格校验、对 agent 能访问的资源做权限控制、给每个工具调用设置超时,防止危险操作、越权访问和单个工具卡死拖垮整个流程。我们的纪律是"每次任务必设最大步数和 token/费用预算硬上限触顶即停、工具调用必设超时和参数校验、输入输出过内容护栏、agent 权限按最小必要授予、所有护栏触发都告警留痕"。护栏与预算的本质认知是:智能体的自主性意味着它的行为空间是开放的、它会基于自己的判断决定下一步做什么、做多少步、花多少资源,而一个基于概率、会犯错、缺乏常识边界感的系统在一个开放的行为空间里自主运行,天然就存在失控的风险——它不会像人一样意识到"我已经重试很多次了该停了""这样下去太烧钱了"这种常识性的边界;guardrails 的智慧是不指望智能体自己具备完美的自我约束、而是从外部用一圈确定性的、不依赖模型判断的硬性规则把它的行为空间围起来——用步数和预算的硬上限给它的"持续时间和成本"封顶、用内容和参数的过滤校验给它的"行为内容"划界、用权限和超时给它的"影响范围"设限,从而让一个本质上不可完全预测的自主系统,被约束在一个可预测、可承受、安全的边界之内运行,这是让智能体从"实验室里的玩具"变成"敢放到生产环境、敢交给它真实资源和权限"的可靠系统的必备安全底座——自主而无护栏,等于放任失控。

八、可观测:从黑盒查不到到全链路 tracing 每步可查

第八仗,是把智能体从一个不透明的黑盒变成一个一举一动都被忠实记录、可回放、可追查的玻璃盒子。古早时代我们的 agent 整个执行过程是完全不可观测的:它在内部想了什么(推理过程)、决定调用哪些工具、传了什么参数、每个工具返回了什么、在哪一步开始跑偏、最终为什么给出那个错误的结果——这一切我们统统看不到,出了线上问题想复盘,面对的就是一个"输入和错误的输出"、中间整个决策过程是一团漆黑的黑盒,只能靠猜、靠反复手动复现去碰运气,排查效率极低。现代做法是建立全链路的 tracing(追踪)可观测体系:把 agent 每一次任务执行的完整轨迹都结构化地记录下来——每一步的推理内容、调用了哪个工具、传入参数和返回结果、每一步的耗时、消耗的 token 和费用、走到了哪个分支、最终如何收敛,形成一条可以完整回放的 trace,配合专门的可观测平台(如 LangSmith、OpenTelemetry 的 GenAI 语义约定等)做可视化、聚合和告警。可观测让我们从"整个执行过程完全不可观测、内部推理了什么决定调哪些工具传什么参数每个工具返回什么在哪步跑偏为何给出错误结果统统看不到、出事复盘只面对输入和错误输出中间一团漆黑只能靠猜靠手动复现碰运气排查效率极低"进化到了"全链路 tracing:把每次执行的完整轨迹结构化记录(每步推理/调用的工具/参数/返回/耗时/token/费用/分支/收敛)形成可完整回放的 trace、配合可观测平台做可视化聚合和告警":过去我们的智能体在可观测性上几乎是一片空白,它的整个执行过程对我们来说是一个彻底的黑盒——我们只能看到喂进去的任务和最后吐出来的结果,而中间它经历的那一长串至关重要的决策过程:它每一步在脑子里是怎么推理的、基于什么判断决定去调用哪一个工具、给那个工具传了什么参数、工具又返回了什么、它从哪一步开始判断出现了偏差、这个偏差又如何一步步导致了最终那个错误的输出——这一切的中间状态我们完全无从知晓,于是每当线上出现一个 agent 行为异常的问题、我们想要复盘根因时,就只能盯着一个"正常的输入"和一个"错误的输出"、对中间那团漆黑的决策黑箱进行徒劳的猜测,或者一遍遍地手动去复现、祈祷能碰巧重现并观察到问题,排查的效率低到令人绝望、很多偶发问题甚至根本查不出来;现在我们建立了覆盖智能体全链路的 tracing 可观测体系,把 agent 每一次任务执行从开始到结束的完整轨迹都结构化地、巨细无遗地记录下来——每一步的推理思考内容、这一步调用了哪个工具、传入的具体参数是什么、工具返回的具体结果是什么、这一步花了多长时间、消耗了多少 token 和多少钱、在有分支判断的地方走了哪个分支、整个循环最终是如何收敛到结果的——所有这些都被串成一条可以事后完整回放、逐步检视的 trace 链路,再配合专门的 LLM 可观测平台对这些 trace 做可视化展示、跨大量请求做聚合统计、对异常情况做实时告警,智能体的内部世界从此对我们完全透明。我们的纪律是"每次 agent 执行必产出完整结构化 trace、记录每步推理/工具/参数/返回/耗时/token/费用、trace 接入统一可观测平台可视化与告警、异常 trace 可一键回放复盘、关键指标(成功率/平均步数/token 成本/延迟)持续监控"。可观测的本质认知是:智能体相比传统软件有一个根本的不同——传统软件的执行逻辑是确定的、写在代码里一目了然,而智能体的执行路径是由大模型在运行时动态决策出来的、每一次都可能不同、且决策依据藏在模型那次推理的"黑箱"里,这意味着如果不主动地、显式地把每一步的决策过程记录下来,这些转瞬即逝的、不可复现的决策轨迹就永远地丢失了、事后根本无从追查;tracing 的智慧是承认智能体的不可完全预测性、并用工程手段对抗这种不可预测带来的不可调试性——通过把每一次执行的完整决策轨迹忠实地、结构化地持久记录下来,把一个运行时动态生成、稍纵即逝的黑盒过程,转化成一份可以事后反复检视、精确定位问题发生在哪一步、为什么发生的白盒档案,从而让智能体系统从"出了事只能靠猜"变成"出了事能精确复盘",这是智能体能够被持续地调试、优化、信任并长期运维下去的根本前提——看不见,就管不了。

九、7 个 P0 事故复盘

7 事故:(1) 一个工具因接口下线持续失败、agent 反复重试陷入死循环一夜烧掉大笔 token,全面给每次任务加最大步数和费用预算硬上限触顶即停;(2) agent 被用户话术诱导自动执行了一笔不该退的退款,把退款/发券等涉钱操作全部纳入 human-in-the-loop 强制人工审批;(3) 正则解析模型自由文本抠工具参数、模型换措辞后解析出错参数传错导致误操作,全量改用原生 function calling 结构化调用;(4) 长期记忆无脑全量召回把上下文撑爆 token 超限任务直接失败,改为语义检索 top_k 受控召回加上下文压缩;(5) 单 agent 工具过多、面对简单任务也被几十个无关工具干扰选错工具,按职责拆成多 agent 各配最小工具集;(6) 一次线上异常因无 tracing 完全查不出根因耗时数天,补全链路 trace 实现一键回放复盘;(7) 无内容护栏 agent 输出了一段不当内容,补输入输出双向内容护栏过滤。每个 P0 都做 5-Why 复盘,固化成预算护栏基线、审批清单或可观测规范,确保同类问题不再复发。

十、AI Agent 工程师的 6 条工程哲学

6 哲学:(1) 智能体的可靠性来自工程而非模型——再强的模型也需要 ReAct 循环、护栏、记忆、观测这套工程骨架才能稳定可用;(2) 自主性必须配护栏——能力越大越要有步数预算上限、关键操作审批、权限边界,自主而无护栏等于放任失控;(3) 工具调用要结构化不要解析自由文本——function calling 把不确定的文本变成确定的指令,正则抠参数注定脆弱;(4) 类型/格式边界即可靠边界——结构化输出加 schema 校验、参数校验,让 agent 与外部的每次交互都可验证;(5) 看不见就管不了——没有全链路 tracing 的智能体是不可调试不可信任的黑盒;(6) 拆分胜过全能——单一职责的多 agent 协作远胜一个塞满一切的全能 agent。这 6 条哲学,是我们用 7 个 P0 事故和 87 天攻坚换来的集体共识。它们共同指向一个认知:AI Agent 的价值不在于"接入了多强的大模型"这个动作本身,而在于把"智能体的可靠、可控、可观测、可信任"从依赖模型恰好不出错和运气,前移成了由 ReAct、护栏、人在回路、结构化工具、分层记忆、全链路观测这套工程体系结构性保障——会做 Agent 工程的团队,是在用工程的确定性去驯服模型的不确定性,而不是把一切赌在模型身上听天由命。

十一、重构收益的量化:7 个关键数字

7 数字:(1) 多步任务完成率:单轮问答面对多步任务基本抓瞎 → ReAct 循环后复杂多步任务自主完成率大幅提升;(2) 工具调用稳定性:正则解析三天两头崩 → function calling 后调用成功率接近满分;(3) 失控烧钱事故:死循环空转烧掉大笔 token → 护栏加预算上限后失控烧钱归零;(4) 高危误操作:全自动误退款误发券 → 人在回路审批后涉钱误操作归零;(5) 上下文相关性:历史无脑全塞既爆 token 又掺噪声 → 分层记忆按需召回后上下文精准且不超限;(6) 故障排查时长:黑盒靠猜耗时数天 → 全链路 tracing 后一键回放分钟级定位;(7) 单任务能力:单 agent 样样稀松 → 多 agent 分工后各专家任务质量显著提升。这些数字背后,是 87 天里 13 个人一个能力一个能力地补、一个失控点一个失控点地堵、一条链路一条链路地接上观测,但每一个都实打实地转化成了可靠性、可控性、成本和可观测性的提升。当我们把这份数据汇报给管理层时,最有说服力的不是任何 Agent 名词,而是"复杂任务真能自动办成了、再没有失控烧钱和高危误操作的深夜惊魂、出了问题分钟级就能查到根因"这三条。

十二、留给后来者的最后一句话

87 天的 AI Agent 现代化战役,我们走过的不只是一条从单轮问答到 ReAct 循环、从正则硬解析到 function calling、从无记忆到分层记忆、从埋头乱做到任务规划、从单 agent 到多智能体编排、从黑盒跑飞到人在回路、从失控烧钱到护栏兜底、从不可观测到全链路 tracing 的技术升级路,更是一次从"靠模型恰好不出错、靠运气不失控"到"靠工程体系结构性兜底、靠确定性机制驯服模型不确定性"的范式跃迁。当一个需要好几步才能办成的复杂任务被 agent 在 ReAct 循环里自主地查、判断、行动、汇总一气呵成地办妥、当每一次工具调用都通过 function calling 稳稳落地再不被脆弱的正则拖垮、当 agent 记得住用户的偏好和这次任务的来龙去脉、当一个高危的退款操作在执行前稳稳地停下来等我们点头、当死循环被预算护栏在烧掉第一块钱之前就掐断、当一次线上异常我们打开 trace 几分钟就精确定位到是哪一步哪个工具出了岔子的那一刻,真正点燃我们的,不是接入了多强的模型本身,而是"智能体的可靠、可控和可信任,终于从依赖模型不出错和运气,变成了由工程体系强制保障"的踏实与笃定。AI Agent 工程没有银弹,关键是理解 ReAct、function calling、记忆、规划、多智能体、人在回路、护栏、可观测各自解决什么问题、又各自带来什么代价,然后从把单轮改成 ReAct 循环和给工具调用上 function calling 的地基起步、用护栏和 tracing 兜底地落地——尤其要克制"图省事单轮糊一个、图省事正则抠一下参数、图省事不设步数上限、图省事全自动不要审批、图省事不接 tracing"的旧习惯,因为每一个没设的预算上限、每一处正则解析、每一个该审批却全自动的高危操作、每一段没有 trace 的执行,都是在亲手埋下未来某次失控烧钱、误操作或查不出根因的事故。愿每一位还在和死循环、工具调用崩溃、智能体失控和黑盒难查搏斗的同行,都能早日让自己的 Agent 被这套工程体系稳稳地守护。共勉,后会有期。

—— 别看了 · 2026