1. 为什么需要给 AI Agent 配一套工程工作流1.1 从“能聊”到“能干活”的鸿沟过去一年我花了不少时间在 AI Agent 的落地上踩过的坑比想象中多得多。最开始我以为只要把大模型的接口接上、把提示词写清楚Agent 就能自动帮我处理任务。结果现实很骨感模型确实能“聊”但一旦让它真正去执行一个多步骤的工程任务比如读代码、改配置、跑测试、提交结果它就开始各种翻车——要么忘了上一步做了什么要么在同一个错误上反复打转要么把中间结果丢得一干二净。这个问题的本质不是模型不够聪明而是我们缺少一套工程工作流来约束和引导它的行为。所谓 Skills说白了就是给 AI Agent 配一套“技能包”加“作业规范”让它知道在什么场景下该调用什么能力、按什么顺序执行、遇到异常怎么回退。这套东西不是提示词的堆砌而是一套可复用、可组合、可调试的工程化结构。我后来总结出一个判断标准如果一个 Agent 只能完成单轮问答那它就是个玩具如果它能稳定地完成一个需要五到十个步骤、涉及多个工具调用的任务那它才算真正进入了工程可用的范畴。而 Skills 就是跨越这条鸿沟的桥。1.2 Skills 到底解决什么问题具体来说Skills 这套工作流主要解决四类问题。第一类是能力边界模糊。模型不知道自己会什么、不会什么用户也不清楚该让它干什么。Skills 通过显式定义每个技能的名称、描述、输入输出格式把能力边界画清楚。比如一个“读取文件”技能和一个“修改文件”技能是分开的模型不会混着用。第二类是执行顺序混乱。多步骤任务最怕顺序错乱Skills 通过工作流编排把步骤固定下来每一步的产出作为下一步的输入形成一条清晰的链路。第三类是错误处理缺失。真实工程任务里失败是常态Skills 要求每个技能都定义失败时的行为——是重试、是跳过、还是回滚都要提前想清楚。第四类是结果不可复现。同样的输入今天跑出来是这个结果明天跑出来是另一个结果这在工程上是不可接受的。Skills 通过固定参数、固定工具版本、固定执行路径让结果尽可能可复现。1.3 适合谁来参考这套方案这套东西不是给纯小白看的但也不需要你是资深架构师。我的经验是只要你满足下面任意一条这套工作流就能帮到你你已经用过大模型接口写过一些简单的调用脚本但想让 Agent 做更复杂的事你在做自动化工具、RPA、或者内部效率平台需要把 AI 能力嵌进去你带团队做 AI 应用需要一套规范让不同人写的 Agent 能互相配合你自己折腾过 Agent 框架但被各种“玄学”问题搞得头大想要一套更工程化的思路。下面我会从整体设计、核心细节、实操过程、问题排查四个层面把这套 Skills 工作流拆开讲清楚。每个部分我都会给出具体的结构、参数和踩坑经验你可以直接拿去改改用。2. 整体设计与思路拆解2.1 为什么选择“技能注册 工作流编排”这套结构市面上做 Agent 的方案大致分两派。一派是“大提示词派”把所有逻辑塞进一个超长的系统提示里靠模型自己理解另一派是“工具调用派”把能力拆成一个个函数让模型按需调用。我两种都试过最后选了后者的变体——技能注册 工作流编排。大提示词派的问题是提示词一长模型的注意力就散了。我实测过一个三千字的系统提示模型在前几轮还能记住关键约束到第五轮之后就开始忽略一些细节。而且提示词没法做单元测试改一个字可能影响全局维护成本极高。纯工具调用派的问题是模型有了工具但不知道怎么组合。它可能在一个简单任务上调用五个工具也可能在复杂任务上只调用一个。缺少编排层执行路径完全不可控。技能注册 工作流编排的思路是技能层负责“能做什么”编排层负责“怎么做”。技能层把每个能力封装成标准接口编排层用状态机或者有向图把技能串起来。这样模型只需要在编排层做决策技能层保持稳定。两层分离之后调试和替换都方便很多。2.2 技能注册表的设计考量技能注册表是整个工作流的基础。我设计的注册表包含以下字段字段名类型说明skill_idstring技能唯一标识用下划线命名namestring人类可读的技能名称descriptionstring一句话说明技能用途给模型看input_schemaobject输入参数的结构定义output_schemaobject输出结果的结构定义handlerfunction实际执行的函数retry_policyobject重试策略含次数和间隔timeoutnumber超时时间单位秒tagsarray标签用于分类和检索这里有几个设计决策值得展开说。为什么用 schema 而不是自由文本描述输入输出因为模型对结构化信息的理解远好于自然语言。我试过用自然语言描述“这个技能需要一个文件路径和一个可选的编码格式”模型经常漏掉可选参数或者把参数名写错。换成 JSON Schema 之后参数错误率下降了大概七成。为什么要有 tags当技能数量超过二十个之后模型在选择技能时开始出现“选择困难”。tags 让编排层可以先按标签过滤再在候选集里做选择。比如一个任务涉及“文件操作”编排层就只把 tags 含 file 的技能给模型看候选集从二十个降到五个准确率明显提升。retry_policy 为什么放在技能层而不是编排层因为不同技能的失败特性不一样。读文件失败可能是路径问题重试没用调接口失败可能是网络抖动重试有用。把重试策略放在技能层每个技能可以有自己的默认策略编排层只在特殊情况下覆盖。2.3 工作流编排的三种模式编排层我实现了三种模式分别应对不同复杂度的任务。线性模式最简单技能按固定顺序执行上一步的输出直接作为下一步的输入。适合流程固定的任务比如“读取配置 → 校验配置 → 应用配置”。分支模式在某个节点根据条件选择不同路径。比如“检查文件是否存在”存在就走“读取”不存在就走“创建”。分支条件可以是上一步的输出也可以是外部状态。循环模式用于需要反复执行直到满足条件的场景。比如“修改代码 → 跑测试 → 如果失败则根据错误信息再修改”这个循环最多跑 N 次超过就报错退出。这三种模式可以嵌套组合。我实际项目里最复杂的任务用了两层嵌套外层是循环内层是分支加线性。关键是每一层都要有明确的退出条件否则容易死循环。2.4 状态管理为什么不能只靠对话历史很多人做 Agent 喜欢把状态放在对话历史里靠模型自己记住。我一开始也这么干后来发现两个致命问题。一是上下文长度限制。任务步骤一多历史就爆了模型开始遗忘早期信息。二是状态污染。对话历史里混着用户的闲聊、模型的思考、工具的返回模型很难从中准确提取当前状态。我的做法是引入一个独立的状态存储用一个 JSON 对象保存当前工作流的所有关键信息当前步骤、已完成步骤、每步的输入输出、全局变量、错误记录。这个状态对象在每一步开始时注入到模型的上下文里模型只看到它需要的那部分而不是全部历史。这样做的好处是状态可序列化、可恢复、可调试。任务跑到一半失败了我可以把状态存下来修完 bug 从断点继续不用从头再跑。3. 核心细节解析与实操要点3.1 技能定义的五个关键要素写一个技能看起来简单但要写得让模型好用、让自己好维护有五个要素必须认真对待。第一是命名。技能名要用动词开头比如read_file、validate_config、send_notification。不要用file_reader这种名词形式因为模型在决策时想的是“我要做什么动作”动词命名更符合它的思考方式。我做过对比测试动词命名的技能被正确调用的概率比名词命名高约两成。第二是描述。描述要回答三个问题这个技能做什么、什么时候用、有什么限制。比如read_file的描述可以写成“读取指定路径的文件内容。适用于需要获取文件原始内容的场景。不支持二进制文件单文件大小限制 10MB。”这样模型在决策时就有充分依据。第三是参数设计。参数宁少勿多必填参数控制在三个以内。可选参数要有合理默认值。参数名要自解释不要用p1、arg这种。如果某个参数有枚举值一定要在 schema 里列出来模型对枚举的遵循度很高。第四是返回值。返回值要结构化包含success、data、error三个字段。success是布尔值data是成功时的结果error是失败时的错误信息。这样编排层可以统一处理不用为每个技能写不同的判断逻辑。第五是幂等性。尽量让技能幂等也就是同样的输入执行多次结果一样。这对重试很重要。如果一个技能不幂等重试就可能产生副作用。比如“发送通知”不幂等重试就会发多条。这种情况要么加去重逻辑要么在重试策略里明确禁止重试。3.2 编排层的决策逻辑怎么写编排层的核心是“下一步做什么”的决策。我的实现是把当前状态和可用技能列表一起给模型让模型输出下一步要调用的技能和参数。这里有个关键技巧不要问模型“下一步做什么”而是问它“从这些选项里选一个”。开放式提问会让模型发散给出各种奇怪的方案封闭式选择则把它的输出限制在可控范围内。具体做法是编排层先根据当前状态和任务类型筛选出一批候选技能然后把候选技能的名称和描述列给模型让它选。如果模型选的技能不在候选集里就报错并要求重选。这样既保留了模型的灵活性又保证了执行路径的可控性。另一个技巧是给模型提供少量示例。在编排提示里放两三个“状态 → 选择”的示例模型的决策准确率会明显提升。示例要覆盖典型场景包括正常流程和异常分支。3.3 错误处理的分层策略错误处理我分了三层。技能层处理技能内部的错误。比如文件不存在、网络超时、参数格式错误。技能层负责捕获这些错误包装成标准错误格式返回并根据 retry_policy 决定是否重试。编排层处理技能返回的错误。如果某个技能最终失败了编排层要决定是换一个技能、跳过这一步、还是终止整个工作流。这个决策也交给模型但要在提示里明确各种错误对应的处理建议。工作流层处理整体失败。如果工作流终止了要保存当前状态记录失败原因并通知相关人员。这一层是兜底的确保任何失败都有记录、可追溯。三层各司其职不要混在一起。我见过有人把所有错误处理都塞在编排层结果编排逻辑变得极其复杂改一处崩一片。3.4 参数传递与数据转换技能之间的参数传递是个容易被忽视的细节。上一步的输出往往不能直接作为下一步的输入需要做转换。比如read_file返回的是文件内容字符串而parse_json需要的是一个 JSON 对象。中间就需要一个转换步骤。我的做法是在编排层加一个轻量的数据映射机制用类似{{step1.output.data}}的模板语法引用上一步的结果并支持简单的转换函数如json_parse、trim、split。这个映射机制要简单不要搞成图灵完备的表达式语言否则调试成本太高。我限制只支持属性访问和几个内置函数够用就行。注意数据映射的失败要单独处理。如果模板引用的字段不存在或者转换函数执行失败要给出明确的错误信息指出是哪个步骤的哪个字段出了问题。含糊的错误信息会让排查变得非常痛苦。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先说一下我的技术栈选择。语言用 Python因为生态最全调试也方便。核心依赖就三个一个大模型客户端库、一个数据校验库、一个日志库。不需要引入重型框架自己写反而更可控。pip install openai pydantic loguru这里解释一下为什么选这三个。大模型客户端库负责和模型通信我选的是官方库稳定且更新及时。pydantic 用来做 schema 校验它的类型提示和验证功能非常成熟能省掉大量手写校验代码。loguru 用来打日志比标准库的 logging 好用太多尤其是结构化日志和异常追踪。环境变量里要配好模型接口的地址和密钥这些不要写死在代码里。我用一个.env文件管理配合python-dotenv加载。4.2 技能注册表的代码实现先定义技能的数据结构。from pydantic import BaseModel, Field from typing import Callable, Any, Optional class RetryPolicy(BaseModel): max_retries: int 2 interval_seconds: float 1.0 backoff_factor: float 2.0 class Skill(BaseModel): skill_id: str name: str description: str input_schema: dict output_schema: dict handler: Callable retry_policy: RetryPolicy Field(default_factoryRetryPolicy) timeout: float 30.0 tags: list[str] Field(default_factorylist) class Config: arbitrary_types_allowed True然后写注册表。class SkillRegistry: def __init__(self): self._skills: dict[str, Skill] {} def register(self, skill: Skill): if skill.skill_id in self._skills: raise ValueError(f技能 {skill.skill_id} 已注册) self._skills[skill.skill_id] skill def get(self, skill_id: str) - Optional[Skill]: return self._skills.get(skill_id) def list_by_tags(self, tags: list[str]) - list[Skill]: return [ s for s in self._skills.values() if any(t in s.tags for t in tags) ] def all_skills(self) - list[Skill]: return list(self._skills.values())注册表本身很简单关键是注册的时机。我的做法是在应用启动时统一注册注册完打印一份技能清单方便核对。不要在运行时动态注册那样容易出并发问题。4.3 一个完整技能的编写示例以read_file为例完整写一遍。import os from pathlib import Path def read_file_handler(path: str, encoding: str utf-8) - dict: try: p Path(path) if not p.exists(): return {success: False, data: None, error: f文件不存在: {path}} if p.stat().st_size 10 * 1024 * 1024: return {success: False, data: None, error: 文件超过 10MB 限制} content p.read_text(encodingencoding) return {success: True, data: content, error: None} except Exception as e: return {success: False, data: None, error: str(e)} read_file_skill Skill( skill_idread_file, name读取文件, description读取指定路径的文本文件内容。适用于需要获取文件原始内容的场景。不支持二进制文件单文件大小限制 10MB。, input_schema{ type: object, properties: { path: {type: string, description: 文件的绝对路径或相对路径}, encoding: {type: string, description: 文件编码默认 utf-8, default: utf-8} }, required: [path] }, output_schema{ type: object, properties: { success: {type: boolean}, data: {type: [string, null]}, error: {type: [string, null]} } }, handlerread_file_handler, retry_policyRetryPolicy(max_retries0), timeout5.0, tags[file, read] )注意这里的 retry_policy 设成了不重试因为文件不存在这种错误重试也没用。如果是网络相关的技能就可以设成重试两次。4.4 工作流引擎的核心循环工作流引擎的主循环大概是这样的。class WorkflowEngine: def __init__(self, registry: SkillRegistry, llm_client, max_steps: int 20): self.registry registry self.llm llm_client self.max_steps max_steps def run(self, task: str, initial_state: dict None) - dict: state { task: task, steps: [], current_step: 0, variables: initial_state or {}, status: running } while state[current_step] self.max_steps: candidates self._select_candidates(state) decision self._ask_llm_for_next(state, candidates) if decision[action] finish: state[status] completed break skill self.registry.get(decision[skill_id]) if not skill: state[steps].append({error: f未知技能 {decision[skill_id]}}) continue result self._execute_with_retry(skill, decision[params]) state[steps].append({ step: state[current_step], skill_id: skill.skill_id, params: decision[params], result: result }) state[current_step] 1 if not result[success] and decision.get(abort_on_failure): state[status] failed break return state这个循环里有几个关键点。max_steps是硬性上限防止死循环。_select_candidates根据当前状态筛选候选技能。_ask_llm_for_next把状态和候选技能给模型让它决策。_execute_with_retry负责执行和重试。4.5 提示词模板的设计编排层的提示词模板我改了十几版最后稳定下来的结构是这样的。你是一个工作流编排器。当前任务{task} 已完成步骤 {steps_summary} 当前可用技能 {skills_description} 请从上述技能中选择下一步要执行的技能或者如果任务已完成返回 finish。 输出格式JSON { action: execute | finish, skill_id: 技能ID, params: {}, reasoning: 选择理由, abort_on_failure: true | false }steps_summary只包含最近五步的摘要不是全部历史避免上下文过长。skills_description只包含候选技能不是全部技能。reasoning字段强制模型给出理由这个理由在调试时非常有用能看出模型是怎么想的。4.6 状态持久化与断点恢复状态持久化我用的是 JSON 文件简单可靠。每执行完一步就把状态写一次盘。import json def save_state(state: dict, path: str): with open(path, w, encodingutf-8) as f: json.dump(state, f, ensure_asciiFalse, indent2) def load_state(path: str) - dict: with open(path, r, encodingutf-8) as f: return json.load(f)恢复的时候把状态加载回来从current_step继续跑就行。这里要注意如果技能有副作用比如已经发了通知恢复时要避免重复执行。我的做法是在状态里记录每步的执行状态已成功执行的步骤在恢复时跳过。5. 常见问题与排查技巧实录5.1 模型选错技能怎么办这是最常见的问题。模型面对一堆技能选了一个看起来相关但实际不对的。排查思路分三步。第一步看候选集是不是太大如果候选超过十个模型的选择准确率会明显下降这时候要加 tags 过滤。第二步看技能描述是不是有歧义两个技能描述太像模型就容易混。第三步看提示词里的示例是不是覆盖了当前场景没有示例的话模型只能靠猜。我的经验是技能描述里要明确写出“不适用于什么场景”。比如read_file的描述里写“不支持二进制文件”模型就不会在需要读图片时选它。5.2 参数传错或漏传参数问题通常有三个原因。一是 schema 定义不清晰模型不知道某个参数是必填的。二是上一步的输出字段名和下一步的输入字段名对不上映射失败。三是模型理解错了参数含义。解决办法schema 里必填参数用required明确标出字段命名保持一致比如统一用path而不是有的地方用file_path有的地方用filepath参数描述里给一个示例值模型对示例的遵循度很高。5.3 工作流陷入死循环死循环的表现是步骤数一直涨但任务没进展。原因通常是循环的退出条件没设计好或者模型在某个分支上反复横跳。我的处理办法是加两个保险。一是max_steps硬上限超过就强制终止。二是进展检测如果连续三步调用了同一个技能且参数相同就判定为卡住强制终止并报错。这两个保险加上之后死循环基本没再出现过。5.4 上下文过长导致模型失忆任务步骤多了之后上下文会越来越长模型开始遗忘早期信息。这个问题我在 4.5 节提过解决办法是只给模型最近几步的摘要而不是全部历史。另外关键信息放在状态对象里每步都重新注入不依赖模型自己记住。如果任务确实需要很长的上下文可以考虑分段执行把一个大任务拆成几个子任务每个子任务独立跑中间结果通过状态传递。5.5 常见问题速查表问题现象可能原因排查方向解决措施模型选错技能候选集过大或描述歧义检查候选数量和技能描述加 tags 过滤描述里写明不适用场景参数传错schema 不清晰或字段名不一致对比 schema 和实际传参明确 required统一命名加示例值死循环退出条件缺失看步骤日志是否重复加 max_steps 和进展检测模型失忆上下文过长看历史长度只给最近摘要关键信息放状态重试产生副作用技能不幂等检查技能是否有副作用加去重逻辑或禁止重试状态恢复后重复执行未记录执行状态检查状态里的步骤记录记录每步执行状态恢复时跳过已完成5.6 几个我踩过的坑第一个坑是技能粒度过细。我一开始把每个小操作都拆成一个技能结果技能数量膨胀到五十多个模型选择困难编排层也复杂。后来合并了一些技能控制在二十个以内效果好很多。技能粒度以“一个完整的业务动作”为准不要拆到原子操作。第二个坑是过度依赖模型的推理。我一开始希望模型自己规划整个工作流结果它规划的路径经常不合理。后来改成编排层给框架、模型做局部决策稳定性大幅提升。模型擅长局部选择不擅长全局规划这个认知很重要。第三个坑是忽略日志。早期我没认真打日志出问题只能靠猜。后来加了结构化日志每步的输入输出、模型决策、执行耗时都记下来排查效率提升了一个数量级。日志不是可选项是必选项。第四个坑是没有做技能的单测。技能本身有 bug但被工作流的复杂性掩盖了排查时以为是编排问题实际是技能问题。后来我给每个技能都写了单测确保技能本身是可靠的再往上排查就快多了。6. 技能组合与扩展思路6.1 技能的分层组织技能多了之后要分层。我分成三层基础技能、组合技能、业务技能。基础技能是最底层的原子能力比如读写文件、调接口、解析数据。组合技能是基础技能的组合比如“读取配置并校验”。业务技能是面向具体业务的比如“部署服务”。分层的好处是复用。组合技能可以复用基础技能业务技能可以复用组合技能。改一个基础技能上层自动受益。分层也让候选集筛选更精准业务任务只需要看业务技能和部分组合技能。6.2 技能的版本管理技能会迭代迭代就要有版本。我的做法是在 skill_id 里带版本号比如read_file_v2。旧版本保留一段时间新版本上线后观察一段时间再下线旧版本。这样避免升级技能时把正在跑的工作流搞崩。版本管理还有个好处是 A/B 测试。同一个功能可以有两个版本的技能编排层根据配置选择用哪个对比效果。6.3 从单 Agent 到多 Agent 协作单个 Agent 的能力有上限复杂任务可以拆给多个 Agent。每个 Agent 有自己的技能集和工作流Agent 之间通过消息传递协作。比如一个“代码审查”任务可以拆成三个 Agent一个负责读代码一个负责分析问题一个负责生成报告。三个 Agent 各自跑自己的工作流通过共享状态交换数据。多 Agent 的难点在协调。我的经验是Agent 之间的接口要定义清楚谁负责什么、产出什么格式、什么时候触发下一个都要明确。不要指望 Agent 之间靠“自然语言”协商那样太不稳定。6.4 性能优化的几个方向工作流跑得慢是常见问题。优化方向有几个。一是并行执行。没有依赖关系的技能可以并行跑。比如同时读取多个文件不用串行。编排层要能识别可并行的步骤。二是缓存。同样的技能同样的参数结果可以缓存。尤其是那些耗时的、结果稳定的技能缓存能省大量时间。三是模型调用优化。编排层的模型调用是瓶颈之一。可以通过减少候选集、简化提示词、用更小的模型来做编排决策来优化。不是所有决策都需要大模型简单的选择用小模型就够。四是技能本身的优化。有些技能写得低效比如每次都重新建立连接。优化技能实现整体性能也会提升。7. 我个人的一些实操体会这套 Skills 工作流我用了大半年从最初的玩具版本迭代到现在能稳定跑生产任务中间改了很多。最大的体会是工程化不是给 AI 加限制而是给它搭舞台。舞台搭得好AI 才能发挥出真正的能力。另一个体会是不要追求一步到位。我一开始想设计一个完美的工作流引擎结果卡了很久。后来改成先跑通最简单的线性流程再逐步加分支、加循环、加错误处理反而进展快很多。工程的东西都是迭代出来的不是设计出来的。还有一点调试工具比功能更重要。我花了不少时间做状态查看、步骤回放、日志分析这些调试功能看起来不产出业务价值但实际省下的排查时间远超投入。做 Agent 系统可观测性是第一位的。最后分享一个小技巧给每个技能加一个dry_run模式只返回将要执行的操作而不真正执行。调试工作流时先用 dry_run 跑一遍确认路径正确再真正执行。这个模式帮我避免了很多误操作。这套东西还在演进后面我打算加上技能的自动发现、工作流的可视化编辑、以及基于历史数据的路径优化。有进展再分享。