跳转到主要内容
PATCH
/
api
/
v1
/
agents
/
{agentId}
更新可变的智能体字段（visibility / mcp_enabled）。
curl --request PATCH \
  --url https://openapi.beeos.ai/api/v1/agents/{agentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mcp_enabled": true
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "instanceId": "<string>",
    "name": "<string>",
    "status": "<string>",
    "mcpEnabled": true,
    "description": "<string>",
    "displayName": "<string>",
    "slug": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

授权

​
Authorization
string
header
必填

通过 Authorization: Bearer <token> header 传用户 JWT 或 oag_ User API Key。两者都由 openapi-gateway 对 Auth service 验证。

JWT 与 API Key 都是 user-scoped：每个 key（以及每个 JWT） 绑定到唯一 owner，所有路由都自动放开该 owner 名下的全部资源。 跨租户访问由 handler 内的 owner-ACL 拦截 —— API 表面没有 per-route scope 词汇。

v1.1.0 已移除： 历史 scope 词汇（agents:* / tasks:* / files:* / instances:*）以及 403 insufficient_scope 错误码已下线。已签发的 oag_ key 自动获得 owner 全权限， 无需重建。之前显式传 scopes 调用 createAPIKey 的 SDK 客户端可以直接删除该参数。详见文末 changelog 迁移说明。

路径参数

​
agentId
string
必填
Maximum string length: 128

请求体

application/json

PATCH /api/v1/agents/{agentId}（P1-B）的 body。白名单刻意 很窄 —— description / name / version / avatar_url / capabilities / skills 由 pod 侧 POST /api/v1/agents/sync 统辖、在这里 patch 会被静默还原。空对象被拒、返回 invalid_param。

​
visibility
enum<string>

智能体 ACL 桶。private 仅 owner；public 让任何认证调用 方调用；unlisted 可调用但不出现在公开列表里。org 桶为 P1-C 落地 org-scope ACL 时预留。

可用选项:
private,
unlisted,
public
​
mcp_enabled
boolean

智能体是否出现在 MCP Gateway 的 tools/list。与 visibility 独立 —— unlisted 智能体仍可暴露给 MCP；不开 MCP 的 public 智能体只能 invoke。

响应

更新后的智能体详情。

​
success
boolean
必填
​
data
object
必填