AI 助理
文档备案控制台
官方文档
首页 智能体构建和治理平台 AgentCore 开发参考 API参考 API目录 GetExternalAgent - 查询外部智能体

GetExternalAgent - 查询外部智能体

更新时间：
复制 MD 格式
我的收藏

查询指定外部智能体的详细信息。

接口说明

查询指定外部智能体的详细信息。

调试

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

调试

授权信息

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

  • 操作：是指具体的权限点。

  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

    • 对于必选的资源类型，用前面加 * 表示。

    • 对于不支持资源级授权的操作，用全部资源表示。

  • 条件关键字：是指云产品自身定义的条件关键字。

  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:GetExternalAgent

get

*ExternalAgent

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

 无 无

请求语法

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

路径参数

名称

类型

必填

描述

示例值
workspaceId

string

是

工作空间 ID。

ws-1
agentId

string

是

外部智能体 ID。

agent-1

请求参数

名称

类型

必填

描述

示例值

当前API无需请求参数

请求参数的具体含义和取值要求见下方参数说明。

返回参数

名称

类型

描述

示例值

object

查询外部智能体的成功响应。

code

string

业务状态码。成功时为 SUCCESS。

SUCCESS
data

object

外部智能体详情信息。

agentId

string

外部智能体 ID。

agent-1
configuredSkills

array<object>

仅包含用户追加或覆盖的 Skill，不包含模板继承项。资源模型读取此字段以保留更新语义；创建和更新仍使用请求中的 skills。

array<object>

name

string

Workspace AI Registry 中的 Skill 名称

web-search
sourceType

string

Skill 来源类型：REFERENCE 引用 AI Registry、STATIC 随包静态提供

REFERENCE
version

string

旧版兼容字段，新请求使用 sourceType 和 versionSelector

1.0.0
versionSelector

object

引用的版本选择器，省略时为 LABEL/latest；本期支持 LABEL/latest

type

string

版本选择器类型：LABEL 按标签、VERSION 按具体版本

LABEL
value

string

选择器取值：LABEL 时为标签名（如 latest），VERSION 时为具体版本号

latest
createMode

string

创建模式。

CUSTOM
createdAt

string

创建时间，RFC 3339 格式。

2026-01-01T00:00:00Z
deployType

string

部署类型。

SELF_HOSTED
description

string

外部智能体描述。

运行在用户环境中的代码评审智能体
externalAgentStatus

object

外部智能体上报的运行状态信息。

heartbeatStatus

string

心跳状态。ONLINE 表示最近心跳未超过配置的超时阈值；STALE 表示心跳已超时；UNKNOWN 表示心跳缺失或格式无效。枚举值：ONLINE（在线）、STALE（心跳过期）、UNKNOWN（未知）。

枚举值：

  • STALE :

    心跳过期

  • UNKNOWN :

    未知

  • ONLINE :

    在线

ONLINE
lastActiveAt

string

外部智能体最近一次活跃时间，RFC 3339 格式。

2026-01-01T00:00:00Z
lastHeartbeat

string

外部智能体最近一次心跳时间，RFC 3339 格式。

2026-01-01T00:00:00Z
localIP

string

外部智能体上报的本地 IP 地址。

10.0.0.42
runtime

string

外部智能体上报的运行时类型。

qwenpaw
instruction

string

智能体指令，用于指导智能体的行为。

你是一个代码评审助手
latestSpecVersion

integer

最新规格版本号。

1
latestVersionStatus

string

最新规格版本的处理状态。枚举值：pending（待处理）、processing（处理中）、waiting_retry（等待重试）、succeeded（成功）、failed（失败）、superseded（已被新版本取代）。

枚举值：

  • waiting_retry :

    等待重试

  • pending :

    待处理

  • processing :

    处理中

  • failed :

    失败

  • superseded :

    已被新版本取代

  • succeeded :

    成功

pending
model

object

模型配置。仅 modelSource 为 PLATFORM 时可用。

modelConnectionId

string

模型连接 ID。

mc-1
modelName

string

上游模型名称。

qwen-max
quota

object

模型 Token 配额配置及当前周期的配额使用状态；未配置配额时为空

enabled

boolean

配额是否处于启用状态；未配置配额时不返回

true
limitType

string

配额限制类型；当前仅支持 token

token
overLimit

boolean

当前周期是否已超出配额；只读，由后端返回

false
periodType

string

配额统计周期；day 表示按天，month 表示按月

day
ruleStatus

string

网关配额规则状态；只读，由后端返回

ACTIVE
usageLimit

integer

单个周期内允许消耗的 Token 上限

1000000
usedAmount

integer

当前周期已消耗的 Token 数；只读，由后端返回

12345
modelSource

string

模型配置来源。PLATFORM 表示由平台解析并下发 model 配置；RUNTIME 表示由外部运行时自行管理模型，不能同时传入 model。枚举值：PLATFORM（平台模型）、RUNTIME（运行时模型）。

枚举值：

  • PLATFORM :

    平台模型

  • RUNTIME :

    运行时模型

PLATFORM
name

string

外部智能体名称。

my-external-agent
regionId

string

地域 ID。

cn-hangzhou
runtime

string

外部智能体上报的运行时类型。

qwenpaw
skills

array<object>

技能配置列表。

array<object>

技能配置列表。

appliedVersion

string

运行时已生效版本，只读

1.0.0
fromTemplate

boolean

是否来自固定模板，只读；模板项不可移除

false
name

string

技能名称。

code-analysis
resolvedVersion

string

当前目标版本，只读

1.0.0
sourceType

string

Skill 来源类型：REFERENCE 引用 AI Registry、STATIC 随包静态提供

REFERENCE
version

string

技能版本。

1.0.0
versionSelector

object

引用的版本选择器，省略时为 LABEL/latest

type

string

版本选择器类型：LABEL 按标签、VERSION 按具体版本

LABEL
value

string

选择器取值：LABEL 时为标签名（如 latest），VERSION 时为具体版本号

latest
status

string

外部智能体状态。枚举值：Creating（创建中）、Running（运行中）、Failed（失败）、Updating（更新中）、Deleting（删除中）、Deleted（已删除）。

枚举值：

  • Creating :

    创建中

  • Failed :

    失败

  • Running :

    运行中

  • Updating :

    更新中

  • Deleted :

    已删除

  • Deleting :

    删除中

Running
template

object

智能体模板配置。

aiRegistry

object

AI Registry 模板配置。

name

string

AI Registry 中模板的名称。

code-review-template
version

string

AI Registry 中模板的版本。

1.0.0
tools

array<object>

工具配置列表。

object

工具配置列表。

name

string

工具名称。

code-reviewer
type

string

工具类型。枚举值：MCP（MCP 工具）。

枚举值：

  • MCP :

    MCP 工具

MCP
updatedAt

string

更新时间，RFC 3339 格式。

2026-01-01T00:00:00Z
workspaceId

string

工作空间 ID。

ws-1
httpStatusCode

integer

HTTP 状态码。成功时为 200。

200
message

string

请求处理结果消息。

success
requestId

string

请求 ID。

1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx
success

boolean

请求是否成功。

成功响应的字段含义见下方响应参数说明。

示例

正常返回示例

JSON格式

{
  "code": "SUCCESS",
  "data": {
    "agentId": "agent-1",
    "configuredSkills": [
      {
        "name": "web-search",
        "sourceType": "REFERENCE",
        "version": "1.0.0",
        "versionSelector": {
          "type": "LABEL",
          "value": "latest"
        }
      }
    ],
    "createMode": "CUSTOM",
    "createdAt": "2026-01-01T00:00:00Z",
    "deployType": "SELF_HOSTED",
    "description": "运行在用户环境中的代码评审智能体",
    "externalAgentStatus": {
      "heartbeatStatus": "ONLINE",
      "lastActiveAt": "2026-01-01T00:00:00Z",
      "lastHeartbeat": "2026-01-01T00:00:00Z",
      "localIP": "10.0.0.42",
      "runtime": "qwenpaw"
    },
    "instruction": "你是一个代码评审助手",
    "latestSpecVersion": 1,
    "latestVersionStatus": "pending",
    "model": {
      "modelConnectionId": "mc-1",
      "modelName": "qwen-max",
      "quota": {
        "enabled": true,
        "limitType": "token",
        "overLimit": false,
        "periodType": "day",
        "ruleStatus": "ACTIVE",
        "usageLimit": 1000000,
        "usedAmount": 12345
      }
    },
    "modelSource": "PLATFORM",
    "name": "my-external-agent",
    "regionId": "cn-hangzhou",
    "runtime": "qwenpaw",
    "skills": [
      {
        "appliedVersion": "1.0.0",
        "fromTemplate": false,
        "name": "code-analysis",
        "resolvedVersion": "1.0.0",
        "sourceType": "REFERENCE",
        "version": "1.0.0",
        "versionSelector": {
          "type": "LABEL",
          "value": "latest"
        }
      }
    ],
    "status": "Running",
    "template": {
      "aiRegistry": {
        "name": "code-review-template",
        "version": "1.0.0"
      }
    },
    "tools": [
      {
        "name": "code-reviewer",
        "type": "MCP"
      }
    ],
    "updatedAt": "2026-01-01T00:00:00Z",
    "workspaceId": "ws-1"
  },
  "httpStatusCode": 200,
  "message": "success",
  "requestId": "1a2b3c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "success": true
}

错误码

HTTP status code

错误码

错误信息

描述
404 Resource.NotFound The specified ExternalAgent does not exist.

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

变更历史

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

上一篇：GetCustomAgentImagePreparation - 查询自定义镜像准备进度下一篇：GetExternalAgentBootstrapOptions - 查询外部智能体接入网络