Composio SDK 工具执行重试策略非幂等写入为何不再自动重试以及如何安全诊断与手动重试【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本指南讲解 Composio SDK 自 Python SDK 0.16.0 与 TypeScript SDK 0.14.0 起在工具执行tools.execute与 Proxy Execute 上的重试行为变更非幂等写入在超时、限流或服务器错误后将不再被自动重试以避免重复副作用如同一封邮件被发送两次。读完本文你将理解这一变更的底层实现原理、为何客户端超时不能等同于执行失败以及如何在升级后正确诊断执行日志、安全手动重试并在重复问题持续时收集有效的排障信息。变更概述哪些版本、哪些行为变了原文档docs/kb/articles/sdk-tool-execution-retries.md明确指出Python SDK 0.16.0 与 TypeScript SDK 0.14.0同时调整了工具执行与 Proxy Execute 的重试逻辑非幂等写入不再在以下三类错误后自动重试客户端/网络超时timeout限流rate limitsHTTP 429服务器错误server errors5xx 响应仓库内变更日志可以相互印证docs/content/changelog/06-25-26-sdk-012-and-python-016.mdx 记录了 Python SDK 0.16.0 的发布说明明确写到 tools.execute()andtools.proxy()no longer retry non-idempotent writes, preventing duplicate side effects after timeouts, 429s, or 5xx responses即修复了重试安全retry safety问题。docs/content/changelog/07-15-26-typescript-sdk-014.mdx 记录了 TypeScript SDK 0.14.0composio/core的同口径变更tools.execute()andtools.proxyExecute()no longer retry non-idempotent writes, preventing a timeout from repeating side effects such as sending the same email twice.因此如果你仍在使用低于上述版本的 SDK在诊断重复发送/重复写入问题前请先升级——旧版本 SDK 的自动重试行为本身就是重复副作用的潜在来源。当前仓库中的 Python 版本信息见 python/composio/version.py实际版本以你安装的发布版本为准。为什么禁止自动重试非幂等写入与重复副作用非幂等写入指同一操作执行两次会产生不同的可观察结果。典型的非幂等动作包括发送邮件 / 发送消息send创建资源create更新资源update删除资源delete对于这类操作自动重试存在一个经典陷阱请求可能在服务器端已经成功执行只是响应在返回途中因超时丢失。此时 SDK 若自动重试会把同一个副作用重复执行一遍——例如同一封邮件被发出两次、同一条记录被创建两次。这一设计决策在源码中留有明确注释。Python 端 python/composio/core/models/tools.py 的execute实现中写道Disable retries: tool execution is a non-idempotent write, and a silent retry after a read timeout can duplicate the side effect.同样的注释也出现在proxy方法中python/composio/core/models/tools.py一个被代理的调用同样是非幂等写入读超时后的静默重试可能重复副作用。TypeScript 端的回归测试注释ts/packages/core/test/tools/tools.test.ts则更直白地描述了后果a retry after a server-side success duplicates the side effect (e.g. sends the same email up to 3 times)——服务器侧已成功后再重试可能导致同一封邮件最多被发送三次。源码级原理without_retries兄弟客户端这一行为并非简单删除了重试代码而是为写路径单独路由到一个禁用重试的兄弟客户端读取类操作与其余 API 调用保持默认重试不变。Python 端实现在 python/composio/client/init.py 中HttpClient暴露了一个缓存属性without_retries它是一个从不重试请求的缓存兄弟客户端a cached sibling client that never retries requests仅用于非幂等写入tools.execute/tools.proxy读操作保持默认重试实现方式是self.with_options(max_retries0)即构造一个仅把max_retries置为 0、其余选项完全相同的克隆该兄弟客户端按实例缓存self._without_retries而不是每次调用都新建因为tools.execute/tools.proxy是最热路径hottest path。值得注意的边界注释明确说明目前只有tools.execute/tools.proxy走这条无重试路径。其他非幂等写入如auth_configs.create/update/delete、mcp.update/delete、connected_accounts.delete/refresh、link.create仍保留默认重试——原因是它们大多数天然具备幂等性持久性的正确修复方案是后端幂等键backend-honoured idempotency keys。调用链上Tools模型的两个写方法都通过self._client.without_retries发起请求python/composio/core/models/tools.py 与 python/composio/core/models/tools.py。TypeScript 端实现TypeScript 端composio/core实现了与 Python 完全对称的方案。在 ts/packages/core/src/models/Tools.ts 中Tools类有一个私有 getterclientWithoutRetries通过this.client.withOptions({ maxRetries: 0 })构建无重试客户端结果缓存在clientWithoutRetriesCache中避免每次调用重新构造客户端源码注释明确说明这是对 Pythonclient.without_retries的镜像实现mirroring Pythonsclient.without_retries。composio/core的变更日志ts/packages/core/CHANGELOG.md也记录了同一提交Disable client retries ontools.executeandtools.proxyExecute. These are non-idempotent writes, so a silent retry after a read timeout could duplicate the side effect... Both now route through a sibling client built withmaxRetries: 0; reads keep the default retry behaviour.测试验证TypeScript 端用回归测试锁定了该行为ts/packages/core/test/tools/tools.test.tsroutes tools.execute through a client with maxRetries: 0断言withOptions以{ maxRetries: 0 }被调用routes tools.proxyExecute through a client with maxRetries: 0同样的断言覆盖proxyExecutereuses one no-retries sibling client across executes (cached per instance)验证兄弟客户端按实例缓存复用。测试注释还提到该变更对标 Python 行为TS parity with Python。这意味着非幂等写入不自动重试是两端 SDK 的有意、受测试保护的设计而不是巧合或回归。客户端超时的歧义性超时 ≠ 执行失败原文档强调了一个容易被忽略的事实一个模糊的客户端超时ambiguous client timeout并不能证明 provider 侧的操作已经失败。超时只说明客户端在约定时间内没有收到响应它可能对应三种截然不同的真实状态请求从未到达服务器网络层失败——此时重试是安全的请求到达并已被处理但响应超时丢失——此时重试会重复副作用请求到达但服务器处理超时/异常——此时状态未知需要进一步确认。因此在手动重试一个 send、create、update 或 delete 动作之前必须先确认第一次尝试是否真的失败了而不是凭超时了就重试。原文档给出的确认途径是两处执行日志execution logComposio 平台会为每次工具执行生成日志日志中包含了执行结果与状态Provider 侧状态provider state直接检查被操作的服务邮件服务、CRM、数据库等中是否存在该操作产生的痕迹。升级后的诊断与手动重试指南综合原文档与上述原理在基于当前版本 SDK 排查疑似重复发送/重复写入问题时建议按以下流程操作第一步确认 SDK 版本Python确认composio版本不低于 0.16.0TypeScript确认composio/core版本不低于 0.14.0。若版本低于上述阈值先升级再继续诊断——旧版 SDK 的自动重试本身就是可疑源头。第二步区分自动重试与手动重试当前 SDK 不会对tools.execute/tools.proxy自动重试因此你在代码中看到的任何重试都来自你自己的应用逻辑或第三方 HTTP 库配置排查范围应从应用层展开。第三步判断超时结果是否真正失败在手动重试 send / create / update / delete 前先查询对应执行的执行日志 ID核对第一次尝试的执行状态或直接检查 provider 侧状态确认操作是否已经生效例如收件箱中是否已有该邮件。第四步只在确认失败后手动重试只有确认第一次尝试确实未生效才重新发起执行并做好去重例如在应用层维护操作的幂等键。第五步重复问题仍存在时收集支持信息如果升级到当前 SDK 后重复问题依然出现请收集并提交以下材料SDK 版本、执行日志 ID、时间戳。这些信息能让平台侧定位是执行链路、后端幂等键还是 provider 集成的问题。建议话术向用户/支持方解释该行为原文档附有一段可直接复用的引导话术用于向终端用户或支持团队解释当前行为建议原样保留Current Composio SDKs do not automatically retry non-idempotent tool executions. A timeout can still be ambiguous, so check the execution log or provider state before manually retrying an action that may have completed.中文释义当前 Composio SDK 不会自动重试非幂等工具执行。超时仍然可能是模糊的因此在手动重试一个可能已经完成的操作之前请先检查执行日志或 provider 状态。延伸其余写路径的幂等性现状从源码注释可以明确不自动重试目前只覆盖tools.execute与tools.proxy两条路径。其余写操作认证配置、连接账号、MCP 配置、链接创建等仍走默认重试其幂等保障依赖后端幂等键机制backend-honoured idempotency keys。如果你的应用还会通过 SDK 调用这些写接口请留意其各自的幂等语义并参考对应 API 文档确认行为边界——相关接口说明可在 docs/content/docs/auth-configuration 与 docs/content/docs/authentication 等文档目录中查阅。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考