Agent Runtime 数据结构

APIKeyInfo

API密钥简略信息

被如下接口引用：DescribeAPIKeyList。

名称	类型	必选	描述
Name	String	否	API密钥名称示例值：LocalDev
KeyId	String	否	API密钥ID 示例值：ark-3edcft6y
Status	String	否	密钥状态。可以为API_KEY_STATUS_ACTIVE，或API_KEY_STATUS_INACTIVE 示例值：API_KEY_STATUS_ACTIVE
MaskedKey	String	否	隐藏部分字符的API密钥，方便用户辨认示例值：ark_g9****ztdA
CreatedAt	String	否	API密钥创建时间示例值：2025-09-12T09:00:03.094Z

AccountQuotaOverview

主账号配额总览

被如下接口引用：DescribeQuotaOverview。

名称	类型	必选	描述
Quota	QuotaResourceInfo	否	主账号各资源维度的配额上限
Usage	QuotaResourceInfo	否	主账号各资源维度的当前用量

AffinityConfiguration

Deployment 对 Sandbox Instance 的亲和配置。

被如下接口引用：CreateDeployment, DescribeDeployment, DescribeDeploymentList, ModifyDeployment。

名称	类型	必选	描述
Mode	String	否	Affinity 模式。枚举值： BEST_EFFORT：优先复用原 Instance，不可用时允许改选。 STRICT：只复用原 Instance，不可用时失败且不改选。 EXCLUSIVE：一个 Affinity ID 独占一个 Instance，不能迁移。缺失或空字符串表示关闭 Affinity。示例值：EXCLUSIVE
HeaderName	String	否	请求和响应使用的 Affinity Header 名称。必须符合 HTTP field-name token 语法，长度为 1..128 个 ASCII 字节，且不能使用平台保留 Header。示例值：X-Tencent-Agr-Affinity-Id

名称

类型

必选

描述

Mode

String

否

Affinity 模式。

枚举值：

BEST_EFFORT：优先复用原 Instance，不可用时允许改选。
STRICT：只复用原 Instance，不可用时失败且不改选。
EXCLUSIVE：一个 Affinity ID 独占一个 Instance，不能迁移。

缺失或空字符串表示关闭 Affinity。

示例值：EXCLUSIVE

HeaderName

String

否

请求和响应使用的 Affinity Header 名称。必须符合 HTTP field-name token 语法，长度为 1..128 个 ASCII 字节，且不能使用平台保留 Header。

示例值：X-Tencent-Agr-Affinity-Id

AgentBucketStorageSource

用于记录 Agent Bucket 的 Storage Source

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
LibraryId	String	否	用于传入 AgentBucket 的 LibraryID 示例值：smh2ke12fou96sys
SpaceId	String	否	用于传入 AgentBucket 的 spaceId 示例值：space2ws4kk3o7ujpa
AccessDomain	String	否	用于传入 AgentBucket 的 AccessDomain 示例值：smh2rnostb718pgk.ap-beijing.api.tencentsmh.cn

CLSConfig

沙箱工具日志推送CLS相关配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
TopicId	String	否	沙箱工具日志推送所使用的CLS日志主题ID 示例值：123e4567-e89b-12d3-a456-426614174000

CfsStorageSource

文件存储配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
FileSystemId	String	否	CFS资源ID 示例值：cfs-123456
Path	String	否	CFS挂载路径示例值：/

CloudAgentSourceInput

Agent Record 内容来源。Type 判别 MANUAL 与 URL_IMPORT。

被如下接口引用：CreateRegistryRecord, UpdateRegistryRecord。

名称	类型	必选	描述
Type	String	是	来源类型。MANUAL：直接提交 Agent Descriptors JSON 文本；URL_IMPORT：从远端 Agent Card / AGUI 端点导入。注意：此字段可能返回 null，表示取不到有效值。示例值：URL_IMPORT
Descriptors	String	否	Type=MANUAL 时必填；值为通用 JSON object 文本；A2A 标准校验或 AGUI/CUSTOM 规则由后端执行。（JSON 字符串形式）注意：此字段可能返回 null，表示取不到有效值。示例值：{"name":"agui-manual-20260918032825-82314","protocol":"ag-ui","url":"https://example.com/agui/v1","transport":"sse","capabilities":{}}
EndpointURL	String	否	A2A：Agent Card URL；AGUI：Runtime Endpoint URL。Type=URL_IMPORT 时必填，HTTPS。注意：此字段可能返回 null，表示取不到有效值。示例值：https://registry.tencentcloudapi.com/agui/agui-url-20260918032825-82314

CloudAuditLog

审计日志条目。记录 Registry / Record / Version 维度的动作。

被如下接口引用：DescribeRegistryAuditLogList。

名称	类型	必选	描述
AuditLogId	String	是	审计日志 ID。注意：此字段可能返回 null，表示取不到有效值。示例值：889f42e1-0361-4426-b948-75de1bf6e2b6
RegistryId	String	是	所属 Registry ID。注意：此字段可能返回 null，表示取不到有效值。示例值：reg-2dqpkr02
Actor	String	是	动作发起者（主账号 UIN 或子账号 UIN）。注意：此字段可能返回 null，表示取不到有效值。示例值：100049523787
Action	String	是	Action 名称，等同 X-TC-Action。注意：此字段可能返回 null，表示取不到有效值。示例值：registry.update
Details	String	是	动作脱敏摘要对象；使用云 API 字段命名，字段随 Action 而变；不包含凭据、预签名 URL 或完整 Descriptor。（JSON 字符串形式）注意：此字段可能返回 null，表示取不到有效值。示例值：{"RecordId":"rec-0123abcd","VersionId":"rv-0123abcd","ApprovalMode":"MANUAL","Comment":"approved"}
CreateTime	String	是	动作发生时间。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-03T11:52:49Z
RecordId	String	否	关联 Record ID；仅 Record / Version 相关动作。注意：此字段可能返回 null，表示取不到有效值。示例值：rec-0123abcd
VersionId	String	否	关联 Version ID；仅 Version 相关动作。注意：此字段可能返回 null，表示取不到有效值。示例值：rv-0123abcd

CloudFilter

通用过滤条件。Name 为字段名，Values 为字段候选值；字段间 AND、Values 内 OR。

被如下接口引用：DescribeRegistryList, DescribeRegistryRecordList, DescribeRegistryRecordVersionList。

名称	类型	必选	描述
Name	String	是	过滤字段名。DescribeRegistryList 支持 `name` / `search`（模糊搜索）与 `archived` / `status`（true / false / all）；DescribeRegistryRecordList 支持 `name` / `search`（模糊）、`descriptor-type`、`lifecycle-status`（精确）。注意：此字段可能返回 null，表示取不到有效值。示例值：search
Values	Array of String	是	过滤字段候选值列表；至少 1 项。注意：此字段可能返回 null，表示取不到有效值。示例值：["C"]

CloudMCPSourceInput

MCP Record 内容来源。Type 判别 MANUAL 与 URL_IMPORT。

被如下接口引用：CreateRegistryRecord, UpdateRegistryRecord。

名称	类型	必选	描述
Type	String	是	来源类型。MANUAL：直接提交 MCP Descriptors JSON 文本；URL_IMPORT：从远端 MCP server.json URL 导入。注意：此字段可能返回 null，表示取不到有效值。示例值：MANUAL
Descriptors	String	否	Type=MANUAL 时必填；值为完整 MCP server.json 对象的 JSON 文本；完整 MCP 2025-12-11 标准校验由后端执行。（JSON 字符串形式）注意：此字段可能返回 null，表示取不到有效值。示例值：{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","name":"example.com/weather","description":"Weather v2","version":"2.0.0"}
EndpointURL	String	否	远端 MCP server.json URL；HTTPS。Type=URL_IMPORT 时必填。Version 从远端 initialize.serverInfo.version 观测获得，无需请求参数。注意：此字段可能返回 null，表示取不到有效值。示例值：https://mcp.deepwiki.com/mcp

CloudRecord

Registry Record 对象。Record 只保存元数据；协议描述符与内容状态请通过 Version 相关接口获取。

被如下接口引用：CreateRegistryRecord, DescribeRegistryRecord, DescribeRegistryRecordList, SyncRegistryRecord, UpdateRegistryRecord。

名称	类型	必选	描述
RecordId	String	是	Record ID；格式 `rec-` + 8 位小写字母/数字。注意：此字段可能返回 null，表示取不到有效值。示例值：rec-hqrxvu1a
RegistryId	String	是	所属 Registry ID。注意：此字段可能返回 null，表示取不到有效值。示例值：reg-n7a2l9no
Name	String	是	Record 名称；同一 Registry 内可重复。注意：此字段可能返回 null，表示取不到有效值。示例值：forC
Description	String	是	描述。注意：此字段可能返回 null，表示取不到有效值。示例值：导入测试
DescriptorType	String	是	协议描述符类型；创建后不可变。注意：此字段可能返回 null，表示取不到有效值。示例值：CUSTOM
LifecycleStatus	String	是	生命周期状态。ACTIVE：可用；DELETED：软删除墓碑，不再参与常规查询、下发或版本配额。注意：此字段可能返回 null，表示取不到有效值。示例值：ACTIVE
AppId	Integer	是	所属租户 AppId。注意：此字段可能返回 null，表示取不到有效值。示例值：1457947897
CreatorUin	String	是	创建者主账号 UIN。注意：此字段可能返回 null，表示取不到有效值。示例值：100051001552
CreatorSubAccountUin	String	是	创建者子账号 UIN；主账号直接创建时为空。注意：此字段可能返回 null，表示取不到有效值。示例值：100051001552
CreateTime	String	是	创建时间，ISO 8601 UTC。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-27T06:43:49Z
UpdateTime	String	是	最近一次更新时间。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-27T06:43:49Z
VersionCount	Integer	否	Record 下未删除 Version 数量。注意：此字段可能返回 null，表示取不到有效值。示例值：1
LabelSet	Array of String	否	Record 下所有 Label Name（含未绑定 Label），包括系统 Label（stable / latest）和自定义 Label。仅名称，不含 VersionId、更新时间或操作者。注意：此字段可能返回 null，表示取不到有效值。示例值：["latest"]

CloudRecordLabelMutation

Record Label 变更操作项。Operation=SET 时可携带 VersionId；DELETE 时禁止 VersionId。

被如下接口引用：UpdateRegistryRecord。

名称	类型	必选	描述
Operation	String	是	操作类型。SET：创建或移动 Label；DELETE：删除自定义 Label（stable/latest 保留 Label 禁止删除）。注意：此字段可能返回 null，表示取不到有效值。示例值：SET
Name	String	是	Label 名称，长度 1..63，格式 ^[a-z][a-z0-9._-]{0,62}$，按小写规范化。stable、latest 为系统保留 Label。注意：此字段可能返回 null，表示取不到有效值。示例值：stable
VersionId	String	否	目标 Version ID。SET 时可选：省略表示未绑定（自定义 Label 允许，stable 禁止）；DELETE 时禁止携带。注意：此字段可能返回 null，表示取不到有效值。示例值：rv-i69ks9v2
Reason	String	否	变更原因，最大 1024 字符，可选。注意：此字段可能返回 null，表示取不到有效值。示例值：正式发布

CloudRecordVersion

Record 的一个不可变 Version 快照；记录了描述符、来源配置与审批状态。

被如下接口引用：ApproveRegistryRecord, CancelRegistryRecord, CreateRegistryRecord, DescribeRegistryRecord, DescribeRegistryRecordVersionList, GetSkillPackageUploadURL, RejectRegistryRecord, SyncRegistryRecord, UpdateRegistryRecord。

名称	类型	描述
VersionId	String	Version ID；格式 `rv-` + 8 位小写字母/数字。注意：此字段可能返回 null，表示取不到有效值。示例值：rv-rgn1zzaa
RecordId	String	所属 Record ID。注意：此字段可能返回 null，表示取不到有效值。示例值：rec-hqrxvu1a
Revision	Integer	Version 递增序号（1 起）。注意：此字段可能返回 null，表示取不到有效值。示例值：1
Status	String	Version 状态。注意：此字段可能返回 null，表示取不到有效值。示例值：APPROVED
ApprovalMode	String	审批模式；创建时锁定，后续变更 Registry 审批模式不影响本 Version。注意：此字段可能返回 null，表示取不到有效值。示例值：AUTO
AppId	Integer	所属租户 AppId。注意：此字段可能返回 null，表示取不到有效值。示例值：1457947897
CreatorUin	String	创建者主账号 UIN。注意：此字段可能返回 null，表示取不到有效值。示例值：100051001552
CreateTime	String	创建时间。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-27T06:43:49Z
UpdateTime	String	最近一次更新时间。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-27T06:43:49Z
VersionName	String	Version 别名（可选）。注意：此字段可能返回 null，表示取不到有效值。示例值：1.0.0
Descriptors	String	协议描述符对象。（JSON 字符串形式）注意：此字段可能返回 null，表示取不到有效值。示例值：{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","name":"com.deepwiki.mcp/deepwiki","description":"Imported MCP server","version":"2.14.3","remotes":[{"type":"streamable-http","url":"https://mcp.deepwiki.com/mcp"}]}
SourceType	String	内容来源。注意：此字段可能返回 null，表示取不到有效值。示例值：URL_IMPORT
SourceConfig	String	规范化来源配置对象。（JSON 字符串形式）注意：此字段可能返回 null，表示取不到有效值。示例值：{"EndpointURL":"https://mcp.deepwiki.com/mcp","Version":"2.14.3"}
ContentStatus	String	内容状态。注意：此字段可能返回 null，表示取不到有效值。示例值：READY
ContentSHA256	String	READY 内容 SHA-256。注意：此字段可能返回 null，表示取不到有效值。示例值：e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
ContentSizeBytes	Integer	READY 内容字节数。注意：此字段可能返回 null，表示取不到有效值。示例值：20480
ConfigSHA256	String	配置内容规范化后的 SHA-256（用于幂等去重）。注意：此字段可能返回 null，表示取不到有效值。示例值：7826ae36c55fd15af48d3043193671ef2cab220fa3f7ddb7786f8faaa010841a
CreatorSubAccountUin	String	创建者子账号 UIN。注意：此字段可能返回 null，表示取不到有效值。示例值：100051001552
ApprovalActions	Array of CloudVersionApprovalAction	Version 历次审批动作。注意：此字段可能返回 null，表示取不到有效值。
ContentReadyTime	String	TAR 内容成功校验、完成物化并进入 READY 的时间；MANUAL / URL_IMPORT 或尚未 READY 的 TAR_PACKAGE 均为空。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-12T09:15:00Z
ChangeLog	String	本次 Version 的变更原因，最大 4096 字符；不可修改。Revision 1 或未填写时返回空字符串。注意：此字段可能返回 null，表示取不到有效值。示例值：增加预警工具
LabelSet	Array of String	当前绑定该 Version 的 Label Name 列表（例如 stable / latest 或自定义 Label 名称）。未绑定 Label 不在此返回。注意：此字段可能返回 null，表示取不到有效值。示例值：["latest"]

CloudRegistry

Registry 对象。包含注册中心的基本信息与 Record 计数。

被如下接口引用：CreateRegistry, DescribeRegistry, DescribeRegistryList, UpdateRegistry。

名称	类型	必选	描述
RegistryId	String	是	Registry ID；格式 `reg-` + 8 位小写字母/数字。注意：此字段可能返回 null，表示取不到有效值。示例值：reg-qdfy2ii2
Name	String	是	Registry 同一 AppId + Region 唯一名称。注意：此字段可能返回 null，表示取不到有效值。示例值：demo
Description	String	是	描述。注意：此字段可能返回 null，表示取不到有效值。示例值：勿删
ApprovalMode	String	是	审批模式；AUTO 自动通过，MANUAL 需人工审批；创建时确定，不可修改。注意：此字段可能返回 null，表示取不到有效值。示例值：MANUAL
Region	String	是	Registry 所在腾讯云地域，如 `ap-guangzhou`。注意：此字段可能返回 null，表示取不到有效值。示例值：ap-guangzhou
Status	String	是	Registry 状态。ACTIVE / ARCHIVED。注意：此字段可能返回 null，表示取不到有效值。示例值：ARCHIVED
CreateTime	String	是	创建时间，ISO 8601 UTC，如 `2026-08-11T10:00:00Z`。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-27T06:42:25Z
UpdateTime	String	是	最近一次更新时间，ISO 8601 UTC。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-27T15:09:54Z
RecordCount	Integer	是	Registry 下 Record 总数。注意：此字段可能返回 null，表示取不到有效值。示例值：7
Tags	Array of CloudTag	是	权威读取的腾讯云自定义标签，按 Key、Value 稳定排序；无标签时固定返回空数组，不返回 null。
PublishedRecordCount	Integer	否	Stable Label 已绑定的 Record 数量。Approved Version 数量和可对外消费的 Record 数量已不再等价。注意：此字段可能返回 null，表示取不到有效值。示例值：3
AppId	Integer	否	所属租户 AppId。注意：此字段可能返回 null，表示取不到有效值。示例值：1251707795
CreatorUin	String	否	创建者主账号 UIN。注意：此字段可能返回 null，表示取不到有效值。示例值：3321337994
CreatorSubAccountUin	String	否	创建者子账号 UIN；主账号直接创建时为空字符串。注意：此字段可能返回 null，表示取不到有效值。示例值：100009277106

CloudSkillSourceInput

AGENT_SKILLS 内容来源。Type 判别 MANUAL 与 TAR_PACKAGE 两种模式。

被如下接口引用：CreateRegistryRecord, UpdateRegistryRecord。

名称	类型	必选	描述
Type	String	是	来源类型。MANUAL：直接提交 SKILL.md 文本；TAR_PACKAGE：由服务端签发 COS PUT 预签名 URL，客户端上传后由服务端异步校验。注意：此字段可能返回 null，表示取不到有效值。示例值：MANUAL
SkillMd	String	否	SKILL.md 原文；Type=MANUAL 时必填非空；Type=TAR_PACKAGE 时不得提供。注意：此字段可能返回 null，表示取不到有效值。示例值：--- name: example-skill description: Example skill --- # Example skill

CloudTag

腾讯云自定义标签。

被如下接口引用：CreateRegistry, DescribeRegistry, DescribeRegistryList, UpdateRegistry。

名称	类型	必选	描述
Key	String	是	自定义标签键；不可使用 qcs:、project 或项目预留前缀，且不可包含首尾空格。注意：此字段可能返回 null，表示取不到有效值。示例值：forC
Value	String	是	自定义标签值，不可包含首尾空格。注意：此字段可能返回 null，表示取不到有效值。示例值：C

CloudVersionApprovalAction

Version 一次审批动作条目。

名称	类型	必选	描述
ActionId	String	否	动作 ID。注意：此字段可能返回 null，表示取不到有效值。示例值：rva-ri4bzzm2
ActionType	String	否	动作类型。注意：此字段可能返回 null，表示取不到有效值。示例值：APPROVE
ActorType	String	否	动作发起者类型。USER 用户；SYSTEM 系统自动通过。注意：此字段可能返回 null，表示取不到有效值。示例值：USER
ActorUin	String	否	发起者主账号 UIN。注意：此字段可能返回 null，表示取不到有效值。示例值：3321337994
ActorSubAccountUin	String	否	发起者子账号 UIN。注意：此字段可能返回 null，表示取不到有效值。示例值：100049523787
Comment	String	否	动作留言。注意：此字段可能返回 null，表示取不到有效值。示例值：1
CreateTime	String	否	发生时间。注意：此字段可能返回 null，表示取不到有效值。示例值：2026-08-21T07:15:51Z
RequestId	String	否	对应云 API 请求的 RequestId。注意：此字段可能返回 null，表示取不到有效值。示例值：c0126355-5a96-4fc8-9eef-6fdad82848c8

ComputerConfiguration

桌面电脑环境类沙箱配置

被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
WAAConfiguration	WAAConfiguration	否	waa沙箱工具配置
OSWorldConfiguration	OSWorldConfiguration	否	配置内置 OSWorld

CosStorageSource

沙箱实例对象存储挂载配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
Endpoint	String	否	对象存储访问域名示例值：test-123456789.cos.ap-guangzhou.myqcloud.com
BucketName	String	否	对象存储桶名称示例值：test-123456789
BucketPath	String	否	对象存储桶路径，必须为以/起始的绝对路径示例值：/

CustomConfiguration

沙箱自定义配置

被如下接口引用：CreateSandboxTool, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
Image	String	否	镜像地址示例值：test.tencentcloudcr.com/example/nginx:latest
ImageRegistryType	String	否	镜像仓库类型：`enterprise`、`personal`、`custom` 枚举值： enterprise： tcr 企业容器镜像服务 personal： ccr 个人容器镜像服务示例值：enterprise
Command	Array of String	否	启动命令示例值：["/bin/bash", "-c"]
Args	Array of String	否	启动参数示例值：["-h", "0.0.0.0", "-p", "8000"]
Env	Array of EnvVar	否	环境变量
Ports	Array of PortConfiguration	否	端口配置
Resources	ResourceConfiguration	否	资源配置
Probe	ProbeConfiguration	否	探针配置
DNSConfig	DNSConfig	否	沙箱 DNS 配置

CustomConfigurationDetail

沙箱自定义配置详细信息

被如下接口引用：DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance。

名称	类型	必选	描述
Image	String	否	镜像地址示例值：test.tencentcloudcr.com/example/nginx:latest
ImageRegistryType	String	否	镜像仓库类型：`enterprise`、`personal`、`custom`。枚举值： enterprise： TCR 企业容器镜像服务 personal： CCR 个人容器镜像服务示例值：TCR
ImageDigest	String	否	镜像 Digest 示例值：sha256:abc123def456...
Command	Array of String	否	启动命令示例值：["/bin/bash", "-c"]
Args	Array of String	否	启动参数示例值：["-h", "0.0.0.0", "-p", "8000"]
Env	Array of EnvVar	否	环境变量
Ports	Array of PortConfiguration	否	端口配置
Resources	ResourceConfiguration	否	资源配置
Probe	ProbeConfiguration	否	探针配置
DNSConfig	DNSConfig	否	沙箱 DNS 配置

DNSConfig

沙箱自定义 dns 配置

被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
Servers	Array of String	是	DNS 服务器地址参数格式：需要有效 IP 地址默认值：10.0.0.1 示例值：["9.9.9.9"]
Searches	Array of String	否	搜索域(对应 resolv.conf 的 search 指令) 示例值：["example.internal"]
Options	Array of String	否	配置项(对应 resolv.conf 选项) 示例值：["ndots:5"]

名称

类型

必选

描述

Servers

Array of String

是

DNS 服务器地址

参数格式：需要有效 IP 地址

默认值：10.0.0.1

示例值：["9.9.9.9"]

Searches

Array of String

否

搜索域(对应 resolv.conf 的 search 指令)

示例值：["example.internal"]

Options

Array of String

否

配置项(对应 resolv.conf 选项)

示例值：["ndots:5"]

Deployment

Deployment 稳定访问入口定义

被如下接口引用：CreateDeployment, DescribeDeployment, DescribeDeploymentList, ModifyDeployment。

名称	类型	必选	描述
DeploymentId	String	否	Deployment 稳定 ID，格式为 dpl- 加 8 位小写 base36 字符。示例值：dpl-a1b2c3d4
DeploymentName	String	否	唯一且创建后不可修改的名称，必须符合 DNS-1123 命名规范。示例值：workspace-service
ToolId	String	否	用于关联 Sandbox Tool 的标识，格式为 sdt- 加 8 位小写 base36 字符。示例值：sdt-a1b2c3d4
ScalingConfiguration	ScalingConfiguration	否	完整的活跃容量配置。
LifecycleConfiguration	LifecycleConfiguration	否	完整的空闲生命周期配置。
AffinityConfiguration	AffinityConfiguration	否	可选 Affinity 配置；未启用时省略。
Status	String	否	Deployment 控制面状态。枚举值： ACTIVE：入口可用。 DELETING：入口已关闭并正在异步删除。 DELETE_FAILED：最近一次异步删除失败，可再次调用 DeleteDeployment。示例值：DELETE_FAILED
StatusReason	String	否	DELETE_FAILED 状态下 1..1024 个 UTF-8 字节的安全失败摘要，格式为 {Code}[.{SubCode}]: {Message}；其他状态省略。示例值：InternalError: internal error
CreatedTime	Timestamp ISO8601	否	创建时间，UTC、秒精度 RFC3339 格式。示例值：2026-08-06T08:00:00Z
UpdatedTime	Timestamp ISO8601	否	最近一次成功公共配置写入或 Deployment 状态迁移时间，UTC、秒精度 RFC3339 格式。示例值：2026-08-06T08:00:00Z
Tags	Array of Tag	否	标签

EnvVar

环境变量

被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
Name	String	否	环境变量名示例值：TEST_ENV
Value	String	否	环境变量值示例值：ABD

EventActionsInfo

Agent 状态切换事件信息

被如下接口引用：AppendEvent, DescribeEvents。

名称	类型	必选	描述
StateDelta	String	否	状态增量，JSON 字符串，最大长度 8192 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：json-text

EventContentInfo

事件内容信息

被如下接口引用：AppendEvent, DescribeEvents。

名称	类型	必选	描述
Role	String	否	角色，最大长度 64 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：user
Parts	Array of EventPartInfo	否	内容片段列表。注意：此字段可能返回 null，表示取不到有效值。

EventInfo

事件信息

被如下接口引用：AppendEvent, DescribeEvents。

名称	类型	必选	描述
EventId	String	否	事件 ID。为空时由服务生成。注意：此字段可能返回 null，表示取不到有效值。示例值：event-a1b2c3d4
InvocationId	String	否	调用 ID，最大长度 128 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：invoke-a1b2c3d4
Author	String	否	事件作者，最大长度 128 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：user
Content	EventContentInfo	否	事件内容。注意：此字段可能返回 null，表示取不到有效值。
Actions	EventActionsInfo	否	事件动作信息。StateDelta 为 JSON 对象字符串注意：此字段可能返回 null，表示取不到有效值。
Metadata	String	否	事件元数据。注意：此字段可能返回 null，表示取不到有效值。示例值：{"k":"v"}
Extensions	String	否	事件扩展信息 JSON 对象字符串，最大长度 8192 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：json-text
ErrorCode	String	否	错误码，最大长度 128 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：503
ErrorMessage	String	否	错误信息，最大长度 2048 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：timeout
Timestamp	String	否	事件时间。示例值：2026-07-08T06:27:42.997Z

EventPartInfo

多模态内容片段信息

被如下接口引用：AppendEvent, DescribeEvents。

名称	类型	必选	描述
Text	String	否	文本内容，最大长度 8192 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：hello
Thought	Boolean	否	是否为思考内容。注意：此字段可能返回 null，表示取不到有效值。示例值：false
FunctionCall	String	否	工具调用信息，JSON 字符串，最大长度 8192 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：json-text
FunctionResponse	String	否	工具返回信息，JSON 字符串，最大长度 8192 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：json-text
InlineData	InlineDataInfo	否	内联数据。注意：此字段可能返回 null，表示取不到有效值。

Filter

过滤列表规则

被如下接口引用：DescribeDeploymentList, DescribeQuotaOverview, DescribeSandboxInstanceList, DescribeSandboxToolList, DescribeSessionSpaces, DescribeSessions。

名称	类型	必选	描述
Name	String	否	属性名称, 若存在多个Filter时，Filter间的关系为逻辑与（AND）关系。示例值：FILTER_KEY_NAME
Values	Array of String	否	属性值, 若同一个Filter存在多个Values，同一Filter下Values间的关系为逻辑或（OR）关系。示例值：["LocalDev"]

HttpGetAction

HTTP GET 探测动作配置

被如下接口引用：CreateSandboxTool, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
Path	String	否	路径示例值：/health
Port	Integer	否	端口示例值：8000
Scheme	String	否	协议示例值：HTTP

ImageStorageSource

镜像卷挂载源配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
Reference	String	否	镜像地址示例值：ccr.ccs.tencentyun.com/example/nginx:latest
ImageRegistryType	String	否	镜像仓库类型：`enterprise`、`personal`。示例值：enterprise
SubPath	String	否	镜像内部的路径示例值：/mnt/sub
Digest	String	否	镜像 Digest，请求时无需传入示例值：sha256:abcdefg123...

InlineDataInfo

文件内容数据信息

被如下接口引用：AppendEvent, DescribeEvents。

名称	类型	必选	描述
MimeType	String	否	媒体类型，最大长度 128 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：text/plain
Data	String	否	Base64 编码数据，最大长度 8192 字符。注意：此字段可能返回 null，表示取不到有效值。示例值：aGVsbG8=

LifecycleConfiguration

Deployment 管理的 Sandbox Instance 的空闲生命周期配置

被如下接口引用：CreateDeployment, DescribeDeployment, DescribeDeploymentList, ModifyDeployment。

名称	类型	必选	描述
IdleTimeoutSeconds	Integer	否	Sandbox Instance 没有活跃 Deployment 请求或连接后进入 IdleAction 的秒数，必须大于等于 30。示例值：300
IdleAction	String	否	空闲处理动作。枚举值： STOP：停止并释放 Sandbox Instance。 PAUSE：暂停并保留 Sandbox Instance 状态。示例值：STOP

名称

类型

必选

描述

IdleTimeoutSeconds

Integer

否

Sandbox Instance 没有活跃 Deployment 请求或连接后进入 IdleAction 的秒数，必须大于等于 30。

示例值：300

IdleAction

String

否

空闲处理动作。

枚举值：

STOP：停止并释放 Sandbox Instance。
PAUSE：暂停并保留 Sandbox Instance 状态。

示例值：STOP

LogConfiguration

沙箱工具日志采集相关配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
CLSConfig	CLSConfig	否	日志推送CLS的配置。
LogSources	LogSources	否	日志源配置

LogSources

日志源配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
Files	Array of String	否	需要采集的日志文件路径，必须是 /logs/ 目录下的文件，不支持子目录，最大支持 10 个文件。注意：此字段可能返回 null，表示取不到有效值。示例值：["/logs/2026-04-08.log"]

MetadataVar

metadata 项

被如下接口引用：CreateSession, DescribeSandboxInstanceList, DescribeSession, DescribeSessions, ModifySession, StartSandboxInstance, UpdateSandboxInstance。

名称	类型	必选	描述
Name	String	否	元数据名示例值：b
Value	String	否	元数据值示例值：b

MountOption

沙箱实例存储挂载配置可选项，用于覆盖沙箱工具的存储配置的部分选项，并提供子路径挂载配置。

被如下接口引用：DescribeSandboxInstanceList, StartSandboxInstance。

名称	类型	必选	描述
Name	String	否	指定沙箱工具中的存储配置名称示例值：Storage1
MountPath	String	否	沙箱实例本地挂载路径（可选），默认继承工具中的存储配置示例值：/home/user
SubPath	String	否	沙箱实例存储挂载子路径（可选）示例值：workspace1
ReadOnly	Boolean	否	沙箱实例存储挂载读写权限（可选），默认继承工具存储配置示例值：false

NetworkConfiguration

沙箱网络配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList, UpdateSandboxTool。

名称	类型	必选	描述
NetworkMode	String	是	网络模式（当前支持 PUBLIC, VPC, SANDBOX）示例值：PUBLIC
VpcConfig	VPCConfig	否	VPC网络相关配置

OSWorldConfiguration

OSWorld 内置版本配置

被如下接口引用：CreateSandboxTool, UpdateSandboxTool。

名称	类型	必选	描述
Version	String	否	指定内置 OSWorld 版本枚举值： osworld1： osworld v1 osworld2： osworld v2 默认值：osworld1 示例值：osworld1

名称

类型

必选

描述

Version

String

否

指定内置 OSWorld 版本

枚举值：

osworld1： osworld v1
osworld2： osworld v2

默认值：osworld1

示例值：osworld1

PortConfiguration

端口配置

被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
Name	String	否	端口名示例值：http
Port	Integer	否	端口示例值：8000
Protocol	String	否	协议示例值：TCP

ProbeConfiguration

健康检查探针配置

被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
HttpGet	HttpGetAction	否	HTTP GET 探测配置
ReadyTimeoutMs	Integer	否	健康检查就绪超时示例值：30000
ProbeTimeoutMs	Integer	否	健康检查单次探测超时示例值：1000
ProbePeriodMs	Integer	否	健康检查间隔示例值：1000
SuccessThreshold	Integer	否	健康检查成功阈值示例值：1
FailureThreshold	Integer	否	健康检查失败阈值示例值：3

QuotaGroupOverview

配额组资源信息

被如下接口引用：DescribeQuotaOverview。

名称	类型	必选	描述
Tag	Tag	否	配额组关联的标签键值
Name	String	否	配额组名称示例值：business-group1
Quota	QuotaResourceInfo	否	配额组各资源维度的配额上限
Usage	QuotaResourceInfo	否	配额组各资源维度的当前用量
CreateTime	String	否	创建时间参数格式：RFC3339 格式示例值：2026-08-17T16:36:09+08:00
UpdateTime	String	否	最后更新时间参数格式：RFC3339 格式示例值：2026-08-17T16:36:09+08:00

QuotaResourceInfo

主账号资源信息

被如下接口引用：DescribeQuotaOverview。

名称	类型	必选	描述
SandboxTools	Integer	否	沙箱工具配额或当前用量单位：个示例值：9
SandboxInstances	Integer	否	沙箱实例配额或当前用量单位：个示例值：10
PausedInstances	Integer	否	暂停实例配额或当前用量单位：个示例值：63
CPUCores	Float	否	暂停实例配额或当前用量。目前只在主账号中返回单位：核示例值：20
MemoryGiB	Float	否	内存配额或当前用量单位：GiB 示例值：40

ResourceConfiguration

资源配置

被如下接口引用：CreateSandboxTool, DescribeSandboxInstanceList, DescribeSandboxToolList, StartSandboxInstance, UpdateSandboxTool。

名称	类型	必选	描述
CPU	String	否	cpu 资源量示例值：500m
Memory	String	否	内存资源量示例值：1Gi
Storage	String	否	自定义磁盘大小枚举值： 1Gi： 1Gi 5Gi： 5Gi 10Gi： 10Gi 20Gi： 20Gi 注意：此字段可能返回 null，表示取不到有效值。示例值：10Gi

名称

类型

必选

描述

CPU

String

否

cpu 资源量

示例值：500m

Memory

String

否

内存资源量

示例值：1Gi

Storage

String

否

自定义磁盘大小

枚举值：

1Gi： 1Gi
5Gi： 5Gi
10Gi： 10Gi
20Gi： 20Gi

注意：此字段可能返回 null，表示取不到有效值。
示例值：10Gi

SandboxInstance

沙箱实例结构体

被如下接口引用：DescribeSandboxInstanceList, StartSandboxInstance。

名称	类型	必选	描述
InstanceId	String	是	沙箱实例唯一标识符示例值：48dd1132cfb96ccee5fd0aa58da2562d2fe3a929
ToolId	String	是	所属沙箱工具 ID 示例值：sdt-def456ghi789
ToolName	String	是	所属沙箱工具名称示例值：code-interpreter-v1
Status	String	是	实例状态：STARTING（启动中）、RUNNING（运行中）、STOPPING（停止中）、STOPPED（已停止）、STOP_FAILED（停止失败）、FAILED（失败状态）示例值：RUNNING
Persistent	Boolean	否	是否常驻实例示例值：false
TimeoutSeconds	Integer	否	超时时间（秒），null 表示无超时设置示例值：600
ExpiresAt	String	否	过期时间（ISO 8601 格式），null 表示无过期时间示例值：2024-01-01T10:30:00Z
StopReason	String	否	停止原因：manual（手动）、timeout（超时）、error（错误）、system（系统），仅在状态为 STOPPED、STOP_FAILED 或 FAILED 时有值。当 provider 停止失败时，状态为 STOP_FAILED，原因为 error 示例值：timeout
CreateTime	String	否	创建时间（ISO 8601 格式）示例值：2024-01-01T10:00:00Z
UpdateTime	String	否	更新时间（ISO 8601 格式）示例值：2024-01-01T10:10:00Z
MountOptions	Array of MountOption	否	存储挂载选项
CustomConfiguration	CustomConfigurationDetail	否	沙箱实例自定义配置
ComputerConfiguration	ComputerConfiguration	否	桌面电脑环境类沙箱配置
NetworkMode	String	否	网络模式枚举值： PUBLIC：公网访问 SANDBOX：无网络 INTERNAL_SERVICE：腾讯云内部公共服务可以覆盖工具级别的网络配置。但如果一个工具本身就不支持 VPC 网络，那么即便在实例设置里选了 VPC 模式，也是无效的示例值：VPC
Metadata	Array of MetadataVar	否	沙箱实例元数据
AuthMode	String	否	沙箱访问认证模式枚举值： DEFAULT：默认，即 TOKEN 认证 TOKEN： Token认证，即所有端口访问都需携带TOKEN NONE：免认证，即所有端口访问无需携带TOKEN PUBLIC：公开模式，即ENVD管理端口（49983）访问需携带TOKEN，其他端口无需携带TOKEN 默认值：DEFAULT 示例值：TOKEN

SandboxTool

沙箱工具结构体

被如下接口引用：DescribeSandboxToolList。

名称	类型	必选	描述
ToolId	String	是	沙箱工具唯一标识符示例值：sdt-ee4ywozw
ToolName	String	否	沙箱工具名称，长度 1-50 字符，支持中英文、数字、下划线。同一 AppId 下沙箱工具名称必须唯一示例值：browser-sandbox
ToolType	String	否	沙箱工具类型，取值：browser（浏览器工具）、code-interpreter（代码解释器工具）、computer（计算机控制工具）、mobile（移动设备工具）示例值：browser
Status	String	否	沙箱工具状态，取值：CREATING（创建中）、ACTIVE（可用）、DELETING（删除中）、FAILED（失败）示例值：ACTIVE
Description	String	否	沙箱工具描述信息，最大长度 200 字符示例值：浏览器沙箱环境
Persistent	Boolean	否	是否常驻沙箱示例值：false
DefaultTimeoutSeconds	Integer	否	默认超时时间，支持格式：5m、300s、1h 等，不指定则使用系统默认值（5 分钟）。最大 24 小时示例值：600
NetworkConfiguration	NetworkConfiguration	否	网络配置
Tags	Array of Tag	否	标签规格，包含资源标签绑定关系。用于为沙箱工具绑定标签，支持多种资源类型的标签绑定
CreateTime	String	否	沙箱工具创建时间，格式：ISO8601 示例值：2024-01-15T10:30:00Z
UpdateTime	String	否	沙箱工具更新时间，格式：ISO8601 示例值：2024-01-15T10:30:00Z
RoleArn	String	否	沙箱工具绑定角色ARN 示例值：qcs::cam::uin/100000001:roleName/test_role
StorageMounts	Array of StorageMount	否	沙箱工具中实例存储挂载配置
CustomConfiguration	CustomConfigurationDetail	否	沙箱工具自定义配置
LogConfiguration	LogConfiguration	否	沙箱工具日志推送相关配置
ComputerConfiguration	ComputerConfiguration	否	桌面电脑环境类沙箱配置
StatusReason	String	否	用于说明沙箱工具处于该状态的原因示例值：InternalError

ScalingConfiguration

Deployment 活跃容量配置

被如下接口引用：CreateDeployment, DescribeDeployment, DescribeDeploymentList, ModifyDeployment。

名称	类型	必选	描述
MinInstanceCount	Integer	否	活跃 Sandbox Instance 下限，必须大于等于 0。示例值：0
MaxInstanceCount	Integer	否	活跃 Sandbox Instance 上限，必须大于等于 1，并且不小于 MinInstanceCount。示例值：10
MaxInstanceRequestConcurrency	Integer	否	每个活跃 Sandbox Instance 同时持有的 Deployment 请求或连接 Lease 上限，必须大于等于 1。示例值：100

SessionInfo

会话信息

被如下接口引用：CreateSession, DescribeSession, DescribeSessions, ModifySession。

名称	类型	描述
SessionId	String	会话 ID。示例值：session-a1b2c3d4
SpaceId	String	会话所属空间 ID。示例值：space-198577ac-324e-4e1b-bfda-f75a2365c9df
State	SessionState	Session 快照状态
Metadata	Array of MetadataVar	会话元数据，以键值对数组形式表示。每个元素包含 Metadata 名称和对应值，最多支持 64 项。
UserId	String	用户 ID。示例值：user-a1b2c3d4
Title	String	会话标题。示例值：测试会话
EventCount	Integer	事件数量。示例值：0
CreateTime	Timestamp ISO8601	创建时间。示例值：2026-06-30T00:00:00Z
UpdateTime	Timestamp ISO8601	更新时间。示例值：2026-06-30T00:00:00Z

SessionSpaceInfo

描述会话空间的完整信息。会话空间是用户状态、会话和事件的上级资源及隔离边界，同一个会话只能属于一个会话空间。

被如下接口引用：CreateSessionSpace, DescribeSessionSpace, DescribeSessionSpaces, ModifySessionSpace。

名称	类型	描述
SpaceId	String	会话空间唯一标识，由服务端生成，最大长度为 128 个字符。调用方不应自行构造或解析。示例值：space-206b6ee7-01d1-4f46-8c2f-5c12519bbc0f
Name	String	会话空间名称，用于标识会话空间的业务用途，最大长度为 128 个字符。示例值：my test space 003
Description	String	会话空间描述，用于说明业务用途和使用范围，最大长度为 512 个字符。为空时该字段可能不返回示例值：for test only
Status	String	会话空间当前状态。枚举值： Active：正常可用 Deleting：正在删除示例值：Active
Default	Boolean	是否为系统默认会话空间。true 表示默认会话空间，false 表示普通会话空间。默认会话空间不允许删除。示例值：true
CreateTime	String	会话空间创建时间，采用 ISO 8601/RFC 3339 格式。示例值：2026-08-17T11:10:13.368Z
UpdateTime	String	会话空间最后更新时间，采用 ISO 8601/RFC 3339 格式。示例值：2026-08-17T11:15:33.392Z

SessionState

Session 快照状态

被如下接口引用：CreateSession, DescribeSession, DescribeSessions, ModifySession。

名称	类型	必选	描述
CustomState	String	否	自定义状态 JSON 对象字符串示例值：{"agentengine:session":{"framework_state":{"strands":{"session_id":"strands-calc-490085f8"}}}}

StorageMount

沙箱工具中实例存储挂载配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
Name	String	否	存储挂载配置名称示例值：Storage1
StorageSource	StorageSource	否	存储配置注意：此字段可能返回 null，表示取不到有效值。
MountPath	String	否	沙箱实例本地挂载路径示例值：/home/user
ReadOnly	Boolean	否	存储挂载读写权限配置，默认为false 示例值：false

StorageSource

挂载存储配置

被如下接口引用：CreateSandboxTool, DescribeSandboxToolList。

名称	类型	必选	描述
Cos	CosStorageSource	否	对象存储桶配置
Image	ImageStorageSource	否	镜像卷配置
Cfs	CfsStorageSource	否	文件存储配置
AgentBucket	AgentBucketStorageSource	否	AgentBucket 存储配置

Tag

标签

被如下接口引用：CreateDeployment, CreateSandboxTool, CreateSessionSpace, DescribeDeployment, DescribeDeploymentList, DescribeQuotaOverview, DescribeSandboxToolList, ModifyDeployment, UpdateSandboxTool。

名称	类型	必选	描述
Key	String	否	标签键示例值：business
Value	String	否	标签值示例值：biz1

VPCConfig

沙箱工具VPC相关配置

被如下接口引用：CreateSandboxTool, UpdateSandboxTool。

名称	类型	必选	描述
SubnetIds	Array of String	否	VPC子网ID列表示例值：["subnet-012abcde", "subnet-012edcba"]
SecurityGroupIds	Array of String	否	安全组ID列表示例值：["sg-abcde012", "sg-210edcba"]

WAAConfiguration

waa自定义配置项

被如下接口引用：CreateSandboxTool, UpdateSandboxTool。

名称	类型	必选	描述
ImageId	String	否	自定义waa镜像ID 示例值：img-p**a

数据结构

本页目录：

APIKeyInfo

AccountQuotaOverview

AffinityConfiguration

AgentBucketStorageSource

CLSConfig

CfsStorageSource

CloudAgentSourceInput

CloudAuditLog

CloudFilter

CloudMCPSourceInput

CloudRecord

CloudRecordLabelMutation

CloudRecordVersion

CloudRegistry

CloudSkillSourceInput

CloudTag

CloudVersionApprovalAction

ComputerConfiguration

CosStorageSource

CustomConfiguration

CustomConfigurationDetail

DNSConfig

Deployment

EnvVar

EventActionsInfo

EventContentInfo

EventInfo

EventPartInfo

Filter

HttpGetAction

ImageStorageSource

InlineDataInfo

LifecycleConfiguration

LogConfiguration

LogSources

MetadataVar

MountOption

NetworkConfiguration

OSWorldConfiguration

PortConfiguration

ProbeConfiguration

QuotaGroupOverview

QuotaResourceInfo

ResourceConfiguration

SandboxInstance

SandboxTool

ScalingConfiguration

SessionInfo

SessionSpaceInfo

SessionState

StorageMount

StorageSource

Tag

VPCConfig

WAAConfiguration