文档首页/ 智果（AgentArts）智能体平台/ 托管与运行智能体/ 运行时/ 调用运行时/ 执行命令
更新时间：2026-09-24 GMT+08:00
查看PDF
分享

执行命令

执行命令接口ExecuteRuntimeCommands允许在运行中的会话沙箱内直接执行Shell命令。命令和Agent运行在同一个容器环境中，共享文件系统。

适用场景：

  • “推理 → 执行”循环：Agent做推理决策后，通过此接口执行具体操作（如运行脚本），然后将执行结果反馈给Agent继续推理。
  • 环境检查与调试：查看沙箱内的文件列表、Python版本、已安装的库等。
  • 安装额外依赖：在当前会话中临时安装Python包或其他工具。
  • 运行用户脚本：执行预先上传到沙箱中的脚本文件。

接口说明

表1 接口说明

项目

说明

请求方法

POST

请求路径

/runtimes/{runtime_name}/commands

前置条件

必须先有一个有效的会话。支持两种方式：

  • 在请求头中传入自定义的X-Hw-Agentarts-Session-Id（隐式创建）；
  • 先调用StartRuntimeSession获取平台分配的session_id（显式创建）。两种方式均可。

请求头

表2 请求头参数

请求头

是否必填

说明

Content-Type

是

固定为application/json。

Authorization

是

身份认证凭据。API Key 方式填写 Bearer {api_key}；IAM 方式由签名 SDK 自动生成；OAuth 2.0 方式填写 Bearer {jwt_token}。

X-Hw-Agentarts-Session-Id

是

会话 ID，用于标识一次会话。您可以自行生成一个字符串（如 UUID），同一个 Session ID 的多次调用在 Agent 侧可关联上下文。由英文、数字、-、_ 组成，不超过 64 个字符。

X-Sdk-Content-Sha256

IAM认证时必填

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

Command-Type

否

设置为chunked时启用NDJSON流式响应模式，命令执行过程中实时推送输出。默认为同步模式（等待命令执行完成后返回完整结果）。

请求体

请求体为JSON格式，包含需要执行的命令信息。

{
  "command": ["可执行程序", "参数1", "参数2"],
  "timeout": 300
}

参数说明：

  • command：必填，表示命令及参数数组。第一个元素为可执行文件路径或命令，后续元素为参数。数组元素个数1-1024，每个元素长度1-8192字符。注意command字段是一个数组（而不是字符串）。
  • timeout：可选，命令执行超时时间（秒）。范围1-3600，默认300（5分钟）。超时后命令会被强制终止。

常见写法对照

表3 命令写法

想执行的命令

command数组写法

ls -la /workspace/

["ls", "-la", "/workspace/"]

python script.py

["python", "script.py"]

bash test.sh

["bash", "test.sh"]

pip install pandas

["pip", "install", "pandas"]

python -c "print('hello')"

["python", "-c", "print('hello')"]

响应格式

同步模式响应

{
  "exit_code": 0,
  "stdout": "命令的标准输出内容",
  "stderr": "命令的错误输出内容"
}

参数说明：

  • exit_code：命令退出码。0表示成功，非0表示失败。注意：即使命令执行失败（exit_code非0），HTTP状态码仍然返回200，因为“命令已执行”这件事本身是成功的，只是命令结果失败。
  • stdout：标准输出内容。如果输出超过 100MB，会被按比例截断并添加TRUNCATED标记。
  • stderr：标准错误输出内容。

流式模式响应（Command-Type: chunked）

启用Command-Type: chunked后，响应为NDJSON（Newline Delimited JSON） 格式，每行一个JSON对象，命令执行过程中实时推送：

{"type": "stdout", "data": "step_1\n"}
{"type": "stdout", "data": "step_2\n"}
{"type": "stderr", "data": "warning: something\n"}
{"type": "exit", "data": {"exit_code": 0}}

参数说明：

  • type：消息类型：stdout（标准输出）、stderr（标准错误）、exit（命令结束，包含最终退出码）。
  • data：stdout/stderr类型时为输出内容字符串；exit类型时为包含exit_code的对象。

调用示例

以下示例使用API Key鉴权方式进行演示。

  • 示例一：查看文件列表 
    curl -X POST "https://{域名}/runtimes/{runtime_name}/commands" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -d '{
    "command": ["ls", "-la", "/workspace/"]
  }'
  • 示例二：安装Python包并验证 
    # 步骤 1：安装
curl -X POST "https://{域名}/runtimes/{runtime_name}/commands" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -d '{
    "command": ["pip", "install", "pandas", "matplotlib"],
    "timeout": 120
  }'

# 步骤 2：验证安装结果
curl -X POST "https://{域名}/runtimes/{runtime_name}/commands" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -d '{
    "command": ["python", "-c", "import pandas; print(pandas.__version__)"]
  }'

    注意：安装的包仅在当前会话内有效。会话停止后，沙箱环境会被销毁，安装的包不会保留。

  • 示例三：Python调用 
    import requests
import json

url = f"https://{域名}/runtimes/{runtime_name}/commands"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
    "X-Hw-Agentarts-Session-Id": session_id
}

# 执行命令
payload = {
    "command": ["python", "--version"],
    "timeout": 30
}

try:
    resp = requests.post(url, headers=headers, json=payload, timeout=60)
    result = resp.json()

    if result["exit_code"] == 0:
        print(f"执行成功:\n{result['stdout']}")
    else:
        print(f"执行失败（exit_code={result['exit_code']}）:\n{result['stderr']}")
except requests.exceptions.Timeout:
    print("请求超时")
except requests.exceptions.RequestException as e:
    print(f"网络请求异常: {e}")
  • 示例四：流式输出模式

    流式模式适合执行日志查看、进度输出频繁的命令，避免长时间等待后一次性返回带来的超时风险。

    对于长时间运行的命令（如tail -f、持续输出的脚本），可以在请求头中添加Command-Type: chunked启用NDJSON流式响应，执行过程中实时推送输出： 
    curl -X POST "https://{域名}/runtimes/{runtime_name}/commands" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -H "Command-Type: chunked" \
  -d '{
    "command": ["bash", "-c", "for i in 1 2 3; do echo step_$i; sleep 1; done"],
    "timeout": 30
  }'
  • 示例五：检查Python版本 
    curl -X POST "https://{域名}/runtimes/{runtime_name}/commands" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -d '{
    "command": ["python", "--version"]
  }'
父主题： 调用运行时

相关文档