1. Agent的“指令集”到底指什么聊Agent之前我先把一个最容易被新手忽略的事实抛出来Agent本质上是一段无人守着的代码。它不像传统程序那样由开发者在IDE里一行行写死业务逻辑而是让模型在运行时自己“读指令、选工具、做决策”。这句听起来简单但落到工程上难度就变了形——模型不是人它不会“猜”你的意图它只会按照你给它的规则去执行。所以Agent能做得多好几乎完全取决于你为它定义的那套指令集。很多人一听“指令集”第一反应是CPU、RISC-V、x86那套觉得这是体系结构的事跟Agent有什么关系关系非常大。你把Agent看作一个“可编程的执行单元”那系统提示词、工具调用协议、编排策略、记忆读写规则、安全边界就共同构成了Agent的“指令集架构”。这套架构决定了Agent能听懂什么指令、能调用哪些能力、在什么条件下终止、出错了怎么恢复。某种意义上写好Agent的第一步不是写代码而是设计这套指令集。我在实际做Agent项目时见过太多“模型很强但Agent很蠢”的情况。模型API是市面上最强的工具也接了一堆最后跑起来却乱七八糟要么在无关请求上反复打转要么一次任务里疯狂调用同一个工具直到token耗尽最离谱的是有一次Agent在循环里把同一个查询发了四十多次直接把上游接口打到限流。排查到最后问题都指向同一个根因没有给Agent定义清晰、完整、分层的指令体系。模型没有错是给它发的指令不够清楚。这篇文章我就从“指令集”这个角度把Agent开发里最关键的一层拆开讲。会覆盖指令集的分层结构、工具协议怎么写、编排策略怎么选、记忆规则怎么定、安全边界怎么设还会把我踩过的坑和排查经验一并交底。无论你是刚开始接触Agent开发还是已经在做Agent框架集成这篇文章都值得花几分钟看完。2. 指令集的分层设计入口、执行、编排、记忆、守护我把Agent的指令集粗略分成五层。每一层负责一类事情层与层之间尽量解耦这样后面要加新工具、换新模型、调策略都不至于牵一发动全身。2.1 入口指令系统提示词里到底该写什么入口指令就是大家常说的System Prompt。很多人写系统提示词习惯性地写一大段“你是一个智能助手你需要帮助用户解决各种问题”然后没了。这在一次性聊天里问题不大但放到Agent场景里这种写法等于没写。Agent需要的是一个可执行的入口指令它至少要包含四个部分角色与环境设定。明确Agent是谁、运行在什么环境里、面向什么用户群体。目标与任务边界。告诉Agent它的核心职责是什么哪些事情默认不做。行为准则与工作流。规定Agent接到任务后第一步做什么、第二步做什么什么情况下求助、什么情况下停止。输出与交互约束。规定回复格式、语言风格、长度控制以及当用户输入模糊时应该如何澄清。实操中我的习惯是把系统提示词按“必须-应该-禁止”三层来组织。必须做的事用祈使句比如“接到计算任务必须先调用计算器工具”应该做的事用建议语气比如“当用户意图不明确时应该主动提问澄清”禁止做的事明确列出负面清单比如“禁止在没有确认的情况下执行任何删除操作”。这样模型在推理时有一个清晰的优先级框架可以遵循而不是面对一大段散文式的描述自己去猜重点。2.2 执行指令工具协议与API调用的关键设计执行指令是Agent指令集里最硬核的部分。只要Agent需要调用外部能力就必须有一份机器可读、模型可懂的工具协议。现在主流的做法是用JSON Schema来定义工具接口。每个工具声明自己的名称、描述、入参结构、必填项、返回格式模型根据这份Schema自己决定什么时候调用、传什么参数。设计工具协议时最容易犯的错误是把工程接口直接暴露给模型。我曾经接一个订单查询服务后端接口是getOrderDetails(userId, startTime, endTime, page, size, sortBy)。要是直接把五个字段丢给模型模型大概率会在参数上翻车尤其是sortBy这种业务枚举值模型根本猜不准该传asc还是desc。后来我改成了面向Agent的专用接口query_latest_order(user_id)把排序、分页全部在工具内部处理只暴露一个最简单的入参调用成功率立刻上来了。“给Agent的工具参数越少越好描述越长越好”——这句话我建议贴在所有Agent开发者的电脑边上。参数少意味着模型不太会传错描述长意味着模型能准确判断这个工具什么时候该用、什么时候不该用。工具返回的结果也一样能精简就精简返回一大坨嵌套JSON只会让模型在处理时晕头转向。2.3 编排指令让Agent学会“自己安排工作”编排指令决定Agent以什么样的“思考-行动”模式工作。目前业界主流的编排模式大概有三种ReAct循环、Plan-and-Execute、Reflection优化。ReAct让模型每一步都先思考再行动适合交互性强、步骤不固定的任务Plan-and-Execute先让模型列计划再逐步执行适合长链路、依赖关系明确的任务Reflection模式则是让模型先做一个答案再自己审一遍、改一遍适合质量敏感的输出型任务。我的建议是不要把编排策略写成自然语言塞进系统提示词而是尽量把策略“代码化”。比如ReAct循环可以在Agent框架里直接实现为一个while循环设定最大迭代步数每一步把思考痕迹和工具结果拼进上下文而不是指望模型在一个系统提示词里自己理解什么叫“逐步推理”。把策略放到代码逻辑里可控性、可观测性都会好很多。这也就是为什么现在很多Agent框架都在强调“编排层”而不是单纯靠一个Prompt打天下。2.4 记忆指令短期上下文与长期记忆的分工Agent的记忆问题本质上是“什么信息该留在当前上下文什么信息该写入持久化存储”。短期内模型的上下文窗口是有限的你不能让一次会话里塞入七天的历史消息那会把上下文窗口填满模型反而会“忘记”系统提示词里的关键指令。长期来看Agent需要把有价值的信息写入外部记忆系统需要时再检索回来。我的做法是给Agent定义两类记忆指令。短期记忆走上下文字段设置最大轮数比如只保留最近五轮对话外加一轮“历史摘要”摘要由Agent自己定期生成。长期记忆则走结构化存储每条记忆必须包含三个字段发生了什么、发生在什么时候、对未来的行为有什么影响。写入时机也由指令约定比如任务结束时、出现异常时、用户反馈重要偏好时。检索时按语义相似度和时间衰减做排序优先返回最相关的几条。2.5 守护指令Agent的安全边界与输出守门人安全这一层很多人做Agent的时候直接跳过了。我理解Demo阶段确实不需要但稍微往生产走一步这层就必须补上。守护指令分两块一块是给模型的内部指令比如明确告诉Agent“不能执行哪些操作、遇到敏感内容怎么处理、输出前要做什么校验”另一块是外部的守门逻辑比如输入过滤、输出过滤、操作确认、限流熔断。我习惯的做法是给Agent配置“先验证、再执行、后复核”的三道闸。验证阶段检查用户意图是否有歧义、参数是否合法执行阶段工具调用前再确认一次目标和预期结果高风险操作要求二次确认复核阶段工具返回结果后做一次关键字段校验确保没有明显异常再继续。虽然多绕了半圈但省下的排查时间远多于多花的这一步。3. 核心实操从零到一搭出一套Agent指令集讲完抽象分层这节直接上实操。我给出一套你可以直接照着改的指令集搭建流程从工具定义到系统提示词到记忆规则每一步都给出可复制的内容结构。3.1 第一步先列工具清单再写提示词很多人的顺序反了先写了一大段提示词再考虑接什么工具。我的建议是先做“工具盘点”。把你希望Agent具备的能力列成一个清单每个能力对应一个或多个工具。工具粒度宁细勿粗细的工具职责单一模型调用时决策负担小一个工具包里塞太多参数和逻辑模型很容易误用。工具清单出来后开始写工具的JSON Schema。下面是一个天气查询工具的定义示例我刻意让它足够简单{ type: function, function: { name: get_weather, description: 根据城市名查询当前天气和温度。仅在用户询问天气、温度、出行穿衣建议时调用。, parameters: { type: object, properties: { city: { type: string, description: 城市中文名例如北京、上海、广州 } }, required: [city] } } }注意description里写了“仅在用户询问天气、温度、出行穿衣建议时调用”。这句是给模型看的触发条件写得越明确模型越不会在无关场景里乱调用。参数只留一个city把其他所有东西都内置到工具逻辑里。工具返回的格式也尽量扁平{ city: 北京, weather: 晴, temperature: 24, humidity: 40, wind: 北风3级 }3.2 第二步系统提示词模板按“三段式”组织工具定义完开始写入口指令。下面这个模板是我在多项目里验证过的结构你可以按自己的业务替换方括号里的内容你是[Agent名称]运行在[运行环境]中服务对象是[目标用户群体]。 你的核心职责是[一句话描述核心职责]。超出此范围的需求礼貌说明无法处理。 工作流程 1. 接到用户请求后先判断意图是否明确。 2. 意图明确时选择最合适的工具执行。 3. 工具执行结果异常时自动重试一次仍失败则向用户说明。 4. 用户请求涉及多个步骤时先确认整体目标再逐步执行。 行为准则 - 必须调用工具前先向用户简要说明即将执行的操作。 - 必须当工具返回结果为空或异常时不能编造结果。 - 应该当用户意图模糊时主动提问澄清而不是猜。 - 禁止禁止在未获用户确认的情况下执行任何不可逆操作。 - 禁止禁止输出与工具返回结果不一致的数据。 输出要求 - 回复使用简体中文。 - 每条回复不超过200字。 - 涉及数据时用简洁的表格展示。这个模板最核心的地方是把“必须-应该-禁止”明确分开。我测试过如果把禁止项混在工作流程里写模型偶尔会“忘记”写成独立区块后触发概率明显下降。这里不需要追求提示词的文采指令集是工程文件不是文学创作。3.3 第三步把编排策略写进框架代码系统提示词负责给模型“定调子”真正的执行控制要落到代码里。我以一个最简单的ReAct循环为例说明如何把编排逻辑代码化max_steps 8 step 0 while step max_steps: response model.call(context, tools) if response.has_tool_call(): result execute_tool(response.tool_call) context.append(f工具结果: {result}) step 1 continue # 模型认为任务已完成输出最终回复 final_answer response.content break几个关键参数值得说明。max_steps设成8意味着Agent最多执行8轮工具调用。我实测下来正常任务通常3到5步就能完成8步已经留足了容错。如果达到上限还没结束就直接终止并向外层抛一个“任务未完成”的标记而不是让Agent无限循环下去。每一轮工具结果都要追加进上下文同时可以做一个简单的截断策略把过长的工具结果预先摘要避免上下文膨胀。Plan-and-Execute模式则略有不同需要先让模型生成一个任务清单再对清单逐项执行。代码上可以在第一轮调用时强制要求模型输出一个JSON格式的plan然后循环里按plan去执行、校验、标记完成。两种模式不需要同时用按任务类型选一种就好。3.4 第四步记忆规则的三条铁律记忆写入不能是“什么都记”。我给Agent定的记忆规则有三条每条都是踩过坑后总结的。第一条只在任务边界处落盘。一个任务结束、一个异常发生、一次用户偏好明确表达这三个时刻才能触发记忆写入。过程中间产生的临时信息一律不写避免记忆库变成垃圾场。第二条记忆格式必须结构化。每条记忆至少包含三要素事件描述、时间戳、对后续行为的影响。没有前两个字段的“纯感想式记忆”检索时基本用不上。第三条检索结果必须限量和限时。从长期记忆里检索出的上下文最多只能带走三条最相关的记录并且要附上时间信息。不然一次检索可能把背景故事全塞进来反而干扰Agent对当前目标的判断。3.5 第五步守门逻辑用最小代码实现安全兜底安全指令这一层如果真的完全依赖大模型自觉那是在赌运气。我更倾向于用少量代码做硬性兜底跟Agent模型层隔离。最基础的一组兜底逻辑包括入参校验。工具调用前校验所有必填参数非法参数直接拦截。操作白名单。高风险操作单独拉一个名单不在名单里的操作不允许静默执行。结果截断。工具返回的内容设置最大长度超过长度做摘要或截断防止上下文被撑爆。执行熔断。检测到连续N次相同工具调用时暂停执行并请求人工确认。这个兜底层不依赖任何模型逻辑简单、执行确定但它能挡住Agent出bug时的大部分破坏力。4. Agent执行失败排查实录“Agent execution terminated due to error”——这行报错估计每个Agent开发者都见过。它的出现往往不是因为代码崩了而是因为Agent在某个环节偏离了指令走到了一个无法恢复的状态。以下是我在处理这类报错时最常碰到的四种情况以及对应的排查方案。4.1 上下文被无效对话塞满症状Agent在任务中途突然“失忆”忘记用户最初要什么。排查时发现上下文里已经被工具返回、历史轮次塞得密密麻麻。原因很典型没有上下文清理策略所有中间结果都原样堆在上下文里模型的处理能力被无效信息稀释。解法给上下文设置预算。我一般会参考模型上下文窗口的长度比如8K的窗口系统提示词预留1K历史记忆预留1.5K工具结果上限预留2K剩下留给当前任务。使用递归摘要法压缩历史内容前一轮对话结束后让模型输出一个100字以内的摘要下一轮上来先加载摘要而不是加载原始历史。4.2 工具调用陷入死循环症状Agent反复调用同一个工具参数几乎不变结果也一样但它就是停不下来。通常有两个原因工具返回的结果没有进入模型可见的上下文模型根本不记得自己刚才查过了或者编排层没有步数上限模型永远有理由“再确认一次”。解法双重保险。第一在代码层强制设置最大迭代步数并且打印每一步的操作日志方便事后回溯。第二在提示词里加一句“如果已经获取过相同结果请勿重复调用该工具”。日志里我还会额外记录每一步的token消耗一旦发现某一步消耗异常偏高基本可以定位到上下文里混入了过长的历史数据。4.3 模型自作主张“编造”工具结果症状工具返回的明明是空模型在最终回复里却写了一个看起来很像样的数据。这是“幻觉”问题在Agent场景里的体现。模型发现工具结果不够用会自动补全一段可信的废话。解法在系统提示词里明确“禁止输出与工具返回结果不一致的数据”同时在外层增加结果校验。校验方法很简单Agent最终回复里涉及的关键数据必须能在工具返回结果里找到原文。如果对不上就拦截回复并要求重新生成。这一步能直接把幻觉率压下一个量级。4.4 多工具协作时指令冲突症状Agent手里有A和B两个工具单独调用A没问题单独调用B也没问题但让Agent先调A再调B时它对B的入参理解就开始飘。原因多半是A工具返回的字段名和B工具需要的入参名不一致模型在字段映射上猜错了。解法在工具协议里明确“来自其他工具的输出字段可能与本工具入参名称不同”并在A的输出JSON里做一次字段预对齐把B需要的字段在A工具内部就格式化好。工程上可以做一个简单的字段映射层让模型永远不需要自己“脑补”字段含义。5. 安全与边界Agent指令集里最容易被漏掉的一层Agent能不能安全地跑在生产环境靠的不只是模型厂商的安全对齐更核心的是开发者给了它什么样的边界。关于安全与边界我自己的实践可以拆成三层来看。第一层是操作边界的“最小授权”原则。Agent能调用的工具只开放任务所需的最小集合。一个内部检索类Agent就不应该挂着发邮件的工具权限一个数据分析Agent就不应该拥有生产库的写权限。很多安全事故追根溯源都是权限配置得比实际需要宽了一档。第三步守门逻辑里说到的白名单机制正是实现最小授权的具体手段。无关的操作拒绝执行有风险的操作需要确认这一条必须写进指令。第二层是可观测性。Agent的每一步决策、每一次工具调用、每一条输入输出都要有日志记录。“黑盒Agent”是生产事故的温床一定要保证每个动作都可以回溯。我自己的项目里每个Agent请求都有一个跟踪ID日志里按ID聚合所有步骤一旦出错直接按时间线回放。这个看起来和“安全”没直接关系但没有它任何安全问题的排查都会变成大海捞针。日志记录本身要严格遵循合规要求只记录任务本身的信息不做无关采集这也是安全的一部分。第三层是对输出的“守门”。Agent生成的内容在直接触达用户之前应该经过一道过滤和校验的关卡。我称它为“输出守门人”它会拦截明显与事实不符的数据、没经过确认的操作结果以及包含内部关键信息的调试内容。这层逻辑可以用关键词、正则、数据校验规则来实现也可以叠加一个轻量模型来做二次判断根据预算和场景灵活取舍。6. 一套可直接落地的Agent指令集模板与发布前检查清单理论讲了坑也排了最后放一套我在多个项目里沉淀下来的“开箱即用”模板。真要做Agent时把方括号里的内容替换成自己的业务值就能跑起来。6.1 指令集模板结构[系统提示词] 角色你是[Agent名称]负责[一句话职责]。 流程[接到任务 → 判断意图 → 调用工具 → 校验结果 → 输出回复]全部过程必须按此顺序执行。 调用规则 - 调用任何工具前先向用户说明操作目标。 - 工具结果异常时先自动重试一次再异常则停止并上报。 - 禁止连续两次调用相同参数的工具。 输出规则 - 所有回复必须基于工具返回结果。 - 禁止编造任何工具未提供的数据。 - 结果展示用列表或表格禁止输出无关解释。 [工具协议] 每个工具遵循统一Schema包含name、description、parameters、required。 工具描述里写清楚触发条件、何时不要使用、返回字段含义。 [编排配置] max_steps: 8 max_consecutive_same_call: 2 context_summary_interval: 5 tool_result_max_length: 2048 [记忆规则] - 任务结束、异常发生、用户明确表达偏好时这三个时机允许写入记忆。 - 记忆字段包含event、timestamp、impact、related_task_id。 - 检索时最多返回三条按relevance和recency加权排序。 [安全规则] - 高风险操作白名单默认关闭。 - 输出守门人数据一致性校验开启。 - 日志跟踪ID所有请求必须携带。这套模板并不是什么花哨的东西它的价值在于把所有关键参数集中在一起调试的时候一眼就能看到全貌。模板的价值是减少决策负担不是把一个不合适的结构强加到你的业务上替换和裁剪都很重要。6.2 发布前检查清单每次部署Agent前我习惯按这个清单过一遍每个工具的description是否说明了触发条件和禁止调用的场景是否存在不必要的高风险权限暴露上下文是否有清理和截断策略避免长时间运行后膨胀是否设置了最大执行步数和连续重复调用上限是否配置了可追溯日志请求ID是否串接所有环节高价值或不可逆操作是否有二次确认机制模型返回是否经过数据一致性校验长期记忆是否需要按时间覆盖过期数据是否会被自动清理清单看起来很简单但每一条背后都有一次实际故障在撑着。如果你照着逐条落地Agent的生产稳定性至少能提升一个台阶。最后再说两句经验做了这么多Agent项目我最大的体会是Agent开发更像是在带一个“能力很强但经验不足的新同事”。它的潜力取决于模型但它的表现取决于你给的指令集。指令集写得粗糙再强的模型也会表现得像个毛手毛脚的新人指令集写得清晰、分层、可执行Agent才能真正成为能独当一面的好帮手。从工具协议到编排策略从记忆规则到安全边界每一层都需要你去认真设计、持续打磨。别怕一开始写得不够好我就没见过哪个Agent指令集是第一次就写完美的所有可靠稳定的Agent都是在一轮轮踩坑、复盘、调整指令中长出来的。