上个月我把一套跑了大半年的自动化脚本彻底推倒重写了。那个脚本用大模型做信息抽取提示词写了快一千字规则堆了十几层可一到边缘情况就翻车改一处坏一处。重写的时候我换了个思路不再让模型按我写死的步骤执行而是给它一个明确目标让它自己规划动作、调用工具、检查结果、发现问题再回头修正。这个思路就是最近被反复提到的 Agentic Workflow——以 Agent 为核心的工作流构建方式。这次在 AI Genius 第五季第二期里聊的主题正好也是这个结合我自己踩坑下来的经验我把 Agentic Workflow 的构建之道从头捋一遍它到底解决了什么问题、核心组件怎么拆、从零怎么搭、有哪些必踩的坑、以及怎么从 Demo 走到线上。这篇稿子的受众很明确——正在做 AI 应用开发或者手里已经有一个 RAG 或单轮 Prompt 应用、想把它升级成真正“能动起来”的 Agent 系统的开发者。如果你只是听说过 Agent 这个词但还没动手试过这篇也能帮你建立一张完整的地图。1. 先搞清楚 Agentic Workflow 到底是什么1.1 传统 Prompt 工程的三道坎先说一个我自己的例子。之前做一个竞品调研工具传统做法是准备一个超长 Prompt把行业背景、调研对象、输出格式全部塞进去要求模型“先搜索、再总结、再对比”最后还要用正则去解析输出。前期跑起来还挺像回事但用着用着就暴露了三个问题。第一提示词越来越长可模型的理解能力跟不上。超长上下文里塞满规则模型会选择性“失忆”经常漏掉中间某个不起眼的约束条件。第二流程一旦写死模型就失去了自主判断能力。比如搜索某个关键词返回为空按脚本逻辑应该换个关键词再试但模型不会它只会拿着空结果硬写报告。第三工具一多编排逻辑就缠在一起。今天加一个数据源明天加一个校验接口Prompt 就得重构一次成本极高。这些问题的根源其实很统一我们把“怎么做事”的思考过程硬编码成了提示词里的固定步骤。而真实任务往往是动态的、有分支的、需要根据中间结果调整策略的。1.2 核心转变从“步骤驱动”到“目标驱动”Agentic Workflow 的做法刚好反过来。不再告诉模型“第一步做什么、第二步做什么”而是告诉它“你要达成什么目标、你有哪些工具可以用、遇到什么情况应该停下来问我”。整个过程变成了一种循环模型接收目标自己拆解出计划执行一个动作比如调用搜索工具观察返回结果再决定下一步。本质上是从“人与模型对话”变成了“模型与工具对话”。我经常用实习生来打比方。传统方式是你给实习生一份 SOP让他照着一步步做中间任何一步出问题都得回来问你。Agent 方式是你给实习生一个明确目标、一套工具、一个反馈机制让他自己想办法搞定关键节点向你汇报。后者前期培养成本更高但遇到意外情况时它的应变能力强了一大截。这个转变对于做 AI 应用的人来说意味着什么意味着你的注意力要从“怎么写提示词”转移到“怎么定义目标、怎么设计工具、怎么建立反馈回路”上。提示词仍然重要但它只是整个系统里的一小块拼图。1.3 不是所有任务都适合上 Agent有一点必须先说清楚Agentic Workflow 不是银弹不是把任务交给 Agent 就万事大吉。我的判断标准很简单——这个任务有没有“决策-执行-验证”的闭环空间。适合的场景有几个共性多步骤操作、跨系统调用、输入不确定性强、状态会随着执行而变化。比如自动化测试一个用例失败后能自己查日志、改参数、重跑、研究报告生成搜索、筛选、综合、对比、代码库理解读代码、查引用、做修改建议、客服工单处理查订单、看售后记录、给方案、运维诊断看指标、查日志、定位根因。不适合的任务也有共性确定性高、延迟敏感、结果必须可预期。比如固定格式的文本解析、缓存查询、鉴权校验、定时通知。这类任务用传统代码几毫秒就搞定引入 Agent 推理反而会变慢变贵属于杀鸡用牛刀。2. 拆开 Agent 看四个核心组件2.1 模型层大脑决定上限模型是整个 Agent 系统的推理核心。选型时我一直遵循一个原则先想清楚任务需要多强的推理能力再去匹配模型尺寸而不是无脑上大参数。纯粹的文本摘要、关键词提取这类任务中等尺寸的模型完全够用。涉及多步推理、工具调用、代码生成的场景就必须上推理能力强的大模型否则 Agent 会在规划阶段就开始犯糊涂。还有一个经常被忽略的点模型对函数调用的遵守程度差异非常大。同样一份工具定义有的模型能稳定输出结构化调用参数有的模型频频生成格式错误。这块建议在选型阶段就做一个工具调用评估测试而不是只看跑分。本地部署是另一个绕不开的话题尤其数据敏感或延迟要求高的场景。本地部署的核心痛点是资源配置一个 7B 模型量化为 4-bit 后显存占用约 5~6GB推理速度大概能跑到每秒几十个 token适合中小规模并发70B 级别模型哪怕量化后也至少需要 40GB 显存通常得两张卡做张量并行工程复杂度上了一个台阶。我的建议是如果团队没有专职的推理优化工程师优先考虑 API 服务等规模起来再评估自部署的性价比。2.2 记忆层短期和长期要分开管Agent 的“记忆”直接决定了它能不能在多轮交互中保持连贯。很多新手做 Agent 只顾把上下文全部塞给模型结果上下文爆炸模型反而忘了开头在干什么。我的做法是把记忆分成两层。短期记忆就是当前任务窗口里的交互记录包括用户目标、每次工具调用和返回结果。这一层要做减法不是所有历史都要保留可以按时间衰减或按相关性裁剪只保留与当前目标直接相关的信息。长期记忆才是真正拉开体验差距的地方它让 Agent 在下次遇到类似问题时能回忆起之前的偏好和结论。长期记忆的落地一般有三种方案向量检索把过去的结论切块存进向量库按语义相似度召回、摘要记忆每次任务结束生成一条结构化摘要、时间回放按时间线直接回看历史记录。三者的对比我整理了一张表方案适合场景优势代价向量检索知识库问答、历史方案推荐召回内容精细扩展性好需要维护向量库切片策略有成本摘要记忆用户偏好、项目长期状态信息密度高token 消耗小会丢失细节摘要可能失真时间回放调试、审计、任务复盘完全保真可追溯长度不可控占用空间大在我的实践里这几种不是互斥的经常是组合使用短期用摘要记忆控制上下文长度长期用向量检索加时间回放做兜底。2.3 工具层给 Agent 一双能干活的手工具设计的核心原则就一句话不要让 Agent 去猜工具怎么用。每次函数调用都是模型基于函数名、参数描述、返回格式做判断工具说明写得越清楚Agent 的出错率就越低。我常用的工具定义规范有三条。第一函数名用动词开头比如search_keyword、fetch_page_content、send_report让模型一看就知道这个工具是干什么的。第二参数描述要写清楚取值范围和单位比如“limit 为返回结果最大条数范围 1~50”避免模型传一个异常值。第三返回结果要尽量结构化纯文本返回会让模型二次解析增加出错概率。工具粒度也很有意思。工具太粗模型在小步骤上做不了自主决策工具太细上下文被频繁占用模型也记不住这么多工具。我踩过最深的坑就是一开始把“抓取网页正文”拆成了“发起 HTTP 请求”“解析 HTML”“清洗文本”三个工具结果模型频繁在三个工具之间来回调用不仅步骤变多错误概率也显著上升。后来合并成一个“抓取正文”工具效果立刻好了。2.4 编排层让 Agent 知道怎么琢磨编排层是 Agentic Workflow 里最容易“卷”的部分市面上有各种模式但万变不离其宗核心就几种。ReAct 是目前最流行也最稳定的模式思路是交替进行 Reason 和 Act模型先思考下一步该做什么然后调用工具拿到结果再继续思考。这种方式适合任务步骤都能在运行中动态确定的场景。Plan-and-Execute 则让模型先输出完整计划再逐步执行适合任务复杂、但可以提前拆解的流程比如“做一个季度竞品分析报告”先规划出数据收集、分析框架、报告生成几个阶段。Self-Refine 是让模型对自己的输出做自评自改适合写作、代码调试这类对质量要求高的任务。Multi-Agent 是在任务足够大时让多个 Agent 分角色协作比如有的管研究、有的管写作、有的管审查协同复杂度会成倍上升一般小团队不建议一上来就尝试。模式选择没有绝对正确我的建议是从 ReAct 起步把单个 Agent 的稳定性打磨到足够好再根据任务复杂度引入 Plan-and-Execute 或 Multi-Agent。3. 从零开始搭一套 Agentic Workflow3.1 动笔写代码前先写清楚任务备忘录我见过太多 Agent 项目翻车不是模型不够聪明而是任务定义太模糊。写代码之前我强烈建议先列一份任务备忘录白纸黑字写清楚五件事目标是什么可量化的结果、输入是什么原始数据格式、输出是什么交付物形态、约束是什么预算、耗时、合规边界、验收标准是什么什么样的结果算成功。举个例子我要做一个“日报自动生成 Agent”如果用“帮我生成今日工作日报”这种表述Agent 根本无从下手。改成“根据今日提交到仓库的 commit 记录、操作后台的工单记录和日历日程生成一份按项目归类的日报每个项目下标注进展、风险和明日计划”Agent 就知道该调哪些工具、输出什么结构了。这一步很多人觉得是浪费时间但在实际运行中任务定义的质量直接决定了 Agent 规划的稳定程度。任务定义越清晰Agent 在规划阶段越不容易跑偏。3.2 技术选型别一开始就陷进框架选择困难Agent 框架这两年冒出来特别多Python 生态有 LangGraph、AutoGen、CrewAIJava 生态有 Spring AI最近 Spring AI Alibaba 也把国内的工具生态补齐了不少。我的选型原则很简单看团队熟悉什么语言、项目要跑多久、调试需求强不强。如果团队的主力栈是 PythonLangGraph 的图编排能力很强而且它的可视化调试工具能直观看到 Agent 每一步在做什么这点对排查问题极其有用。AutoGen 的多 Agent 对话机制设计得比较完善适合做协作型任务。CrewAI 的上手曲线最平缓适合快速验证想法。Java 团队如果想把 Agent 嵌进现有的 Spring Boot 服务Spring AI 的抽象层做得比较干净跟 Spring 生态的集成几乎无痛。还有一个容易被忽略的选型因素开发环境。别小看 IDE 插件的价值我用 VS Code 配 AI 插件比如 Codex写 Agent 代码时效率提升是肉眼可见的尤其在补全工具定义和调优提示词模板这类重复性工作上。PyCharm 的 AI 插件对 Python 项目的函数签名补全和错误提示也很友好。工具链顺手了才能把精力集中在 Agent 本身的逻辑上。3.3 一个最小可运行的 Agent 骨架不管用哪个框架Agent 的核心循环都很像。下面是一段简化版的 ReAct 模式代码展示了最基本的“思考-行动-观察”循环结构import json from typing import Callable, Any # 1. 定义工具 def search_keyword(keyword: str, limit: int 5) - list[dict]: 按关键词搜索返回匹配结果列表 # 实际场景这里会调用搜索 API / 数据库 return [{title: f{keyword} 相关结果{i}, url: fhttps://example.com/{i}} for i in range(limit)] def fetch_page(url: str) - str: 抓取指定 URL 的正文内容 # 实际场景这里会做页面抓取和正文提取 return f这是 {url} 的正文内容…… def summarize(text: str) - str: 对文本做摘要 # 实际场景这里会调用模型做摘要 return f摘要{text[:30]}…… class MinimalAgent: def __init__(self, model, tools: list[Callable]): self.model model # 用函数名作为工具名方便 Agent 按名字调用 self.tools {tool.__name__: tool for tool in tools} self.system_prompt ( 你是任务规划助手。请根据用户目标逐步调用可用工具完成任务。 每次需要调用工具时严格输出 JSON格式为 {action: 工具名, action_args: {参数对象}}。 如果任务已经完成直接输出最终答案。 ) def parse_action(self, response: str) - dict | None: 从模型输出中解析工具调用解析失败返回 None 表示直接回答 try: return json.loads(response) except json.JSONDecodeError: return None def run(self, task: str, max_steps: int 10) - str: messages [ {role: system, content: self.system_prompt}, {role: user, content: task}, ] for _ in range(max_steps): response self.model.chat(messages) action self.parse_action(response) if action is None: return response # 模型认为任务已完成 if action[action] not in self.tools: return f错误工具 {action[action]} 不存在 # 记录工具执行前后的上下文这是调试 Agent 最关键的痕迹 tool self.tools[action[action]] result tool(**action[action_args]) messages.append({role: assistant, content: response}) messages.append({role: tool, content: f工具返回{str(result)[:500]}}) raise TimeoutError(超过最大执行步数终止任务)这段代码是典型的教学骨架生产环境绝对不能直接用但它的意义在于把 Agent 的核心逻辑浓缩得很清晰模型输出结构化指令、代码解析指令、调用对应工具、把结果塞回对话上下文、循环直到完成。我给团队做内部培训时都是先用这个 50 行的版本让大家理解原理再切换到成熟框架写业务代码。3.4 上下文管理与工具注册的实操细节搭完骨架之后真正决定 Agent 能不能稳定跑起来的是几个容易被忽略的细节。上下文长度的管理是第一要务。每次工具调用的结果都会塞回 messages 列表如果工具返回的是几万字的长文本几轮下来上下文就爆了。我的做法是对工具返回做截断列表类结果只保留前 5 到 10 条长文本先自动摘要再进上下文。摘要本身可以用一个小模型完成成本很低。工具注册时要注意命名空间隔离尤其是多 Agent 场景。我曾经在一个项目里两个 Agent 各有一个叫search的工具行为却完全不同结果 Agent 之间互相调用了对方的工具问题排查了整整一个下午。后来所有工具注册都强制加前缀比如research_search和ticket_search再也没出现过这种混乱。最大步数限制一定不能省。我见过不少真实案例Agent 遇到无法解决的死结时会在原地反复尝试直到把预算烧穿。50 行骨架里的max_steps参数生产系统里通常设成 15 到 25 步并且配合“重复操作检测”如果模型连续 3 次调用同一个工具且参数不变直接让它换一条思路。4. 构建 Agent 时必踩的六个坑4.1 Agent 陷入死循环症状很典型模型在几个工具之间反复调用来回折腾输出内容几乎没有变化。原因是模型在某个决策点上失去了判断力不知道该走哪条分支。我的应对方案是三重防线。第一设最大步数这是底线宁可任务失败也不能烧钱。第二做重复操作检测连续相同动作触发提醒。第三在系统提示词里明确告诉模型“如果发现自己在重复请停止并换一个更优化的方法”或者“直接向用户询问澄清”。最后这一句话看着简单实际效果相当好等于给模型的推理加了一个出口。4.2 工具返回值污染上下文工具返回结果并不能保证干净。搜索接口偶尔会返回乱码、营销噪音、甚至与问题无关的内容。这些脏数据一旦进入上下文模型很容易被带偏输出一些与目标无关的内容。我在工具输出前加了一层清洗逻辑列表结果过滤明显无意义的内容长文本先做主题抽取保留与任务关键词匹配的段落。更稳妥的方案是“双通道”——原始数据存到数据库上下文里只放加工后的摘要需要溯源时再查原始记录。4.3 工具调用参数格式不稳模型生成的 JSON 参数经常出幺蛾子多了一个逗号、字段名大小写不一致、数组类型传成了字符串。这类错误在小模型上尤其明显。解决思路有三个层次。第一工具定义里使用严格的 JSON Schema并给每一个参数写清楚类型和示例值。第二在系统提示词里附加 2 到 3 个 few-shot 示例示范正确的调用格式。第三编码层面做容错解析比如先用json.loads解解不出来就用正则抽取字段。三层叠加能把格式错误率从两位数降到个位数。4.4 没有评估集改了一版反而变笨了这是最隐蔽也最坑的问题。Agent 系统不是传统的一次性输入输出改了提示词之后可能旧问题修好了新问题冒出来了或者之前已经跑通的用例开始失败。如果不做回归评估根本发现不了。我的习惯是维护一个小型评估集包含三类样本50 条历史真实 case、20 条边界 case比如空输入、超长输入、模糊指令、10 条异常输入比如用户故意给出无法完成的请求。每次改动提示词或者工具定义就跑一遍全部样本对比结果是否有劣化。这个评估集就是 Agent 的“护城河”也是你改代码时的“逃生舱”。4.5 权限过大Agent 被“借刀杀人”给 Agent 的工具权限必须用最小权限原则。别让一个做文本处理的 Agent 拥有删除数据库的权限也别让它能以管理员身份调用内部接口。有一次我的 Agent 调用内部搜索接口时被搜索注入了一段指令结果模型直接偏离原任务开始执行注入内容里的要求。这类问题的防护思路是分层外部输入和工具返回一律视为不可信数据不能直接拼进系统提示词Agent 需要执行敏感操作时强制走人工审批环节调用外部系统时用白名单限制可访问的域名和接口范围。安全不是可有可无的装饰而是 Agent 上线的必答题。4.6 日志缺失问题定位全靠猜Agent 是状态系统每一步动作的执行顺序会因为模型的不确定性而千差万别。没有日志就去排查问题等同于闭着眼睛找针。我的要求是每次生产运行必留三类痕迹模型的完整思考链包括被截断的中间内容、每次工具调用的入参和出参、每一步的时间戳和 token 消耗。把这些信息落到结构化日志里排查问题时按任务 ID 一查就出来了。这一步从项目第一天开始做后面省下的时间绝对值得。5. 从 Demo 到生产我的实战建议5.1 可观测性先让 Agent“透明”再谈智能Agent 的“透明”比“聪明”重要。一个不可解释的 Agent 哪怕准确率再高也无法赢得信任更没法在出了问题之后快速修复。我给 Agent 系统配的观测层包含四个维度的记录观测维度记录内容触发时机思考链模型每次输出的推理文本、决策理由每轮循环工具调用工具名、参数、返回码、耗时、结果摘要每次调用前后运行指标每轮 token 消耗、延迟、步数每次任务结束外部追踪任务 ID、用户 ID、会话 ID 与业务关联任务初始化时这些记录的价值在调试阶段就体现出来了你可以把 Agent 的每一步拿出来逐条对照它当时的输入判断究竟是模型理解错了、工具返回错了还是编排逻辑有问题。没有这个基础后续的优化都是盲人摸象。5.2 评估集建设从第一天就开始攒评估集不是上线前临时做的工作而是伴随项目成长持续维护的基础设施。我的建议是从第一天就开始攒真实用户的输入和期望输出哪怕前两周只有 20 条也没关系关键是形成“每次改动必跑回归”的习惯。攒评估集还有一个技巧把 Agent 跑错过的 case 全部留档并标注错误类型。比如“因为工具返回噪声多导致误判”“因为上下文截断丢失关键信息”“因为参数格式错误”这样每次跑完测试你能直观看到自己的改动在解决哪些类型的错误、有没有引入新的错误。时间越长这个评估集越值钱。5.3 成本控制别让智能把你的预算烧穿Agent 模式的成本天然比传统 API 调用高因为一次任务可能要触发几十次模型调用。成本控制不能靠事后看账单要在架构层面提前设计。我的做法有四个。第一结果缓存对相同或高度相似的任务请求直接返回上次的结果适合信息查询类任务。第二模型分层用轻量模型做意图识别、路由和粗筛只有复杂推理才调用大模型。比如先让一个小模型判断“这个问题需要多步搜索吗”如果不需要直接用大模型单轮回答能省不少钱。第三摘要前置超长文档先做递归摘要再喂给模型避免上下文膨胀导致费用飙升。第四任务级预算上限每个任务设定最大 token 消耗超过自动降级为“让用户确认”。成本这件事提前控制的效果远好于事后优化。我见过太多团队Demo 阶段跑得欢上生产第一周账单出来就傻眼最后不得不推翻重做架构。从第一天就把成本意识刻进设计里后面会轻松很多。最后说一点我个人的体会。Agentic Workflow 不是银弹它本质上把工程问题从“写好提示词”变成了“搭好系统”——定义好目标、设计好工具、建立好反馈回路、完善好观测手段。它比传统 Prompt 工程复杂但这种复杂换来了更强的应变能力。我现在做 AI 应用第一件事不是写提示词而是先想清楚这个系统的反馈回路在哪里模型在什么情况下该继续、什么情况下该停止、什么情况下该向用户求助。把这些问题想透了比堆更长的提示词和更炫的编排模式要重要得多。希望这篇能从最底层的逻辑到可落地的实践给你一条能直接上手走的路。