UpdateCustomAgent - 更新自定义智能体-智能体构建和治理平台 AgentCore-阿里云帮助中心

更新指定工作空间中的自定义智能体配置，并异步执行更新。省略的顶层字段保留原配置，可通过 GetCustomAgent 查询更新结果。

接口说明

至少提供一个需要更新的顶层字段；省略的顶层字段保留原配置。提供配置对象时，请同时填写其必需子字段，并一并提供需要保留的可选配置。数组整体替换，传 [] 可清空列表；agenticFsMounts 不接受 null。description 传 null 可清除描述，healthCheck 传 null 可移除健康检查。

沿用当前 ACR 镜像来源时，可只提交需要修改的 artifact 子字段。例如，更新同一仓库的镜像标签只需提交 artifact.container.tag，未提交的端口、来源字段和启动命令保留原值。切换来源时，合并后的制品配置须满足对应来源的必需字段和 code/container 互斥要求。

代码包模式填写 artifact.port 和 artifact.code 的 sourceUri、languageRuntime、entrypoint，不能同时填写 container。依赖由用户打包，支持 ZIP 或 TAR.GZ，压缩包大小不超过 500000000 字节。运行环境标识通过 ListAgentCodeRuntimes 查询。sourceUri 支持 oss:// 或标准 OSS 公网域名的 HTTPS 对象地址（含签名链接）。本地文件先通过 GetAgentCodePackageUploadUrl 获取地址并直传，再提交返回的 sourceUri。

提交新代码包来源时，后端重新检查读取权限、对象和大小，转存成功后才保存配置；转存失败不保存本次配置。已保存的固定包可复用。代码包请求建议客户端超时设置为 210 秒；归档完整性及安全解压在启动时检查，受理成功不代表运行就绪。

实例数与弹性：提供 runtime 时，compute 和 sessionPolicy 必须同时存在。省略 hpa 或其部分字段时，未指定的弹性配置使用默认值：enabled=false、minSandboxCount=1、maxSandboxCount=10、maxConcurrentSessionsPerSandbox=100、sessionTtlSeconds=600；保留原弹性配置时须一并提供完整 hpa。省略整个 runtime 则保留原配置。minSandboxCount、maxSandboxCount 是配置边界，实际实例数量通过 sandboxPhaseCounts 查询。提供 network 时，省略的访问项按允许处理，实际访问仍受工作空间网络限制；保留原限制时请同时提供 accessInternet 和 accessVpc。提供 healthCheck 时必须填写 port，其他未指定项使用默认值。提供 logging.sls 时须同时填写 project 和 logstore。

环境变量：省略整个 environment 保留原配置；提供 variables 时整体替换列表，保留的变量也须一并提交。variables=[] 或 environment=null 可清空用户配置的环境变量；提供 environment 但省略 variables 同样会清空。变量名称须非空且在列表中唯一，value 必须为字符串，允许空字符串。

更新为异步过程。响应成功表示请求已受理，通过 GetCustomAgent 查询 latestSpecVersion、effectiveSpecVersion、latestVersionStatus 和 latestExecutionError，并结合 status、sandboxPhaseCounts 确认配置处理进度与实例状态。配置处理成功不代表全部旧实例已经替换完成。

显式提交 customImage 时须提供 clientToken。传入 clientToken 后，后端按租户、工作空间和该标识记录本次提交；相同参数重试复用受理结果，不同提交内容使用新标识。不传时请先查询状态再决定是否重试。健康检查的 healthyThreshold 当前不生效，请省略。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:UpdateCustomAgent

update

*CustomAgent

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/customAgent/{#agentId}

无

请求语法

PATCH /workspaces/{workspaceId}/custom-agents/{agentId} HTTP/1.1

路径参数

名称	类型	必填	描述	示例值
workspaceId	string	是	自定义智能体所属的工作空间 ID。	ws-a1b2c3d4e5f6
agentId	string	是	自定义智能体的唯一标识，可从 CreateCustomAgent 或 ListCustomAgents 的响应中获取。	agent-550e8400e29b41d4a716446655440000

请求参数

名称	类型	必填	描述	示例值
body	object	否	自定义智能体更新配置，至少提供一个顶层字段。省略的顶层字段保留原值；artifact 沿用已有来源时可更新部分子字段。runtime 按结构提供 compute、sessionPolicy，并携带需要保留的完整 hpa；environment.variables 及其他数组按完整列表替换。
accessMode	string	否	入站访问方式枚举值： API_KEY USER	API_KEY
accessScope	string	否	用户访问范围枚举值： ALL SPECIFIED	ALL
agenticFsMounts	array<object>	否	AgenticFS 额外挂载列表，与 ossMounts 合计最多 10 项。创建时省略或传 [] 表示无额外挂载；更新时省略保留原值，传 [] 清空。不能传 null。
	object	否	一个 AgenticFS AccessPoint 目录挂载配置项。
mountPath	string	否	容器内 /mnt/agenticfs/ 下的子目录，每个挂载项必填。挂载目标不得重复或形成父子覆盖。	/mnt/agenticfs/data
path	string	否	AccessPoint 下已存在的非空相对目录，每个挂载项必填。不允许根目录、绝对路径或上级目录跳转。	workspace/data
readOnly	boolean	否	是否只读挂载。true 表示只读，false 表示可读写；省略时默认为 false。	false
server	string	否	AccessPoint 域名，每个挂载项必填。取 NAS ListAccessPoints 响应中的 DomainName，不含协议、端口或路径。	ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com
artifact	object	否	部署制品更新配置。省略整个 artifact 时保留原配置；沿用当前来源时可只修改部分子字段，合并后的配置须有合法 port，且 code 与 container 中只能存在一种来源。
code	object	否	代码包部署配置，与 container 互斥。代码包使用 ZIP 或 TAR.GZ 格式，依赖由用户打包，平台不安装依赖或在线构建。
entrypoint	string	否	代码包启动命令，代码包模式必填。工作目录为解压后的代码根目录 /code，例如 python main.py。支持引号和转义，不自动展开环境变量、管道或逻辑运算；复杂命令请使用包内脚本。	python main.py
languageRuntime	string	否	代码运行环境标识，例如 python3.12。创建或切换环境时使用 ListAgentCodeRuntimes 返回的标识，由当前版本目录校验，不是固定枚举。	python3.12
sourceUri	string	否	代码包来源地址。支持 oss:// 地址或标准 OSS 公网域名的 HTTPS 对象地址（含 OSS 签名链接）；不支持任意外部站点、自定义域名或额外认证请求头。本地上传后使用 GetAgentCodePackageUploadUrl 返回的 sourceUri。创建或更新时重新校验并转存，保存后返回平台固定 oss:// 地址；普通更新可复用该固定地址。	oss://my-agent-bucket/packages/main.zip
container	object	否	容器镜像更新配置。沿用当前 ACR 来源时可只修改 tag 等子字段，省略的来源字段保留。切换来源时须使合并后的配置包含对应来源的必要字段。
entrypoint	string	否	可选的可执行程序及启动参数，指定时须为非空字符串。更新时省略此字段保留原启动配置；单独修改 entrypoint 不重新访问镜像来源。支持引号和转义，不自动展开变量、管道或逻辑运算。	python app.py
instanceId	string	否	镜像仓库所属的 ACR 实例 ID，不能为空。	cri-a1b2c3d4e5f6
namespace	string	否	ACR 镜像仓库所属的命名空间，不能为空。	my-agent
repo	string	否	ACR 命名空间中的镜像仓库名称，不能为空。	chat-agent
tag	string	否	部署使用的镜像标签，指定时须为非空字符串。沿用同一 ACR 仓库时可只提交此字段，例如 v1.0.1；省略时保留原标签。	v1.0.0
type	string	否	镜像来源类型。当前仅支持 acr，表示阿里云容器镜像服务 ACR。枚举值： acr : 阿里云容器镜像服务	acr
port	integer	否	智能体服务监听的 TCP 端口，取值为 1～65535。更新时可单独修改；省略时保留原端口。	8080
customImage	object	否	省略表示保留来源，完整提交表示主动更新自定义镜像；仅端口和启动命令变化无需提交
image	string	否	提交 customImage 时必填，由后端校验；完整 registry[:port]/repository:tag 或 registry[:port]/repository@sha256:digest，支持多级路径，不带协议或用户信息	registry.example.com/team/agent:v1
password	string	否	本次仓库密码或 Token	example-registry-token
pullNetwork	object	否	提交 customImage 时必填，由后端校验；完整独立拉取网络配置，公网只传 type=public
securityGroupId	string	否	type=vpc 时必填，须属于所选 VPC	sg-example
type	string	否	提交 pullNetwork 时必填，由后端校验；新建默认公网，与 Agent 运行网络独立枚举值： public vpc	public
vSwitchId	string	否	type=vpc 时必填，须属于所选 VPC	vsw-example
vpcId	string	否	type=vpc 时必填，所属账号和地域由后端校验	vpc-example
skipTlsVerify	boolean	否	跳过 HTTPS 证书校验	false
username	string	否	本次仓库用户名	reader
description	string	否	智能体的用途说明，去除首尾空白后最多 1024 个字符。省略保留原值，传 null 清除描述。	提供对话服务的自定义智能体
environment	object	否	智能体进程的用户环境变量配置。省略整个 environment 保留原值；提供 variables 时整体替换列表，保留的变量须一并提交。variables=[]、environment=null，或提供 environment 但省略 variables，均可清空用户配置的环境变量。
variables	array<object>	否	用户环境变量完整列表。非空列表整体替换原列表，空数组清空；每项 name 必须非空且在列表中唯一，value 必须为字符串，允许空字符串。
	object	否	一个环境变量配置项。
name	string	是	环境变量名称，不能为空，且在本次环境变量列表中不得重复。	LOG_LEVEL
value	string	是	环境变量值，必须为字符串，允许空字符串。	info
healthCheck	object	否	可选的 HTTP 健康检查配置。提供该对象时必须填写 port，未指定的其他项使用默认值。创建时省略表示不配置；更新时省略该顶层字段保留原配置，传 null 移除健康检查。
healthyThreshold `deprecated`	integer	否	此参数当前不生效，请省略。	1
intervalSeconds	integer	否	两次健康检查的间隔，单位为秒，必须为正整数，省略时默认为 10。	10
path	string	否	HTTP 健康检查路径，必须以 / 开头，省略时默认为 /healthz。	/healthz
port	integer	否	健康检查访问的端口，配置健康检查时必须填写，取值为 1～65535。	8080
timeoutSeconds	integer	否	单次健康检查的超时秒数，必须为正整数且小于 intervalSeconds，省略时默认为 2。	2
unhealthyThreshold	integer	否	连续健康检查失败达到该次数后判定不健康，必须为正整数，省略时默认为 3。	3
logging	object	否	智能体日志投递配置，可指定日志服务 SLS 的 Project 和 Logstore。创建或更新成功后，请确认日志是否正常投递。
sls	object	否	SLS 日志投递目标。更新该对象时，project 和 logstore 须同时提供且不能为空。
logstore	string	否	接收智能体日志的 SLS Logstore 名称。	agent-runtime
project	string	否	接收智能体日志的 SLS Project 名称。	my-agent-logs
name	string	否	自定义智能体名称，去除首尾空白后长度为 1～128 个字符，同一工作空间内不可重名。省略保留原值，不能传 null 或空白名称。	my-custom-agent
network	object	否	智能体的网络访问配置。提供该对象时，省略的访问项按允许处理；实际可访问范围仍受工作空间网络配置限制。更新时若需保留原限制，请同时填写 accessInternet 和 accessVpc。
accessInternet	object	否	互联网访问配置。省略该访问项时，智能体侧不限制互联网访问；仍需工作空间允许互联网访问。
enabled	boolean	否	是否允许智能体访问互联网。配置 accessInternet 时必须提供布尔值；实际生效还需工作空间允许互联网访问。
accessVpc	object	否	用户 VPC 访问配置。省略该访问项时，智能体侧不限制 VPC 访问；仍需工作空间配置并允许访问用户 VPC。
enabled	boolean	否	是否允许智能体访问工作空间配置的用户 VPC。配置 accessVpc 时必须提供布尔值；实际生效还需工作空间允许 VPC 访问。
observability	object	否	高代码 Agent 观测配置
enabled	boolean	否	启用 Agent 观测
ossMounts	array<object>	否	OSS 挂载列表，与 agenticFsMounts 合计最多 10 项。每项须填写 bucketName、path 和 mountPath；挂载目标不得重复或相互覆盖。更新时整体替换该列表，传 [] 清空。
	object	否	一个 OSS 目录挂载配置项。
bucketName	string	否	OSS Bucket 名称，每个挂载项必填。长度为 3～63 个字符，仅包含小写字母、数字和短横线，不能以短横线开头或结尾。	my-agent-data
mountPath	string	否	容器内 /mnt/oss/ 下的子目录，每个挂载项必填。挂载目标不得重复或形成父子覆盖。	/mnt/oss/train
path	string	否	Bucket 内非空的对象目录前缀，例如 datasets/train。首尾的 / 会被去除；不支持根目录，请勿使用上级目录跳转。	datasets/train
readOnly	boolean	否	是否只读挂载。true 表示只读，false 表示可读写；省略时默认为 false。
protocol	array<object>	否	智能体支持的调用协议列表，每项包含协议类型以及可选的路径和请求头。更新时整体替换该列表。
	array<object>	否	一种调用协议及其路径、请求头配置。
headers	object	否	当前协议的请求头配置。键为非空的请求头名称，值必须为字符串。
	string	否	协议请求头的字符串值。	application/json
paths	array<object>	否	当前协议对应的接口路径列表。
	object	否	一个接口路径及其用途说明。
description	string	否	当前接口路径的用途说明。	AG-UI 对话接口
name	string	是	当前协议对应的非空接口路径。	/agui
type	string	是	调用协议类型。agui：AG-UI 协议；openai-chat-completion：OpenAI Chat Completions 兼容协议；custom：自定义协议。枚举值： openai-chat-completion : OpenAI 对话补全兼容协议 agui : AG-UI 协议 custom : 自定义协议	agui
roleArn	string	否	智能体访问用户云资源时使用的 RAM 角色 ARN。角色需具备所访问云资源的权限。	acs:ram::1234567890123456:role/agentcore-runtime-role
runtime	object	否	运行配置。提供该对象时，compute 和 sessionPolicy 必须同时存在；若需保留原弹性策略，请一并提供完整的 hpa 配置。省略 runtime 顶层字段保留原配置。
compute	object	是	智能体运行实例的计算资源配置。
computeClass	string	是	计算规格。INTERACTIVE：1 vCPU、2 GiB 内存；STANDARD：2 vCPU、4 GiB 内存；HEAVY：4 vCPU、8 GiB 内存。枚举值： HEAVY : 高负载型：4 vCPU、8 GiB 内存 INTERACTIVE : 交互型：1 vCPU、2 GiB 内存 STANDARD : 标准型：2 vCPU、4 GiB 内存	STANDARD
hpa	object	否	弹性、单实例并发会话和会话空闲超时配置。提供 runtime 时，省略 hpa 或其字段使用默认值：enabled=false、minSandboxCount=1、maxSandboxCount=10、maxConcurrentSessionsPerSandbox=100、sessionTtlSeconds=600。更新时若需保留原策略，请一并提供完整 hpa；省略整个 runtime 保留原配置。数量上下限是配置值，实际实例数量见 sandboxPhaseCounts。
enabled	boolean	是	是否启用弹性扩缩容。true 开启，false 关闭。提供 runtime 但未配置 hpa 时默认关闭；省略整个 runtime 时保留原配置。
maxConcurrentSessionsPerSandbox	integer	否	单个运行实例的最大并发会话数，取值为 1～100。提供 runtime 时，省略本字段使用默认值 100。	100
maxSandboxCount	integer	否	配置的实例数量上限，范围 0～100，且不能小于 minSandboxCount。提供 runtime 时，省略本字段使用默认值 10；自动扩缩容关闭时，该值不表示固定部署的实例数量。	10
minSandboxCount	integer	否	配置的实例数量下限，范围 0～100，且不能大于 maxSandboxCount。提供 runtime 时，省略本字段使用默认值 1；实际实例数量通过 sandboxPhaseCounts 查询。	1
sessionTtlSeconds	integer	否	会话空闲上限，单位为秒，取值为 60～86400。提供 runtime 时，省略本字段使用默认值 600。	600
sessionPolicy	object	是	会话策略配置，用于设置请求的会话关联方式。
headerName	string	否	会话策略使用的 HTTP 请求头名称。type 为 ISOLATED_HEADER_FIELD 时必填，须为合法的 HTTP 请求头名称；其他策略请省略。	X-Session-Id
type	string	是	会话策略类型。AFFINITY：会话亲和；ISOLATED_HEADER_FIELD：使用 headerName 指定请求头关联会话。ISOLATED_COOKIE 暂不建议使用。DISABLED 为兼容选项，响应返回 AFFINITY。枚举值： DISABLED : 兼容选项，响应为会话亲和 AFFINITY : 会话亲和 ISOLATED_HEADER_FIELD : 基于请求头的会话策略 ISOLATED_COOKIE : Cookie 会话选项（暂不建议使用）	AFFINITY
useImageCache	boolean	否	更新未传保留原值；显式 true/false 设置，不自动补 false。新契约拒绝 null 和非法类型；既有兼容入口按迁移约定处理。	true
clientToken	string	否	提交幂等标识，长度为 1～128 个字符，允许字母、数字、点、下划线、冒号和连字符。显式提交 customImage 时必填；传入后按租户和工作空间记录本次提交，相同参数重试返回已有受理结果，不同提交内容须使用新标识。不传时，重试前先查询更新状态。	custom-agent-request-20261010-001

以下均为 body 参数值；路径参数 workspaceId、agentId 单独填写。

更新同一 ACR 仓库的镜像标签，沿用其余制品配置：

{
  "artifact": {
    "container": {
      "tag": "v1.0.1"
    }
  }
}

替换用户环境变量列表，列表中包含希望保留的全部变量；未提交 runtime，原运行配置保持不变：

{
  "environment": {
    "variables": [
      {
        "name": "APP_ENV",
        "value": "production"
      },
      {
        "name": "LOG_LEVEL",
        "value": "info"
      }
    ]
  }
}

清空用户环境变量：

{
  "environment": {
    "variables": []
  }
}

开启弹性时，计算规格和会话策略填写期望保留或更新的配置，并携带完整 hpa：

{
  "runtime": {
    "compute": {
      "computeClass": "STANDARD"
    },
    "sessionPolicy": {
      "type": "AFFINITY"
    },
    "hpa": {
      "enabled": true,
      "minSandboxCount": 1,
      "maxSandboxCount": 3,
      "maxConcurrentSessionsPerSandbox": 10,
      "sessionTtlSeconds": 600
    }
  }
}

返回参数

名称	类型	描述	示例值
	object
code	string	请求结果码。成功时为 SUCCESS。	SUCCESS
data	object	自定义智能体的最新提交配置及状态。响应成功表示请求已受理，配置可能尚未生效。
accessMode	string	入站访问方式枚举值： API_KEY USER	API_KEY
accessScope	string	用户访问范围枚举值： ALL SPECIFIED	ALL
agentId	string	自定义智能体的唯一标识，可从 CreateCustomAgent 或 ListCustomAgents 的响应中获取。	agent-550e8400e29b41d4a716446655440000
agenticFsMounts	array<object>	最新提交的 AgenticFS 额外挂载列表。
	object	一个 AgenticFS AccessPoint 目录挂载配置项。
mountPath	string	容器内的 AgenticFS 挂载目录，位于 /mnt/agenticfs/ 下。	/mnt/agenticfs/data
path	string	挂载的 AccessPoint 内相对目录。	workspace/data
readOnly	boolean	是否只读挂载。true 表示只读，false 表示可读写。	false
server	string	挂载使用的 AgenticFS AccessPoint 域名。	ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com
artifact	object	最新提交的部署制品配置，包含服务监听端口和 ACR 容器镜像。是否已生效请结合 latestVersionStatus 判断。
code	object	代码包部署配置，与 container 互斥。代码包使用 ZIP 或 TAR.GZ 格式，依赖由用户打包，平台不安装依赖或在线构建。
entrypoint	string	代码包启动命令，代码包模式必填。工作目录为解压后的代码根目录 /code，例如 python main.py。支持引号和转义，不自动展开环境变量、管道或逻辑运算；复杂命令请使用包内脚本。	python main.py
languageRuntime	string	当前已保存配置的代码运行环境标识。运行镜像使用已保存的快照，目录增加新版本不会自动改变现有配置。	python3.12
sourceUri	string	当前已保存配置引用的平台固定代码包 oss:// 地址，不包含源 HTTPS 链接的签名参数。可用于复用已有代码包；下载内容请调用 GetAgentCodePackageDownloadUrl。	oss://agentcore-platform-example/code-packages/workspaces/ws-a1b2c3d4e5f6/550e8400-e29b-41d4-a716-446655440000/package.zip
container	object	最新提交的 ACR 容器镜像配置。
entrypoint	string	自定义的可执行程序及启动参数。未配置时使用镜像默认启动方式。	python app.py
instanceId	string	镜像仓库所属的 ACR 实例 ID。	cri-a1b2c3d4e5f6
namespace	string	ACR 镜像仓库所属的命名空间。	my-agent
repo	string	ACR 命名空间中的镜像仓库名称。	chat-agent
tag	string	最新提交的镜像标签。	v1.0.0
type	string	镜像来源类型，acr 表示阿里云容器镜像服务 ACR。枚举值： acr : 阿里云容器镜像服务	acr
port	integer	智能体服务监听的 TCP 端口。	8080
codePackageInfo	object	当前已保存代码包信息
crc64	string	代码包对象 CRC64	456
etag	string	代码包对象 ETag	fixed-etag
fileName	string	原始代码包文件名	main.zip
fileSize	integer	代码包压缩大小	123
format	string	代码包格式枚举值： zip : ZIP 压缩包 tar.gz : GZIP 压缩的 TAR 归档包	zip
createMode	string	智能体创建方式。自定义智能体返回 CUSTOM。	CUSTOM
createdAt	string	智能体创建时间，采用 ISO 8601 格式，末尾 Z 表示 UTC 时区，可包含小数秒。	2026-10-10T06:00:00Z
currentImage	object	当前有效配置版本的镜像来源快照；首次配置生效前为 null，不代替健康状态
image	string	custom 来源的原始镜像地址	registry.example.com/team/agent:v1
instanceId	string	acr 来源的实例 ID	cri-example
namespace	string	acr 来源的命名空间	team
pullNetwork	object	custom 来源的独立拉取网络
securityGroupId	string	type=vpc 时必填，须属于所选 VPC	sg-example
type	string	提交 pullNetwork 时必填，由后端校验；新建默认公网，与 Agent 运行网络独立枚举值： public vpc	public
vSwitchId	string	type=vpc 时必填，须属于所选 VPC	vsw-example
vpcId	string	type=vpc 时必填，所属账号和地域由后端校验	vpc-example
repo	string	acr 来源的仓库名	agent
skipTlsVerify	boolean	custom 来源的证书例外选项	false
sourceType	string	当前有效版本的镜像来源类型枚举值： acr custom	custom
tag	string	acr 来源的标签	v1
username	string	有效镜像的来源用户名	reader
customImage	object	最近保存的来源与该来源已验证用户名；可能准备中或失败，不返回密码
image	string	最新保存的来源地址，可能仍在准备中	registry.example.com/team/agent:v1
pullNetwork	object	保存的独立拉取网络
securityGroupId	string	type=vpc 时必填，须属于所选 VPC	sg-example
type	string	提交 pullNetwork 时必填，由后端校验；新建默认公网，与 Agent 运行网络独立枚举值： public vpc	public
vSwitchId	string	type=vpc 时必填，须属于所选 VPC	vsw-example
vpcId	string	type=vpc 时必填，所属账号和地域由后端校验	vpc-example
skipTlsVerify	boolean	保存的 HTTPS 证书例外选项	false
username	string	已验证的来源用户名	reader
deployType	string	智能体部署方式。自定义智能体由平台部署和管理，返回 MANAGED。	MANAGED
description	string	智能体的用途说明。	提供对话服务的自定义智能体
effectiveSpecVersion	integer	已生效配置版本	1
environment	object	智能体进程的环境变量配置。
variables	array<object>	最新提交的环境变量列表。
	object	一个环境变量配置项。
name	string	环境变量名称。	LOG_LEVEL
value	string	环境变量的字符串值，允许空字符串。	info
healthCheck	object	智能体的 HTTP 健康检查配置。未配置时为空。
healthyThreshold `deprecated`	integer	此参数当前不生效。	1
intervalSeconds	integer	两次健康检查的间隔，单位为秒。	10
path	string	HTTP 健康检查路径。	/healthz
port	integer	HTTP 健康检查访问的端口。	8080
timeoutSeconds	integer	单次健康检查的超时时间，单位为秒。	2
unhealthyThreshold	integer	连续健康检查失败达到该次数后判定不健康。	3
imageCacheId	string	当前关联镜像缓存 ID	img-example
imageCachePreparation	object	本次缓存准备受理摘要
imageId	string	本次关联缓存 ID	img-example
statusAtAcceptance	string	受理时缓存状态枚举值： READY : 缓存已就绪 FAILED : 缓存准备失败 PENDING : 缓存准备中	PENDING
submissionStatus	string	缓存准备受理状态枚举值： ACCEPTED : 请求已受理	ACCEPTED
imagePreparation	object	当前关联的镜像准备任务；phase 为受理提示，实时进度查询准备接口，普通保存不创建镜像准备
phase	string	本次镜像准备阶段；配置受理不等于部署成功枚举值： QUEUED CHECKING COPYING STARTING HEALTH_CHECKING SUCCEEDED FAILED CANCELLED	QUEUED
preparationId	string	Console 本次提交任务 ID，不是 RM operationId	agent-example:1
latestExecutionError	object	最新配置版本的等待或执行错误，仅在该版本等待重试或执行失败时返回。
code	string	最新配置的等待或执行失败原因码，用于判断后续处理方式。	AgentExecutionFailed
message	string	最新配置等待或执行失败的原因说明。请结合 code 和 retryable 判断后续操作。	Agent 执行失败，请检查配置后重新提交。
retryable	boolean	是否会自动重试。true 时可稍后再次查询；false 时请根据原因检查并修复配置后重新提交。
latestSpecVersion	integer	当前最新配置版本号。相同配置的更新可能保留原版本号；本字段不代表该配置已经生效。	1
latestVersionStatus	string	latestSpecVersion 对应的执行状态。pending：等待执行；processing：执行中；waiting_retry：等待重试；succeeded：执行成功；failed：执行失败；superseded：已被后续版本替代。枚举值： waiting_retry : 等待重试 pending : 等待执行 processing : 执行中 failed : 执行失败 superseded : 已被后续版本替代 succeeded : 执行成功	succeeded
logging	object	最新提交的日志投递配置。
sls	object	SLS 日志投递目标。
logstore	string	接收智能体日志的 SLS Logstore 名称。	agent-runtime
project	string	接收智能体日志的 SLS Project 名称。	my-agent-logs
name	string	自定义智能体名称。	my-custom-agent
network	object	智能体的网络访问配置，实际访问范围还受工作空间网络配置限制。
accessInternet	object	智能体的互联网访问配置。未配置该项时，智能体侧允许访问，仍受工作空间限制。
enabled	boolean	智能体侧是否允许访问互联网，实际访问仍受工作空间限制。
accessVpc	object	智能体的用户 VPC 访问配置。未配置该项时，智能体侧允许访问，仍受工作空间限制。
enabled	boolean	智能体侧是否允许访问工作空间配置的用户 VPC，实际访问仍受工作空间限制。
observability	object	高代码 Agent 观测配置
enabled	boolean	启用 Agent 观测
ossMounts	array<object>	最新提交的 OSS 目录挂载列表。
	object	一个 OSS 目录挂载配置项。
bucketName	string	挂载的 OSS Bucket 名称。	my-agent-data
mountPath	string	容器内的 OSS 挂载目录，位于 /mnt/oss/ 下。	/mnt/oss/train
path	string	挂载的 Bucket 内对象目录前缀。	datasets/train
readOnly	boolean	是否只读挂载。true 表示只读，false 表示可读写。
protocol	array<object>	智能体的调用协议配置列表。
	array<object>	一种调用协议及其路径、请求头配置。
headers	object	当前协议的请求头配置，键为名称，值为字符串。
	string	协议请求头的字符串值。	application/json
paths	array<object>	当前协议对应的接口路径列表。
	object	一个接口路径及其用途说明。
description	string	当前接口路径的用途说明。	AG-UI 对话接口
name	string	当前协议对应的接口路径。	/agui
type	string	调用协议类型。agui：AG-UI 协议；openai-chat-completion：OpenAI Chat Completions 兼容协议；custom：自定义协议。枚举值： openai-chat-completion : OpenAI 对话补全兼容协议 agui : AG-UI 协议 custom : 自定义协议	agui
regionId	string	智能体所属工作空间的地域 ID。	cn-hangzhou
roleArn	string	智能体访问用户云资源时使用的 RAM 角色 ARN。	acs:ram::1234567890123456:role/agentcore-runtime-role
runtime	object	最新提交的运行配置，包括计算规格、会话策略和弹性策略。
compute	object	智能体运行实例的计算资源配置。
computeClass	string	计算规格。INTERACTIVE：1 vCPU、2 GiB 内存；STANDARD：2 vCPU、4 GiB 内存；HEAVY：4 vCPU、8 GiB 内存。枚举值： HEAVY : 高负载型：4 vCPU、8 GiB 内存 INTERACTIVE : 交互型：1 vCPU、2 GiB 内存 STANDARD : 标准型：2 vCPU、4 GiB 内存	STANDARD
hpa	object	当前保存的弹性策略配置，包含开关、实例数量上下限、单实例并发会话上限和会话空闲超时。实例数量上下限属于配置，实际数量以 sandboxPhaseCounts 查询快照为准。
enabled	boolean	当前保存的自动扩缩容开关。true 开启，false 关闭；未配置 HPA 时由后端补齐为 false。
maxConcurrentSessionsPerSandbox	integer	配置的单个运行实例最大并发会话数。	100
maxSandboxCount	integer	当前保存的实例数量上限，范围 0～100；未配置时默认 10，且不能小于 minSandboxCount。	10
minSandboxCount	integer	当前保存的实例数量下限，范围 0～100；未配置时默认 1。实际运行实例数量见 sandboxPhaseCounts。	1
sessionTtlSeconds	integer	配置的会话空闲上限，单位为秒。	600
sessionPolicy	object	智能体的会话策略配置。
headerName	string	会话策略使用的 HTTP 请求头名称，适用于 ISOLATED_HEADER_FIELD。	X-Session-Id
type	string	会话策略类型。AFFINITY：会话亲和；ISOLATED_HEADER_FIELD：使用 headerName 指定请求头关联会话。ISOLATED_COOKIE 暂不建议使用。请求中的兼容值 DISABLED 返回为 AFFINITY。枚举值： DISABLED : 兼容选项，响应为会话亲和 AFFINITY : 会话亲和 ISOLATED_HEADER_FIELD : 基于请求头的会话策略 ISOLATED_COOKIE : Cookie 会话选项（暂不建议使用）	AFFINITY
sandboxPhaseCounts	object	按运行实例阶段统计数量。键包括 PENDING（创建或初始化中）、RUNNING（运行中）、HIBERNATING（休眠中）、HIBERNATED（已休眠）、RESUMING（恢复中）、TERMINATING（终止中）和 FAILED（失败）。仅返回实际出现的阶段，缺少的键按 0 理解。
	integer	对应运行实例阶段的实例数量。	1
status	string	智能体整体状态。Creating：创建中；Running：运行中；Failed：失败；Updating：更新中；Deleting：删除中；Deleted：已删除。最新配置执行进度请查询 latestVersionStatus。枚举值： Creating : 创建中 Failed : 失败 Running : 运行中 Updating : 更新中 Deleted : 已删除 Deleting : 删除中	Running
updatedAt	string	智能体最近更新时间，采用 ISO 8601 格式，末尾 Z 表示 UTC 时区，可包含小数秒。	2026-10-10T06:05:00Z
useImageCache	boolean	镜像缓存开关	true
workspaceId	string	自定义智能体所属的工作空间 ID。	ws-a1b2c3d4e5f6
httpStatusCode	integer	本次请求的 HTTP 状态码。成功时为 200。	200
message	string	本次请求的处理结果说明。成功时为 success。	success
requestId	string	本次请求的唯一标识，用于定位和排查问题。	550E8400-E29B-41D4-A716-446655440000
success	boolean	请求是否处理成功。true 表示处理成功；创建、更新或删除成功不代表后台操作已经完成。

success=true 表示本次更新请求已受理。通过 GetCustomAgent 查询 latestSpecVersion（最新期望配置版本）、effectiveSpecVersion（已生效配置版本）、latestVersionStatus（配置处理状态）和 latestExecutionError（处理失败或等待原因）。

runtime.hpa 返回保存的弹性配置，sandboxPhaseCounts 返回按实例 Phase 统计的数量快照。配置数量上下限、当前运行实例数和配置处理状态分别表示不同信息；latestVersionStatus=succeeded 不能单独证明全部旧实例已经释放或替换。

示例

正常返回示例

JSON格式

{
  "code": "SUCCESS",
  "data": {
    "accessMode": "API_KEY",
    "accessScope": "ALL",
    "agentId": "agent-550e8400e29b41d4a716446655440000",
    "agenticFsMounts": [
      {
        "mountPath": "/mnt/agenticfs/data",
        "path": "workspace/data",
        "readOnly": false,
        "server": "ap-0123456789abcdef0.0123456789-vlm36.cn-hangzhou.nas.aliyuncs.com"
      }
    ],
    "artifact": {
      "code": {
        "entrypoint": "python main.py",
        "languageRuntime": "python3.12",
        "sourceUri": "oss://agentcore-platform-example/code-packages/workspaces/ws-a1b2c3d4e5f6/550e8400-e29b-41d4-a716-446655440000/package.zip"
      },
      "container": {
        "entrypoint": "python app.py",
        "instanceId": "cri-a1b2c3d4e5f6",
        "namespace": "my-agent",
        "repo": "chat-agent",
        "tag": "v1.0.0",
        "type": "acr"
      },
      "port": 8080
    },
    "codePackageInfo": {
      "crc64": "456",
      "etag": "fixed-etag",
      "fileName": "main.zip",
      "fileSize": 123,
      "format": "zip"
    },
    "createMode": "CUSTOM",
    "createdAt": "2026-10-10T06:00:00Z",
    "currentImage": {
      "image": "registry.example.com/team/agent:v1",
      "instanceId": "cri-example",
      "namespace": "team",
      "pullNetwork": {
        "securityGroupId": "sg-example",
        "type": "public",
        "vSwitchId": "vsw-example",
        "vpcId": "vpc-example"
      },
      "repo": "agent",
      "skipTlsVerify": false,
      "sourceType": "custom",
      "tag": "v1",
      "username": "reader"
    },
    "customImage": {
      "image": "registry.example.com/team/agent:v1",
      "pullNetwork": {
        "securityGroupId": "sg-example",
        "type": "public",
        "vSwitchId": "vsw-example",
        "vpcId": "vpc-example"
      },
      "skipTlsVerify": false,
      "username": "reader"
    },
    "deployType": "MANAGED",
    "description": "提供对话服务的自定义智能体",
    "effectiveSpecVersion": 1,
    "environment": {
      "variables": [
        {
          "name": "LOG_LEVEL",
          "value": "info"
        }
      ]
    },
    "healthCheck": {
      "healthyThreshold": 1,
      "intervalSeconds": 10,
      "path": "/healthz",
      "port": 8080,
      "timeoutSeconds": 2,
      "unhealthyThreshold": 3
    },
    "imageCacheId": "img-example",
    "imageCachePreparation": {
      "imageId": "img-example",
      "statusAtAcceptance": "PENDING",
      "submissionStatus": "ACCEPTED"
    },
    "imagePreparation": {
      "phase": "QUEUED",
      "preparationId": "agent-example:1"
    },
    "latestExecutionError": {
      "code": "AgentExecutionFailed",
      "message": "Agent 执行失败，请检查配置后重新提交。",
      "retryable": true
    },
    "latestSpecVersion": 1,
    "latestVersionStatus": "succeeded",
    "logging": {
      "sls": {
        "logstore": "agent-runtime",
        "project": "my-agent-logs"
      }
    },
    "name": "my-custom-agent",
    "network": {
      "accessInternet": {
        "enabled": true
      },
      "accessVpc": {
        "enabled": true
      }
    },
    "observability": {
      "enabled": true
    },
    "ossMounts": [
      {
        "bucketName": "my-agent-data",
        "mountPath": "/mnt/oss/train",
        "path": "datasets/train",
        "readOnly": true
      }
    ],
    "protocol": [
      {
        "headers": {
          "key": "application/json"
        },
        "paths": [
          {
            "description": "AG-UI 对话接口",
            "name": "/agui"
          }
        ],
        "type": "agui"
      }
    ],
    "regionId": "cn-hangzhou",
    "roleArn": "acs:ram::1234567890123456:role/agentcore-runtime-role",
    "runtime": {
      "compute": {
        "computeClass": "STANDARD"
      },
      "hpa": {
        "enabled": true,
        "maxConcurrentSessionsPerSandbox": 100,
        "maxSandboxCount": 10,
        "minSandboxCount": 1,
        "sessionTtlSeconds": 600
      },
      "sessionPolicy": {
        "headerName": "X-Session-Id",
        "type": "AFFINITY"
      }
    },
    "sandboxPhaseCounts": {
      "key": 1
    },
    "status": "Running",
    "updatedAt": "2026-10-10T06:05:00Z",
    "useImageCache": true,
    "workspaceId": "ws-a1b2c3d4e5f6"
  },
  "httpStatusCode": 200,
  "message": "success",
  "requestId": "550E8400-E29B-41D4-A716-446655440000",
  "success": true
}

错误码

HTTP status code	错误码	错误信息
400	AgentCodePackage.Invalid	The code package source or format is invalid.
400	AgentCodePackage.SizeExceeded	The compressed code package exceeds 500000000 bytes.
400	AcrEditionUnsupported	The ACR edition is not supported.
400	AcrAccountUnsupported	The ACR account is not supported.
400	AcrRegionUnsupported	The ACR region is not supported.
400	InvalidParameter.%s	The specified parameter %s is not valid. Reason: %s Expected format: %s
400	InvalidArgument	The specified request parameter is invalid.
400	CustomImage.InvalidReference	Use registry/repository:tag or registry/repository@sha256:digest without a scheme or credentials.
400	CustomImage.CredentialPairRequired	Provide non-empty customImage.username and customImage.password together, or omit both for anonymous access.
403	AgentCodePackage.SourceAccessDenied	The workspace role cannot read the source code package object.
403	AcrRamUnauthorized	The shared role is not authorized for the specified ACR instance.
403	AgenticFsRamUnauthorized	Authorize the Workspace role for this AgenticFS AccessPoint.
403	AgenticFsMountDisabled	New or changed AgenticFS mounts are not enabled.
502	AgentCodePackage.CopyFailed	The code package could not be transferred to platform storage. The configuration was not saved.
404	AgentCodePackage.SourceNotFound	The source code package object does not exist.
404	AgenticFsAccessPointNotFound	The AccessPoint is not available in this Workspace account and region.
503	AgentCodePackage.StorageUnavailable	The platform code package storage is unavailable.
503	AgentCodePackage.AuthorizationUnavailable	The code package authorization service is unavailable.
503	AgentCodeRuntime.Unavailable	The code runtime catalog is unavailable or invalid.
503	AcrAuthorizationServiceUnavailable	The authorization service is temporarily unavailable.
503	AgenticFsIntegrationNotConfigured	The NAS discovery and RAM authorization integration is not configured.
503	AgenticFsServiceUnavailable	NAS resource or RAM authorization lookup failed.
503	ImageCacheUnavailable	No image cache execution resources are available in the requested cache region.
503	ACRProviderUnavailable	The Agent image credential provider is temporarily unavailable.
504	AgentCodePackage.CopyTimeout	The code package transfer timed out. The configuration was not saved.
409	AgentCodePackage.SourceChanged	The source object changed during reading. Retry this operation.
409	AgentCodePackage.Unavailable	The saved configuration has no downloadable code package.
409	Agent.Operation.Conflict	The agent configuration changed or the operation conflicts with its current state.
409	AcrRoleConflict	The workspace has conflicting authorization role references.
409	AcrPrerequisiteNotReady	The workspace is not ready for private image access.
409	AcrCapacityUnsupported	The workspace capacity mode is not supported.
409	WorkspaceDeleting	The workspace is being deleted.
409	AcrOperationConflict	A conflicting authorization operation is in progress.
409	AgenticFsPrerequisiteNotReady	AgenticFS requires an active RAM-enabled AccessPoint and user VPC access.
409	ImageCacheRegionMismatch	The registered cache region is incompatible with the requested region.
409	WorkspaceNotReady	The Agent workspace is not ready.
409	ImageCacheVersionConflict	The source tag is already registered with another digest. Select a new tag.
409	ImageCacheDeleting	The image cache is being deleted.
409	ImageCacheTargetChanged	The current execution configuration is incompatible with the registered cache target.
409	ImageCacheNetworkUnavailable	No configured source transfer network supports the requested access modes.
409	SubmissionPending	The submission result is not confirmed. Query the current Agent and cache status before submitting again.
409	ACRCapabilityUnsupported	The Agent execution target does not support the required image credentials.
409	ACRProfileConflict	The Agent image credential configuration conflicts with the current profile.
409	Agent.Binding.NotReady	The %s binding for workspace %s is not ready.
409	CustomImage.NotPrepared	No verified fixed image is available for this source. Check its image preparation.
409	ImageCacheBusy	Another image cache or Agent submission is in progress; retry later.

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。