文档首页/ 智果（AgentArts）智能体平台/ API参考/ API/ 智能体运行时/ 智能体运行时执行（高代码）/ 调用智能体运行时--执行命令 - ExecuteRuntimeCommands
更新时间：2026-06-10 GMT+08:00
查看PDF
分享

调用智能体运行时--执行命令 - ExecuteRuntimeCommands

功能介绍

该接口用于调用已经部署好的高代码智能体运行时，在智能体内执行命令。部署智能体运行时请参见部署智能体运行时。

  • 适用场景：

调用已经部署好的高代码智能体运行时。

调用方法

请参见如何调用API。

授权信息

当前API调用无需身份策略权限。

URI

POST /runtimes/{runtime_name}/commands

表1 路径参数

参数

是否必选

参数类型

描述

runtime_name

是

String

参数解释：

智能体运行时名称。

智能体运行时名称获取方式：

  1. 进入AgentArts平台，在左侧导航栏选择“部署运行 > 智能体运行时 ”。

  2. 在智能体运行时列表中“智能体运行时名称/ID”处获取智能体运行时名称。

约束限制:

不涉及。

取值范围：

以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。

默认取值:

不涉及。
表2 Query参数

参数

是否必选

参数类型

描述

endpoint

否

String

参数解释：

用于调用智能体运行时使用的访问方式名称，访问指定的智能体运行时版本。

获取访问方式名称请参考如下：

  1. 进入AgentArts平台，在左侧导航栏选择“部署运行 > 智能体运行时 ”。

  2. 单击已创建的智能体运行时名称，在“基本信息”页签下即可查看访问方式。

如未创建访问方式，则默认使用该运行时的Latest访问方式。

约束限制:

不涉及。

取值范围：

以字母开头，以字母或数字结尾，可以包含字母、数字和中划线，长度为2-48个字符。

默认取值:

Latest

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Hw-Agentarts-Session-Id

是

String

参数解释：

会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意字符串，例如“123e4567e89b12d3a456426614174000”，无需在其他地方获取。

约束限制:

不涉及。

取值范围：

由英文，数字，“-”，“_”组成，不超过64位字符。

默认取值:

不涉及。

X-Hw-Agentgateway-User-Id

否

String

参数解释：

本次智能体运行时调用对应的用户唯一ID，用于标识此次调用的用户身份，用户可将会话ID设置为任意字符串，例如“123e4567e89b12d3a456426614174000”，无需在其他地方获取。

约束限制:

不涉及。

取值范围：

由英文，数字，“-”，“_”组成，不超过128位字符。

默认取值:

不涉及。

Authorization

是

String

参数解释：

本次智能体运行时调用对应的身份认证凭据。需要根据实际的智能体运行时的入站身份认证方式获取对应的身份认证凭据。

API Key认证、IAM认证及OAuth 2.0认证具体请参见认证鉴权。

约束限制:

不涉及。

取值范围：

不超过4096位字符。

默认取值:

不涉及。

X-Sdk-Content-Sha256

否

String

参数解释：

如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。

约束限制:

不涉及。

取值范围：

固定为UNSIGNED-PAYLOAD。

默认取值:

不涉及。

Command-Type

否

String

参数解释：

设置为 chunked 时启用 NDJSON 流式响应模式，在命令执行过程中逐行实时推送 stdout/stderr 输出，适用于长时间运行的命令（如 tail -f /var/log/app.log）。

默认为同步模式（默认），等待命令执行完成后返回完整结果。适用于一次性执行的命令（如 ls、cat）

约束限制:

不涉及。

取值范围：

以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。

默认取值:

不涉及。
表4 请求Body参数

参数

是否必选

参数类型

描述

command

是

Array of strings

参数解释：

命令及参数数组（必需）。

约束限制:

  • 第一个元素为可执行文件路径或命令

  • 后续元素为参数

  • 数组元素个数: 1-1024

  • 每个元素长度: 1-8192 字符

  • 无显式限制，实际受 Linux ARG_MAX 约束（约 2MB）。

取值范围：

参考dockerfile的exec-form格式，例如 ["executable", "param1", "param2"]

默认取值:

不涉及

timeout

否

Integer

参数解释：

命令执行超时阈值（秒）。

约束限制:

  • 0 或负数将被忽略，使用默认值

  • 默认和最大值为 300 秒

取值范围：

最大值为 300 秒

默认取值:

300

响应参数

状态码：200

表5 响应Body参数

参数

参数类型

描述

exit_code

Integer

命令退出码 (0 表示执行成功，非零表示执行失败)。非零退出码仍返回 HTTP 200

stdout

String

标准输出内容。

  • 响应体超过 100MB 时按比例截断 stdout/stderr，截断处添加 [TRUNCATED] 标记

stderr

String

标准错误输出内容

状态码：401

表6 响应Body参数

参数

参数类型

描述

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

状态码：500

表7 响应Body参数

参数

参数类型

描述

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

请求示例

执行test.sh命令, gateway_domain为运行时的访问域名，可以在智能体运行时的运行时详情页面中获取

POST https://{gateway_domain}/runtimes/{runtime_name}/commands

{
  "command" : [ "bash", "test.sh" ]
}

响应示例

状态码：200

智能体调用成功的响应Body体。

{
  "exit_code" : 0,
  "stdout" : "total 80\ndrwxr-xr-x 1 root root 4096 May 18 02:18 .\ndrwxr-xr-x 1 root root 4096 May 18 02:18 ..",
  "stderr" : ""
}

状态码：404

运行时资源不存在。

{
  "error_code" : 404,
  "error_msg" : "[node-proxy] Sandbox instance not found"
}

状态码：504

命令执行超时。

{
  "error_code" : 504,
  "error_msg" : "command execution timed out"
}

状态码

状态码

描述

200

智能体调用成功的响应Body体。

400

请求参数错误（纯文本响应）

401

未授权（认证令牌缺失、无效或已过期）。

404

运行时资源不存在。

500

服务器内部错误。

504

命令执行超时。

错误码

请参见错误码。

相关文档