# 使用API调用单/多智能体（IAM认证） 本案例介绍如何通过IAM认证（AK/SK签名）的方式，调用智能体的API接口。 与API Key认证的主要区别：IAM认证使用您华为云账号的访问密钥（AK/SK）进行请求签名，无需在平台单独管理API Key，更适合企业级应用集成场景，权限管控由统一的IAM服务管理。 #### API接口签名约束 根据华为云API网关（APIG）与AgentArts平台的认证鉴权规范，智能体运行时（Runtime）的执行接口（POST /runtimes/{runtime_name}/invocations）在签名鉴权上具备以下核心规则： 1. **签名算法（V11-HMAC-SHA256）：** - 采用华为云API网关V11-HMAC-SHA256签名算法。 - 密钥派生机制（HKDF）：该算法采用HKDF密钥派生函数，结合AK + SK + 请求日期 + 区域(Region) + 域名服务的方式动态派生加密密钥，进一步提升了安全等级。因此在初始化签名器时须指定正确的region_id。 2. **Body体免签名规则（UNSIGNED-PAYLOAD）：** - 由于智能体数据面交互的请求Body内容较长且包含大模型复杂文本，按照平台规范，请求Body不参与签名哈希计算。 - 须在请求头中配置 "X-Sdk-Content-Sha256": "UNSIGNED-PAYLOAD"，通知签名SDK和API网关跳过Body的摘要签名。 3. **时间戳与防重放校验：** - 请求头必须包含ISO 8601 UTC格式的时间戳（X-Sdk-Date）。API网关除了校验时间格式外，还会校验该时间值与网关收到请求的时间差，如果时间差大于15分钟，网关将拒绝请求。 4. **会话上下文追踪：** - 请求头须携带客户端生成的会话ID（x-hw-agentarts-session-id）。在多轮对话中保持相同的session_id即可在服务端关联对话上下文。 #### 前置检查 - 已开通AgentArts服务。 - 已接入可用模型。调用智能体/工作流API时不支持使用平台赠送的免费token，确保配置的模型满足以下任一条件： - 接入华为云MaaS服务模型并配置模型API Key（平台默认模型来源），操作请参考[接入华为云MaaS服务付费模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0095.html)。 - 已在智能体/工作流中自行对接外部第三方模型，操作请参考[手动接入和使用OpenAI协议模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0096.html)。 未接入MaaS模型且未使用第三方模型时，调用API将返回"Model call failed"报错。 #### 步骤一：部署智能体并选择IAM认证 1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。 2. 在左侧导航栏中选择"开发中心 \> 智能体管理"，选择需要调用的智能体。单击智能体名称进入智能体编辑页面。在"提交版本"或者"更新版本"时，需要勾选"部署至实例"选项。勾选后单击"确定"。 图1勾选"部署至实例" ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002674441370.png "点击放大") 3. **入站身份认证选择"IAM 认证"** ，并勾选日志记录、指标、调用链。其余配置可以使用默认值。 图2选择"IAM 认证" ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002686275577.png "点击放大") 4. **获取智能体的调用路径（API_URL）** 。 智能体部署完成后，返回列表页，获取调用路径。 图3获取智能体调用路径 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002686275911.png "点击放大") #### 步骤二：准备SDK环境 **安装运行环境：** - 安装Python：如果您还没装，去[python.org](https://www.python.org/)下载并安装（记得安装时勾选 "Add Python to PATH"）。 - 安装requests库： 打开电脑的"命令提示符"（Windows按Win+R键输入cmd），输入以下命令并按回车： ``` pip install requests ``` **获取API签名所需的SDK包：** 1. 在[签名指南](https://support.huaweicloud.com/devg-apisign/api-sign-sdk-python.html)文档中下载Python SDK，并在本地解压。签名指南文档中的其他内容本案例中可不用关注。 图4获取SDK ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002656195206.png "点击放大") 解压后的文件目录结构如下： ``` ApiGateway-python-sdk/ ← 根目录（解压出来的文件夹） │ ├── apig_sdk/ ← 【核心签名库，不要动！】 │ ├── __init__.py ← 包的入口标识文件 │ └── signer.py ← 签名核心代码（所有签名逻辑都在这里） │ ├── main.py ← 【您要改的文件】调用示例 │ └── licenses/ ← 开源许可证文件夹（不用管） └── license-requests ← requests库的许可证说明 ``` 图5目录结构 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002686435989.png "点击放大") **配置环境变量：** 1. 登录控制台"[我的凭证 \> 访问密钥](https://console.huaweicloud.com/iam/#/mine/accessKey)"，获取AK和SK。AK、SK最多可添加2个。 图6获取AK、SK ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002656355130.png "点击放大") 图7AK、SK示例 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002686434629.png "点击放大") 2. 通过以下命令，在Windows的命令提示符cmd中设置临时环境变量。 ``` set HUAWEICLOUD_SDK_AK=您的Access Key set HUAWEICLOUD_SDK_SK=您的Secret Key ``` 3. 通过以下命令检查环境变量是否生效。 ``` echo %HUAWEICLOUD_SDK_AK% echo %HUAWEICLOUD_SDK_SK% ``` #### 步骤三：构造智能体调用脚本 1. 打开Python SDK的文件夹目录，编辑main.py脚本，添加具体的业务接口信息。 用记事本（或者安装了代码编辑器如VS Code）打开main.py脚本，删除原有内容，并将下方代码添加进去。 智能体的调用路径（API_URL）按实际进行填写，获取方法参考[步骤一：部署智能体并选择IAM认证]。 ``` # -*- coding: utf-8 -*- """ AgentArts 智能体 API 交互式调用脚本（IAM / AK-SK 认证方式） """ # ============================================================================== # 【配置区域】请在此处修改接口地址与区域Region信息 # ============================================================================== # 1. 智能体完整的调用路径 (直接粘贴自 AgentArts 控制台) API_URL = "填写实际的智能体路径" # 2. 部署区域代号 (根据域名填写，如贵阳一为 cn-southwest-2) REGION_ID = "cn-southwest-2" # ============================================================================== import os import json import uuid import requests from urllib.parse import urlparse, urlunparse from apig_sdk import signer def _normalize_api_url(url: str) -> str: parsed = urlparse(url.strip()) clean_url = urlunparse(parsed._replace(query="", fragment="")) if parsed.query: print(f"[提示] 检测到 API_URL 携带查询参数「?{parsed.query}」，已自动剥离。") print(f" 实际使用的调用路径: {clean_url}\n") return clean_url def build_and_sign_request(sig, api_url: str, prompt: str, session_id: str): """构造请求并执行签名 (每次调用都会自动获取当前最新时间戳重新计算签名)""" method = "POST" payload = {"query": prompt} body = json.dumps(payload, ensure_ascii=False) headers = { "Content-Type": "application/json", "X-Sdk-Content-Sha256": "UNSIGNED-PAYLOAD", "x-hw-agentarts-session-id": session_id } req = signer.HttpRequest(method, api_url, headers, body) sig.Sign(req) return req def main(): # 1. 自动规范化 API_URL，剥离可能携带的查询参数 api_url = _normalize_api_url(API_URL) # 2. 读取环境变量凭证 ak = os.getenv('HUAWEICLOUD_SDK_AK', '').strip() sk = os.getenv('HUAWEICLOUD_SDK_SK', '').strip() if not ak or not sk: print("错误：环境变量中未检测到 HUAWEICLOUD_SDK_AK 或 HUAWEICLOUD_SDK_SK！") return # 3. 初始化 V11 签名器 sig = signer.Signer(algorithm="V11-HMAC-SHA256", region_id=REGION_ID) sig.Key = ak sig.Secret = sk session_id = str(uuid.uuid4()) # 4. 展示当前的鉴权 Header 信息 init_req = build_and_sign_request(sig, api_url, "hello", session_id) print(f"X-Sdk-Date : {init_req.headers.get('X-Sdk-Date')}") print(f"Authorization: {init_req.headers.get('Authorization')}\n") # 5. 进入交互对话循环 while True: try: prompt = input("【请输入您的问题】: ").strip() if not prompt: continue if prompt.lower() in ["exit", "quit"]: print("程序已退出。") break # 提问时自动在后台重新计算带最新时间戳的签名 req = build_and_sign_request(sig, api_url, prompt, session_id) resp = requests.request( method=req.method, url=f"{req.scheme}://{req.host}{req.uri}", headers=req.headers, data=req.body, timeout=(5, 60) ) print(f"【HTTP 状态码】: {resp.status_code}") print("【智能体响应内容】:") print(resp.text) print("-" * 50 + "\n") except KeyboardInterrupt: print("\n程序已退出。") break if __name__ == '__main__': main() ``` 2. 脚本编辑完成后，保存并关闭该脚本。 #### 步骤四：运行脚本获取接口响应 1. 在Python SDK的文件夹上方显示路径的地址栏里，清空地址，直接输入cmd后按回车。 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002686436027.png "点击放大") 2. 在打开的命令提示符窗口中会显示出当前的文件夹路径，输入以下命令执行脚本。 ``` python main.py ``` 运行该脚本会返回接口的鉴权信息值，以及接口的响应结果。 图8运行示例 ![](https://support.huaweicloud.com/api-agentarts/zh-cn_image_0000002686274801.png "点击放大") #### 常见问题 - **请求返回401或 {"code":401,"message":"Authorization failed!"}报错** 原因1：智能体部署时"入站身份认证"未勾选IAM认证（如误选了API Key模式）。 原因2：签名算法使用了普通SDK-HMAC-SHA256算法，未切换为要求的V11-HMAC-SHA256。 原因3：AK/SK复制有误，或该AK在华为云控制台 "我的凭证 \> 访问密钥" 中已被停用或删除；或环境中的AK/SK未更新。 排查方法：确认智能体已选择IAM认证并重新提交部署，确保代码初始化使用的是 signer.Signer(algorithm="V11-HMAC-SHA256", region_id=...)。在控制台重新生成一对有效的AK/SK，打开一个全新的终端重新 set HUAWEICLOUD_SDK_AK=...设置AK/SK后再尝试调用智能体接口。 - **返回Model call failed（模型调用失败）** 原因：AgentArts智能体配置的基础大模型未绑定正式模型。 排查方法：进入AgentArts平台配置华为云MaaS服务付费模型API Key或第三方OpenAI协议模型，免费赠送的测试Token不支持API方式调用。 - **请求返回400 Bad Request（时间偏差报错）** 原因：本地客户端的系统时间与标准UTC时间偏差超过了15分钟，导致签名的时间戳X-Sdk-Date校验失败。 排查方法：将本地电脑或服务器的时钟与NTP服务器进行网络时间同步。