调用概述

运行时API一览

调用运行时不仅仅是向智能体发一条消息、拿到一段回复。AgentArts运行时提供了一套规范的RESTful API，覆盖智能体交互中的常见操作：

请求体由您的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实际传参为空，导致智能体无法正常回答问题。

• 如果您团队中的不同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 获取运行时接口
  
• 已配置身份认证凭据。根据创建运行时选择的入站认证方式（IAM认证、API Key认证或OAuth 2.0），准备好对应的认证信息。
• 如需进行文件上传或下载操作，在托管智能体，创建运行时过程中需要开启“文件上传下载”功能。如果创建时未开启，后续将无法使用文件传输能力。
  图2 文件上传下载
  

关于身份认证

每一个调用请求的Authorization请求头都必须携带有效的身份认证凭据。AgentArts运行时支持三种入站认证方式：

认证方式在部署运行时时选定。本章节的示例以API Key认证为主（最简单直观），IAM认证的签名流程请参见使用API调用运行时接口（IAM认证）。