帮你快速理解、总结文档立即下载
文档中心>WorkBuddy Enterprise>WorkBuddy Managed Agents>OpenAPI>外部 Agent 管理相关接口>获取绑定的外部 Agent 详情

获取绑定的外部 Agent 详情

最近更新时间：2026-10-29 18:19:32
我的收藏

本页目录：

接口描述

查询已绑定外部 Agent 的详情（含 Agent Card 声明的能力）。
GET /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}/external-agents/{a2aAgentId}

输入参数

路径参数

参数
类型
说明
enterpriseId
string
WorkBuddy 企业 ID
agentId
string
等价于请求体字段 AgentId
a2aAgentId
string
等价于请求体字段 A2AAgentId

查询参数

无

请求体

无（GET / DELETE 不带请求体，条件走路径与查询参数）

输出参数

（200，业务出参包装在 code / data / msg / requestId 中）
ExternalAgentItem 外部 agent 摘要。
字段
类型
说明
a2aAgentId
string
A2AAgentId 外部 Agent 的公开引用 ID（注册中心分配），绑定 / 解绑 / 详情查询 都以它为定位键。URL 直连型绑定没有公开引用，此字段回填绑定时的 ProviderURL。
bindingId
string
BindingId 本企业与该外部 Agent 的绑定记录 ID。解绑时推荐直接传它， 服务端可直接定位，无需再按 A2AAgentId 反查；未绑定时为空。
name
string
Name 外部 Agent 名称，取自对端 Agent Card 的 name。
description
string
Description 外部 Agent 描述，取自对端 Agent Card 的 description， 对端未提供时为空。
iconUrl
string
IconUrl 头像地址，取自 provider card 的 iconUrl（A2A v1.0 §4.4.1）。 为空表示该 Agent 未设头像，由前端回落首字母头像。
endpoint
string
Endpoint 外部 A2A Server URL。
a2aVersion
string
A2AVersion 外部 agent card 声明的版本号。加 A2A 前缀与同结构的 A2AAgentId / A2ASkillSet 对齐，也避免与内部 VersionId 混淆。
a2aSkillSet
A2ASkillItem[]
A2ASkillSet 外部 Agent 声明的能力列表（Agent Card skills）， 绑定后可作为子 Agent 的能力被调用。
bound
boolean
Bound 本企业是否已绑定该外部 Agent。列表缺省返回「已绑定 + 未绑定」合并视图， 需要只取其一时可传过滤参数 Bound=BOUND / UNBOUND。
latestVersionName
string
LatestVersionName 子 agent 的最新版本名：有 prod 取最新 prod，否则取最新 test， 再否则取 default。仅企业 Agent 来源有值（其 Card 版本恒为 "default"，无展示意义）； 其他来源或解析失败时为空，由调用方回落 A2AVersion。
注意：不代表 A2A 入站实际执行的版本，后者见 a2aversion.SelectExecution。

示例

输入示例

GET /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}/external-agents/{a2aAgentId}
Authorization: Bearer pt_<YOUR_APP_KEY>

输出示例

{
  "code": 0,
  "data": {
    "a2aAgentId": "ref_7f3c1a2b9d",
    "a2aSkillSet": [
      {
        "a2aSkillId": "skill_order_query",
        "description": "负责每日数据汇总",
        "name": "数据分析助手"
      }
    ],
    "a2aVersion": "1.0.0",
    "bindingId": "1200345678901234567",
    "bound": true,
    "description": "负责每日数据汇总",
    "endpoint": "https://a2a.example.com/inventory",
    "iconUrl": "https://example.com/avatar/agent-001.png",
    "latestVersionName": "prod",
    "name": "数据分析助手"
  },
  "msg": "OK",
  "requestId": "3c6d138e-1234-5678-9abc-def012345678"
}

错误码

说明：
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见错误响应与公共错误码。
错误码
说明
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
租户未开通，或企业不存在
中国站