更新时间：2026-09-15 GMT+08:00

使用API调用运行时接口（API Key认证）

本指南面向通过编写代码并将智能体托管到AgentArts运行时的开发者，介绍如何使用API Key认证调用已部署的智能体运行时API。

与IAM认证相比，API Key认证方式更为轻量，无需进行复杂的请求签名，仅需在请求头中携带平台颁发的鉴权参数即可完成鉴权。本指南将详细说明如何获取API Key、构造请求。

理解托管运行时与调用接口

什么是托管运行时

AgentArts托管运行时是一种将您的智能体代码容器化并部署到云端的服务。您通过编写代码定义智能体核心逻辑，并利用agentarts-sdk提供的AgentArtsRuntimeApp类将业务函数封装为符合平台规范的HTTP服务。AgentArtsRuntimeApp会自动为您注册两个标准接口：

表1 AgentArtsRuntimeApp类说明
接口路径	方法	用途
/ping	GET	平台健康检查，判断容器是否存活。
/invocations	POST	智能体调用入口，接收用户请求并返回处理结果。

运行时部署后，平台为您生成一个API网关地址，所有调用请求先经过网关鉴权，再路由到您的容器实例。运行时接口格式为：

https://{网关信息}.cn-southwest-2.huaweicloud-agentarts.com/runtimes/{运行时名称}/invocations

调用接口的传参如何与智能体代码对应

运行时接口的请求体字段结构完全由您的业务代码决定，平台网关仅做透传，不会修改请求体内容。

您在编写智能体服务时，会可以使用@app.invocation_handler装饰器注册一个处理函数，该函数接收一个request参数（即HTTP请求体解析后的字典），并返回一个字典作为HTTP响应体。

# 在您的服务代码中（文件名任意）
from agentarts.sdk import AgentArtsRuntimeApp

app = AgentArtsRuntimeApp()

@app.invocation_handler
def handle_invocation(request: dict) -> dict:
    # request 是调用方传入的请求体字典
    message = request.get("message", "")  # 此处定义了需要接收的字段名
    # ... 业务处理 ...
    return {"reply": result}              # 此处定义了响应体结构

调用方在发送请求时，请求体中的字段名必须与处理函数中request.get()读取的字段名完全一致。例如，如果您的处理函数使用request.get("query")读取用户输入，则调用方必须传递{"query": "..."}；如果处理函数使用message读取用户输入，则调用接口也需要使用message参数。

响应体同理，调用方收到的结构取决于您处理函数返回的字典内容。通常会使用 {"response": "...", "status": "success"}，但这完全由您自定义。

API Key认证原理

API Key认证是AgentArts提供的一种简化的鉴权方式，其核心流程如下：

部署时生成：当您在控制台部署运行时并选择“API Key”作为入站身份认证方式时，平台会自动生成一个与该运行时绑定的唯一API Key。
调用时携带：调用方在HTTP请求头中携带Authorization: Bearer {API_Key}，平台网关在接收请求时会校验该Token是否有效。
无需签名：与IAM认证不同，API Key认证无需对请求进行复杂的V11-HMAC-SHA256签名，也无需配置AK/SK，极大简化了调用流程。

适用场景：

快速验证与开发调试
内部测试环境
无需细粒度权限管控的场景（如单体应用后端调用）

安全提示：API Key是固定凭证，一旦泄露，任何持有者都可以调用您的运行时。生产环境中建议使用IAM认证。

API Key认证 vs IAM认证

表2 认证方式说明
对比维度	API Key认证	IAM认证
凭证类型	固定字符串（Bearer {API_Key}）	AK/SK（访问密钥/私有密钥）
调用复杂度	简单：仅需在请求头中携带Token	复杂：需实现V11-HMAC-SHA256签名
安全性	较低：Token长期有效，但存在泄露风险	较高：AK/SK可定期轮换，支持细粒度权限
适用场景	快速验证、内部测试	生产环境、企业级集成
凭证管理	在AgentArts控制台查看/重置	在华为云“我的凭证”中管理

步骤一：前置准备

获取调用接口

通过AgentArts页面部署运行时，请在“入站身份认证”处选择API Key认证。

在运行时列表中找到部署的实例，在基本信息页面获取运行时接口。

图1 获取运行时接口
点击放大

获取API Key

单击运行时名称，进入基本信息页面。找到URN，单击URN名称，获取API Key的值。

获取到的API Key值后，调用时需在API请求头中拼接为Authorization: Bearer {API_Key} 格式（注意Bearer后有一个空格）。

图2 获取API Key值
点击放大

步骤二：调用接口

示例中的"message"是请求体中的一个字段，用于传递您的问题。该字段名称并非固定值，而是由您部署的智能体服务代码中实际定义的入参字段决定的。本示例使用"message"作为演示，实际调用时请根据您的服务代码中定义的字段名进行替换。

示例中的接口地址（API_URL）、Authorization、x-hw-agentarts-session-id请按实际情况填写参数值。

Python调用示例：

import requests
import json

# 替换为真实的API接口
url = "https://{endpoint}/runtimes/{runtime_name}/invocations"

payload = json.dumps({
    "message": "你好"
})

headers = {
  'Content-Type': 'application/json',
  'Authorization': '您的Authorization，格式为Bearer {api_key}',
  'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、“-”、“_”组成，不超过64位字符。'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

cURL调用示例：

针对不同操作系统，命令的转义和换行符有所不同。

Windows

在CMD（命令提示符）中执行如下命令：

curl -X POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: 您的Authorization，格式为Bearer {api_key}" ^
  -H "x-hw-agentarts-session-id: 您的会话ID" ^
  -d "{ \"message\": \"你好\" }"

Linux/macOS

在Terminal（终端）中执行如下命令：

curl -X POST "https://{endpoint}/runtimes/{runtime_name}/invocations" \
  -H "Content-Type: application/json" \
  -H "Authorization: 您的Authorization，格式为Bearer {api_key}" \
  -H "x-hw-agentarts-session-id: 您的会话ID" \
  -d '{
    "message": "你好"
  }'

父主题： API调用实践