调用智能体

工作原理

当您发起调用时，请求经过以下路径到达您的Agent代码：

调用链路说明：

客户端发起接口请求，携带消息体{"message": "你好"}。请求首先到达API网关，网关按序完成三项处理：

1. 身份校验：校验Authorization头中的认证凭据，确认调用方有权限访问该runtime；
2. 格式校验：校验请求头格式（如Session ID等），确保请求符合协议规范；
3. 路由分发：根据路径中的runtime_name查找对应的目标容器实例，并将请求转发过去。

请求到达Agent容器后，平台将请求体原样传递给您Agent中定义的handler函数。handler通过request.get("message")取出用户消息 "你好"，执行业务逻辑后返回结果对象{"reply": "你好！"}。

返回值再经由API网关原样回传给调用方，调用方最终收到响应{"reply": "你好！"}。

网关在整个过程中 不解析、不修改 请求体和响应体的内容，仅负责鉴权和路由。

接口说明

请求头

请求体

请求体为JSON格式，具体字段由您的Agent代码定义。网关不做任何校验，原样转发。

以下是一个常见的请求体示例（假设您的Agent代码使用message字段接收用户输入）：

{
  "message": "你好，请介绍一下你自己"
}

响应体

响应体同样为JSON格式，结构由您的Agent代码的返回值决定。

调用示例

本示例主要演示通过API Key认证调用运行时接口，除了本文档之外，您也可以参考最佳实践了解如何调用运行时API。

最佳实践：使用API调用运行时接口（IAM认证）

最佳实践：使用API调用运行时接口（API Key认证）

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

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

   图2 获取运行时接口
   

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

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

   图3 获取API Key值
   

3. 调用运行时API。

   示例中的"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": "你好"
       }'

多轮对话

同一个X-Hw-Agentarts-Session-Id下的多次调用，在同一个会话上下文中执行，Agent侧可以基于此会话ID关联多次调用的内容，从而实现多轮对话。

SESSION_ID = "23e4567e89b12d3a456426614174000"

# 第一轮
resp1 = call_agent(session_id=SESSION_ID, message="我叫张三")
# → Agent 回复："你好，张三！有什么可以帮助你的？"

# 第二轮（相同 Session ID）
resp2 = call_agent(session_id=SESSION_ID, message="你还记得我叫什么吗？")
# → Agent 回复："你叫张三。"

# 第三轮（换一个新的 Session ID → 新会话，上下文清空）
resp3 = call_agent(session_id="another-session", message="你还记得我叫什么吗？")
# → Agent 回复："抱歉，我不清楚你的名字。"

X-Hw-Agentarts-Session-Id提供的是会话标识，用于平台将多次请求路由到同一个会话上下文。但上下文是否能保持（即Agent能否记住之前的对话），取决于您的Agent代码是否实现了对话记忆逻辑（例如集成了记忆库组件，关于记忆库的使用，可参考进阶示例：构建全能出行助手（集成模型/记忆/代码解释器/网关/高德mcp））。

指定访问方式（版本路由）

如果您为同一个运行时创建了多个访问方式（如dev、staging、prod），可以通过endpoint查询参数指定调用哪个版本：

# 调用 dev 版本
POST https://{域名}/runtimes/{runtime_name}/invocations?endpoint=dev

# 调用 prod 版本
POST https://{域名}/runtimes/{runtime_name}/invocations?endpoint=prod

# 不指定时，默认使用 Latest 版本
POST https://{域名}/runtimes/{runtime_name}/invocations

访问方式的创建和管理请参见管理访问方式。