接口描述
把外部 A2A Agent 绑定到某个 Managed Agent，绑定后可作为子 Agent 调用。
POST /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}/external-bindings输入参数
路径参数
参数 | 类型 | 说明 |
enterpriseId | string | WorkBuddy 企业 ID |
agentId | string | 等价于请求体字段 AgentId |
查询参数
无
请求体
字段 | 类型 | 说明 |
AgentId | string | AgentId Agent 业务 ID，由路径参数注入。 |
A2AAgentId | string | A2AAgentId 要绑定的外部 Agent 公开引用 ID（取自外部 Agent 列表的 A2AAgentId）。 |
VersionId | string | VersionId 指定这条绑定落在父 agent 的哪个版本（AgentOS agent_versions.id）。 缺省（空串）= 落在当前编辑版本（default），与本字段引入前行为一致。 显式指定时服务端校验该版本确实属于本 agent，不属于则 ResourceNotFound.Version。 注意：指定一个已发布版本会直接改变该版本的运行时行为——已发布版本原本是 发版那一刻冻结的不可变快照。调用方应确保这是用户的明确意图。 |
输出参数
（
201，业务出参包装在 code / data / msg / requestId 中）OKResponse 操作确认（Bind/Unbind）。
字段 | 类型 | 说明 |
status | string | Status 操作结果状态（大写枚举，CAPI 规范 1.2.2） BOUND：已绑定 UNBOUND：已解绑。 |
bindingId | string | BindingId 本次绑定产生的绑定记录 ID，解绑时可直接使用；解绑响应不回填。 |
示例
输入示例
POST /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}/external-bindingsAuthorization: Bearer pt_<YOUR_APP_KEY>Content-Type: application/json{"A2AAgentId": "ref_7f3c1a2b9d"}
输出示例
{"code": 0,"data": {"bindingId": "1200345678901234567","status": "string"},"msg": "OK","requestId": "3c6d138e-1234-5678-9abc-def012345678"}
错误码
说明：
错误码 | 说明 |
FailedOperation.ExternalBindFailed | 绑定外部 Agent 失败 |
FailedOperation.ExternalOperationFailed | 外部 Agent 操作失败 |
InvalidParameter.AgentIDRequired | 缺少 AgentId |
InvalidParameter.EndpointInvalid | Endpoint 必须是绝对的 http(s) URL |
InvalidParameter.EndpointRequired | 缺少 Endpoint |
InvalidParameter.ExternalAgentIDRequired | 缺少 A2AAgentId |
InvalidParameter.InvalidRequestBody | 请求体不合法 |
InvalidParameter.Pagination | 分页参数不合法 |
InvalidParameterValue.InvalidBindingID | BindingId 必须是正整数形式的字符串 |
InvalidParameterValue.InvalidVersionID | VersionId 必须是正整数形式的字符串 |
MissingParameter.UinRequired | 公共参数中缺少 Uin |
ResourceNotFound.Agent | Agent 不存在 |
ResourceNotFound.ExternalAgent | 该外部 Agent 未绑定到当前 Agent |
ResourceNotFound.Version | 版本不存在 |
ResourceUnavailable.A2ANotConfigured | 未配置 A2A 网关 |
UnauthorizedOperation.UnprovisionedTenant | 租户未开通，或企业不存在 |
