1. 为什么“给 AI Agent 配工作流”是个真问题1.1 从“会聊天”到“能干活”的鸿沟过去一年我身边不少做开发的朋友都在折腾 AI Agent。大家最初的兴奋点都差不多模型能理解自然语言能调用工具能写代码感觉离“全自动干活”只差一步。但真正把 Agent 放进一个实际项目里跑上几天几乎所有人都会撞上同一堵墙——它不稳定不可控不可复现。举个我亲身踩过的例子。我让一个 Agent 帮我处理一批日志文件读取目录、过滤错误行、按模块归类、生成一份汇总报告。第一次跑它干得挺漂亮第二次跑它换了一种过滤逻辑第三次跑它干脆把某个目录跳过了理由是“看起来不重要”。你问它为什么它给你一段听起来很有道理的解释但那段解释和它实际做的事对不上。这就是问题的核心大模型擅长的是“生成”而工程需要的是“确定性”。生成意味着每次都可能不一样而工程流程要求同样的输入必须得到同样的输出至少要在可接受的范围内稳定。Agent 本身没有“工程纪律”它有的是概率和联想。所以想让 Agent 真正参与生产就必须在它外面套一层东西——这层东西就是工作流。1.2 工作流到底给 Agent 补了什么我习惯把 Agent 比作一个能力很强但没上过班的实习生。他聪明、学得快、什么都能聊但你不敢把关键任务直接交给他因为他不知道公司的规矩文件放哪、命名怎么起、什么情况要请示、什么情况必须停下来。工作流就是那本《员工手册》加上一套打卡和审批系统。具体来说一套工程工作流给 Agent 补的是四样东西边界明确哪些事能做、哪些不能做、做到什么程度算完成。没有边界的 Agent 会无限发散你让它写个函数它顺手把整个模块重构了。顺序先做什么、后做什么、什么必须等什么。工程任务大多有依赖关系Agent 天然倾向于“想到哪做到哪”。校验每一步的产出怎么检查、不合格怎么办。Agent 自己不会怀疑自己它生成什么就信什么。记录做了什么、为什么这么做、中间状态是什么。出了问题要能回溯不然排查就是玄学。这四样东西单靠提示词是补不齐的。提示词能约束一次对话但约束不了跨会话、跨任务的长期行为。你需要的是结构化的、可执行的、能落地的流程定义。这就是“Skills”这个概念要解决的问题——把工程工作流拆成一个个可复用的技能单元让 Agent 按需加载、按规执行。1.3 这套东西适合谁如果你只是拿 Agent 聊聊天、写写文案、做做头脑风暴那确实不需要这么重的工作流提示词写好一点就够了。但如果你符合下面任意一条这套思路就值得认真看你在用 Agent 处理多步骤任务比如数据清洗、代码生成、文档处理、自动化测试。你希望 Agent 的产出可复现今天跑和明天跑结果要一致。你需要多个 Agent 协作或者一个 Agent 在多个任务间切换而不混乱。你打算把 Agent 接入已有的工程体系比如 CI、代码仓库、任务管理系统。我自己的判断标准很简单当你会因为 Agent 的一次“发挥”而需要手动返工时就该上工作流了。返工一次是偶然返工三次就是流程缺失。2. 拆解“Skills”这套工作流的核心设计2.1 为什么是“技能”而不是“流程”这里有个设计上的关键选择值得说清楚。很多人第一反应是设计一套“大流程”从任务开始到结束一条龙定义好。但实际用下来这种大流程非常脆弱——任务稍微变一点整条流程就得改改完还要重新测维护成本极高。“Skills”的思路不一样。它把工作流拆成一个个独立的、自包含的技能单元。每个技能只负责一件事有自己的输入、输出、执行规则和校验标准。Agent 面对一个任务时不是走一条固定流水线而是根据任务需要组合调用不同的技能。这个选择背后的逻辑是工程任务的多样性远大于共性。你没法用一条流程覆盖所有情况但你可以用一组技能拼出大多数情况。就像乐高你不设计“一辆车”你设计轮子、底盘、座椅然后按需拼装。我实测下来这种拆法有三个明显好处可测试每个技能单独测输入输出明确坏了容易定位。可复用一个“读取并解析配置文件”的技能在十个任务里都能用。可演进改一个技能不影响其他技能迭代风险低。2.2 一个技能单元应该包含什么我参考了几个开源 Agent 框架的设计也结合自己踩坑的经验总结出一个技能单元至少要有下面这几个部分。缺了任何一个实际跑起来都会出问题。组成部分作用缺失后的典型症状触发条件什么情况下该用这个技能Agent 该用不用或者乱用输入定义需要哪些参数、什么格式传参错误技能内部报错执行步骤具体怎么做分几步执行顺序混乱漏步骤输出规范产出什么、什么格式下游技能接不上校验规则怎么判断做对了错误产出被当成正确结果传递失败处理出错后怎么办整个任务卡死或静默失败我特别想强调校验规则和失败处理这两块。大多数人在设计技能时只关注“怎么做”忽略了“怎么知道做对了”和“做错了怎么办”。结果就是 Agent 一路狂奔产出一堆看似合理实则错误的东西等到最后才发现中间过程已经没法回溯了。提示校验规则要尽量具体、可执行。不要写“检查结果是否合理”要写“检查输出行数是否等于输入行数”“检查每个字段是否非空”“检查数值是否在预期范围内”。模糊的校验等于没有校验。2.3 技能之间怎么衔接技能拆开了下一个问题就是怎么串起来。这里有两种常见模式我两种都用过各有适用场景。第一种是显式编排你提前定义好技能的执行顺序Agent 按顺序调用。比如“先解析配置再读取数据再清洗再汇总”。这种模式适合流程固定、步骤明确的任务可控性最强但灵活性差。第二种是动态选择你只给 Agent 一组技能和任务目标让它自己决定用哪些、按什么顺序。这种模式灵活能处理你没预料到的情况但可控性弱容易跑偏。我的经验是核心链路用显式编排边缘情况用动态选择。也就是说任务的主干流程固定死保证稳定性主干之外的异常处理、补充操作允许 Agent 灵活调用技能。这样既稳又不死板。具体实现上我通常会在工作流里加一个“调度层”。调度层不干活只负责判断当前处于哪个阶段、下一步该调哪个技能、上一个技能的产出是否合格。调度层本身也可以是一个技能但它的规则要写得非常明确不能有歧义。3. 核心技能模块的实操拆解3.1 任务解析技能把模糊需求变成明确指令这是整条工作流的入口也是最容易被低估的一环。用户给的需求往往是模糊的“帮我处理一下这批数据”“把这个模块优化一下”。Agent 如果直接拿这种需求去干活结果基本不可控。任务解析技能要做的是把模糊需求翻译成结构化的任务描述。我一般让它输出这么几个字段任务类型属于哪类操作读取、转换、生成、校验等。目标对象操作什么哪个文件、哪个目录、哪个模块。预期产出最终要得到什么一份报告、一个文件、一段代码。约束条件有什么限制不能改哪些东西、必须用什么格式。完成标准怎么算做完了。这个技能的难点在于追问。用户给的信息往往不全Agent 需要主动识别缺失项并追问。但追问不能无限进行我一般设一个上限最多追问两轮两轮后还没说清就按最保守的默认值执行并在产出里标注假设。# 任务解析技能的输出结构示例伪代码 task_spec { task_type: data_transform, target: {path: ./logs, pattern: *.log}, expected_output: {format: markdown, path: ./report.md}, constraints: [不修改原始文件, 只处理最近7天的日志], completion_criteria: [报告包含错误统计, 报告包含模块分布], assumptions: [未指定时区按本地时间处理] }注意假设一定要显式写出来。Agent 默默做的假设是后期排查问题的最大障碍。写出来用户能看到错了也能改。3.2 执行规划技能把任务拆成可执行的步骤拿到结构化任务描述后下一步是规划。这个技能负责把任务拆成一个个具体步骤并标注每步用哪个技能、依赖什么、产出什么。我踩过的一个坑是规划太粗。比如“处理数据”算一步结果执行时 Agent 不知道从哪下手又得临时想等于没规划。后来我要求规划必须细到每个步骤都能对应到一个具体技能不能有“然后处理一下”这种模糊步骤。规划技能的另一个要点是依赖标注。哪些步骤可以并行、哪些必须串行、哪些步骤的产出是下一步的输入都要标清楚。这样执行时才能知道什么时候可以等什么时候必须等。步骤使用技能依赖产出1读取日志文件无原始日志列表2解析日志行步骤1结构化日志记录3过滤错误行步骤2错误记录列表4按模块归类步骤3模块到错误的映射5生成报告步骤4Markdown 报告这张表看起来简单但它是整个工作流的骨架。有了它执行层就不用“思考”只管按表干活稳定性大幅提升。3.3 执行技能真正干活的那一层执行技能是具体操作的封装。每个执行技能应该是一个纯函数式的存在给定确定的输入产出确定的输出不依赖外部状态不产生副作用或者副作用被严格限定。我写执行技能时有个习惯先写校验再写逻辑。也就是说先想清楚“怎么判断这个技能做对了”再去实现“怎么做”。这个顺序反过来很容易写出“能跑但不知道对不对”的代码。以“解析日志行”这个技能为例我的实现顺序是定义输入格式一行原始日志文本。定义输出格式包含时间戳、级别、模块、消息的结构化对象。定义校验规则时间戳能解析、级别在枚举范围内、模块非空。实现解析逻辑。写测试用例正常行、缺字段行、格式错误行。import re from datetime import datetime LOG_PATTERN re.compile( r(?Pts\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) r\[(?Plevel\w)\] r(?Pmodule[\w\.]): r(?Pmsg.) ) VALID_LEVELS {DEBUG, INFO, WARN, ERROR} def parse_log_line(line: str) - dict: m LOG_PATTERN.match(line.strip()) if not m: raise ValueError(f日志行格式不匹配: {line[:50]}) result m.groupdict() # 校验时间戳 datetime.strptime(result[ts], %Y-%m-%d %H:%M:%S) # 校验级别 if result[level] not in VALID_LEVELS: raise ValueError(f未知日志级别: {result[level]}) # 校验模块非空 if not result[module]: raise ValueError(模块名为空) return result这段代码不长但包含了执行技能该有的所有要素明确的输入输出、前置校验、失败时抛异常而不是返回 None。抛异常比返回 None 好因为 None 会被下游当成合法值继续传递异常会立刻中断流程让问题暴露在发生的地方。3.4 校验技能别让错误悄悄溜过去校验技能是工作流里的“质检员”。它的职责是在每个关键步骤后检查产出不合格就拦截。我见过太多 Agent 项目前面干得热火朝天最后产出一份报告人一看全是错的。问题就出在中间没有校验错误一路传递越滚越大。校验技能的设计要点是分层。我一般分三层格式校验产出是不是符合约定的格式JSON 能不能解析、字段全不全。逻辑校验产出在逻辑上是否自洽统计数字加起来对不对、引用关系是否成立。业务校验产出是否符合业务规则数值是否在合理范围、是否满足特定约束。三层校验的成本递增但收益也递增。格式校验几乎零成本逻辑校验需要写一些规则业务校验需要领域知识。我的建议是格式校验必须做逻辑校验尽量做业务校验按需做。提示校验失败时不要只报“校验失败”要报“哪个字段、期望什么、实际什么”。这样排查时能直接定位不用重新跑一遍。3.5 记录与回溯技能让每一步都有据可查这个技能经常被忽略但它是工作流能否长期维护的关键。记录技能负责把每个步骤的输入、输出、耗时、状态、异常都存下来。我一般会记录这么几类信息执行日志什么时间、执行了哪个技能、输入是什么、输出是什么、耗时多久。决策记录Agent 在动态选择时为什么选了这个技能而不是那个。异常记录哪里出错了、错误信息是什么、当时的状态是什么。版本信息用的哪个版本的技能定义、哪个版本的模型。这些记录平时看着没用一旦出问题就是救命稻草。我经历过一次线上任务失败靠记录发现是某个技能的定义被改过但没重新测试五分钟定位十分钟修复。没有记录的话这种问题能查一整天。记录技能的实现可以很简单写文件、写数据库、发消息队列都行。关键是结构化别写成一堆自由文本不然查的时候还得再解析一遍。4. 把技能串成工作流的完整实操4.1 环境与依赖准备动手之前先把环境理清楚。我用的技术栈比较朴素因为工作流这东西越简单越稳。运行环境Python 3.10主要是看中它的类型提示和异步支持。模型接入任意支持函数调用的模型接口我用的是通用的对话补全接口。存储本地文件系统存日志和中间产物简单任务够用复杂任务上 SQLite。配置YAML 文件定义技能和流程改配置不用改代码。目录结构我习惯这么组织agent_workflow/ ├── skills/ # 技能定义 │ ├── task_parse.py │ ├── plan.py │ ├── execute.py │ ├── validate.py │ └── record.py ├── flows/ # 流程定义 │ └── log_process.yaml ├── runtime/ # 运行时 │ ├── scheduler.py │ └── context.py ├── logs/ # 执行记录 └── tests/ # 测试用例这个结构的好处是技能和流程分离。技能是通用的流程是具体的。同一个技能可以在多个流程里复用改流程不影响技能。4.2 定义第一个技能从 YAML 开始我倾向于用 YAML 定义技能因为可读性好非开发人员也能看懂。一个技能定义大概长这样name: parse_log_line description: 解析单行日志文本为结构化对象 trigger: when: 输入为原始日志文本行 input: type: string description: 一行原始日志 output: type: object fields: - ts: string - level: string - module: string - msg: string steps: - 用正则匹配日志格式 - 提取各字段 - 校验时间戳可解析 - 校验级别在允许范围内 validation: - 时间戳格式为 YYYY-MM-DD HH:MM:SS - level 属于 [DEBUG, INFO, WARN, ERROR] - module 非空 on_failure: action: raise message: 日志行解析失败请检查格式这个定义里steps是给人看的validation是给机器执行的。实际运行时执行层会按 steps 调用对应的代码按 validation 做检查。注意YAML 里的步骤描述要具体到“能对应到一段代码”不能写“处理一下数据”这种。我一般要求每个步骤都能映射到一个函数。4.3 编排流程把技能连起来流程定义就是把技能按顺序连起来加上分支和循环。我用的是最朴素的顺序加条件判断没上复杂的工作流引擎因为大多数任务用不上。name: log_process_flow description: 处理日志文件并生成报告 steps: - skill: task_parse input: ${user_input} output: task_spec - skill: plan input: ${task_spec} output: plan - skill: read_files input: ${task_spec.target} output: raw_lines - skill: parse_log_line input: ${raw_lines} output: parsed_records loop: true - skill: filter_errors input: ${parsed_records} output: error_records - skill: group_by_module input: ${error_records} output: module_map - skill: generate_report input: ${module_map} output: report - skill: validate_report input: ${report} output: validation_result - skill: save_report input: ${report} output: saved_path这个流程里loop: true表示对列表里的每一项都执行一次。${}是变量引用指向前一步的产出。整个流程读下来逻辑一目了然。实际运行时调度器会按顺序执行每步执行完做校验校验不过就按on_failure处理。如果某步是动态选择调度器会把候选技能列表和当前上下文交给模型让模型选一个。4.4 跑起来一次完整的执行记录我拿一批模拟日志跑了一遍记录一下关键节点。输入一个包含 500 行日志的目录日志格式统一。第一步任务解析。Agent 识别出这是“日志处理”类任务目标目录是./logs预期产出是 Markdown 报告约束是“不修改原始文件”。这里它追问了一次“报告需要包含哪些统计维度”我回复“错误数、模块分布、时间趋势”。追问一次后信息够了继续。第二步规划。Agent 输出了 9 个步骤和上面流程定义基本一致。我检查了一下没有遗漏继续。第三步到第五步读取和解析。500 行日志解析成功 498 行2 行格式异常。异常行被记录到parse_errors.log没有中断流程。这里校验技能起作用了它检查了解析成功率发现 99.6%在可接受范围内我设的阈值是 95%放行。第六步到第八步过滤、归类、生成报告。错误行 47 条分布在 6 个模块。报告生成后校验技能检查了报告结构包含三个必需章节数字加总一致通过。第九步保存。报告写入./report.md同时执行记录写入./logs/run_20240115_143022.json。整个流程跑了大概 40 秒其中模型调用占了大头。如果纯脚本跑可能 2 秒就完了但 Agent 的价值在于它能处理格式变化、能追问、能在异常时做判断。这个 trade-off 我觉得值。4.5 参数选择与调优经验跑了几十次之后我总结出几个关键参数的调优经验都是踩坑换来的。解析成功率阈值我一开始设的 99%结果稍微有点格式差异就中断。后来降到 95%配合异常记录既不会因为个别坏行卡死又能保证整体质量。如果你的日志格式很规范可以设高一点如果来源杂设低一点。追问轮数上限设成 2 轮。1 轮往往不够3 轮用户会烦。2 轮是个平衡点大部分情况能问清楚问不清的就按默认值走。校验层级格式校验全开逻辑校验开关键项业务校验按任务重要性开。全开的话小任务也会变得很重没必要。记录详细程度我分三档。调试时全量记录包括每步的完整输入输出正常运行时只记摘要和异常批量任务时只记最终结果和统计。全量记录很占空间别一直开着。参数保守值激进值我的常用值解析成功率阈值99%90%95%追问轮数上限312校验层级全开仅格式格式关键逻辑记录详细程度全量仅结果摘要异常5. 常见问题与排查实录5.1 Agent 不按流程走怎么办这是最常见的问题。表现是明明定义了流程Agent 却跳步、乱序、或者自己发明步骤。原因通常有三个一是流程定义太模糊Agent 理解不了二是技能描述不清楚Agent 不知道什么时候该用三是模型本身倾向于“自由发挥”约束不够强。我的解决办法是加硬约束。在调度层里每一步执行前都检查“当前状态是否允许执行这个技能”不允许就直接拒绝不给模型商量的余地。同时把流程定义写得非常具体每个步骤的输入输出都明确减少模型的解释空间。还有一个技巧在提示词里明确说“你只能从以下技能中选择不能自己发明”。这句话看着简单但很管用。模型有时候就是需要被明确告知边界。5.2 技能之间传参出错怎么排查传参错误的表现是技能 A 产出的东西技能 B 接不住。常见原因是格式不匹配、字段名不一致、或者 A 的产出是 B 不支持的变体。排查思路是从后往前查。先看 B 期望什么输入再看 A 实际产出了什么对比差异。我一般会在每个技能的入口加一个参数校验不匹配就直接报错报错信息里带上期望格式和实际格式。def validate_input(data, expected_schema): for field, field_type in expected_schema.items(): if field not in data: raise ValueError(f缺少字段: {field}期望类型: {field_type}) if not isinstance(data[field], field_type): raise TypeError( f字段 {field} 类型错误: f期望 {field_type}, 实际 {type(data[field])} )这个校验函数我每个技能入口都调一次虽然有点啰嗦但省下的排查时间远超这点开销。5.3 校验太严导致流程频繁中断校验是好事但太严会适得其反。我一开始把校验写得很死结果稍微有点偏差就中断任务成功率很低。后来我改成分级处理严重问题中断轻微问题记录并继续。比如解析日志时个别行格式不对记录到异常文件继续处理其他行但如果解析成功率低于阈值才中断。分级的关键是定义清楚什么算严重。我的标准是影响最终结果正确性的算严重只影响完整性的算轻微。错误统计数字算错了严重少统计了一两条边缘日志轻微。5.4 常见问题速查表问题现象可能原因排查方向解决手段Agent 跳步流程定义模糊检查流程步骤是否具体加硬约束明确步骤传参出错格式不匹配对比上下游格式入口加参数校验频繁中断校验过严检查校验规则分级校验轻微放行结果不可复现依赖外部状态检查技能是否有副作用技能纯函数化执行慢模型调用过多统计各步耗时合并简单步骤减少调用记录丢失记录技能未覆盖检查记录点每步强制记录5.5 几个我踩过的坑坑一技能定义和实现不同步。我改过技能的实现但忘了更新 YAML 定义结果校验规则还是旧的跑出来的结果和预期对不上。后来我加了一个检查启动时对比技能定义和实现不一致就报警。坑二过度依赖模型做判断。我一开始让模型决定“这步做完了没”结果它经常说“做完了”但实际没完。后来改成用明确的完成标准来判断模型只负责执行不负责判断完成。坑三记录写太多导致磁盘满。全量记录跑批量任务一天写了 20G 日志。后来改成滚动记录只保留最近 7 天老记录归档压缩。坑四技能粒度太细。拆得太细技能之间调用开销比干活还大。后来合并了一些简单技能比如“读取文件”和“解析内容”合成一个减少调用次数。提示技能粒度没有标准答案我的经验是“一个技能对应一个可独立测试的单元”。如果两个技能总是一起出现、从不分开用那它们可能就该合并。6. 技能库的维护与演进6.1 技能版本管理技能是会变的。今天写的解析逻辑明天日志格式变了就得改。改的时候怎么保证不影响正在跑的任务是个实际问题。我的做法是给技能加版本号流程定义里引用具体版本。新任务用新版本老任务继续用老版本跑完为止。这样改技能不会影响存量任务风险可控。版本号我一般用语义化版本主版本号变表示不兼容次版本号变表示新增功能修订号变表示修 bug。流程定义里写parse_log_line1.2.0明确到修订号保证可复现。6.2 技能复用与组合技能库大了之后复用就成了关键。我一般会定期整理技能库把功能重叠的合并把没人用的归档把常用的标记出来。复用还有一个技巧把技能分成基础技能和组合技能。基础技能是最小单元比如“读文件”“解析行”“写文件”组合技能是基础技能的组合比如“处理日志文件”就是“读文件解析行过滤写文件”。组合技能让流程定义更简洁基础技能保证灵活性。6.3 从单 Agent 到多 Agent 协作单个 Agent 跑工作流能力有上限。任务复杂到一定程度就需要多个 Agent 分工。我的做法是按技能域拆分 Agent一个 Agent 负责解析类技能一个负责生成类技能一个负责校验类技能。Agent 之间通过工作流调度层通信不直接对话。调度层负责把任务分给合适的 Agent收集结果决定下一步。这样每个 Agent 的职责清晰提示词可以针对性地优化整体稳定性比一个大而全的 Agent 高。多 Agent 的代价是复杂度上升调试更难。我的建议是单 Agent 能搞定就别上多 Agent。只有当单 Agent 的提示词长到难以维护、或者不同任务的技能需求冲突严重时才考虑拆分。6.4 持续改进的节奏工作流不是写完就完了得持续改进。我的节奏是每周看一次执行记录找出失败率高的技能和步骤每月做一次技能库整理合并、归档、优化每季度做一次大版本回顾看整体架构有没有需要调整的。改进的依据是数据不是感觉。执行记录里有什么技能失败率高、什么步骤耗时长、什么校验经常不过一目了然。根据数据改比拍脑袋改靠谱得多。我个人在实际操作中的体会是这套东西最大的价值不在于让 Agent 变聪明而在于让 Agent 变可管理。聪明是模型的事可管理是工程的事。模型会越来越聪明但可管理这件事得靠工作流来兜底。把技能拆清楚、把流程定明白、把校验做扎实、把记录留完整Agent 才能真正从“玩具”变成“工具”。最后分享一个小技巧如果你刚开始搭这套东西别一上来就追求完整。先挑一个最痛的任务把它的流程跑通跑顺了再往其他任务上扩展。我见过太多人一上来就设计大而全的框架结果框架没搭完热情先耗完了。小步快跑跑通一个是一个这才是工程化的正确打开方式。