本章是各接口用到的结构定义，字段名统一小驼峰；某个接口具体能传哪些字段，以该接口的“输入参数”为准。
A2AConfig
Agent 的 A2A 对外互通配置与注册态。随 Agent 详情下发：a2aEnabled 恒返回，其余字段在未注册时为空。
字段 | 类型 | 说明 |
a2aEnabled | boolean | A2A 对外互通开关；恒返回，未开启时为 false。 |
a2aPublicRef | string | 对外 A2A handle，A2A 已注册时下发，未注册为空。 |
a2aEndpoint | string | 对外 A2A Card 发现地址，A2A 已注册时下发，未注册为空。 |
a2aStatus | string | A2A 注册态：DRAFT / REGISTERED / DISABLED / NONE / UNKNOWN。 |
A2ASkillInput
A2A 能力宣告条目：写入时带标签 / 示例 / 输入输出模态，读取时只回标识、名称与描述。
字段 | 类型 | 说明 |
a2aSkillId | string | 能力 ID。加 A2A 前缀以与技能管理中的 skillId 区分。 |
name | string | 能力名称，对外宣告时展示。 |
description | string | 能力描述。 |
tags | string[] | 能力标签，供检索与分类。 |
examples | string[] | 能力示例输入，用于向调用方说明用法。 |
inputModes | string[] | 支持的输入模态（A2A 约定，如 text/plain）。 |
outputModes | string[] | 支持的输出模态（A2A 约定，如 text/plain）。 |
A2ASkillItem
外部 Agent 的能力声明（A2A Agent Card 里的 skills 子集）。能力标识用 a2aSkillId，与技能管理里的 skillId 区分。
字段 | 类型 | 说明 |
a2aSkillId | string | A2ASkillId 能力 ID，对外宣告时作为唯一标识。 |
name | string | Name 能力名称。 |
description | string | Description 能力描述。 |
AgentInfo
Agent 详情。routingSet 里的 versionId 以字符串下发。
字段 | 类型 | 说明 |
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 不可见；仅创建人查询时返回。 |
AgentItem
Agent 列表项：携带最新版本的轻量摘要（latestVersionId / latestVersionName / model），完整版本信息走版本查询接口。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID，创建后由服务端生成，后续接口都用它定位 Agent。 |
agentName | string | Agent 名称。 |
description | string | Agent 描述。 |
avatarUrl | string | 头像地址，为空表示未设头像。 |
createdTime | string | 创建时间，UTC RFC3339。 |
modifiedTime | string | 最后修改时间，UTC RFC3339。 |
a2aEnabled | boolean | A2A 对外互通开关；恒返回，未开启时为 false。 |
a2aEndpoint | string | 对外 A2A Card 发现地址；未开启或未注册时为空。 |
a2aStatus | string | A2A 注册状态：DRAFT / REGISTERED / DISABLED / NONE / UNKNOWN。 |
publicApiEnabled | boolean | 公网访问开关；恒返回，未开启时为 false。 |
publicApiUrl | string | 公网访问地址，形如 https://{agentId}.{endpoint_suffix}；未配置后缀时为空。 |
creatorId | string | 创建人标识：能解析到成员时下发成员名，否则下发用户 ID。 |
creatorName | string | 创建人展示名；未解析到时为空，此时可展示 creatorId。 |
accountId | string | 绑定的 OneID 企业账号 ID；未绑定时不返回该字段，绑定后不可修改。 |
sessionCount | integer | 历史会话总数（含全部状态，不含已删除）。 |
model | string | 最新版本使用的模型标识；Agent 尚无版本时为空。 |
latestVersionId | string | 最新版本的版本 ID；Agent 尚无版本时为空。 |
latestVersionName | string | 最新版本的展示名（test / prod 等）；Agent 尚无版本时为空。 |
agentSource | string | Agent 来源：wb（本企业自建）/ wma（其他企业推送而来）。仅在查询时按来源筛选才返回，用于区分混排结果中每一行的来源。 |
syncToWma | boolean | 对话回显开关；仅 wma 来源的 Agent 返回。 |
ownership | 资产归属范围，语义同 Agent 详情；只对超级管理员或创建人返回。 | |
clientEnabled | boolean | 是否下发到客户端；仅按来源筛选时返回。 |
clientVisibility | 客户端可见范围（与 ownership 是两份独立配置），与 clientEnabled 同条件下发；未配置范围时 visibilityType 为 all。 |
AgentVersionItem
版本列表项。
字段 | 类型 | 说明 |
versionId | string | VersionId 版本 ID，归属某一 Agent。 |
versionName | string | VersionName 版本名称（test / prod 等展示名）。 |
versionType | string | VersionType 版本类型：DEFAULT / TEST / PROD。 |
model | string | Model 版本使用的模型标识。 |
sandboxTemplateId | string | SandboxTemplateId 沙箱模板 ID，仅沙箱后端版本有值。 |
status | string | Status 版本状态：ENABLED / DISABLED。 |
sessionCount | integer | SessionCount 该版本累计承接的会话总数。 |
createdTime | string | CreatedTime 创建时间，UTC RFC3339。 |
modifiedTime | string | ModifiedTime 最后修改时间，UTC RFC3339。 |
BindExternalAgentRequest
把外部 agent 绑定到某 managed agent。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID，由路径参数注入。 |
a2aAgentId | string | 要绑定的外部 Agent 公开引用 ID（取自外部 Agent 列表的 a2aAgentId）。 |
versionId | string | 指定这条绑定生效的版本，缺省为 default 版本。指定的版本必须属于本 Agent，否则返回 ResourceNotFound.Version。 |
BuiltinModelItem
内置模型列表项。
字段 | 类型 | 说明 |
modelId | string | 模型 ID，创建 / 修改 Agent 时填在 model 字段。 |
name | string | 模型展示名。 |
vendor | string | 模型厂商。 |
maxOutputTokens | integer | 单次输出最大 token 数。 |
maxInputTokens | integer | 单次输入最大 token 数（上下文窗口）。 |
supportsToolCall | boolean | 是否支持工具调用（function calling）。 |
supportsImages | boolean | 是否支持图片输入。 |
supportsThinking | boolean | 是否支持思考能力；支持时可在 manifest 的 thinking.level 中配置档位。 |
thinkingLevels | string[] | 可选强度 MINIMAL/LOW/MEDIUM/HIGH/XHIGH/MAX，不含关闭；空数组表示不能调强度。 |
defaultThinkingLevel | string | 默认强度；空串表示未声明。 |
canDisableThinking | boolean | 是否提供「关闭」。 |
descriptionZh | string | 模型中文描述。 |
descriptionEn | string | 模型英文描述。 |
tags | string[] | 模型标签，供检索与分类。 |
clients | string[] | 支持该模型的客户端列表。 |
serviceEndpoint | string | 模型服务地址（本环境统一配置）。 |
status | string | 状态：ENABLED / DISABLED。 |
agentCount | integer | 是本企业内绑定该模型的 Agent 数（已过滤软删除 Agent/版本与调试 Agent）。 |
ChatEndpoint
聊天接入点。
字段 | 类型 | 说明 |
endpointType | string | 接入点类型，当前为 PUBLIC（公网）。 |
url | string | 接入点地址。 |
ClientVisibilityOutput
客户端可见范围出参。
字段 | 类型 | 说明 |
visibilityType | string | 可见范围类型：all（全员）/ none（不可见）/ scope_list（按明细指定）。 |
scopes | none / all 时为空；scope_list 时为配置的明细。 |
ClientVisibilityScopeOutput
客户端可见范围明细出参。
字段 | 类型 | 说明 |
scopeType | string | ScopeType 可见范围类型：user / department / group。 |
scopeId | string | ScopeId 范围对象 ID。 |
scopeName | string | ScopeName 范围对象展示名，解析不到时缺省。 |
ConnectorInfo
连接器详情（基础信息 + 最新版本）。
字段 | 类型 | 说明 |
headerMappings | 请求头映射规则：把指定来源值复制到 MCP 请求的目标 header。 | |
connectorId | string | 连接器 ID（控制台连接器目录无此字段，恒为空）。 |
connectorSlug | string | 连接器 slug（控制台连接器目录无此字段，恒为空）。 |
connectorKey | string | 连接器 key，在 manifest 中引用连接器时使用（控制台连接器目录无此字段）。 |
name | string | 连接器名称。控制台连接器目录下为存储名（含 scope 前缀，如 enterprise_xxx），不用于展示；展示请用 displayName。 |
displayName | string | 展示名：取连接器的展示名配置，未配置时回落存储名。 |
description | string | 连接器描述。 |
avatarUrl | string | 连接器头像地址。 |
source | string | 来源：OFFICIAL（官方）/ ENTERPRISE（企业）/ PERSONAL（个人）。 |
enterpriseId | string | 上游归属键。连接器挂在主账号下，故此处回显的即调用方主账号 UIN。 |
type | string | 连接器类型：MCP_SERVER / A2A / API_SERVICE。 |
serviceUrl | string | 连接器服务地址（上游 MCP / A2A 服务 URL）；控制台连接器目录下为空。 |
authModes | string[] | 授权方式：NONE / ONEID / OAUTH2_IDP / API_KEY / DYNAMIC_API_KEY；控制台连接器目录可能额外返回 MCP_OAUTH。 |
latestVersionNo | integer | 最新版本号；控制台连接器目录下为空。 |
status | string | 连接器状态：ACTIVE / DISABLED；控制台连接器目录只返回可用（ACTIVE）的条目。 |
creatorId | string | 创建人 ID。 |
createdTime | string | 创建时间，UTC RFC3339。 |
modifiedTime | string | 最后修改时间，UTC RFC3339。 |
authInjectType | string | AuthInject 注入方式（BEARER 型回显缺省 Bearer 前缀口径）。 |
authHeaderName | string | 自定义注入时使用的 header 名；authInjectType=BEARER 时为空。 |
authValuePrefix | string | 凭据值前缀（如 Bearer ）；为空表示不加前缀。 |
bindable | boolean | / unbindableReason / mirrorExists 仅控制台连接器目录返回：表示该连接器能否用当前企业凭据绑定，以及本企业是否已有绑定记录。 |
unbindableReason | string | 不可绑定原因，bindable=false 时给出。 |
mirrorExists | boolean | 本企业是否已有绑定镜像（已有 Agent 以绑定方式使用）。 |
vpcConfigId | string | 最新版本的出站 VPC 网络配置；空 = 公网。 |
ConnectorRefInput
连接器引用入参：按 connectorId 定位连接器。
字段 | 类型 | 说明 |
connectorId | string | 连接器 ID，字符串形式的数字 ID。 |
ConsoleConnectorCredentialInput
绑定凭据入参。
字段 | 类型 | 说明 |
credentialId | string | 凭据 ID（OneID alias_id）。 |
credentialType | string | OAUTH2_IDP \\| API_KEY；缺省按连接器 auth_type 推导。 |
ConsoleConnectorRefInput
控制台连接器选择入参。
字段 | 类型 | 说明 |
name | string | 连接器存储名，用于指定要绑定的连接器。 |
credential | 绑定时使用的凭据；不传表示不为该连接器绑定凭据，运行时使用会话用户自己的凭据。 |
CreateAgentRequest
创建 Agent 时同时写入 default 版本；Agent 首次对外可用还需创建 test / prod 版本并设置版本路由。
字段 | 类型 | 说明 |
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 = 不下发；不传 = 默认下发且不限可见范围。 |
CreateAgentSessionRequest
CreateAgentSessionRequest 对应 /CreateAgentSession 请求体。
字段 | 类型 | 说明 |
agentId | string | AgentId Agent 业务 ID（必填）。 |
versionId | string | 指定版本 ID（可选）。传了就用该版本，不再按路由权重挑选；不传则按 Agent 的版本路由决定。 |
CreateAgentSessionResponse
会话创建出参：返回会话 ID、所属版本与聊天接入点。
字段 | 类型 | 说明 |
sessionId | string | SessionId 新建会话的 ID，后续对话与查询均以它定位。 |
endpointSet | 可用的聊天接入点列表，至少包含一个公网接入点。 |
CreateAgentVersionFromSourceRequest
基于源版本（default / test / prod）创建新版本：manifest / model / description 传入即整体覆盖，未传则沿用源版本；落 test 或 prod 由 isTest 决定。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID（必填）。 |
sourceVersionId | string | 源版本 ID（必填），同 Agent 下未 DISABLED 的任意版本。 |
isTest | boolean | 新版本类型：true=test，false=prod；未传默认创建 test 版本。 |
model | string | 可选，覆盖源版本的 model。 |
description | string | 可选，覆盖源版本的 description。 |
manifest | string | 可选，完整 v2.0 manifest JSON 字符串；传入则整体覆盖源版本 manifest。 |
sandboxTemplateId | string | 可选，覆盖源版本的沙箱模板 ID；仅沙箱后端版本有意义。 |
CreateAgentVersionRequest
完全新建版本：外部准备完整 manifest 后直接传入，不引用任何已有版本。isTest=true 落 test，isTest=false 落 prod（都是 status=ENABLED 冻结快照）。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID（必填）。 |
model | string | 模型标识。 |
manifest | string | v2.0 精简 manifest 原文（JSON 对象序列化后的字符串），必填。 |
description | string | 版本变更说明。 |
isTest | boolean | 版本类型：true=test，false=prod；未传默认创建 test 版本。 |
sandboxTemplateId | string | 沙箱模板 ID，仅 backend=SANDBOX 时使用；缺省由服务端选择默认模板。 |
backend | string | 版本运行时后端：LAMP（存算分离）/ SANDBOX（沙箱），缺省 LAMP；创建后不可修改。 |
DeleteAgentRequest
对应 /DeleteAgent 请求体。
字段 | 类型 | 说明 |
agentId | string | AgentId Agent 业务 ID，由路径参数注入。 |
DeleteSessionArtifactListRequest
删除会话物料：sessionId（清空该会话全部物料）与 artifactIdSet（按 ID 批量删除，跨会话生效）二选一。
字段 | 类型 | 说明 |
sessionId | string | 非空时删除该会话的全部物料。 |
artifactIds | string[] | 要删除的物料 ID，单次上限 100 条（去重后计数）。 |
DeleteSessionArtifactListResponse
字段 | 类型 | 说明 |
deletedCount | integer | 实际删除的物料数，已删除或不存在的 id 不计入。 |
DescribeAgentListRequest
对应 /DescribeAgentList 请求体。
字段 | 类型 | 说明 |
sortBy | string | 排序字段。 |
sortDirection | string | 排序方向：asc / desc。 |
DescribeAgentListResponse
对应 /DescribeAgentList 响应体。
字段 | 类型 | 说明 |
totalCount | integer | TotalCount 符合条件的 Agent 总数（过滤后、分页前）。 |
agentSet | AgentSet 当前页的 Agent 列表。 |
DescribeAgentRequest
对应 /DescribeAgent 请求体。
字段 | 类型 | 说明 |
agentId | string | AgentId Agent 业务 ID，由路径参数注入。 |
DescribeAgentSessionListRequest
对应 /DescribeAgentSessionList 请求体。
字段 | 类型 | 说明 |
sortBy | string | 排序字段：CREATED_AT / UPDATED_AT / LAST_ACTIVE_AT。 |
sortDirection | string | 排序方向：ASC / DESC。 |
DescribeAgentSessionListResponse
会话列表出参。
字段 | 类型 | 说明 |
totalCount | integer | 符合条件的会话总数（过滤后、分页前）。 |
sessionSet | 当前页的会话列表。 |
DescribeAgentSessionRequest
字段 | 类型 | 说明 |
sessionId | string | SessionId 会话 ID（必填）。 |
DescribeAgentSessionResponse
字段与列表项一致，额外返回 endpointSet。
字段 | 类型 | 说明 |
sessionId | string | 会话 ID。 |
sessionName | string | 会话名称（暂无来源时为空）。 |
agentId | string | Agent 业务 ID。 |
agentName | string | Agent 名称。 |
versionId | string | 会话绑定的版本 ID；创建时未显式指定（由系统按路由权重自选）时为空字符串。 |
versionName | string | 会话使用的版本名称（与 versionId 区分：此为版本名，非 ID）。 |
status | string | 会话状态：CREATING / ACTIVE / IDLE / MIGRATING / FAILED / ARCHIVED。 |
creator | string | 会话发起人用户 ID（与 Skill 侧 creatorId「资源作者」语义不同）。 |
source | string | 创建来源：CLOUD（云端自建）/ CHANNEL（渠道）/ SCHEDULED_TASK（自动化任务）/ A2A（A2A 调用）。 |
endpointSet | 可用的聊天接入点列表（仅查询会话详情时返回，结构与创建会话响应一致）。 | |
createdTime | string | 会话创建时间，UTC RFC3339。 |
modifiedTime | string | 会话最后修改时间，UTC RFC3339。 |
DescribeAgentVersionListRequest
版本列表查询：versionType 可取 DEFAULT / TEST / PROD，缺省返回全部。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID，由路径参数注入。 |
DescribeAgentVersionListResponse
对应 /DescribeAgentVersionList 响应体。
字段 | 类型 | 说明 |
totalCount | integer | TotalCount 符合条件的版本总数（过滤后、分页前）。 |
agentVersionSet | 版本列表。字段名带实体前缀，与 Skill 版本列表的 versionSet 区分。 |
DescribeAgentVersionRequest
对应 /DescribeAgentVersion 请求体。
字段 | 类型 | 说明 |
agentId | string | AgentId Agent 业务 ID，由路径参数注入。 |
versionId | string | VersionId 版本 ID，由路径参数注入。 |
DescribeBuiltinModelsRequest
字段 | 类型 | 说明 |
accountId | string | 可选。传入时按 (enterpriseId, accountId) 走授权门禁并解析出对应企业的 EnterpriseID，用于调用 copilot 拉模型；未传则使用调用方 enterpriseID。 |
DescribeBuiltinModelsResponse
字段 | 类型 | 说明 |
totalCount | integer | TotalCount 符合条件的模型总数（过滤后、分页前）。 |
builtinModelSet | BuiltinModelSet 当前页的内置模型列表。 |
DescribeConsoleConnectorListRequest
控制台连接器目录查询入参：过滤与分页规则与连接器列表一致。
空结构。
DescribeConsoleConnectorListResponse
控制台连接器目录出参：name 为存储名，displayName 为展示名（未配置时回落存储名），source 取 OFFICIAL / ENTERPRISE / PERSONAL。
字段 | 类型 | 说明 |
totalCount | integer | TotalCount 符合条件的连接器总数（过滤后、分页前）。 |
connectorSet | ConnectorSet 当前页的连接器列表。 |
DescribeExpertListReq
专家列表查询：expertId 可重复传多个，传入后按 ID 批量反查并忽略分页；否则分页返回。
字段 | 类型 | 说明 |
source | string | 专家来源，必填：BUILTIN（内置）/ CUSTOM（自建）。 |
DescribeExpertsResp
字段 | 类型 | 说明 |
maxBindings | integer | 单个 Agent 最多可绑定的专家数。 |
totalCount | integer | 符合条件的专家总数（按 ID 批量查询时 = 实际命中数） |
expertSet | 专家列表 | |
counts | 全局计数（不受 keyword 影响） |
DescribeExternalAgentRequest
查询某 Managed Agent 绑定的单个外部 Agent 详情。
字段 | 类型 | 说明 |
agentId | string | AgentId Agent 业务 ID，由路径参数注入。 |
a2aAgentId | string | A2AAgentId 外部 Agent 的公开引用 ID，由路径参数注入。 |
DescribeMessageEventListRequest
查询指定 Session 的标准化消息事件。
字段 | 类型 | 说明 |
subAgentId | string | 可选，只看指定子 Agent 产生的事件。 |
agentId | string | Agent 业务 ID（必填）。 |
sessionId | string | 会话 ID（必填）。 |
DescribeMessageEventListResponse
消息事件列表出参。
字段 | 类型 | 说明 |
totalCount | integer | 该会话的消息事件总数（分页前）。 |
messageEventSet | 当前页的消息事件列表，按 sequence 升序。 |
DescribeSessionArtifactDownloadUrlRequest
只为 READY 且未过保留期的物料签发链接，链接有效期不超过物料过期时间。
字段 | 类型 | 说明 |
artifactId | string | 物料 ID，必填。 |
expiredSeconds | integer | 链接有效期，单位秒；缺省 3600，取值 60 ~ 86400。 |
DescribeSessionArtifactDownloadUrlResponse
字段 | 类型 | 说明 |
downloadUrl | string | 限时预签名 GET 下载链接。 |
expiredTime | string | 链接过期时间，RFC3339 UTC。 |
fileName | string | 文件名。 |
fileSizeBytes | integer | 文件大小，单位字节。 |
fileSha256 | string | 文件 SHA256 摘要。 |
DescribeSessionArtifactListRequest
会话物料列表查询：artifactId 可重复传多个，传入后按 ID 批量反查并忽略分页；否则按 page / pageSize 分页。
字段 | 类型 | 说明 |
sessionId | string | 必填。 |
DescribeSessionArtifactListResponse
字段 | 类型 | 说明 |
totalCount | integer | 符合条件的物料总数，按 ID 批量查询时即命中数。 |
artifactSet | 物料列表；无数据时返回空数组。 |
DescribeSkillListReq
技能列表查询：按 source（BUILTIN / CUSTOM / AUTHORIZED）走对应数据通路；skillId 可重复传多个，传入后按 ID 批量反查，否则分页返回。
字段 | 类型 | 说明 |
source | string | 技能来源，必填：BUILTIN（内置）/ CUSTOM（自建）/ AUTHORIZED（企业授权）。 |
accountId | string | 授权方标识；仅 source=AUTHORIZED 时生效。不传：后端用 enterpriseId 自动推导全部已获授权范围内的 skill；传了：在自动推导基础上收窄到该 accountId 对应的单个授权方。 |
agentId | string | 可选；仅 source=AUTHORIZED 时生效。Agent 绑定 OneID 租户时，授权集合会收窄到该租户（此时传入的 accountId 必须与绑定值一致）。 |
DescribeSkillListResp
DescribeSkillListResp DescribeSkillList 响应体（TCAPI Data 字段）。
字段 | 类型 | 说明 |
totalCount | integer | Total 符合条件的技能总数 |
skillSet | Items 技能列表 | |
counts | Counts 全局计数（不受 keyword 影响） |
DescribeUserAccessTokenResponse
查询用户级 access_token 响应体。
字段 | 类型 | 说明 |
accessToken | string | 用户本人的访问凭证，用于连接数据面（ACP 对话），原样下发。 |
tokenType | string | 凭证类型，目前固定 Bearer。 |
expiresIn | integer | 凭证有效期，单位：秒；无法从凭证解析出有效期时返回 0。 |
scope | string | 凭证可访问用户信息的范围。 |
ExpertCounts
ExpertCounts 全局专家计数。
字段 | 类型 | 说明 |
builtin | integer | Builtin 内置专家数量。 |
custom | integer | Custom 自定义专家数量。 |
total | integer | Total 专家总数（内置 + 自定义）。 |
ExpertItem
Expert 资源信息（列表项与详情共用）。
字段 | 类型 | 说明 |
expertId | string | 专家标识（原 ItemRef，标识字段统一 XxxId 形态）。 |
source | string | 专家来源：BUILTIN（内置）/ CUSTOM（自建）。 |
expertType | string | 专家形态：AGENT（普通专家）/ TEAM（专家团，暂不支持绑定到 Agent）。 |
name | string | slug（仅 custom 返回）。 |
displayName | string | 展示名。 |
description | string | 描述。 |
icon | string | 图标 URL。 |
expertVersion | string | 版本号（原 Version；与 skill 侧 skillVersion 同款命名口径，消除与 versionId 等标识类字段的歧义）。 |
categoryId | string | 分类 ID。 |
categoryName | string | 分类名（仅 builtin 直接返回）。 |
publishStatus | string | 发布状态：DRAFT / PUBLISHED（仅 custom）。 |
enabled | boolean | 是否启用。 |
disabledReason | string | 禁用原因。 |
downloadUrl | string | 下载 URL。 |
updatedBy | string | 更新者 ID。 |
status | string | 启停状态：ENABLED / DISABLED（大写枚举）。 |
zipFileName | string | zip 文件名。 |
zipSizeBytes | string | zip 大小（字节，字符串序列化的 int64，避免 JS 超长精度问题）。 |
zipMd5 | string | zip MD5。 |
zipSha256 | string | zip SHA256。 |
modifiedTime | string | 更新时间（RFC3339 格式，时间戳收尾）。 |
ExternalAgentItem
外部 Agent 摘要。
字段 | 类型 | 说明 |
a2aAgentId | string | 外部 Agent 的公开引用 ID（注册中心分配），绑定 / 解绑 / 详情查询都以它为定位键。URL 直连型绑定没有公开引用。 |
bindingId | string | 本企业与该外部 Agent 的绑定记录 ID。解绑时推荐直接传它，服务端可直接定位，无需再按 a2aAgentId 反查；未绑定时为空。 |
name | string | 外部 Agent 名称，取自对端 Agent Card 的 name。 |
description | string | 外部 Agent 描述，取自对端 Agent Card 的 description，对端未提供时为空。 |
iconUrl | string | 头像地址，取自 provider card 的 iconUrl（A2A v1.0 §4.4.1）。为空表示该 Agent 未设头像。 |
endpoint | string | 外部 A2A Server URL。 |
a2aVersion | string | 外部 Agent Card 声明的版本号。 |
a2aSkillSet | 外部 Agent 声明的能力列表（Agent Card skills），绑定后可作为子 Agent 的能力被调用。 | |
bound | boolean | 本企业是否已绑定该外部 Agent。列表缺省返回「已绑定 + 未绑定」合并视图，需要只取其一时可传查询参数 bound=BOUND / UNBOUND。 |
latestVersionName | string | 子 Agent 的最新版本名：优先取最新的 prod 版本，其次 test，最后 default。仅企业 Agent 来源有值；其他来源或解析失败时为空，调用方可回落 a2aVersion 展示。 |
HeaderMapping
把上游返回的某个值复制到指定 MCP 请求头。
字段 | 类型 | 说明 |
sourceKey | string | SourceKey 来源键：从上游返回的哪个值取数。 |
targetHeader | string | TargetHeader 目标 header：取到的值写入 MCP 请求的该 header。 |
ListExternalAgentsRequest
外部 Agent 查询入参：bound 取 BOUND / UNBOUND，缺省返回已绑定与未绑定的合并视图。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID（必填：绑定状态的归属主体）。 |
versionId | string | 按 Agent 的指定版本查询绑定，缺省为 default 版本。返回该版本的绑定加上对该 Agent 所有版本生效的绑定；版本不属于本 Agent 时返回 ResourceNotFound.Version。 |
ListExternalAgentsResponse
外部 Agent 列表出参。
字段 | 类型 | 说明 |
totalCount | integer | TotalCount 符合条件的外部 Agent 总数（过滤后、分页前）。 |
externalAgentSet | ExternalAgentSet 当前页的外部 Agent 列表。 |
Message
表示用户输入或 Assistant 输出。
字段 | 类型 | 说明 |
content | string | 消息正文。 |
tokenUsage | 模型用量，仅 ASSISTANT 消息有值。 |
MessageEvent
MessageEvent 是由会话历史标准化得到的判别联合结构。 USER/ASSISTANT 只返回 Message，TOOL 只返回 ToolCall。
字段 | 类型 | 说明 |
sequence | integer | Sequence 事件在会话内的递增序号，按它排序即为对话顺序。 |
eventType | string | EventType 事件类型：USER / ASSISTANT / TOOL；决定 Message 与 ToolCall 哪个有值。 |
occurredAt | string | OccurredAt 事件发生时间，UTC RFC3339；上游缺失时为空。 |
message | Message 用户输入或 Assistant 输出，仅 USER / ASSISTANT 事件有值。 | |
toolCall | ToolCall 工具调用记录，仅 TOOL 事件有值。 |
MigrateAgentSessionRequest
把会话迁到同一 Agent 下的指定版本；agentId 必须与会话当前所属 Agent 一致，不支持跨 Agent 迁移。
字段 | 类型 | 说明 |
sessionId | string | SessionId 待迁移的会话 ID（必填）。 |
agentId | string | AgentId 目标 Agent 业务 ID（必填），必须与 Session 原 Agent 相同。 |
targetVersionId | string | TargetVersionId 目标版本 ID（必填，字符串形式）。需归属同一 Agent 且状态为 ENABLED。 |
MigrateAgentSessionResponse
sessionId 回显原值；status 为迁移后的新状态。客户端无需重新获取。
字段 | 类型 | 说明 |
sessionId | string | SessionId 被迁移的会话 ID。 |
status | string | Status 迁移后的会话状态（迁移成功为 MIGRATING，随后由运行时推进到 ACTIVE）。 |
ModifyAgentA2AConfigRequest
a2aEnabled 是 Agent 级唯一开关；a2aSkillSet 是 Agent 级能力宣告（card.skills 数据源），两者与具体版本和流量分发策略无关。a2aSkillSet 为 null/缺省时不修改，空数组时清空。
字段 | 类型 | 说明 |
agentId | string | AgentId Agent 业务 ID，由路径参数注入。 |
a2aEnabled | boolean | A2AEnabled 是否开启 A2A 对外互通；开启后服务端注册 card 并回填地址。 |
a2aSkillSet | A2ASkillSet 对外宣告的能力列表；不传表示不改，传空数组表示清空。 |
ModifyAgentRequest
agentName / description / avatarUrl 均为可选：仅传递需要更新的字段。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID，由路径参数注入。 |
agentName | string | 新的 Agent 名称，2~50 个字符；不传表示不改。 |
description | string | 新的描述；不传表示不改，传空串表示清空。 |
avatarUrl | string | 新的头像地址；不传表示不改，传空串表示清空。 |
ownership | 资产归属范围（可选），为全量替换语义：不传 = 保持既有配置；传了 = 以传入内容整体替换（明细不能为空）。 |
ModifyAgentRoutingRequest
所有 versionId 必须属于同 Agent 且状态为 ENABLED。routingSet 必须非空且每项 versionId 必须非空；下线 Agent 请通过其他接口，禁止用空 routingSet 全量下线。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID，由路径参数注入。 |
routingSet | 全量覆盖的流量路由配置，不能为空：要下调某版本流量请按权重调整，下线整个 Agent 请调用删除接口。 |
ModifyAgentVersionRequest
仅 default 或 test 版本可原地更新，prod 拒绝。三个可选字段必须至少提供一个非空。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID，由路径参数注入。 |
versionId | string | 版本 ID，由路径参数注入。 |
manifest | string | 新的 manifest 原文；不传表示不改。 |
model | string | 新的模型标识；不传表示不改。 |
description | string | 新的版本描述；不传表示不改，传空串表示清空。 |
sandboxTemplateId | string | 新的沙箱模板 ID；不传表示不改，仅沙箱后端版本有意义。 |
connectorSet | 该版本最终绑定的连接器集合（全量覆盖语义）：缺省 = 不改动；空数组 = 解绑全部；非空 = 以传入集合为准整体替换。 | |
consoleConnectors | 控制台连接器选择，三态语义与 connectorSet 一致。 |
OKResponse
操作确认（绑定 / 解绑）。
字段 | 类型 | 说明 |
status | string | 操作结果状态：BOUND（已绑定）/ UNBOUND（已解绑）。 |
bindingId | string | 本次绑定产生的绑定记录 ID，解绑时可直接使用。 |
OwnershipInput
创建 Agent 时的资产归属范围入参。user / department / group 三类范围平等叠加，部门范围包含其下级部门。
字段 | 类型 | 说明 |
ownershipType | string | 归属范围类型：all（归属企业全员）/ scope_list（按 scopes 控制）。缺省 = all。 |
enforceMode | string | 展示启停形态：''（正常）/ default_off / force_on。缺省 = ''。 |
scopes | ownership_type=scope_list 时的范围明细（至少一条）；all 时忽略。 |
OwnershipOutput
资产归属范围出参。只下发给能修改该配置的人（超管 / 资产创建人）；仅命中归属范围、无修改权限的成员不返回该字段。
字段 | 类型 | 说明 |
ownershipType | string | 归属范围类型：all（归属企业全员）/ scope_list（按 scopes 收敛）。 |
enforceMode | string | 展示启停形态：''（正常）/ default_off / force_on，缺省 ''。 |
scopes | 明细（ all 时为空数组；scope_list 时 ≥1 条，与写入侧校验一致）。 |
OwnershipScopeInput
归属范围明细入参：一条范围记录。
字段 | 类型 | 说明 |
scopeType | string | 维度：user（成员）/ department（部门，判定含祖先）/ group（用户组）。 |
scopeId | string | 维度对象 ID（用户 UUID / 部门 ID / 用户组 ID）。 |
scopeName | string | 展示名（冗余，回显用；可空）。 |
OwnershipScopeOutput
归属范围明细出参。
字段 | 类型 | 说明 |
scopeType | string | 范围类型：user（成员）/ department（部门）/ group（用户组）。 |
scopeId | string | 范围对象 ID：成员或部门的 ID，或用户组 ID。 |
scopeName | string | 范围对象展示名，解析不到时缺省。 |
RoutingItem
路由项：{versionId, weight}，weight 为 (0, 1] 之间的浮点百分比。入参与出参共用此类型，读回来的结构与写进去的一致。
字段 | 类型 | 说明 |
versionId | string | 参与路由的版本 ID，须归属同一 Agent。 |
weight | number | 该版本的流量权重，取值 (0, 1]；同一 Agent 下所有版本权重之和必须为 1。 |
SessionArtifactDetail
会话物料详情（列表项与详情共用）。
字段 | 类型 | 说明 |
artifactId | string | 物料 ID。 |
sessionId | string | 会话 ID。 |
agentId | string | Agent 业务 ID，UUID 格式。 |
fileName | string | 文件名。 |
filePath | string | 沙箱内的文件路径。 |
fileSizeBytes | integer | 文件字节数：READY 前为登记时的大小，READY 后为实际写入 COS 的大小。 |
fileSha256 | string | 文件 SHA256 摘要，READY 后才有值。 |
status | string | 物料状态：PENDING / READY / FAILED。 |
createdTime | string | 创建时间，RFC3339 UTC。 |
uploadedTime | string | 上传完成时间，RFC3339 UTC，未 READY 时为空串。平台描述写的是「更新时间」。 |
expiredTime | string | 物料过期时间，RFC3339 UTC。 |
SessionItem
会话列表项。
字段 | 类型 | 说明 |
sessionId | string | 会话 ID。 |
sessionName | string | 会话名称，暂无来源时为空。 |
agentId | string | 会话所属的 Agent 业务 ID。 |
agentName | string | 会话所属的 Agent 名称。 |
versionName | string | 会话使用的版本名称（与 versionId 区分：此为版本名，非 ID）。 |
versionId | string | 会话绑定的版本 ID（int64 转 string，防 JS 精度丢失）；创建时未显式指定（由系统按路由权重自选）时为空字符串。 |
status | string | 会话状态：CREATING / ACTIVE / IDLE / MIGRATING / FAILED / ARCHIVED。 |
creator | string | 会话发起人用户 ID（与 Skill 侧 creatorId「资源作者」语义不同）。 |
source | string | 创建来源：CLOUD（云端自建）/ CHANNEL（渠道）/ SCHEDULED_TASK（自动化任务）/ A2A（A2A 调用）。 |
createdTime | string | 会话创建时间，UTC RFC3339。 |
modifiedTime | string | 会话最后修改时间，UTC RFC3339。 |
SkillCounts
全局技能计数。
字段 | 类型 | 说明 |
builtin | integer | 内置技能数量。 |
custom | integer | 自定义技能数量。 |
total | integer | 技能总数（内置 + 自定义 + 已授权）。 |
SkillItem
Skill 列表项。只包含列表展示所需字段。
字段 | 类型 | 说明 |
skillId | string | 技能标识。 |
source | string | 技能来源：BUILTIN、CUSTOM（编排侧据此判定来源，不可用 downloadUrl 推导）。 |
name | string | slug（仅 custom 返回；列表名称列作副行展示）。 |
displayName | string | 展示名（列表名称列主行）。 |
description | string | 描述（列表描述列）。 |
icon | string | 图标 URL（列表名称列头像）。 |
skillVersion | string | 当前生效版本号。 |
downloadUrl | string | 产物下载地址：custom / authorized 为预签名 URL，builtin 为官方下发地址。 |
enabled | boolean | 是否启用（列表状态列：已启用 / 已停用）。 |
createTime | string | 创建时间（RFC3339）。内置技能取不到时间信息时为空。 |
updateTime | string | 更新时间（RFC3339）。内置技能取不到时间信息时为空。 |
TokenUsage
表示上游明确提供的模型 Usage。因此只挂在 ASSISTANT message 上。
字段 | 类型 | 说明 |
inputTokens | integer | 输入 token 数。 |
outputTokens | integer | 输出 token 数。 |
totalTokens | integer | 总 token 数（输入 + 输出）。 |
scope | string | 统计口径，目前固定 TURN（整轮模型调用），不可拆分归因到单个工具调用。 |
ToolCall
合并同一 toolCallId 的 function_call 与 function_call_result。input 和 output 为 JSON 字符串（如 "{\\"command\\":\\"ls\\"}"）。
字段 | 类型 | 说明 |
expertId | string | 该次调用归属的专家 ID；由专家技能发起时才有值。 |
expertName | string | 该次调用归属的专家名称。 |
expertVersion | string | 该次调用归属的专家版本。 |
subAgentId | string | 该次调用归属的子 Agent ID；子 Agent 嵌套调用时才有值。 |
subAgentName | string | 该次调用归属的子 Agent 名称。 |
parentToolCallId | string | 父级工具调用 ID；用于还原子 Agent 的嵌套调用树。 |
toolCallId | string | 工具调用 ID，function_call 与其结果按它合并成一条记录。 |
toolName | string | 工具名称。 |
status | string | 调用状态：PENDING / IN_PROGRESS / SUCCEEDED / FAILED。 |
input | string | 调用入参，JSON 字符串形式（如 "{\\"command\\":\\"ls\\"}"）。 |
output | string | 调用结果，JSON 字符串形式；无终态结果时为空。 |
startedAt | string | 调用发起时间，UTC RFC3339。 |
endedAt | string | 调用结束时间，UTC RFC3339；无终态结果时为空。 |
durationMs | integer | 调用耗时（毫秒），由 startedAt / endedAt 派生；无终态结果时为空。 |
UnbindExternalAgentRequest
解除绑定请求体。推荐传 bindingId：绑定与查询接口都会返回该字段，服务端可直接据此解绑。
字段 | 类型 | 说明 |
agentId | string | Agent 业务 ID，由路径参数注入。 |
a2aAgentId | string | Deprecated: 改用 bindingId。 |
bindingId | string | 绑定记录 ID，解绑推荐传它；服务端可直接定位，无需按 a2aAgentId 反查。 |
versionId | string | 指定在 Agent 的哪个版本下解绑，缺省为 default 版本。取值语义与绑定接口的 versionId 一致。 |
VersionInfo
版本详情。
字段 | 类型 | 说明 |
versionId | string | 版本 ID，归属某一 Agent。 |
agentId | string | 版本所属的 Agent 业务 ID。 |
versionName | string | 版本名称（test / prod 等展示名）。 |
versionType | string | 服务端派生：DEFAULT / TEST / PROD。 |
description | string | 版本描述。 |
model | string | 版本使用的模型标识。 |
manifest | string | 版本 manifest 原文（JSON 对象序列化后的字符串）。 |
sandboxTemplateId | string | 沙箱模板 ID，仅沙箱后端版本有值。 |
status | string | 版本状态：DRAFT / ENABLED / DISABLED。该字段恒返回，不会因未设置而缺省。 |
sessionCount | integer | 该版本累计承接的会话总数（历史累计值，只增不减）。仅在查询版本详情时返回。 |
createdTime | string | 创建时间，UTC RFC3339。 |
modifiedTime | string | 最后修改时间，UTC RFC3339。 |
