WorkBuddy Enterprise 获取 Agent

接口描述
查询单个 Agent 的属性、路由配置与访问入口。
GET /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}
输入参数
路径参数
参数
类型
说明
enterpriseId
string
WorkBuddy 企业 ID
agentId
string
等价于请求体字段 AgentId
查询参数
无
请求体
无（GET / DELETE 不带请求体，条件走路径与查询参数）
输出参数
（200，业务出参包装在 code / data / msg / requestId 中）
AgentInfo Agent 详情。
字段
类型
说明
agentId
string
AgentId Agent 业务 ID，建号时生成，后续接口一律以它定位 Agent。
agentName
string
AgentName Agent 名称。
description
string
Description Agent 描述。
avatarUrl
string
AvatarUrl 头像地址，为空表示未设头像（由前端回落首字母头像）。
isDebug
boolean
IsDebug 是否为调试 Agent：工作台调试入口创建，不进入正式下发链路。
routingSet
﻿RoutingItem[]
RoutingSet 流量路由配置。空路由输出空数组而非省略字段 —— 「未配置路由」与「字段缺失」对调用方语义不同，不能混同。
createdTime
string
CreatedTime 创建时间，UTC RFC3339。
modifiedTime
string
ModifiedTime 最后修改时间，UTC RFC3339。
activeSessionCount
integer
ActiveSessionCount 当前活跃 session 数（ACTIVE/CREATING/MIGRATING，未软删）。 指针语义区分"未统计"与"统计为 0"：nil=未统计/降级（字段缺失），非 nil 含 0 显式输出。 仅 DescribeAgent 读路径填充；写路径回显保持 nil，omitempty 不下发，避免触碰 CAPI 白名单。
accountId
string
AccountId 绑定的 OneID 企业账号 ID；空=未绑定（omitempty 下发缺省）。 创建时可选传入，之后不可变。 
仅 DescribeAgent 读路径填充（mirrorToAgentInfo）：写路径回显该字段会被网关按 出参白名单判为「未定义字段: AccountId」，整个响应变成 InternalError。 详见 mergeToAgentInfo 的说明。
creatorId
string
CreatorUin 创建人 UIN（建号时落库的 sub_account_uin；主账号自建时为主账号 uin）。 云上 CAPI 键名为 CreatorUin，恒为用户 ID；云下 REST 键名为 creatorId， 已解析到展示名（成员名 / 服务账号应用名）时直接下发展示名，否则仍为用户 ID。 
仅 DescribeAgent 读路径填充（mirrorToAgentInfo）——与 AccountId 同理，写路径回显该字段会被网关按出参白名单判为「未定义字段」；omitempty 保证写路径回包不含它。
creatorName
string
CreatorName 创建人名称，仅云下 REST，与 creatorId 同值（页面当前只读 creatorId， 名称字段供后续前端迁移消费）。未解析到时缺省，调用方按 creatorId 原值展示。
a2aConfig
﻿A2AConfig[]
A2AConfig A2A 对外互通配置与注册态（只读回显）。 四个字段原先平铺在 AgentInfo 上，收进结构后调用方按 A2AConfig.A2AEnabled 取值。不加 omitempty：A2AEnabled 无 omitempty 时恒输出 false， 「未开启 A2A」表现为「有对象、值为 false」；若让对象整体缺省，该语义会 退化成「字段缺失」，调用方的判空分支含义就变了。
ownership
﻿OwnershipOutput[]
Ownership 归属范围：仅云下 REST 回显（rest:"only" tag → 云上出参由框架裁剪， 见 protoout）。新增云下专属字段一律按这个方式加；通用字段仍受 CAPI 出参白名单约束 （未注册字段会让整个响应变 InternalError，例：A2A skills 走版本 Manifest，不在这里）。
clientEnabled
boolean
ClientEnabled 「客户端可见」开关：仅 DescribeAgent 读路径、仅创建人本人下发 （填充口径见 clientEnabledForCreator），前端据此决定详情页是否展示开关； 非创建人（含命中归属范围的成员）字段缺失。值为「创建人自己是否在客户端可见范围内」， 写入口是 ModifyAgentClientEnabled（可开可关）。
示例
输入示例
GET /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}
Authorization: Bearer pt_<YOUR_APP_KEY>
输出示例
{
  "code": 0,
  "data": {
    "a2aConfig": {
      "a2aEnabled": true,
      "a2aEndpoint": "https://a2a.example.com/card/736918300000000001",
      "a2aPublicRef": "ref_7f3c1a2b9d",
      "a2aStatus": "DRAFT"
    },
    "accountId": "1200345678901234567",
    "activeSessionCount": 2,
    "agentId": "736918300000000001",
    "agentName": "数据分析助手",
    "avatarUrl": "https://example.com/avatar/agent-001.png",
    "clientEnabled": true,
    "createdTime": "2026-10-20T09:30:00Z",
    "creatorId": "<REDACTED_USER>",
    "creatorName": "<REDACTED_USER>",
    "description": "负责每日数据汇总",
    "isDebug": false,
    "modifiedTime": "2026-10-20T09:30:00Z",
    "ownership": {
      "enforceMode": "default_off",
      "ownershipType": "all",
      "scopes": [
        {
          "scopeId": "1200345678901234567",
          "scopeName": "数据分析助手",
          "scopeType": "user"
        }
      ]
    },
    "routingSet": [
      {
        "versionId": "2087791755109965825",
        "weight": 1
      }
    ]
  },
  "msg": "OK",
  "requestId": "3c6d138e-1234-5678-9abc-def012345678"
}
错误码
说明：
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见错误响应与公共错误码。
错误码
说明
InternalError.AgentOperationFailed
Agent 操作失败
InvalidParameter.AgentIDRequired
缺少 AgentId
InvalidParameter.InvalidRequestBody
请求体不合法
MissingParameter.UinRequired
公共参数中缺少 Uin
ResourceNotFound.Agent
Agent 不存在
UnauthorizedOperation.UnprovisionedTenant
租户未开通，或企业不存在

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

字段	类型	说明
agentId	string	AgentId Agent 业务 ID，建号时生成，后续接口一律以它定位 Agent。
agentName	string	AgentName Agent 名称。
description	string	Description Agent 描述。
avatarUrl	string	AvatarUrl 头像地址，为空表示未设头像（由前端回落首字母头像）。
isDebug	boolean	IsDebug 是否为调试 Agent：工作台调试入口创建，不进入正式下发链路。
routingSet	RoutingItem[]	RoutingSet 流量路由配置。空路由输出空数组而非省略字段 —— 「未配置路由」与「字段缺失」对调用方语义不同，不能混同。
createdTime	string	CreatedTime 创建时间，UTC RFC3339。
modifiedTime	string	ModifiedTime 最后修改时间，UTC RFC3339。
activeSessionCount	integer	ActiveSessionCount 当前活跃 session 数（ACTIVE/CREATING/MIGRATING，未软删）。指针语义区分"未统计"与"统计为 0"：nil=未统计/降级（字段缺失），非 nil 含 0 显式输出。仅 DescribeAgent 读路径填充；写路径回显保持 nil，omitempty 不下发，避免触碰 CAPI 白名单。
accountId	string	AccountId 绑定的 OneID 企业账号 ID；空=未绑定（omitempty 下发缺省）。创建时可选传入，之后不可变。仅 DescribeAgent 读路径填充（mirrorToAgentInfo）：写路径回显该字段会被网关按出参白名单判为「未定义字段: AccountId」，整个响应变成 InternalError。详见 mergeToAgentInfo 的说明。
creatorId	string	CreatorUin 创建人 UIN（建号时落库的 sub_account_uin；主账号自建时为主账号 uin）。云上 CAPI 键名为 CreatorUin，恒为用户 ID；云下 REST 键名为 creatorId，已解析到展示名（成员名 / 服务账号应用名）时直接下发展示名，否则仍为用户 ID。仅 DescribeAgent 读路径填充（mirrorToAgentInfo）——与 AccountId 同理，写路径回显该字段会被网关按出参白名单判为「未定义字段」；omitempty 保证写路径回包不含它。
creatorName	string	CreatorName 创建人名称，仅云下 REST，与 creatorId 同值（页面当前只读 creatorId，名称字段供后续前端迁移消费）。未解析到时缺省，调用方按 creatorId 原值展示。
a2aConfig	A2AConfig[]	A2AConfig A2A 对外互通配置与注册态（只读回显）。四个字段原先平铺在 AgentInfo 上，收进结构后调用方按 `A2AConfig.A2AEnabled` 取值。不加 omitempty：`A2AEnabled` 无 omitempty 时恒输出 false，「未开启 A2A」表现为「有对象、值为 false」；若让对象整体缺省，该语义会退化成「字段缺失」，调用方的判空分支含义就变了。
ownership	OwnershipOutput[]	Ownership 归属范围：仅云下 REST 回显（`rest:"only"` tag → 云上出参由框架裁剪，见 protoout）。新增云下专属字段一律按这个方式加；通用字段仍受 CAPI 出参白名单约束（未注册字段会让整个响应变 InternalError，例：A2A skills 走版本 Manifest，不在这里）。
clientEnabled	boolean	ClientEnabled 「客户端可见」开关：仅 DescribeAgent 读路径、仅创建人本人下发（填充口径见 clientEnabledForCreator），前端据此决定详情页是否展示开关；非创建人（含命中归属范围的成员）字段缺失。值为「创建人自己是否在客户端可见范围内」，写入口是 ModifyAgentClientEnabled（可开可关）。

错误码	说明
`InternalError.AgentOperationFailed`	Agent 操作失败
`InvalidParameter.AgentIDRequired`	缺少 AgentId
`InvalidParameter.InvalidRequestBody`	请求体不合法
`MissingParameter.UinRequired`	公共参数中缺少 Uin
`ResourceNotFound.Agent`	Agent 不存在
`UnauthorizedOperation.UnprovisionedTenant`	租户未开通，或企业不存在

获取 Agent

本页目录：

接口描述

输入参数

路径参数

查询参数

请求体

输出参数

示例

输入示例

输出示例

错误码