runtime 命令用于操作华为云 AgentArts 运行时,提供会话管理、文件传输、命令执行等数据平面操作能力。所有 runtime 子命令均仅支持云端模式(已部署的 Agent)。
| 子命令 | 说明 | 是否需要会话 |
|---|---|---|
start-session |
创建运行时会话,获取 session_id | 否 |
invoke |
调用 Agent 发送 JSON 请求 | 可选 |
exec-command |
在运行时中执行命令 | 可选 |
upload-files |
上传文件到运行时 | 是 |
download-files |
从运行时下载文件 | 是 |
stop-session |
停止运行时会话 | 是 |
| 子命令 | HTTP 方法 | API 路径 |
|---|---|---|
start-session |
POST | /runtimes/{agent-name}/sessions-start |
stop-session |
POST | /runtimes/{agent-name}/sessions-stop |
invoke |
POST | /runtimes/{agent-name}/invocations |
exec-command |
POST | /runtimes/{agent-name}/commands |
upload-files |
POST | /runtimes/{agent-name}/upload-files |
download-files |
GET | /runtimes/{agent-name}/download-files |
所有 runtime 子命令支持以下通用参数:
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--agent |
-a |
Agent 名称 | 使用默认 Agent |
--region |
-r |
华为云区域 | 从配置文件读取 |
--endpoint |
-e |
指定端点名称 | 无 |
--bearer-token |
-bt |
Bearer 认证令牌 | 无 |
--skip-ssl-verification |
-k |
跳过 SSL 证书验证 | false |
--user-id |
-u |
用户 ID(用于 OAuth2 出站凭据) | 无 |
创建运行时会话,返回 session_id 用于后续有状态操作(如文件传输、命令执行)。
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--agent |
-a |
Agent 名称(必填) | 无 |
--region |
-r |
华为云区域 | 从配置文件读取 |
--bearer-token |
-bt |
Bearer 认证令牌 | 无 |
--endpoint |
-e |
指定端点名称 | 无 |
--skip-ssl-verification |
-k |
跳过 SSL 证书验证 | false |
--user-id |
-u |
用户 ID(用于 OAuth2 出站凭据) | 无 |
{
"data": {
"session_id": "session-xxxx-xxxx-xxxx"
}
}agentarts runtime start-session --agent my-agentagentarts runtime start-session -a my-agent -r cn-southwest-2agentarts runtime start-session -a my-agent -bt your-tokenagentarts runtime start-session -a my-agent -e my-endpointagentarts runtime start-session -a my-agent --skip-ssl-verification停止运行时会话,释放会话资源。
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--agent |
-a |
Agent 名称(必填) | 无 |
--session |
-s |
会话 ID(必填) | 无 |
--region |
-r |
华为云区域 | 从配置文件读取 |
--bearer-token |
-bt |
Bearer 认证令牌 | 无 |
--endpoint |
-e |
指定端点名称 | 无 |
--skip-ssl-verification |
-k |
跳过 SSL 证书验证 | false |
--user-id |
-u |
用户 ID(用于 OAuth2 出站凭据) | 无 |
agentarts runtime stop-session --agent my-agent --session session-xxxagentarts runtime stop-session -a my-agent -s session-xxxagentarts runtime stop-session -a my-agent -s session-xxx -bt your-token调用 Agent 发送 JSON 请求,获取响应。支持自定义路径扩展。
注意: 此命令与顶层
agentarts invoke命令功能相同。
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
payload |
无 | JSON 请求数据(位置参数,必填) | 无 |
--agent |
-a |
Agent 名称 | 使用默认 Agent |
--region |
-r |
华为云区域 | 从配置文件读取 |
--endpoint |
-e |
指定端点名称 | 无 |
--session |
-s |
会话 ID(用于有状态 Agent) | 无 |
--bearer-token |
-bt |
Bearer 认证令牌 | 无 |
--timeout |
无 | 请求超时时间(秒) | 900 |
--skip-ssl-verification |
-k |
跳过 SSL 证书验证 | false |
--user-id |
-u |
用户 ID(用于 OAuth2 出站凭据) | 无 |
--custom-path |
无 | 自定义路径追加到 /invocations | 无 |
--custom-path 允许在 /invocations 路径后追加自定义路径段:
- 有效格式: 字母、数字、连字符、下划线、点、斜杠(用于嵌套路径)
- 无效字符:
!、@、#、$、%、^、&、*、(、)、空格 - 路径遍历: 不允许
..序列
示例:
--custom-path stream→/invocations/stream--custom-path api/v2→/invocations/api/v2
使用 --custom-path 需要在配置文件中设置 url_match_type: PREFIX_MATCH:
runtime:
invoke_config:
url_match_type: PREFIX_MATCH若配置为 ACCURATE_MATCH(默认),使用 --custom-path 会因后端期望精确路径匹配而失败。
agentarts runtime invoke '{"message": "hello"}' --agent my-agentagentarts runtime invoke '{"message": "hello"}' -a my-agent -s session-xxxagentarts runtime invoke '{"message": "hello"}' -a my-agent --custom-path streamagentarts runtime invoke '{"message": "hello"}' -a my-agent --timeout 60在运行时环境中执行命令(如 ls、cat、pip install 等)。
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
command |
无 | 要执行的命令(位置参数,必填) | 无 |
--agent |
-a |
Agent 名称(必填) | 无 |
--session |
-s |
会话 ID | 无 |
--chunked |
无 | 启用流式响应(application/x-ndjson) | false |
--region |
-r |
华为云区域 | 从配置文件读取 |
--bearer-token |
-bt |
Bearer 认证令牌 | 无 |
--endpoint |
-e |
指定端点名称 | 无 |
--skip-ssl-verification |
-k |
跳过 SSL 证书验证 | false |
--user-id |
-u |
用户 ID(用于 OAuth2 出站凭据) | 无 |
--timeout |
无 | 请求超时时间(秒) | 60(最大 300) |
- 默认超时: 60 秒
- 最大超时: 300 秒
- 超时参数直接传递给 HTTP 客户端,超出后请求将被终止
启用 --chunked 后:
- 请求头:
Command-Type: chunked - 响应格式:
application/x-ndjson(每行一个 JSON 对象)
agentarts runtime exec-command "ls -la" --agent my-agent --session session-xxxagentarts runtime exec-command "ls -la" -a my-agent -s session-xxx --chunkedagentarts runtime exec-command "pip install pandas" -a my-agent -s session-xxx --timeout 120agentarts runtime exec-command "cat /tmp/data.txt" -a my-agent -s session-xxx -bt your-token上传本地文件到运行时环境。
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--agent |
-a |
Agent 名称(必填) | 无 |
--session |
-s |
会话 ID(必填) | 无 |
--files |
-f |
本地文件路径(可多次指定,必填) | 无 |
--path |
-p |
远程目录路径,必须以 / 结尾(如 /tmp/)。默认 /tmp/,因为 /tmp 在多数镜像中可写,而 /home/user 在很多镜像中无写入权限 |
/tmp/ |
--file-user-id |
无 | 文件所有者用户 ID | 1000 |
--file-group-id |
无 | 文件所有者组 ID | 1000 |
--file-mode |
-m |
文件权限(八进制格式) | 0644 |
--region |
-r |
华为云区域 | 从配置文件读取 |
--bearer-token |
-bt |
Bearer 认证令牌 | 无 |
--endpoint |
-e |
指定端点名称 | 无 |
--skip-ssl-verification |
-k |
跳过 SSL 证书验证 | false |
--user-id |
-u |
用户 ID(用于 OAuth2 出站凭据) | 无 |
--timeout |
无 | 请求超时时间(秒) | 900 |
文件上传到默认目录 /tmp/(/tmp 在多数镜像中可写;若镜像中 /home/user 无写入权限,请用 --path 指定可写目录):
agentarts runtime upload-files -a my-agent -s session-xxx -f local_file.txt使用 --path / -p 参数指定远程目录,路径必须以 / 结尾:
agentarts runtime upload-files -a my-agent -s session-xxx -f local_file.txt -p /app/data/多次使用 -f 参数,所有文件上传到同一目录:
agentarts runtime upload-files -a my-agent -s session-xxx -f file1.txt -f file2.txt -f file3.txtagentarts runtime upload-files -a my-agent -s session-xxx \
-f file1.txt -f file2.txt -f file3.txt \
-p /app/data/单个文件最大 100MB,超过将报错拦截。
使用 upload-files 需要在部署时启用文件传输:
runtime:
invoke_config:
file_transfer_config:
enabled: true若配置为 false(默认),上传操作将失败。
注意:
file_transfer_config.enabled参数不支持对已有 agent 进行修改。如需启用文件传输,请创建新的 agent 并在配置中设置enabled: true,然后通过agentarts deploy部署。
agentarts runtime upload-files --agent my-agent --session session-xxx -f data.txtagentarts runtime upload-files -a my-agent -s session-xxx -f file1.txt -f file2.txtagentarts runtime upload-files -a my-agent -s session-xxx -f file1.txt -f file2.txt -p /app/data/agentarts runtime upload-files -a my-agent -s session-xxx -f script.sh --file-mode 0755agentarts runtime upload-files -a my-agent -s session-xxx -f data.txt --file-user-id 1001 --file-group-id 1001从运行时环境下载文件或目录。
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--agent |
-a |
Agent 名称(必填) | 无 |
--session |
-s |
会话 ID(必填) | 无 |
--path |
-p |
远程文件/目录路径(必填) | 无 |
--output |
-o |
本地输出路径 | 使用文件名 |
--recursive |
下载目录为 tar 归档 | false |
|
--region |
无 | 华为云区域 | 从配置文件读取 |
--bearer-token |
-bt |
Bearer 认证令牌 | 无 |
--endpoint |
-e |
指定端点名称 | 无 |
--skip-ssl-verification |
-k |
跳过 SSL 证书验证 | false |
--user-id |
-u |
用户 ID(用于 OAuth2 出站凭据) | 无 |
--timeout |
无 | 请求超时时间(秒) | 900 |
使用 download-files 需要在配置文件中启用文件传输:
runtime:
invoke_config:
file_transfer_config:
enabled: true若配置为 false(默认),下载操作将失败。
agentarts runtime download-files --agent my-agent --session session-xxx --path /tmp/data.txtagentarts runtime download-files -a my-agent -s session-xxx -p /tmp/data.txt -o ./local_data.txtagentarts runtime download-files -a my-agent -s session-xxx -p /tmp/project --recursiveagentarts runtime download-files -a my-agent -s session-xxx -p /tmp/data.txt -bt your-token- 创建会话
agentarts runtime start-session --agent my-agent
# 输出: {"data": {"session_id": "session-xxx"}}- 执行操作(使用会话 ID)
# 上传文件
agentarts runtime upload-files -a my-agent -s session-xxx -f data.txt
# 执行命令
agentarts runtime exec-command "pip install pandas" -a my-agent -s session-xxx
# 下载文件
agentarts runtime download-files -a my-agent -s session-xxx -p /tmp/result.txt- 停止会话
agentarts runtime stop-session --agent my-agent --session session-xxx- 有状态操作: upload-files、download-files、exec-command 可使用会话保持状态
- 文件传输: 同一会话中的文件操作共享文件系统状态
- 命令执行: 同一会话中的命令共享执行环境(如已安装的包)
原因: Agent 未部署或认证失败
解决方案:
- 确认 Agent 已成功部署
- 检查 AK/SK 或 Bearer Token 配置
- 验证区域配置是否正确
原因: 文件传输未启用
解决方案:
- 在配置文件中设置
file_transfer_config.enabled: true - 重新部署 Agent
- 或在华为云控制台直接更新配置
原因: 命令执行时间超过限制
解决方案:
- 设置
--timeout参数(最大 300 秒) - 优化命令执行效率
- 将长时间任务拆分为多个命令
原因: URL 匹配类型配置错误
解决方案:
- 在配置文件中设置
url_match_type: PREFIX_MATCH - 重新部署 Agent
原因: AK/SK 配置错误或 Token 过期
解决方案:
- 检查环境变量
HUAWEICLOUD_SDK_AK和HUAWEICLOUD_SDK_SK - 更新 Bearer Token
- 确认 Agent 认证类型配置正确
- 会话 ID: upload-files 和 download-files 必须提供会话 ID
- 文件大小: 单文件最大 100MB
- 超时限制: exec-command 最大超时 300 秒
- 配置依赖: 文件传输和自定义路径需要特定配置
- 认证类型: IAM 认证使用 AK/SK 签名,其他认证类型使用 Bearer Token
- 会话生命周期: 建议在操作完成后停止会话释放资源
- 文件权限: 上传文件时注意设置正确的用户 ID、组 ID 和权限
- 远程目录: upload-files 的
--path参数必须以/结尾,多文件上传到同一目录