WorkBuddy Enterprise 提供了一套面向企业级 Agent 管理与会话编排的 OpenAPI 接口，用于创建和管理 Agent、发布 Agent 版本、发起会话并查询对话记录，以及查询可用的技能、模型、专家、连接器等资源。
基础约定
Base Path：
/v2/enterprises/{enterpriseId}/managedagent，enterpriseId 为 WorkBuddy 企业 ID。企业 ID 只能用路径参数声明 —— X-Enterprise-Id 是网关与 console 注入的内网可信头，客户端自报会被剥除，与控制台登录态不同，本面不接受 X-Tenant-Id 声明租户。成功响应统一包装为
{ "code": 0, "data": <业务出参>, "msg": "OK", "requestId": "..." }；业务错误 code 为字符串错误码（如 ResourceNotFound.Agent、UnauthorizedOperation.PermissionDenied），结构同上但 code 非 0。字段命名：请求体字段为首字母大写（PascalCase，如
AgentName）；响应字段为小驼峰（如 agentName），下文“响应”与“数据结构”表格均按响应口径列出。分页：列表接口统一使用
page（缺省 1）与 pageSize（缺省 20，上限 100）查询参数，返回 xxxSet 数组 + totalCount。服务端内部按 Offset/Limit 换算，数据结构章节里出现的 offset / limit 是内部字段，REST 调用方无需传。鉴权：只有应用身份与个人身份两类凭据，详见下节 认证方式。
认证方式
按调用方身份分为两类，接口路径与行为完全一致，差异只在身份与计费归属：
身份 | 凭据 | 请求形式 | 身份主体 | 计费归属 |
应用身份 | 开放平台应用 Key pt_ | Authorization: Bearer pt_<key> | 应用服务账号 | 应用所属企业 |
个人身份 | 个人 API Key | X-Api-Key: <keyID>.<secret> 或 Authorization: Bearer <keyID>.<secret>（keyID 以 ck_ 开头） | key 属主 | key 属主 |
应用身份：pt_
在开放平台应用管理侧生成（
POST /enterprises/{eid}/apikey/generate/{appId}），长期有效；网关用幻影 token 透明换签，调用方无需实现换票、续期与并发刷新。身份是应用服务账号，可访问范围与计费都归属应用所属企业。
说明：
建会话与迁移会话需要个人运行时凭据：
POST /agents/{agentId}/sessions、POST /agents/{agentId}/sessions/{sessionId}/migrate 在应用身份下用 pt_ 即可；若手上只有服务账号票（如 client_credentials 换的 access_token），会因为拿不到个人凭据而失败，请改用 pt_ 或个人身份 ck_。个人身份：ck_
在个人设置 - API Keys 创建，格式
<keyID>.<secret>（keyID 自带 ck_ 前缀）。身份是 key 属主：云下资源按“key 属主可见 / 写限属主创建（管理员除外）”收敛，数据面对话的积分消耗记在属主名下；key 等价于属主本人凭据，请妥善保管。
Authorization: Bearer <key> 与 X-Api-Key: <key> 两种传法都支持，同时出现时以 Authorization 为准；pt_ 则只认 Authorization，放进 X-Api-Key 会按 ck_ 口径校验并失败。通用约定
失败语义：凭据缺失 / 无效 / 过期 →
401；凭据所属企业与路径 {enterpriseId} 不一致 → 403；网关单 IP 触发限频（默认 600 次/秒）→ 429。与数据面的区别：
POST /user-access-token 下发的 access_token 用于连接数据面（ACP 对话），不是控制面凭据；控制面始终使用上表凭据。接口目录
分类 | 接口名称 | 方法与路径 |
外部 Agent 管理 | GET /agents/{agentId}/external-agents | |
| GET /agents/{agentId}/external-agents/{a2aAgentId} | |
| POST /agents/{agentId}/external-bindings | |
| DELETE /agents/{agentId}/external-bindings/{bindingId} | |
会话物料 | POST /artifacts/{artifactId}/download-url | |
| POST /artifacts/delete | |
| GET /sessions/{sessionId}/artifacts | |
对话记录 | POST /agents/{agentId}/sessions | |
| GET /agents/{agentId}/sessions/{sessionId} | |
| POST /agents/{agentId}/sessions/{sessionId}/migrate | |
| GET /message-events | |
| GET /sessions | |
版本管理 | GET /agents/{agentId}/versions | |
| POST /agents/{agentId}/versions | |
| GET /agents/{agentId}/versions/{versionId} | |
| PUT /agents/{agentId}/versions/{versionId} | |
| POST /agents/{agentId}/versions/from-source | |
Agent 管理 | POST /agents | |
| GET /agents | |
| GET /agents/{agentId} | |
| PUT /agents/{agentId} | |
| DELETE /agents/{agentId} | |
| PUT /agents/{agentId}/a2a-config | |
| PUT /agents/{agentId}/routing | |
Skill 管理 | GET /skills | |
模型管理 | GET /builtin-models | |
Expert 管理 | GET /experts | |
连接器管理 | GET /connectors | |
访问凭证 | POST /user-access-token | |
