ListCustomAgents - 查询自定义智能体列表
分页查询指定工作空间中的自定义智能体摘要。完整配置及最新版本的执行结果请通过 GetCustomAgent 查询。
接口说明
maxResults 默认值为 20，最大值为 100；省略或传入 0 时使用默认值。
首次请求省略 nextToken，后续请求原样传入上一次响应返回的 nextToken，并保持相同的工作空间。nextToken 是不透明令牌，请勿解析或自行构造。响应中的令牌为空时，表示没有下一页。
本接口返回当前页摘要，不返回完整部署配置或最新版本的执行错误。需要这些信息时，使用 items 中的 agentId 调用 GetCustomAgent。
调试
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
调试
授权信息
|
操作 |
访问级别 |
资源类型 |
条件关键字 |
关联操作 |
|
agentcore:ListCustomAgents |
list |
*CustomAgent
|
无 | 无 |
请求语法
GET /workspaces/{workspaceId}/custom-agents HTTP/1.1路径参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| workspaceId |
string |
是 |
自定义智能体所属的工作空间 ID。 |
ws-a1b2c3d4e5f6 |
请求参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| maxResults |
integer |
否 |
每页最大返回数量，取值为 1～100；省略或传入 0 时使用默认值 20。 |
20 |
| nextToken |
string |
否 |
查询下一页的不透明令牌。首次请求省略，后续原样使用上一次响应的 nextToken，并保持相同工作空间。请勿自行构造。 |
djE6YWdlbnRjb3JlLmFnZW50Lmxpc3QuY3VzdG9tOjIw |
返回参数
|
名称 |
类型 |
描述 |
示例值 |
|
object |
|||
| code |
string |
请求结果码。成功时为 SUCCESS。 |
SUCCESS |
| httpStatusCode |
integer |
本次请求的 HTTP 状态码。成功时为 200。 |
200 |
| items |
array<object> |
当前页的自定义智能体摘要列表。完整配置和最新版本执行结果请调用 GetCustomAgent 查询。 |
|
|
array<object> |
|||
| accessMode |
string |
入站访问方式 |
API_KEY |
| accessScope |
string |
用户访问范围 |
ALL |
| agentId |
string |
自定义智能体的唯一标识，可从 CreateCustomAgent 或 ListCustomAgents 的响应中获取。 |
agent-550e8400e29b41d4a716446655440000 |
| artifact |
object |
智能体制品 |
|
| 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 |
容器镜像部署配置。 |
|
| entrypoint |
string |
自定义的容器启动命令及参数；未配置时使用镜像默认启动方式。 |
python main.py |
| instanceId |
string |
ACR 企业版实例 ID。 |
cri-example |
| namespace |
string |
ACR 命名空间。 |
team |
| repo |
string |
ACR 镜像仓库名称。 |
app |
| tag |
string |
镜像标签。 |
v1 |
| type |
string |
容器镜像来源类型。 枚举值：
|
acr |
| port |
integer |
智能体服务监听端口。 |
8080 |
| codePackageInfo |
object |
当前已保存代码包信息 |
|
| crc64 |
string |
代码包对象 CRC64 |
456 |
| etag |
string |
代码包对象 ETag |
fixed-etag |
| fileName |
string |
原始代码包文件名 |
main.zip |
| fileSize |
integer |
代码包压缩大小 |
123 |
| format |
string |
代码包格式 枚举值：
|
zip |
| createMode |
string |
智能体创建方式。自定义智能体返回 CUSTOM。 |
CUSTOM |
| createdAt |
string |
智能体创建时间，采用 ISO 8601 格式，末尾 Z 表示 UTC 时区，可包含小数秒。 |
2026-10-10T06:00:00Z |
| deployType |
string |
智能体部署方式。自定义智能体由平台部署和管理，返回 MANAGED。 |
MANAGED |
| description |
string |
智能体的用途说明。 |
提供对话服务的自定义智能体 |
| latestSpecVersion |
integer |
当前最新配置版本号。相同配置的更新可能保留原版本号；本字段不代表该配置已经生效。 |
1 |
| name |
string |
自定义智能体名称。 |
my-custom-agent |
| 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：自定义协议。 枚举值：
|
agui |
| runtime |
string |
智能体的计算规格，取值为 INTERACTIVE、STANDARD 或 HEAVY。 |
STANDARD |
| status |
string |
智能体整体状态。Creating：创建中；Running：运行中；Failed：失败；Updating：更新中；Deleting：删除中；Deleted：已删除。最新配置执行进度请调用 GetCustomAgent 查询。 枚举值：
|
Running |
| updatedAt |
string |
智能体最近更新时间，采用 ISO 8601 格式，末尾 Z 表示 UTC 时区，可包含小数秒。 |
2026-10-10T06:05:00Z |
| workspaceId |
string |
自定义智能体所属的工作空间 ID。 |
ws-a1b2c3d4e5f6 |
| maxResults |
integer |
本次查询使用的每页最大返回数量。 |
20 |
| message |
string |
本次请求的处理结果说明。成功时为 success。 |
success |
| nextToken |
string |
查询下一页使用的不透明令牌。为空时表示没有下一页。请原样传入后续请求。 |
djE6YWdlbnRjb3JlLmFnZW50Lmxpc3QuY3VzdG9tOjIw |
| requestId |
string |
本次请求的唯一标识，用于定位和排查问题。 |
550E8400-E29B-41D4-A716-446655440000 |
| success |
boolean |
请求是否处理成功。true 表示处理成功；创建、更新或删除成功不代表后台操作已经完成。 |
|
| totalCount |
integer |
指定工作空间内符合查询条件的自定义智能体总数。 |
40 |
示例
正常返回示例
JSON格式
{
"code": "SUCCESS",
"httpStatusCode": 200,
"items": [
{
"accessMode": "API_KEY",
"accessScope": "ALL",
"agentId": "agent-550e8400e29b41d4a716446655440000",
"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 main.py",
"instanceId": "cri-example",
"namespace": "team",
"repo": "app",
"tag": "v1",
"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",
"deployType": "MANAGED",
"description": "提供对话服务的自定义智能体",
"latestSpecVersion": 1,
"name": "my-custom-agent",
"protocol": [
{
"headers": {
"key": "application/json"
},
"paths": [
{
"description": "AG-UI 对话接口",
"name": "/agui"
}
],
"type": "agui"
}
],
"runtime": "STANDARD",
"status": "Running",
"updatedAt": "2026-10-10T06:05:00Z",
"workspaceId": "ws-a1b2c3d4e5f6"
}
],
"maxResults": 20,
"message": "success",
"nextToken": "djE6YWdlbnRjb3JlLmFnZW50Lmxpc3QuY3VzdG9tOjIw",
"requestId": "550E8400-E29B-41D4-A716-446655440000",
"success": true,
"totalCount": 40
}错误码
访问错误中心查看更多错误码。
变更历史
更多信息，参考变更详情。