# 调用概述
运行时部署成功后，开发者即可通过AgentArts提供的RESTful API与该运行时进行交互。AgentArts的运行时调用能力不仅限于向Agent发送消息获取回复，还涵盖了在会话隔离沙箱中动态执行系统命令、在本地与运行时沙箱环境之间进行大文件传输，以及调用用户在镜像中定义的自定义前缀接口。
#### 运行时API一览
调用运行时不仅仅是向智能体发一条消息、拿到一段回复。AgentArts运行时提供了一套规范的RESTful API，覆盖智能体交互中的常见操作：
表1运行时API 
| 功能             | API标识                        | 接口                                                    | 说明                                                                        |
|:---|:---|:---|:---|
| 向智能体发送并获取消息      | ExecuteRuntime               | POST /runtimes/{runtime_name}/invocations             | 最核心的调用接口。将用户输入发送给 Agent，获取 Agent 的回复。                                    |
| 创建会话              | StartRuntimeSession         | POST /runtimes/{runtime_name}/sessions-start         | 创建一个独立的会话实例。执行命令、文件上传下载等操作依赖会话提供的沙箱环境。                                   |
| 停止会话            | StopRuntimeSession          | POST /runtimes/{runtime_name}/sessions-stop         | 销毁会话实例并释放资源。会话内的文件会被自动清除。                                                   |
| 在会话中执行Shell命令 | ExecuteRuntimeCommands        | POST /runtimes/{runtime_name}/commands                | 在会话沙箱内执行命令，返回标准输出和错误输出。                                                   |
| 上传文件到会话          | ExecuteRuntimeUploadFiles    | POST /runtimes/{runtime_name}/upload-files          | 将本地文件上传到会话沙箱的文件系统中。                                                      |
| 从会话下载文件       | ExecuteRuntimeDownloadFiles | GET /runtimes/{runtime_name}/download-files         | 将会话沙箱中的文件下载到本地。                                                          |
| 调用自定义路径接口       | ExecuteRuntimeWithPrefix    | 任意 /runtimes/{runtime_name}/invocations/{custom_path} | 当Agent暴露了自定义路由时，通过此接口访问非标准路径。该接口支持所有HTTP方法（包括但不限于POST、GET、DELETE、PUT等）。 |
   
#### 请求体由您的Agent代码决定
您的 Agent 代码定义了它接收什么字段、返回什么字段，平台网关只做鉴权和路由，不对请求体做任何修改。您在调用 API 时传入的 JSON Body，会被原样转发到您的 Agent 容器中。
这意味着：
- 请求体中应该包含哪些字段，完全取决于您编写的 Agent 代码中定义的接收逻辑。
- 响应体的结构也完全由您的 Agent 代码返回值决定。
举例说明，假设您的 Agent 代码如下：
```
@app.invocation_handler
def handle_invocation(request: dict) -> dict:
    user_msg = request.get("message", "")   # 您的代码读取 "message" 字段
    # ... 业务处理 ...
    return {"reply": result, "status": "success"}  # 您的代码返回这两个字段
```
将该智能体打包成镜像，部署到AgentArts运行时后，调用API时，那么调用时就必须传 "message" 字段，收到的响应就是 "reply" 和 "status" 字段。如果API参数填写为其他参数，运行时接口虽然能调用，但会因为message实际传参为空，导致智能体无法正常回答问题。
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
- 如果您团队中的不同Agent使用了不同的字段名（例如有的用message，有的用query），调用方需要分别适配。
- 调用前请与Agent开发者确认接口约定。
- 本文档示例统一使用message作为请求字段名、reply作为响应字段名，仅作演示用途。实际调用时请以您的Agent代码为准。
 
#### 典型调用场景
根据业务场景的不同，AgentArts运行时支持以下几种典型交互场景：
**场景一：基础对话**
最简单的场景：向智能体发消息，拿到回复。
```
调用智能体（ExecuteRuntime）
 → 发送 {"message": "你好"}
 ← 收到 {"reply": "你好！有什么可以帮助你的？"}
```
基础对话场景下，您只需直接调用ExecuteRuntime接口即可。在请求头中携带X-Hw-Agentarts-Session-Id，同一个Session ID的多次调用在Agent侧可以关联上下文，实现多轮对话。
**场景二：涉及文件处理**
当您需要让Agent处理本地文件（如分析CSV数据），流程为：
```
① 创建会话（StartRuntimeSession）      → 获取沙箱环境
② 上传文件（ExecuteRuntimeUploadFiles） → 文件进入沙箱
③ 调用智能体（ExecuteRuntime）           → Agent 读取并处理文件
④ 下载文件（ExecuteRuntimeDownloadFiles）→ 取回处理结果
⑤ 停止会话（StopRuntimeSession）        → 释放资源
```
必须先通过StartRuntimeSession创建会话来初始化沙箱环境，上传下载文件才有目标容器可操作。
创建运行时过程中需要开启"文件上传下载"功能。
**场景三：涉及命令执行**
当您需要在 Agent 的沙箱环境中直接执行 Shell 命令（如运行脚本、安装依赖、检查环境），流程为：
```
① 创建会话（StartRuntimeSession）      → 获取沙箱环境
② 调用智能体（ExecuteRuntime）           → Agent 推理决策
③ 执行命令（ExecuteRuntimeCommands）    → 运行 Agent 决策的脚本
④ 调用智能体（ExecuteRuntime）           → Agent 基于命令结果继续推理
⑤ 停止会话（StopRuntimeSession）        → 释放资源
```
步骤②③④可以多次循环，形成"推理 → 执行 → 再推理"的闭环。
#### 前置条件与调用依赖
在开始调用运行时之前，请确保已完成以下准备：
- 运行时已部署且状态为"正常"。您可以在AgentArts控制台的"智能体运行时"列表中查看运行时状态。
- 已获取"运行时接口"。在运行时详情页的"基本信息"区域可以找到接口地址。
  图1获取运行时接口   
  ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002750409345.png "点击放大") 
- 已配置身份认证凭据。根据创建运行时选择的入站认证方式（IAM认证、API Key认证或OAuth 2.0），准备好对应的认证信息。
- 如需进行文件上传或下载操作，在托管智能体，创建运行时过程中需要开启"文件上传下载"功能。如果创建时未开启，后续将无法使用文件传输能力。
  图2文件上传下载   
  ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002750329755.png "点击放大") 
 
#### 关于身份认证
每一个调用请求的Authorization请求头都必须携带有效的身份认证凭据。AgentArts运行时支持三种入站认证方式：
表2入站身份认证 
| 认证方式           | Authorization 格式       | 使用复杂度                               | 适用场景           |
|:---|:---|:---|:---|
| API Key        | Bearer {api_key}     | 低，直接在请求头中写入固定凭证。                   | 快速验证、开发调试、内部测试。 |
| IAM 认证（AK/SK） | 由签名 SDK 自动生成          | 高，需要使用签名SDK对请求进行V11-HMAC-SHA256签名。 | 生产环境、企业级集成。    |
| OAuth 2.0    | Bearer {OAuth_Token} | 高，需要先通过OAuth流程获取Token。             | 第三方应用集成。      |
   
认证方式在部署运行时时选定。本章节的示例以API Key认证为主（最简单直观），IAM认证的签名流程请参见[使用API调用运行时接口（IAM认证）](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0063.html)。