# 执行命令
执行命令接口[ExecuteRuntimeCommands](https://support.huaweicloud.com/api-agentarts/ExecuteRuntimeCommands.html)允许在运行中的会话沙箱内直接执行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"]
    }'
  ```