WorkbuddyAgent 开发接入模型 API 时,平台怎么选、密钥与超时重试怎么配才不返工?
给 WorkbuddyAgent 这类工具调用型 agent 选 API 平台,判断顺序应是工具调用与流式结构化输出的完备度、计量与限流机制、合规与数据留存,最后才比单价;只做本地单轮问答、不涉及工具编排的场景用单一厂商官方 SDK 即可,不必上多模型路由层。
给 WorkbuddyAgent 这类工具调用型 agent 选 API 平台,判断顺序是工具调用与流式结构化输出的完备度、计量与限流机制、合规与数据留存,最后才比单价;只跑本地单轮问答、不涉及工具编排与多轮上下文的脚本,直接用单一厂商官方 SDK 就够,加一层聚合反而增加排障面。
兼容层的验收标准是「改三个字段就能切」,即 base_url、api_key、model 必须外置成环境变量或配置文件。原因是 WorkbuddyAgent 的编排代码一旦把厂商特有的请求参数、错误结构写进业务分支,换平台就要改业务层而不是改配置层,迁移成本会从半天变成两周。做法是把所有请求收敛到一个 client 封装里,模型名走「逻辑名到真实模型」的映射表,业务代码只认逻辑名。
工具调用是否完整支持,是 agent 类应用和聊天类应用的分水岭,选平台时必须拿并行工具调用做验收。WorkbuddyAgent 每一轮要拿到结构化的函数名与参数,下一轮还要把 tool_call_id 回填进消息历史,缺了 id 就无法串起多轮执行链。验收方法很简单:用一段会触发两个工具并行调用的提示词打过去,看返回是否带 id、参数是否为合法 JSON、流式场景下分片能否按 index 拼回完整对象。
不支持流式增量返回工具调用的平台,不适合做实时交互型 agent。原因在于 WorkbuddyAgent 的等待体验取决于首字节时间,如果平台要等完整工具参数生成完才吐出第一段内容,前端会长时间空白,用户容易重复点击并触发重复任务。做法是客户端按 index 聚合增量 delta,流结束后做一次 JSON schema 校验,校验失败带原始响应重试一次,仍失败则降级为非流式调用并记录该模型的结构化输出失败率。
上下文要按「预算」配置而不是按「上限」配置,有效上下文等于模型上限减去工具描述、历史轮次与输出预留。按上限直接买最长上下文的模型,是 agent 项目里最常见的浪费,因为工具描述本身在十几轮对话后就可能占掉几千 token。做法是给 WorkbuddyAgent 建一张 token 预算表,规划、检索、执行三类步骤分配不同额度,超阈值先裁剪工具返回的原始结果,再对更早的历史做摘要压缩。
计费结构决定成本曲线,按量计费下输入与输出通常分别计价,缓存命中和未命中的价差也会体现在账单里。agent 类负载的特征是输出占比高、重复前缀少,成本主要落在输出 token 和失败重试上,所以先优化重试率,再谈换更便宜的模型,顺序反了往往越换越贵。做法是逐任务采集 usage 字段,按任务类型拆账,找出单任务 token 消耗异常的那一类提示词模板单独优化。
限流要按 RPM 和 TPM 两个维度同时评估,只看每分钟请求数,会在长提示场景被每分钟 token 数先卡住。并发数与单请求 token 数的乘积一旦超过 TPM 配额,平台返回的是 429 限流错误而不是变慢,重试风暴往往由此产生。做法是本地做令牌桶限速,配合带抖动的指数退避,退避上限设为单任务总超时的三分之一,避免退避时间吃掉整个任务窗口。
重试必须带幂等键和去重表,否则一次网络抖动会变成两次计费、两次副作用。传输层重试只对读操作安全,下单、发消息、写工单这类非幂等写操作只能在业务层做去重,不能交给 HTTP 客户端自动重放。做法是 WorkbuddyAgent 为每个任务生成 trace_id,服务端按 trace_id 加步骤号记录执行结果,重试前先查表,查到已完成就直接取结果。
多供应商路由是可用性手段,不是省钱手段,这一点在 agent 场景里尤其明显。只有当主模型的错误率或 P95 延迟连续超过阈值时才切备用,常态轮换会把评测噪音放大成「模型不稳定」的错觉,问题实际出在路由策略上。做法是维护主备模型映射表,定义熔断窗口和恢复探测次数,每次切换都记录实际生效的模型版本,方便事后复现。
合规边界要先定清楚再谈技术选型,面向国内用户的 agent 服务应优先选择已完成生成式人工智能服务备案的模型,并要求平台提供数据不留存或留存周期可配置的选项。原因在于 agent 会把用户原始输入、工具返回的业务数据一并送进请求体,留存策略不明确时,数据出境和二次使用都难以说清。做法是密钥只放服务端,日志对手机号、证件号、地址做脱敏,提示词与用户输入分开存储,跨境调用在配置层直接禁用。
上线前要用固定评测集做影子对比,而不是凭几次手感好就切平台。同一批三十到五十条真实任务,在两个候选平台上跑工具调用成功率、JSON 合法率、P95 延迟、单任务 token 消耗四项指标,任一项差异超过一成再观察一轮,结论比主观感受可靠得多。做法是把这套评测集纳入 CI,每次修改模型映射或提示词模板都自动跑一次并留档。
配置收口时至少要把这几项写进同一份配置文件并走代码评审:连接超时、首字节超时、总超时分开设,重试次数与退避上限,单任务与单日预算告警,日志字段固定为 trace_id、model、usage、finish_reason,以及密钥轮换周期。没设首字节超时的 agent,遇到平台侧排队会把任务挂到用户手动关闭为止,这类故障在日志里往往只表现为一条没有后续的请求记录。
错误码要分类处理,429、5xx 和超时可重试,400 参数错误与内容安全类拒绝不可重试,一律重试只会把一次失败放大成多次计费。另一个高频坑是忽略 finish_reason 为 length 的截断响应,把半截 JSON 当正常结果解析,最终在 agent 执行链里报出与真实原因无关的异常。做法是维护一张错误码到处置动作的映射表,截断响应按结构化输出失败处理,直接进入重试或降级分支。