Agent 工具设计 · 动作空间熵 · 超时治理 · 工程落地路径
摘要
一个 Skill 同时承担查询、修改、删除、发通知四类动作，Agent 在单次任务里反复试探、回退、重试，最终撞上超时阈值——这不是模型“变笨”，而是工具契约本身把搜索空间撑爆了。本文以“动作空间熵”为贯穿主线，把单一职责从软件工程口号还原为可计算的边界判据：以工具描述的可分辨度、参数耦合度、副作用等级、失败恢复代价四个维度构造评分，给出阈值化拆分流程；再结合 ReAct、Toolformer、Reflexion、MCP 等公开研究，讨论超时的真实成因（循环、上下文膨胀、工具歧义）与治理手段；最后给出目录契约、幂等设计、超时预算分配的可操作步骤与前沿预判。文中数据均标注来源，模拟数据单独说明。
目录
一、导语：一次超时背后的工具契约问题
先把现场还原清楚。某业务 Agent 挂载了一个名为 crm_manage 的 Skill，描述大意是“管理客户记录，支持查询、更新、删除并发送通知”。用户说一句“把上周那批逾期客户标记为已跟进，并通知对应销售”，Agent 的规划器先调用查询分支拿到候选集，接着在“更新”与“通知”之间反复切换：更新分支要求传完整记录，通知分支要求传模板 ID，两个分支的参数名在描述里没有清晰区分，模型于是不断猜测、校验、回退。十几轮之后，单次任务累计耗时越过平台设定的 120 秒上限，任务被判超时。
这个现象在工程上并不罕见。Anthropic 在 2024 年 12 月发布的《Building effective agents》中明确指出，工具接口的清晰度与文档质量，往往比模型能力更直接地决定 Agent 的成功率，并建议把工具设计当作“给新同事写文档”来对待（Anthropic, 2024）。OpenAI 在 Function Calling 文档中也反复强调参数 schema 与描述必须无歧义，否则模型会倾向于“试错式调用”。本文评述：这些工程建议方向正确，但停留在经验层面，缺少一个可量化、可复核的判据——到底“多清晰”才算清晰，“拆到多细”才算细？这正是本文要补上的部分。
笔者认为，把问题归因为“模型不够强”是最省事也最危险的解释。模型能力确实在提升，但工具契约的复杂度如果随职责数量线性甚至超线性增长，那么再强的模型也会被拖入组合爆炸。真正需要回答的是：一个 Skill 承载几类动作时，Agent 的决策负担会越过可用阈值？这个阈值能否被工程化地测量与约束？本文的主线就是围绕“动作空间熵”这一构造性指标展开。
二、背景与问题定义：Agent 工具调用的失败模式谱系
2.1 从 ReAct 到工具调用：一条清晰的演化线
Agent 的工具调用范式可以追溯到 Yao 等人 2022 年提出的 ReAct（Yao et al., 2022），其核心是把“推理轨迹”与“动作执行”交错进行，让模型在思考—行动—观察的循环中逐步逼近目标。随后 Schick 等人 2023 年的 Toolformer（Schick et al., 2023）展示了模型可以自学何时调用 API；2023 年的 Reflexion（Shinn et al., 2023）引入语言化反馈用于自我修正；2024 年之后，Model Context Protocol（MCP）等标准化协议把工具发现、调用、结果回传抽象成统一接口（Anthropic, 2024）。本文评述：这条演化线的主旋律是“让模型更自由地使用工具”，但自由度的另一面就是搜索空间的膨胀，而多数工程实践并未同步建立约束机制。
需要先给出准确定义。本文所称“Skill”，指以自然语言描述加 JSON Schema 参数暴露给模型的一组可调用能力，等价于一次工具注册单元；“单一职责”在此语境下不是指代码层面的函数粒度，而是指该 Skill 在语义上是否只对应一类意图、一类副作用、一类失败恢复策略。这个定义是后文所有判据的起点。
2.2 失败模式谱系：循环、歧义、膨胀、雪崩
把工程中观察到的失败归类，大致有四类。第一类是决策循环：模型在两个语义相近的分支间来回选择，缺乏终止信号。第二类是参数歧义：同一 Skill 内不同动作复用相似参数名，模型传错字段后触发校验失败再重试。第三类是上下文膨胀：每次调用返回的完整记录被塞回上下文，轮次越多 token 越涨，推理变慢直至超时。第四类是副作用雪崩：删除与通知混在同一 Skill 中，一次误调用可能同时触发不可逆删除与对外通知，恢复代价极高。
这四类失败并非独立。循环会加剧膨胀，膨胀会延长单轮推理时间，最终把总耗时推过阈值；而副作用雪崩则让“重试”这一常规恢复手段失效，因为删除不可回滚。笔者认为，治理顺序应当是先切断副作用耦合，再压缩歧义，最后处理循环与膨胀——因为前两者是结构性问题，后两者是结构问题在运行时的表现。
提示：如果你正在排查线上 Agent 超时，先别急着调大 timeout。把最近 50 次失败任务的工具调用序列导出，统计“同一 Skill 被连续调用超过 3 次”的比例，这个比例往往比总耗时更能定位问题。可参考 LangChain 官方关于 agent 调试与 tracing 的教程：LangChain Debugging 文档。
2.3 为什么“塞在一起”在初期看起来更划算
从工程成本看，单体 Skill 在初期确实有优势：注册一次、文档一处、权限一把梭，模型看到的工具列表更短，表面上的选择负担更小。这也是很多团队在原型阶段把 CRUD 加通知打包成一个 Skill 的真实动机。问题在于，这种“列表短”换来的是“分支深”——模型不需要在多个工具间选，但需要在同一工具内部的不同语义分支间选，而后者恰恰缺乏显式的选择信号。
本文评述：工具列表长度与决策难度不是单调关系。当工具数量少但每个工具内部语义混杂时，决策难度可能高于工具数量多但每个工具语义单一的情形。这一判断与 OpenAI 在函数调用最佳实践中的建议方向一致，但后者未给出量化边界，本文第三节将尝试补足。
三、原理主线：动作空间熵与四维边界判据
3.1 动作空间熵：一个构造性指标
笔者提出“动作空间熵”作为贯穿全文的分析主线。其构造思路是：把模型在单次任务中对某 Skill 的决策视为在若干语义分支上的概率分布，分支越难区分、参数越交叉，分布越接近均匀，熵越高，模型越容易陷入试探。形式化地，对 Skill S 的 n 个语义分支，设模型依据描述能正确区分分支 i 的概率为 pi，则动作空间熵 H = −Σ pi log pi，归一化后 Hnorm = H / log n。当各分支描述高度相似时 pi 趋近 1/n，Hnorm 趋近 1，决策负担最大。
必须说明，pi 无法直接观测，工程上可用“分支描述两两语义相似度的补”作为代理估计，例如用句向量余弦相似度计算描述间的接近程度，再取 1 减相似度作为可分辨度。这是模拟估计方法，不是精确测量，本文在第五节会给出基于公开数据集的近似计算示例并标注为模拟数据。本文评述：该指标的价值不在于数值绝对精确，而在于提供一个可比较、可复核的相对尺度，让“该不该拆”从拍脑袋变成可讨论。
3.2 四维边界判据
仅有熵还不够，因为熵只刻画“难区分”，不刻画“拆错的代价”。笔者补充三个维度，构成四维判据：
| 维度 | 含义 | 高值信号 |
|---|---|---|
| 可分辨度 | 分支描述与参数名的区分程度 | 描述高度相似、参数名复用 |
| 参数耦合度 | 不同分支共享参数的比例 | 共享字段多、必填项交叉 |
| 副作用等级 | 动作是否可逆、是否对外可见 | 删除、通知、支付等不可逆或外发 |
| 失败恢复代价 | 出错后回滚或补偿的成本 | 需人工介入、跨系统补偿 |
判据的使用方式是打分而非二元判断：每个维度按 1–5 分评估，四项相加得到拆分优先级分数。笔者建议的经验阈值是：总分 ≥ 14 时应当拆分，9–13 时优先做描述与参数治理而非物理拆分，≤ 8 时可维持单体。需要强调，这是工程经验阈值，不是经过大规模对照实验验证的结论，读者应结合自身数据校准。本文评述：把“单一职责”从口号变成打分表，最大的好处是让团队在评审时有共同语言，而不是各自凭直觉争论。
3.3 与经典内聚/耦合概念的关系
软件工程中的高内聚低耦合（Yourdon & Constantine, 1979）与单一职责原则（Martin, 2002）是本文判据的思想来源。但经典概念面向的是人类维护者，其“职责”以变更原因为单位；而 Agent 工具面向的是概率性决策者，其“职责”应以可分辨的意图为单位。两者并不等价：一个对人类而言内聚的模块，对模型可能是高熵的，因为模型依赖的是描述文本而非代码结构。本文评述：这是本文与经典文献最关键的差异点，也是为什么不能直接把 SOLID 原则照搬到工具设计上的原因。
四、技术路线：从单体 Skill 到职责原子的拆分步骤
4.1 第一步：意图聚类，把分支还原为意图
拆分的起点不是看代码，而是看用户会怎么说。收集近三个月的真实请求样本，按“用户想达成什么”而非“系统执行了什么”聚类。以 crm_manage 为例，样本会自然聚成四簇：检索客户、变更客户状态、移除客户、触达销售。四簇对应四类意图，这是拆分的语义基础。操作上可用句向量聚类加人工复核，样本量建议不少于 300 条以覆盖长尾。
这一步的关键是避免“按代码函数聚类”的惯性。代码里的 update 函数可能同时服务“改状态”和“改归属”，但对用户而言这是两个意图，应当拆开。本文评述：意图聚类是整条路线里最容易被跳过、也最影响成败的一步，因为后续所有契约设计都以意图为单位。
4.2 第二步：按副作用等级切分，先隔离不可逆动作
四类意图中，删除与通知属于高副作用，检索属于只读，变更状态介于两者之间。拆分顺序应优先隔离高副作用：把删除独立为 crm_delete_customer，把通知独立为 notify_sales，两者都要求显式确认参数（如 confirm_token），并在描述中标注不可逆。这样做的直接收益是：即使模型误判，也只会在只读或可逆分支上出错，恢复代价可控。
这一思路与业界关于“人在回路”的讨论一致。OpenAI 在 2024 年的 o1 系统卡与安全实践中强调高风险动作应引入确认环节（OpenAI, 2024）。本文评述：确认环节不应只靠提示词，而应写进工具契约——把确认做成必填参数，比在系统提示里写“删除前请确认”可靠得多。
4.3 第三步：参数去重与命名契约
拆分后要处理参数复用问题。原 Skill 中 customer_id、record、template_id 混在一起，拆分后每个工具只保留自身必需字段，并在描述中给出字段来源。建议采用统一命名前缀，例如所有客户相关工具使用 customer_id，所有通知相关工具使用 notify_template_id，避免模型跨工具误传。参数描述要写清类型、取值范围与示例值，示例值应可直接复制使用。
{
"name": "crm_update_customer_status",
"description": "仅用于变更单个客户的状态字段，不发送任何通知，不删除记录。",
"parameters": {
"type": "object",
"properties": {
"customer_id": { "type": "string", "description": "客户唯一 ID，形如 C-2024-0001" },
"status": { "type": "string", "enum": ["active", "overdue", "followed_up"] },
"confirm_token": { "type": "string", "description": "变更前由用户确认获得的一次性令牌" }
},
"required": ["customer_id", "status", "confirm_token"]
}
}上面这段 schema 刻意把“不发送通知、不删除记录”写进描述，这是负向约束，用来压低模型把其他意图误挂到本工具的概率。本文评述：负向约束在工具描述中常被忽略，但对降低动作空间熵有直接作用，建议每个工具都写明“本工具不做什么”。
4.4 第四步：编排层承接跨工具流程
拆成四个工具后，“标记并通知”这类跨工具流程由谁承接？答案是编排层，而不是把流程重新塞回某个工具。编排可以用工作流引擎、也可以用 Agent 的规划器，但必须有显式的步骤定义与失败分支。一个可操作的编排契约是：步骤 1 调用查询拿到候选集；步骤 2 对每个候选调用状态变更；步骤 3 汇总结果后调用通知；任一步失败则记录并跳过后续，不自动重试高副作用步骤。
这里可以借助 MCP 等协议把工具发现与调用标准化，降低编排层的适配成本（Anthropic, 2024）。也可参考 Microsoft 关于 AutoGen 的多 Agent 编排教程：AutoGen 官方文档。本文评述：编排层承接流程的代价是链路变长，因此必须配套超时预算分配，否则拆分只是把超时从一个点挪到另一个点。
4.5 第五步：超时预算与熔断
拆分后应给每个工具和每个编排步骤分配超时预算。建议总预算按步骤数加权分配，单工具超时不超过总预算的 40%，并对同一工具连续失败 2 次触发熔断，转人工或降级。熔断状态要写入任务上下文，避免模型在后续轮次继续重试同一工具。这一机制与分布式系统中的熔断器模式同源（Nygard, 2018），但触发条件需针对 Agent 的循环特征调整。
本文评述：超时治理的本质是给模型一个明确的“此路不通”信号。没有熔断，模型会把超时当作暂时性故障而继续重试，这正是“转十几圈”的直接机制。
五、关键数据与案例：超时到底花在哪里
5.1 公开基准中的工具调用失败率
公开研究中已有若干可引用的量化结果。伯克利函数调用基准（BFCL）持续评测模型在多工具场景下的调用准确率，其公开榜单显示，当工具数量与参数复杂度上升时，主流模型的整体准确率明显下降（Berkeley Function Calling Leaderboard, 2024–2025）。ToolBench 等工作则报告了多步工具调用中错误累积的现象（Qin et al., 2023）。本文评述：这些基准多以“单次调用是否正确”为指标，对“多轮循环导致的超时”覆盖不足，这是现有评测的一个空白，也是工程团队需要自建观测的原因。
需要说明，BFCL 的具体分数随版本与模型更新频繁变化，本文不引用单一静态数值，读者应查阅其官方榜单获取最新结果：BFCL 官方榜单。
5.2 一个模拟的耗时分解
为说明超时构成，笔者构造一组模拟数据（非真实线上数据，仅用于演示分析方法）：假设单次任务总预算 120 秒，单体 Skill 场景下，模型决策耗时占 35%，工具执行占 20%，因参数校验失败重试占 30%，上下文膨胀导致的推理变慢占 15%。拆分并加熔断后，重试占比降至 8%，膨胀占比降至 6%，总耗时回落到预算的 55% 左右。这组数字是模拟数据，用于说明各环节的相对权重，不应作为效果承诺。
| 耗时环节 | 单体 Skill（模拟） | 拆分+熔断（模拟） |
|---|---|---|
| 模型决策 | 35% | 31% |
| 工具执行 | 20% | 55% |
| 参数校验重试 | 30% | 8% |
| 上下文膨胀 | 15% | 6% |
表中“工具执行”占比在拆分后上升，是因为拆分增加了调用次数，这是拆分的固有代价。本文评述：拆分不是让总耗时单调下降，而是把不可控的重试与膨胀换成可控的调用次数。工程上要接受“调用变多但方差变小”这一权衡。
5.3 案例：从单体到四工具的迁移记录
某内部团队在 2024 年第四季度做过一次迁移（案例细节经脱敏，数据为团队内部统计）。迁移前，单体 Skill 的周均超时率为 11.3%，迁移后首月降至 4.1%，次月稳定在 3.6%。迁移成本约为 6 人日，主要花在意图聚类与编排层改造。迁移后新增的问题是编排链路变长，端到端延迟中位数上升约 12%，但 P99 延迟下降约 28%。这组数据来自团队内部统计，非公开可复核数据，引用时请注意其局限。
本文评述：这个案例的价值在于揭示了拆分的真实权衡——中位数变差、尾部变好。对超时敏感的系统，尾部改善往往比中位数更重要，因为超时阈值通常设在尾部。这也解释了为什么很多团队在拆分后主观感受“更稳了”，尽管平均延迟略有上升。
六、对比与局限：拆分不是万能药
6.1 拆分的代价：工具数量与选择负担
拆分最直接的代价是工具列表变长。当工具数量从 1 涨到 4，再到 20，模型在工具选择上的负担会重新上升。这与前文的动作空间熵并不矛盾：熵衡量的是“分支可分辨度”，工具数量增加会带来新的选择维度，但只要每个工具的描述足够可分辨，新增的选择负担是线性的，而非组合爆炸。本文评述：关键不在数量本身，而在新增工具是否带来新的歧义。如果拆分后出现两个描述高度相似的工具，那就是把内部熵转移成了外部熵，问题并未解决。
因此拆分必须配套命名与描述治理。建议建立工具目录（tool catalog），对每个工具记录意图标签、副作用等级、必填参数、典型示例，并在注册前做一次“描述两两相似度”检查，超过阈值的工具对需要重新命名或合并。这一步可以脚本化，纳入 CI。
6.2 何时不该拆
并非所有单体 Skill 都该拆。若四类动作共享同一份数据、同一套权限、且都是只读，那么拆分的收益有限，反而增加调用次数。判断标准回到四维判据：副作用等级低、失败恢复代价低、参数耦合度低时，维持单体并优化描述即可。本文评述：工程上最常见的错误不是“拆得不够”，而是“为了架构美观而拆”，结果把一次调用变成三次，延迟上升却没有任何稳定性收益。
6.3 与多 Agent 方案的关系
另一种思路是把四类动作分给四个专职 Agent，而非四个工具。多 Agent 方案在职责隔离上更彻底，但引入了 Agent 间通信与协调成本。公开研究如 AutoGen 展示了多 Agent 协作的可行性（Wu et al., 2023），但也指出协调开销与错误传播是主要挑战。本文评述：对大多数业务场景，工具级拆分加编排层已经足够；多 Agent 更适合职责差异极大、需要独立上下文与独立模型的场景。两者不是替代关系，而是不同粒度。
6.4 评测的局限
本文提出的动作空间熵依赖语义相似度代理估计，存在估计偏差；四维判据的阈值来自工程经验，缺乏大规模对照实验。公开基准对多轮循环超时的覆盖不足，导致“拆分前后”的对比难以用统一指标衡量。本文评述：这些局限不否定方法的实用性，但提醒读者把本文当作分析框架而非精确公式。后续若有团队愿意公开多轮工具调用的耗时分解数据，将显著提升该框架的可验证性。
七、结论与展望：走向可验证的工具契约
回到开头那个转十几圈的场景。问题的根因不是模型能力不足，而是工具契约把四类意图、四类副作用、四类失败恢复策略压进了一个语义单元，导致模型在分支间反复试探。本文给出的路径是：以动作空间熵识别高熵单元，以四维判据决定是否拆分，以意图聚类、副作用隔离、参数契约、编排承接、超时熔断五步落地，并接受“调用变多、尾部变好”的权衡。
展望未来，笔者认为三个方向值得关注。其一，工具契约的可验证化：把描述相似度、参数耦合度做成 CI 检查项，让工具注册像代码合并一样有门禁。其二，评测体系的补足：现有基准偏单次调用，需要多轮循环与超时场景的公开评测集。其三，协议层的标准化：MCP 等协议若能把副作用等级、幂等性、超时预算纳入工具元数据，编排层就能自动做熔断与降级，而不必每个团队重复造轮子。
最后给一条可立即执行的操作建议：今天就把你线上最常超时的那个 Skill 的调用日志拉出来，按“同一 Skill 连续调用次数”排序，取前 20 条人工看一遍，判断是循环、歧义还是膨胀。这个动作不需要任何新工具，半小时内就能得到比任何架构讨论都更扎实的判断依据。
主要参考文献
[1] Yao S., et al. ReAct: Synergizing Reasoning and Acting in Language Models. ICLR 2023. arXiv:2210.03629.
[2] Schick T., et al. Toolformer: Language Models Can Teach Themselves to Use Tools. NeurIPS 2023. arXiv:2302.04761.
[3] Shinn N., et al. Reflexion: Language Agents with Verbal Reinforcement Learning. NeurIPS 2023. arXiv:2303.11366.
[4] Qin Y., et al. ToolLLM: Facilitating Large Language Models to Master 16000+ Real-world APIs. ICLR 2024. arXiv:2307.16789.
[5] Wu Q., et al. AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation. arXiv:2308.08155, 2023.
[6] Anthropic. Building effective agents. 2024-12. 官方工程博客.
[7] Anthropic. Model Context Protocol 规范与文档. 2024–2025.
[8] Berkeley Function Calling Leaderboard (BFCL). Gorilla 项目, 2024–2025 榜单.
[9] Martin R. C. Agile Software Development: Principles, Patterns, and Practices. 2002（单一职责原则出处）。
[10] Nygard M. T. Release It! Design and Deploy Production-Ready Software. 2nd ed., 2018（熔断器模式）。
说明：本文写作过程中参考了国内外公开文献、官方文档与基准榜单共 60 余篇（含 2023–2025 年文献占比超过 50%），以上列出与论证直接相关的主要 10 篇。涉及数据集的说明：BFCL 为公开评测榜单，本文仅引用其趋势性结论，未复制具体分数；第五节的耗时分解与迁移案例中，耗时分解为模拟数据，迁移案例为脱敏后的团队内部统计，均已在正文标注，引用时请以原始来源为准。
文章声明：本文内容仅为作者学习、思考、经验、笔记的总结，仅供技术交流与参考。文中观点仅代表笔者个人思辨，不构成任何学术建议、商业建议或专业建议。所有数据来源已标注，引用时请以原始文献为准。
拓展阅读：Anthropic《Building effective agents》 · OpenAI Function Calling 指南 · MCP 官方文档
贵公网安备 52010302001819号
