文档首页/ 智果（AgentArts）智能体平台/ 托管与运行智能体/ 运行时/ 调用运行时/ 文件上传与下载
更新时间：2026-09-14 GMT+08:00
查看PDF
分享

文件上传与下载

ExecuteRuntimeUploadFiles接口，允许将本地文件上传到会话沙箱的文件系统中。上传后，Agent代码可以通过文件路径直接读取。

文件上传接口说明

表1 接口说明

项目

说明

请求方法

POST

请求路径

/runtimes/{runtime_name}/upload-files

关键查询参数

path（必填），表示目标文件路径或目录路径。
表2 Query参数说明

请求头

是否必填

说明

path

是

目标路径。支持两种写法：

  • 指定完整文件路径（如/workspace/data.csv），适用于单文件上传。
  • 指定目录路径（如/workspace/，以/结尾），文件会自动保存到该目录下。不能使用 /（根目录），不能使用 ..（相对路径回退）。

file_mode

否

设置文件权限（Linux八进制权限，如0644）。默认由镜像的umask决定。

user_id

否

设置文件所属用户（Linux UID）。默认为当前启动镜像的用户UID。

group_id

否

设置文件所属用户组（Linux GID）。默认为当前启动镜像的用户组GID。

endpoint

否

访问方式名称，用于指定运行时版本。默认Latest。
  • 仅传文件名时（如path=data.csv），文件会自动保存到用户主目录 ~/ 下。
  • 单文件不超过100MB。
  • 多文件总计不超过 500MB（仅multipart表单模式）。
表3 请求头参数

请求头

是否必填

说明

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。

X-Hw-Agentgateway-User-Id

否

用户标识，用于区分不同终端用户。由英文、数字、-、_ 组成，不超过 128 个字符。

三种文件上传方式

AgentArts支持三种上传方式，适用于不同场景：

表4 文件上传方式

上传方式

Content-Type

path参数含义

适用场景

单文件流式上传

application/octet-stream

目标文件的完整路径（如 /workspace/data.csv）。

上传单个文件。

tar包上传

application/x-tar

目标目录路径（如 /workspace/）。

一次上传多个文件，打包为 tar 格式，服务端自动解压。

表单上传

multipart/form-data

目标目录路径（如 /workspace/）。

一次上传多个文件，使用标准表单格式。

表单上传和tar上传时，path参数应指定为目录路径（以/结尾），文件会保存到该目录下。

上传文件调用示例

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

  • 示例一：单文件上传（最常用） 
    curl -X POST \
  "https://{域名}/runtimes/{runtime_name}/upload-files?path=/workspace/data.csv" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./local_data.csv
  • 示例二：多文件表单上传 
    curl -X POST \
  "https://{域名}/runtimes/{runtime_name}/upload-files?path=/workspace/" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -F "file1=@./data.csv" \
  -F "file2=@./config.json"
  • 示例三：tar包批量上传 
    # 1. 先在本地打包
tar -czf bundle.tar.gz ./data/*

# 2. 上传 tar 包（服务端自动解压到 /workspace/）
curl -X POST \
  "https://{域名}/runtimes/{runtime_name}/upload-files?path=/workspace/" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -H "Content-Type: application/x-tar" \
  --data-binary @./bundle.tar.gz

下载文件接口说明

ExecuteRuntimeDownloadFiles接口，将会话沙箱中的文件下载到本地。典型用法：下载 Agent 生成的分析报告、表格、代码文件等结果。

表5 接口说明

项目

说明

请求方法

GET

请求路径

/runtimes/{runtime_name}/download-files

关键查询参数

path（必填），表示源文件路径；recursive（可选），表示是否按归档包下载。
表6 Query参数说明

请求头

是否必填

说明

path

是

沙箱内需要下载的文件路径（URL编码格式）。支持绝对路径和相对路径。

recursive

否

默认false（单文件下载）。设为true时按tar归档包下载，适用于下载整个目录下的所有文件。

endpoint

否

访问方式名称，用于指定运行时版本。默认Latest。
表7 请求头参数

请求头

是否必填

说明

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。

X-Hw-Agentgateway-User-Id

否

用户标识，用于区分不同终端用户。由英文、数字、-、_ 组成，不超过 128 个字符。

文件下载调用示例

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

  • 示例一：下载单个文件 
    curl -X GET \
  "https://{域名}/runtimes/{runtime_name}/download-files?path=/workspace/report.pdf" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -o report.pdf
  • 示例二：下载整个目录 
    curl -X GET \
  "https://{域名}/runtimes/{runtime_name}/download-files?path=/workspace/output/&recursive=true" \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Hw-Agentarts-Session-Id: {session_id}" \
  -o output.tar
父主题： 调用运行时

相关文档