帮你快速理解、总结文档立即下载
文档中心>WorkBuddy Enterprise>WorkBuddy Managed Agents>OpenAPI>Agent 管理相关接口>修改 Agent

修改 Agent

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

本页目录：

接口描述

修改 Agent 的名称、描述、头像与归属范围；未传的字段保持不变（Manifest 请通过版本接口修改）。
PUT /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}

输入参数

路径参数

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

查询参数

无

请求体

ModifyAgentRequest 请求体。
字段
类型
说明
agentName
string
新的 Agent 名称，2~50 个字符；不传表示不改。
description
string
新的描述；不传表示不改，传空串表示清空。
avatarUrl
string
新的头像地址；不传表示不改，传空串表示清空。
ownership
资产归属范围（可选），为全量替换语义：不传 = 保持既有配置；传了 = 以传入内容整体替换（明细不能为空）。

输出参数

（200，业务出参包装在 code / data / msg / requestId 中）
字段
类型
说明
agentId
string
Agent 业务 ID，创建后由服务端生成，后续接口都用它定位 Agent。
agentName
string
Agent 名称。
description
string
Agent 描述。
avatarUrl
string
头像地址，为空表示未设置。
isDebug
boolean
是否为调试 Agent：从调试入口创建，不进入正式下发流程。
routingSet
版本流量路由；未配置路由时返回空数组。
createdTime
string
创建时间，UTC RFC3339。
modifiedTime
string
最后修改时间，UTC RFC3339。
activeSessionCount
integer
当前活跃会话数（状态为 ACTIVE / CREATING / MIGRATING）。未统计时不返回该字段；统计结果为 0 时返回 0。
accountId
string
绑定的 OneID 企业账号 ID；未绑定时不返回该字段，绑定后不可修改。
creatorId
string
创建人标识：能解析到成员时下发成员名，否则下发用户 ID。
creatorName
string
创建人展示名；未解析到时为空。
a2aConfig
A2AConfig
A2A 对外互通配置与注册状态；未开启时 a2aEnabled 为 false。
ownership
资产归属范围；未配置时不返回该字段。
clientEnabled
boolean
当前调用方在客户端是否可见：true 可见，false 不可见；仅创建人查询时返回。

示例

输入示例

PUT /v2/enterprises/{enterpriseId}/managedagent/agents/{agentId}
Authorization: Bearer pt_<YOUR_APP_KEY>
Content-Type: application/json

{
  "AgentId": "736918300000000001",
  "AgentName": "数据分析助手",
  "AvatarUrl": "https://example.com/avatar/agent-001.png",
  "Description": "负责每日数据汇总",
  "Ownership": {
    "EnforceMode": "default_off",
    "OwnershipType": "all",
    "Scopes": [
      {
        "ScopeId": "1200345678901234567",
        "ScopeName": "数据分析助手",
        "ScopeType": "user"
      }
    ]
  }
}

输出示例

{
  "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"
}

错误码

说明：
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见错误响应与公共错误码。
错误码
说明
FailedOperation.RoutingInvalidVersion
路由项必须引用同一 Agent 下未停用的 prod 版本
InternalError.AgentOperationFailed
Agent 操作失败
InvalidParameter.AgentIDRequired
缺少 AgentId
InvalidParameter.AgentNameLength
AgentName 长度必须在 2~50 个字符之间
InvalidParameter.InvalidRequestBody
请求体不合法
InvalidParameter.NoUpdatableField
没有可更新的字段（Manifest / Model / Description 至少传一个）
InvalidParameter.Ownership
资产归属范围参数不合法
MissingParameter.UinRequired
公共参数中缺少 Uin
ResourceInUse.AgentIDConflict
Agent ID 冲突
ResourceNotFound.Agent
Agent 不存在
ResourceUnavailable.RuntimeAPIUnavailable
未配置 agentos 运行时 API
UnauthorizedOperation.UnprovisionedTenant
租户未开通，或企业不存在
中国站