GetCustomAgent - 查询自定义智能体详情-智能体构建和治理平台 AgentCore-阿里云帮助中心

查询指定工作空间中的自定义智能体详情，包括部署配置、最新配置版本的执行状态和运行实例状态统计。

接口说明

创建或更新后，可轮询本接口查询最新配置版本的执行结果。latestVersionStatus 与 latestSpecVersion 对应；latestExecutionError 表示该版本的等待或失败原因，retryable 为 true 时可稍后再次查询。

返回的配置为最新提交的配置，可能尚未生效。请结合 latestVersionStatus、智能体整体状态 status 和运行实例统计 sandboxPhaseCounts 确认部署及运行情况。

查询不存在、已完成删除或不属于指定工作空间的自定义智能体时，返回资源不存在错误。

调试

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

调试

授权信息

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

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

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:GetCustomAgent

get

*CustomAgent

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

无

请求语法

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

路径参数

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

请求参数

名称

类型

必填

描述

示例值

当前API无需请求参数

返回参数

名称	类型	描述	示例值
	object
code	string	请求结果码。成功时为 SUCCESS。	SUCCESS
data	object	自定义智能体的最新提交配置及状态，配置是否已生效请结合 latestVersionStatus 判断。
accessMode	string	入站访问方式	API_KEY
accessScope	string	用户访问范围	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
vSwitchId	string	type=vpc 时必填，须属于所选 VPC	vsw-example
vpcId	string	type=vpc 时必填，所属账号和地域由后端校验	vpc-example
repo	string	acr 来源的仓库名	agent
skipTlsVerify	boolean	custom 来源的证书例外选项	false
sourceType	string	当前有效版本的镜像来源类型	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
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
imagePreparation	object	当前关联的镜像准备任务；phase 为受理提示，实时进度查询准备接口，普通保存不创建镜像准备
phase	string	本次镜像准备阶段；配置受理不等于部署成功	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	智能体的弹性策略配置。
enabled	boolean	是否启用弹性扩缩容。true 表示开启，false 表示关闭。
maxConcurrentSessionsPerSandbox	integer	配置的单个运行实例最大并发会话数。	100
maxSandboxCount	integer	配置的最大运行实例数。	10
minSandboxCount	integer	配置的最小运行实例数。	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 表示处理成功；创建、更新或删除成功不代表后台操作已经完成。

示例

正常返回示例

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",
    "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	错误码	错误信息	描述
404	Resource.NotFound	The specified CustomAgent does not exist.

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

变更历史

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