接口描述
创建一个 Agent，同时生成 default 版本作为初始配置；需要对外提供对话时再创建 prod 版本。
POST /v2/enterprises/{enterpriseId}/managedagent/agents输入参数
路径参数
参数 | 类型 | 说明 |
enterpriseId | string | WorkBuddy 企业 ID |
查询参数
无
请求体
字段 | 类型 | 说明 |
agentName | string | Agent 名称，必填，2~50 个字符。 |
description | string | Agent 描述，可选。 |
avatarUrl | string | 头像地址，可选。 |
model | string | 绑定的模型标识，必填，取值来自「列出内置模型」接口。 |
accountId | string | 绑定的 OneID 企业账号 ID，可选。必须是当前调用方已获授权的账号；绑定后不可修改。 |
manifest | string | 精简版 manifest 原文（JSON 对象序列化后的字符串），作为 default 版本的初始配置；不传时服务端生成一份不含 prompt 的最小配置，需要自定义人设或数据面对话时必须显式传入，至少包含 {"version":"2.0","prompt":"..."}。 |
sandboxTemplateId | string | 沙箱模板 ID，仅 backend=SANDBOX 时使用；缺省由服务端选择默认模板。 |
backend | string | default 版本的运行后端，取值 LAMP（存算分离）/ SANDBOX（沙箱），缺省 LAMP。只作用于创建时生成的 default 版本，后续版本在创建版本接口单独指定；创建后不可修改。 |
connectorSet | 随创建一并绑定的连接器集合，按传入内容整体写入。 | |
consoleConnectors | 控制台侧的连接器选择，按传入内容整体写入。 | |
ownership | 创建时一并写入的资产归属范围（可选）。不传则默认全员可见；传了则按传入内容写入（明细不能为空）。 | |
clientEnabled | boolean | 是否下发到 WorkBuddy 客户端，可选。true = 仅创建人本人可见并下发；false = 不下发；不传 = 默认下发且不限可见范围。 |
输出参数
（
201，业务出参包装在 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 | A2A 对外互通配置与注册状态；未开启时 a2aEnabled 为 false。 | |
ownership | 资产归属范围；未配置时不返回该字段。 | |
clientEnabled | boolean | 当前调用方在客户端是否可见：true 可见，false 不可见；仅创建人查询时返回。 |
示例
输入示例
POST /v2/enterprises/{enterpriseId}/managedagent/agentsAuthorization: Bearer pt_<YOUR_APP_KEY>Content-Type: application/json{"AgentName": "数据分析助手","Description": "负责每日数据汇总","AvatarUrl": "https://example.com/avatar/agent-001.png","Model": "hunyuan-turbos-latest","Manifest": "{\\"version\\":\\"2.0\\",\\"prompt\\":\\"你是数据分析助手，负责汇总运营数据。\\"}"}
输出示例
{"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.AgentAccountIDInvalid | AccountId 必须是去除首尾空白后的非空字符串，且不超过 64 个字符 |
InvalidParameter.AgentNameLength | AgentName 长度必须在 2~50 个字符之间 |
InvalidParameter.InvalidRequestBody | 请求体不合法 |
InvalidParameter.ManifestRequired | 缺少 Manifest |
InvalidParameter.Ownership | 资产归属范围参数不合法 |
MissingParameter.UinRequired | 公共参数中缺少 Uin |
ResourceInUse.AgentIDConflict | Agent ID 冲突 |
ResourceNotFound.Agent | Agent 不存在 |
ResourceUnavailable.RuntimeAPIUnavailable | 未配置 agentos 运行时 API |
UnauthorizedOperation.AccountNotAuthorized | 该 OneID 账号未被授权到当前主账号 |
UnauthorizedOperation.UnprovisionedTenant | 租户未开通，或企业不存在 |
