Agent服务描述优化：3.2万条样本总结的六要素写法-北京尧图网络

做 Agent 开发的人很多都有过这种经历模型选的是当下最强的框架用的是社区最火的工具接了一大堆结果一跑起来Agent 不是东答西问就是明明连着十个工具却只用一个。这时候大多数人的第一反应是换模型、调温度、重写 Prompt折腾一圈没用最后才发现问题出在那些根本没人愿意多看一眼的服务描述上。服务描述通俗点说就是你给 Agent 看的能力说明书这个工具是干什么的、什么场景该用、参数怎么填、结果返回什么。模型不读你的代码也看不到你的接口文档它只能靠这段文字来判断这个请求该不该调用这个服务、参数怎么传。描述写得好Agent 就是个靠谱的执行者写得不好它就是个对着工具瞎转悠的实习生实在不行就自己编个答案糊弄你。我把公开能接触到的 Agent 项目、工具市场、开源仓库里的服务描述翻了个底朝天累计整理了 3.2 万条有效样本。这篇文章就是这次调研的完整复盘3.2 万条描述里到底有哪些通病真正能用的描述长什么样以及一套可以直接照抄的六要素框架。如果你是做 Agent 应用开发、要给工具写接入说明或者正在被模型就是不调用我的服务逼到怀疑人生这篇应该能帮你少走好几个星期的弯路。1. 先搞明白服务描述在 Agent 里到底是干嘛的1.1 Agent 不是靠代码读懂工具而是靠描述举一个我调试过的真实案例。有个项目接了一个天气接口代码链路完全正常工具也成功注册到了 Agent 引擎里。但用户问昆明明天适合穿什么Agent 就是不调天气服务反而一本正经地编了一句昆明明天多云建议穿长袖外套。如果把这类日志翻出来看你会看到一个扎心的事实模型不是不会调而是根本不知道用户问穿衣建议时该用天气工具。原因很简单那个工具的服务描述只有五个字获取天气信息。模型拿到用户问题之后要在几十个工具描述里做匹配获取天气信息和用户想了解穿什么衣服之间存在着巨大的语义鸿沟。模型拿不准这个工具能不能回答穿什么的问题于是选择了最保守的策略——自己编一段看起来合理的回答。原理其实很好理解。Agent 和传统程序不一样它没有所谓导过来的接口文档模型感知外部能力的唯一通道就是服务描述。代码里那些精心实现的参数校验、异常处理、数据覆盖范围模型一概不知。服务描述就是模型和外部世界之间的独木桥桥窄了什么东西都过不去。打个生活化的比方。你给新来的实习生分配工作如果只丢一句你负责处理用户问题他大概率会愣住处理什么问题、用什么系统、边界在哪、卡住了找谁而如果你写清楚岗位职责、处理流程、权限边界、例外情况他第二天就能直接进入状态。模型其实比实习生更需要这份岗位说明书因为它连主动追问都不敢——描述里没写的它就默认不存在然后开始自由发挥。1.2 描述质量直接影响 Agent 的整体表现再往深一层说服务描述不是锦上添花而是直接决定 Agent 成败的基础设施。我见过很多项目前期调试时模型死活不调工具开发者怀疑是模型不行把温度从 0.2 调到 0换了更新的模型重写了主提示词问题依然在。最后回头把服务描述逐字逐句重写一遍场景立刻通了。这不是玄学而是 Agent 的执行链路决定的。通常一次任务要经过这样的路径模型读用户请求扫描全部服务描述判断哪个服务匹配根据描述里的参数说明生成调用参数工具执行并返回结果模型再把结果整理成回答。纵观整条链路服务描述在第一、二、三步都有参与。工具本身再快再稳前面这几步走错了后面全是白搭。如果给 Agent 的行为做量化统计服务描述质量差通常会暴露成三类指标异常一是工具调用率偏低模型宁可自由发挥也不用现有能力二是参数错误率高虽然调了工具但传进去的日期格式、城市名、单位总是有偏差三是任务完成率波动大同一类问题时好时坏。这轮调研里我反复看到这三类问题的影子几乎每一个都能回溯到描述本身的缺陷上。1.3 服务描述不止工具描述一种形态这里需要先做个概念清点。服务描述并不只在工具这一层出现Agent 生态里至少存在四种常见形态工具型服务描述描述一个 API、函数或 Skill 的用途和参数最常见也是后面六要素框架的主要应用对象。子 Agent 描述多 Agent 架构里每个子 Agent 也有一份身份说明主 Agent 靠它判断这个子任务该交给谁。插件描述类似工具型但往往包含更完整的触发条件、执行流程、权限声明不少插件还要说明自己会读取哪些文件、访问哪些网页。系统级 Agent 描述定义整个 Agent 的定位、边界和回答风格市面上多数平台里叫人设或系统提示词。这四种形态的载体和颗粒度不同但底层逻辑完全一致用一段模型能高效解析的自然语言把能力边界和使用方式说清楚。后面要讲的写作框架对这四种形态都适用只是不同形态侧重点略有差异这一部分我会在第三章节单独展开。2. 翻了 3.2 万条之后最常见的五种通病2.1 先把研究样本和方法说清楚在讲结论之前先交代一下这 3.2 万条是怎么来的。样本主要来自四个渠道公开的 Agent 项目仓库重点看工具配置、Skill 定义、能力清单国内外主流 Agent 平台和工具市场看开发者在发布工具时填写的说明文本几个主流框架自带的示例和官方模板以及社区里流传的提示词库、工具合集中的描述片段。去重、筛掉明显无效的空文本之后累计保留了 3.2 万条有效描述。分析方法不复杂。先把样本通读一遍建立整体感觉再按质量粗分三档明显不合格、中规中矩、值得借鉴。之后对明显不合格和中规中矩的样本做模式归纳最后把值得借鉴的样本逐条拆解提取它们的共性。这里先放一个最直接的结论真正能达到看到一个描述就知道怎么调、什么时候调、调完怎么用这一标准的样本占比非常低。大量描述连最基本的功能边界都没讲清楚。2.2 通病一只有名字没有上下文最常见的低质量描述就是一句话版。比如获取天气发送邮件查询订单。这类描述说起来言简意赅但对模型来讲信息量几乎为零。我拿一个只有获取天气信息五个字的工具做过一次对照实验。用户问昆明明天适合穿短袖吗模型完全不调用工具直接凭训练数据里的常识编了一段天气还煞有介事地给出了穿衣建议。整个回复流畅、自信但没有任何真实数据支撑。这就是典型的有工具不会用——描述里没有给模型任何这件事该用我的提示模型宁可自己编答案也不敢把一个它理解不了的请求托付给工具。这类问题很有迷惑性因为代码里getWeather这个函数名本身是自解释的开发者看代码觉得没问题但模型看到的不是函数名而是你在工具配置里写的那段描述。函数名再清晰描述里没写出来模型也感知不到。2.3 通病二参数说明随意模型瞎填只写功能、不写参数是第二类高频毛病。比如描述里写输入城市但没说清楚要的是城市中文名、城市代码还是拼音更别提格式、单位、取值范围和必填项。日期参数是最容易翻车的重灾区。用户说帮我定下周三早上 8 点的闹钟如果描述里没有写明日期请按 YYYY-MM-DD 格式输出并基于今天日期自动换算模型很可能把下周三这三个字原封不动地当成参数传进去工具拿到之后自然是解析失败。还有一类是单位问题有的接口温度单位是摄氏度有的在内部换算成华氏度描述里不写模型传出来的值可能直接差出几十度。模型对参数的生成完全依赖描述里的约束约束越清晰参数就越准确。2.4 通病三只写做什么不写什么时候不该做很多开发者以为服务描述就是把做什么写清楚就够了但模型的匹配机制决定了你还得把不做什么一起写明白。举个例子。某个天气工具只支持国内城市描述里没写这个限制。用户问东京明天天气如何模型检索能力清单时发现这个工具名字里带天气两个字触发了匹配于是一通调用结果返回查询失败。这就是典型缺乏边界条件的后果。模型不会自动知道你的数据覆盖范围、权限边界、支持的语言种类、时间粒度你不主动声明它就会默认什么都能干。更微妙的是多工具场景。假设系统里同时有天气查询和空气质量查询两个工具前者描述里没写本服务不含空气污染数据用户问今天空气好不好模型可能随机选一个甚至两个都调返回结果又互相矛盾。边界声明就是在帮模型做排除法排除得干净模型才能选得果断。2.5 通病四不给示例全靠模型猜文本描述写得再完整终归是抽象规则而模型对具体示例的模仿能力远强于对抽象规则的解析能力。这个特性在服务描述里可以发挥到极致写一个用户问题 → 调用参数 → 返回结果的完整示例模型遇到类似场景时会直接模仿示例来生成调用。我改过一个订单查询工具。原始描述只有一句话查询用户订单加上一条示例之后模型调用参数的正确率肉眼可见地高了。那条示例是这样写的当用户说我上个月买的东西发货了吗时应传 userId 等于用户 ID、orderTimeRange 设为最近 30 天、status 置空返回结果里优先提取物流状态字段。模型看完示例基本能依葫芦画瓢遇到我买的东西到哪了它知道要查物流状态遇到我买过哪些东西它知道要罗列订单列表。示例把抽象规则翻译成了可模仿的行为模式而这正是模型最擅长做的事情。2.6 通病五描述写成散文有效信息被稀释与太短相对的另一个极端是太长太散。有些开发者生怕模型理解不了把服务描述写成了一篇小作文前面还铺一层营销话术本工具采用先进技术功能强大、性能卓越、智能高效是你最值得信赖的选择。这类文字对模型来说就是信息噪声。模型处理文本时注意力资源是有限的一长串形容词和宣传语会稀释真正重要的指令信息。我在 3.2 万条样本里见过不少这样的散文式描述读的时候感觉业务方很用心洋洋洒洒写了一大段但套到实际任务里模型反而抓不住重点该触发的没触发该传对的参数传错。3. 高质量服务描述怎么写六要素框架直接套3.1 六要素总览一段描述该包含什么先亮框架。在拆解了大量优质样本之后我把服务描述的核心信息归纳成六个要素这六个要素基本能回答模型做决策时的所有疑问要素要解决的问题写作要点一句话职责声明模型快速判断这个服务是不是干这个的动词开头写明对象与动作触发条件模型决定现在该不该用它写明适合场景也要写排除场景输入参数说明模型生成调用参数不乱填写清类型、格式、单位、必填项输出格式说明模型解析返回结果不困惑写清结构、字段含义、示例值边界与禁忌模型不会把不合适的任务硬塞进来写明能力范围、数据限制、权限前提典型示例模型有可模仿的完整流程给一段用户问法加对应调用参数要特别说明的是六要素并不需要每一条都在所有场景下大篇幅展开。工具很简单时触发条件和边界可以直接合并成一句话服务逻辑复杂时示例可以写两到三个覆盖不同分支。但职责、参数、边界、示例这四个关键要素任何情况下都不建议省省掉哪一个模型都会在对应环节多一次猜错的机会。3.2 可以直接抄的通用模板下面这个模板可以直接复制去改结构上是六要素的展开版服务名称... 一句话职责这个服务负责... 触发场景 - 适合用户询问...或表达...意图时 - 不适合用户询问...或数据范围超出...时输入参数 - param1类型必填说明。示例... - param2类型选填说明。示例... 输出格式 - 返回结构{字段含义} - 失败时返回{error原因} - 回答用户问题时优先使用...字段边界与禁忌 - 仅支持... - 不支持... - 查不到结果时请明确回复无法查询不要编造数据典型示例用户... 调用参数... 返回结果...模板里一句话职责我建议用动词短语开头比如查询并返回指定城市的实时天气而不是天气工具。原因是模型做能力匹配时动词短语更接近自然指令语义命中率更高。参数部分要区分必填和选填还要写明什么情况下可以省略输出格式不能只列字段名最好说明模型在组织最终回答时应该优先使用哪个字段这能直接提升回答质量。3.3 触发条件和边界词怎么写才有用触发条件是最容易被低估的要素。很多开发者只会写正向触发用户询问天气时调用但模型在实际匹配中更需要反向排除。以天气和空气质量工具混用的例子来说如果天气工具描述里的触发条件写成用户询问天气、气温、降水、穿衣建议时触发本服务不包含空气质量与污染指数信息该类问题请不要调用模型的选择就会清晰很多。写触发条件时用词越具体越好。与其写与天气相关的问题不如枚举几种典型问法用户问明天出门要不要带伞用户问某地温度冷不冷用户问周末适不适合露营让模型的匹配有据可依。边界部分则要说得绝对一些模型是概率推理系统你不写不要编造它在查询失败之后真的会编一个看起来合理的答案。3.4 不同 Agent 形态的侧重点差异六要素是通用框架但不同形态的描述核心侧重点要跟着变。工具型服务描述要重点打磨参数与输出格式因为工具对接的是真实 API字段错一个就可能整个报错子 Agent 描述则要把重心放在职责边界和协作说明上写清楚我擅长什么、不擅长什么、什么情况应该把任务转交给其他子 Agent否则多 Agent 编排时容易出现职责重叠和互相推诿。插件和 Skill 描述与工具型类似但额外要说明执行步骤和权限范围。尤其像读取本地文件、访问外部网页这类带副作用的操作务必要写明需要用户授权后才可执行这也是一道安全边界。系统级 Agent 描述则重在整体风格与通用边界服务级别的细节交给各层级描述去展开不必全部堆在最顶层否则主题太长反而稀释核心人设。4. 实战复盘把一条天气服务描述从 17 个字改到 200 字4.1 原始版本为什么不行为了把六要素框架落到实地我用一个常见的例子完整复盘一遍。假设你有一个查询实时天气的工具原始描述是这样的获取天气信息。输入城市。返回天气。这条描述刚好踩中了前面提到的至少三类通病。第一没有触发条件模型不知道穿衣建议这类问题也归它管第二参数只说城市没写类型和格式模型不知道传中文名还是拼音更不知道用户提到地标时需要先换算第三输出只写了天气两个字模型既不知道返回结构也不知道该怎么把结果转述给用户。没有边界模型默认它能查全世界没有示例参数怎么写全靠猜。用这条描述上线的结果是模型偶尔能调对但只限于用户问法非常直白的情况比如北京天气怎么样这种描述里直接出现过词的问法。一旦问题绕个弯比如明天去上海需要带伞吗模型就容易犹豫甚至干脆放弃调用工具直接编答案因为带伞这个意图和获取天气信息之间的语义关联太弱了描述里没有任何提示告诉模型可以用降水概率来回答带伞问题。4.2 四轮迭代逐层加东西第一轮先补上职责声明和触发条件服务名称实时天气查询职责根据用户提供的城市和日期返回该城市的实时天气与近期预报。触发条件用户询问天气、气温、降水、风力、穿衣建议等相关问题时使用。这一轮改完模型至少不会被穿衣这类问题绕晕。但参数说明还是模糊继续第二轮。第二轮把参数说清楚输入参数 - city字符串必填城市中文名如北京。若用户只说了地标、景区或区域名请先换算为所属城市如上海迪士尼→上海。 - date字符串选填日期格式 YYYY-MM-DD。缺省表示今天。 - unit字符串选填温度单位celsius 或 fahrenheit缺省 celsius。这一轮的亮点是给了一个换算规则。模型遇到明天去上海迪士尼穿什么这种问题就能把地标换算成上海再触发天气查询而不是卡在这是哪个城市上。第三轮补输出说明和边界条件输出格式 - 返回 JSON主要包含 current当前天气、forecast逐日预报、tips穿衣建议字段。 - 回答用户时优先使用 tips 字段组织成自然语句。边界与禁忌 - 仅支持中国大陆城市不支持港澳台及海外城市。 - 不包含空气质量/污染指数信息此类问题请不要调用本服务。 - 查询失败或城市不支持时请明确回复无法查询不要编造数据。到了这一轮描述已经覆盖了绝大多数真实情况。第四轮加上典型示例收尾典型示例用户北京明天需要穿羽绒服吗调用city北京, date2025-01-10, unitcelsius 返回{current: {...}, forecast: [...], tips: 北京明天最低气温零下6℃建议穿羽绒服、毛衣和厚裤子。}一个完整链路示例放进去模型对穿衣相关提问的调用行为马上就稳了。因为它能看到用户怎么问、参数怎么填、返回结果怎么用这三者之间的对应关系。4.3 改完之后的效果对比这条描述从最初的 17 个字符改到 200 字左右全程没有换模型、没有改框架、没有调任何推理参数只动了服务描述本身。在我自己搭的一组测试问题集上效果变化非常直观。首先是工具调用率明显上升原先部分擦边问题模型会直接编答案改完之后绝大多数问题都会先尝试调用工具其次是参数正确率大幅提升最突出的是日期格式和地标换算基本不再出错最后是回答可控性变好有了输出字段的指示模型不再自由发挥而是按 tips 字段里的信息组织语言。说实话描述不是魔法它不能让一个本身就残缺的工具变得无所不能但它能把工具已经实现的能力真正暴露给模型。你每多写一个要素都是在帮模型降低一次猜错的概率。很多团队花大精力选模型、调框架却连这种几乎零成本的优化都不做属实可惜。5. 高频问题排查与调试实录5.1 模型不调用服务先查这四件事遇到模型就是不调用我的服务别急着怀疑模型按顺序排查四件事。第一服务描述里有没有明确的触发场景。如果描述只有获取信息这种没头没尾的话模型压根没有触发依据。改法很直接把用户可能会说的三四句典型问法直接写进描述里让模型看到匹配点。第二描述里的用词是否贴近用户的自然表达。模型做能力匹配时依赖描述文本与用户问题之间的语义相似度你写的是获取气象数据用户说的是明天穿什么这中间的语义距离就需要靠描述里的触发条件去拉近。第三Agent 引擎本身的配置是否正确。有些框架要求注册时的 name 字段与代码中的函数名保持一致还有的要显式声明启用状态配置错位的话描述写得再好也白搭这时候要翻运行时日志确认工具确实被加载了。第四是否存在描述过于相似的其他服务。两个服务描述高度雷同模型会因分不清而随机挑一个导致另一个始终不被调用把各自的边界写明确就能解决。5.2 模型总传错参数可能是描述挖的坑参数传错先别急着怪模型回头看看描述里有没有埋坑。最常见的几类坑包括没写类型模型把布尔值传成了字符串没写格式日期传成明天而不是 YYYY-MM-DD没写单位温度值直接按华氏度传没写取值范围数字参数传了负数。请在描述里为每个参数写清五样东西类型、必填还是选填、格式、示例值、约束条件。还有一类更隐蔽的问题参数与参数之间存在依赖关系。比如当 startTime 为空时endTime 也必须为空这种约束模型很难自己推出来建议直接写成明确指令若 startTime 为空则忽略 endTime。模型对自然语言指令的遵循能力比你想象中强很多前提是你真的把它写出来。5.3 多个服务互相抢调用怎么划清边界多个服务并存时最怕的是边界不清。我的经验是先给每个服务安排一个专属场景确保至少有一种用户问法会让模型稳定选到它然后再用排除法处理重叠区。举个例子系统里同时有天气查询和穿衣建议两个服务前者提供原始气象数据后者基于气象数据生成穿搭建议。如果不加边界模型面对明天北京穿什么这个问题可能两个都调给用户返回两段冗余信息。更好的做法是让天气查询描述里写明穿衣建议请交给穿衣建议服务本服务只提供原始气象数据同时让穿衣建议服务描述写明本服务依赖天气查询获取温度和降水数据若用户未提供城市信息请先向用户确认。边界一旦写明白模型就不会在服务之间左右横跳。5.4 一个反向问题服务被过度调用有些服务不是没人调而是什么都被往它身上塞。我在调研里也见过不少这类案例根源往往是触发条件写得太宽泛比如天气相关问题时调用结果用户问明天空气质量怎么样模型也把空气质量问题甩给了天气服务。解决思路是给描述加一个不适用场景清单而且这种清单应该越具体越好。数据类服务尤其适合这样做比如气象工具可以明确写不包含空气污染、紫外线指数、日出日落数据。对于执行成本较高的操作还要写明触发门槛比如只有在用户明确要求执行时才能调用禁止仅凭猜测触发。这个写法不仅是功能需要也是一种安全约束能防止 Agent 在不合适的时机做出有副作用的动作。6. 两个让我省下大量返工的习惯6.1 给服务描述建一个专属测试集描述写得好不好不能靠感觉一定要有可回归的验证手段。我强烈建议每个 Agent 项目维护一份测试集20 到 30 条覆盖典型用户提问的小样本每条标注期望行为包括期望调用哪个服务、期望参数是什么、期望回答用什么字段。每次改完描述就把这套测试集完整跑一遍记录调用是否命中、参数是否准确、回答是否符合预期。它的价值和代码单元测试一样大因为服务描述之间会互相影响你改了 A 服务的描述可能意外让 B 服务的匹配率下降没有测试集你根本发现不了。我用 JSON 文件维护测试集按场景分组管理每隔两周补几条新出现的边界提问随着 Agent 能力增加这套测试集会慢慢变成一个覆盖核心场景的验收清单。6.2 服务描述要像代码一样进版本管理服务描述是运行时要被模型读取的代码级产物必须放进版本管理不能只躺在平台后台里。它要跟代码一起提交、一起评审、一起回滚。比较推荐的做法是为每个服务维护一份 Markdown 或 YAML 格式的描述文件放在 services 目录下由主程序加载。这样描述既能被运行时读取也能被人读、被评审、被 diff。每次改动都留下 commit 记录等 Agent 行为突然异常时可以直接对照描述变更记录定位原因。我在实际项目中遇到过前一天还好好的第二天突然不调工具的情况最后排查发现不是模型变了而是有人手滑把描述里的触发条件改窄了。如果当时没有版本记录这类问题查起来基本只能靠肉眼翻后台效率和体验都非常差。6.3 最后说一个关于写作心态的建议从这 3.2 万条样本里我总结出一个比较实用的心态不要试图一次把描述写到完美。服务描述和代码一样需要小步迭代、测试驱动、持续重构。第一次能覆盖八成常见场景就已经超过大多数项目了剩下的问题会在真实使用里逐渐暴露只要你留了测试集和版本记录修补成本就会非常低。我自己的习惯是每接入一个新工具先写一版只覆盖核心场景的粗略描述然后边测边改迭代个三五轮之后才会稳定下来。比起闷头写一上午完美描述这种先跑起来再打磨的方式效率高得多也更能真实地反映出模型到底能理解到哪一层。写描述这事没什么高深诀窍无非是不断把模型猜不到的信息提前写进去让它的每一步选择都有据可依。

Agent服务描述优化：3.2万条样本总结的六要素写法

相关推荐

河道垃圾识别：无人机图像识别的工程化落地实践

大模型decode阶段硬件部署：显存带宽、KV Cache与批处理调优实战

FFT替换自注意力：SPECTRE如何将长序列建模复杂度降至N log N

更多资讯

从单Agent到多Agent：DeepSeek Harness编排实战解析

Altium Designer 22画板全流程：从原理图到PCB新手避坑指南

老芯片新用：XL1509降压芯片原理与维修实战

放电齿设计指南：低成本ESD防护与PCB布线实战

批量PDF/OCR归档系统建设指南：核心需求与工程实践

华为H12-831题库实战指南：eNSP+VRPv8.181深度排错与考点拆解

今日更新

Multisim仿真NE555 PWM控制器：从搭电路到调占空比全流程

S32K312 AUTOSAR BSW开发实战：从配置踩坑到烧录交付

双目视觉三维人脸重建：从视差图到点云粗配准全流程解析

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？