# 使用API调用运行时接口（API Key认证）
本指南面向通过编写代码并将智能体托管到AgentArts运行时的开发者，介绍如何使用API Key认证调用已部署的智能体运行时API。
与IAM认证相比，API Key认证方式更为轻量，无需进行复杂的请求签名，仅需在请求头中携带平台颁发的鉴权参数即可完成鉴权。本指南将详细说明如何获取API Key、构造请求。
#### 理解托管运行时与调用接口
#### 什么是托管运行时
AgentArts托管运行时是一种将您的智能体代码容器化并部署到云端的服务。您通过编写代码定义智能体核心逻辑，并利用agentarts-sdk提供的AgentArtsRuntimeApp类将业务函数封装为符合平台规范的HTTP服务。AgentArtsRuntimeApp会自动为您注册两个标准接口：
表1AgentArtsRuntimeApp类说明 
| 接口路径           | 方法    | 用途                       |
|:---|:---|:---|
| /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提供的一种简化的鉴权方式，其核心流程如下：
1. 部署时生成：当您在控制台部署运行时并选择"API Key"作为入站身份认证方式时，平台会自动生成一个与该运行时绑定的唯一API Key。
2. 调用时携带：调用方在HTTP请求头中携带Authorization: Bearer {API_Key}，平台网关在接收请求时会校验该Token是否有效。
3. 无需签名：与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获取运行时接口   
![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002748617927.png "点击放大")
#### 获取API Key
单击运行时名称，进入基本信息页面。找到URN，单击URN名称，获取API Key的值。
获取到的API Key值后，调用时需在API请求头中拼接为Authorization: Bearer {API_Key} 格式（注意Bearer后有一个空格）。
图2获取API Key值   
![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002719098284.png "点击放大")
#### 步骤二：调用接口
示例中的"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": "你好"
    }'
  ```