只读、幂等、超时和限流为什么属于能力声明？

关键词Agent 工具幂等、AI 工具调用重试、Agent 超时、Agent 限流、业务 API 执行约束假设一套企业系统向 Agent 提供四项能力order.read 查询订单 refund.request.create 创建退款申请 notification.batch.send 批量发送通知 report.generate 生成经营报表它们的参数都可以由 OpenAPI 或其他输入 Schema 描述运行时也知道应该向哪个地址发送请求。但只知道“怎么调用”仍然不足以安全执行。运行时还需要知道查询订单是否真的不改变业务状态创建退款申请失败后能不能用同一组参数重试报表生成等待多久应该停止批量通知在一分钟内最多允许调用多少次这些问题看起来像运行时配置实际上首先描述的是 operation 本身的稳定执行属性。如果每个 Agent 平台都靠 HTTP 方法、接口名称或私有经验重新猜一次就会出现完全不同的行为运行时 A 看到 GET默认无限重试 运行时 B 看到 POST永不重试 运行时 C 等待模型接口的默认 30 秒 运行时 D 没有限流短时间发起数百次批量通知因此能力声明除了说明参数结构和治理意图还需要一组最小、可移植的执行提示。执行提示不负责替运行时编排整个工作流但它应该让不同运行时对“这项操作能否安全读取、重复、等待和限速”形成同一基本理解。1. 输入 Schema 描述形状执行语义描述行为下面这段 Schema 可以告诉运行时退款接口需要哪些参数type:objectrequired:-order_id-amountproperties:order_id:type:stringamount:type:number它不能回答调用会不会改变业务状态 网络断开后重发会不会创建两笔退款 等待 10 秒后超时服务端是否仍可能继续执行 这个能力能承受多高调用频率参数结构与执行行为是两个维度。前者保证调用格式正确后者帮助运行时避免用错误方式调用一项本来合法的能力。对于普通人工页面这些知识可能被写死在前端代码、SDK 或开发者经验里。进入 Agent 场景后调用者可能来自不同模型、平台、工作流和网关隐含知识就会迅速失效。这正是把最小执行语义放进能力声明的原因。2.readonly描述的是业务状态不只是 HTTP 方法ACC v1 可以这样声明execution:readonly:true它表示该 operation 不应改变业务状态。这里强调的是业务效果不是网络协议表面。一个GET请求通常只读但并不天然安全GET /export-and-mark-as-downloaded GET /track-email-open GET /legacy/trigger-sync这些历史接口可能产生状态变化或外部副作用。反过来一些只读查询因为参数复杂可能使用POSTPOST /reports/query POST /search/advanced如果运行时只根据 HTTP 方法推断就可能同时犯两类错误把会改变状态的GET当作只读能力把使用POST的纯查询当作写操作。显式readonly为不同绑定和运行时提供一项稳定信号。但它仍然只是一项声明不是最终保证。API 作者必须如实标注实现本身必须真的不改变业务状态读取敏感数据仍然需要主体和业务授权“只读”不等于“无风险”大规模导出即使不修改状态也可能具有高后果。所以readonly回答的是执行效果不替代risk、subject和最终 Authority。3.idempotent解决的是“同一动作能不能安全重复”分布式系统里最危险的一句话之一是刚才好像超时了再发一次试试。客户端超时时可能存在至少三种情况请求根本没有到达服务端请求到达但业务事务失败请求已经成功只是响应没有返回客户端。如果第三种情况下直接重试可能产生两笔退款两次库存扣减两条通知两个重复工单两次外部部署。ACC v1 的声明是execution:idempotent:true它表示使用相同参数重复调用该 operation可以被安全地视为同一逻辑动作。这项语义让运行时知道重试是否可能成立但它不会凭空让接口获得幂等性。真正的幂等通常需要业务实现提供稳定的幂等键唯一约束请求指纹重复结果回放明确的幂等窗口对并发请求的原子处理。如果 API 没有这些保证却把idempotent: true写进声明运行时会基于错误信号采取危险行动。因此幂等声明描述已经存在的能力属性不是要求运行时替业务系统发明幂等。同样idempotent: true也不等于“应该无限自动重试”。是否重试还需要考虑错误类型最大次数退避策略剩余任务期限服务端是否返回明确终态当前调用是否仍绑定原始主体和参数外部系统是否具有同样的幂等保证。幂等是重试的必要信号之一不是完整重试策略。4.timeout_ms是等待边界提示不是取消保证长时间没有结果时Agent 运行时必须决定继续等待、转为异步、返回待处理还是终止本次尝试。ACC v1 支持execution:timeout_ms:10000它表示 invocation 的超时提示以毫秒为单位。这项信息有几个现实价值避免运行时无限等待帮助工作流设置有界阻塞时间让用户界面区分同步操作和长任务为模型提供明确的“暂未完成”状态而不是让它自行猜测让不同运行时不必为同一 operation 各自发明默认值。但“客户端停止等待”和“服务端停止执行”不是一回事。下面这条链路完全可能发生运行时等待 10 秒后超时 - 客户端关闭连接 - 业务服务继续处理 - 第 15 秒完成退款 - Agent 因为超时又发起一次调用所以timeout_ms不能被解释为服务端已经取消业务事务已经回滚可以立即安全重试超时后一定没有产生业务后果运行时必须采用某一种 UI 或错误文本。如果系统需要真正的取消语义还必须定义取消令牌、服务端确认、可取消阶段、补偿动作和最终状态查询。这已经超出一个简单执行提示能够承担的范围。5.rate_limit描述调用节奏不替代企业配额系统一项能力单次调用可能完全合法但短时间高频调用仍会产生风险。例如批量发送通知单次参数正确连续调用会骚扰大量客户 报表导出单次只读高频执行会拖垮数据库 库存查询单次低风险循环调用会放大成本 外部供应商 API超过频率会触发封禁或额外费用ACC v1 可以声明execution:rate_limit:count:30window:1m它表达一项运行时限流提示在给定窗口内调用次数不应超过声明上限。这让兼容运行时能够在调用到达业务系统之前建立基本节奏控制。但一条通用声明无法替整个企业回答所有配额问题是按 route、Agent、用户、主体还是租户计数多个运行时如何共享计数窗口是固定、滑动还是令牌桶超限后拒绝、排队还是降级不同客户套餐是否有不同额度内部重试是否计入配额审批等待后的恢复是否重新计数这些问题依赖部署策略、计费体系和组织边界。因此通用契约适合提供可移植的调用频率提示部署方负责决定计数键、算法、共享状态和失败行为。6. 四项执行提示彼此正交不能相互推导一项能力可以同时具有不同组合能力readonlyidempotenttimeoutrate limit查询单个订单truetrue短较宽松生成复杂报表truetrue长较严格创建退款申请false可能为 true中严格批量发送通知false取决于业务键长很严格触发一次性部署false通常为 false长严格从readonly: true不能自动推出数据不敏感风险一定是 low可以无限并发可以无限重试不需要可信主体。从idempotent: true也不能自动推出操作是只读没有业务副作用任何错误都值得重试相同参数在任何时间都代表同一业务意图。执行提示的价值就在于它们分别描述不同事实而不是被压缩成一个模糊的“safe”字段。7. 为什么这些信息不能只留在运行时私有配置里团队当然可以在某个平台里配置refund.create timeout10s refund.create retryfalse refund.create limit10/min问题是同一业务能力可能同时被Difyn8nMCP Client自研 AgentAPI Gateway本地执行器云端工作流调用。如果执行语义只存在某一个运行时里其他调用方仍然需要重新猜测和配置。随着平台增加配置会分叉平台 A 认为可重试 平台 B 认为不可重试 平台 C 等待 30 秒 平台 D 没有限流把 operation 的稳定属性放在能力声明里可以建立一份共同事实源。部署方仍可采用更保守的本地策略声明上限 30/min当前组织限制为 10/min 声明超时 10s当前路由只允许等待 5s 声明可幂等重试当前高风险场景仍选择不自动重试但本地策略不应该悄悄放宽声明中的安全边界。8. 为什么 ACC 不继续定义重试、并发和事务看到idempotent和timeout_ms后一个自然问题是为什么不顺便把重试次数、退避算法、并发数、回滚和事务都写进 ACC因为这些概念已经从稳定 operation 属性进入具体执行策略和工作流语义。重试策略需要区分网络错误、业务拒绝、超时、限流和未知终态还要定义退避、抖动、预算和截止时间。并发控制需要确定计数维度、共享状态、一致性模型和租户边界。事务与回滚跨多个业务 API 的原子性不能由一个atomic: true字段创造。它需要事务协调、Saga、补偿授权、状态恢复和失败语义。取消需要服务端协议确认而不是客户端停止等待。这些都是真实需求但它们属于运行时、工作流、业务系统或独立协议。把它们没有边界地塞进能力声明会让一个薄契约逐渐变成无法跨实现兑现的编排语言。9. 声明、运行时与业务系统怎样分工一条可靠链路可以这样理解能力声明 告诉调用方 operation 是否只读、是否幂等、建议等待多久、调用频率上限 运行时 结合本地策略决定等待、限流、是否尝试重试以及怎样报告状态 业务系统 真正保证状态变化、幂等唯一性、最终授权和业务结果更完整地说层次责任ACC Core定义可移植执行提示及其稳定含义协议 Binding映射承载协议的原生信号、优先级和保守回退Agent 运行时执行超时与限流结合错误和本地政策作保守决策工作流系统管理重试预算、异步等待、并发、编排和补偿业务系统保证真实只读效果、幂等实现、最终权限和状态一致性这仍然遵循 Reach 与 Authority 的分离。执行提示告诉运行时“怎样更安全地尝试调用”并不授予主体操作业务对象的最终权限。10. 一段完整声明应该怎样理解例如x-agent-capability:version:1enabled:truescope:order.readrisk:level:lowsubject:required:trueaudit:sensitive:trueexecution:readonly:trueidempotent:truetimeout_ms:5000rate_limit:count:60window:1m它表达的是该 operation 显式允许进入 Agent-facing 候选范围当前场景可通过稳定 scope 引用它最坏合理后果被声明为 low每次调用都需要可信行动主体参数或响应可能含敏感数据需要保守日志处理操作不应改变业务状态相同参数可以安全重复运行时建议在 5 秒处建立等待边界运行时应尊重每分钟 60 次的调用频率提示。它没有表达当前用户一定可以读取这个订单所有 low 风险能力都不需要治理运行时可以无限重试5 秒后服务端一定取消任何租户都拥有相同配额审计和限流已经由某个产品自动完成。契约的专业性不在于字段看起来多而在于每项声明都清楚说明自己保证什么、不保证什么。11. 八个常见误区误区一GET 一定只读历史接口和不规范实现可能在 GET 中产生副作用显式声明与实现审查仍然必要。误区二POST 一定不可幂等带稳定业务键、唯一约束和结果回放的 POST 可以具备幂等语义。误区三幂等就应该自动重试重试仍要看错误类型、次数、截止时间和未知终态。误区四客户端超时代表业务没有执行停止等待不等于服务端取消更不等于事务回滚。误区五限流只为保护服务器性能限流也控制外部通知、资金动作、第三方成本和业务影响范围。误区六只读操作天然低风险大规模导出、敏感查询和跨租户读取即使不改状态也可能具有严重后果。误区七声明了幂等运行时就能替业务系统保证幂等幂等必须由真正持有业务状态的一侧实现。误区八执行提示等于最终授权调用方式正确不代表当前主体有权操作当前资源。12. 一份最小执行语义检查表在把 operation 暴露给 Agent 前可以先回答readonly是否按真实业务效果标注而不是只看 HTTP 方法只读能力是否仍按数据敏感性和影响范围评估风险idempotent: true是否有服务端唯一约束或等价机制支撑相同参数在幂等窗口内是否真的代表同一逻辑动作超时后是否可以查询最终状态而不是立即盲目重试客户端停止等待与服务端取消是否被明确区分限流的本地计数维度和失败行为是否已经定义部署策略是否只会收紧而不会悄悄放宽声明边界重试、并发、补偿和事务是否留在正确的运行时或工作流层业务系统是否仍执行最终主体权限与业务状态校验日志和审计能否区分首次调用、重试、重复消费和幂等命中如果这些事实只能藏在某一个 SDK 或某位开发者脑中多 Agent、多运行时接入后迟早会产生不一致。13. 结语执行语义是能力的一部分但不是整个执行系统Agent 调用业务能力时风险不只来自“选错工具”或“参数写错”。即使工具和参数完全正确错误的执行方式仍然可能造成真实后果把有副作用的操作当成查询把未知终态当成失败并重复执行无限等待一个已经失联的任务在短时间内放大一项原本有限的业务动作。因此只读、幂等、超时和限流不是某个产品的界面偏好而是不同运行时理解一项能力时需要共享的最小执行语义。它们应该进入能力声明因为它们描述 operation 的稳定属性。它们又必须保持克制因为完整的重试、取消、并发、事务和补偿需要更丰富的运行时与业务协议。好的契约不会试图执行一切。它只会在不同系统即将采取行动之前把那些不能继续依赖猜测的事实明确说出来。对 Agent 系统而言这已经足以避免大量昂贵而且完全可以预防的错误。