文档首页/ 智果（AgentArts）智能体平台/ 最佳实践/ API调用实践/ 使用API调用单/多智能体（IAM认证）
更新时间：2026-08-10 GMT+08:00
查看PDF
分享

使用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将返回“Model call failed”报错。

步骤一：部署智能体并选择IAM认证

  1. 登录AgentArts智能体平台。
  2. 在左侧导航栏中选择“开发中心 > 智能体管理”，选择需要调用的智能体。单击智能体名称进入智能体编辑页面。在“提交版本”或者“更新版本”时，需要勾选“部署至实例”选项。勾选后单击“确定”。

    图1 勾选“部署至实例”

  3. 入站身份认证选择“IAM 认证”，并勾选日志记录、指标、调用链。其余配置可以使用默认值。

    图2 选择“IAM 认证”

  4. 获取智能体的调用路径（API_URL）。

    智能体部署完成后，返回列表页，获取调用路径。

    图3 获取智能体调用路径

步骤二：准备SDK环境

安装运行环境：

  • 安装Python：如果您还没装，去python.org下载并安装（记得安装时勾选 "Add Python to PATH"）。
  • 安装requests库：

    打开电脑的“命令提示符”（Windows按Win+R键输入cmd），输入以下命令并按回车：

    pip install requests

获取API签名所需的SDK包：

  1. 在签名指南文档中下载Python SDK，并在本地解压。签名指南文档中的其他内容本案例中可不用关注。

    图4 获取SDK

    解压后的文件目录结构如下：

    ApiGateway-python-sdk/              ← 根目录（解压出来的文件夹）
│
├── apig_sdk/                       ← 【核心签名库，不要动！】
│   ├── __init__.py                 ← 包的入口标识文件
│   └── signer.py                   ← 签名核心代码（所有签名逻辑都在这里）
│
├── main.py                         ← 【您要改的文件】调用示例
│
└── licenses/                       ← 开源许可证文件夹（不用管）
    └── license-requests            ← requests库的许可证说明
    图5 目录结构

配置环境变量：

  1. 登录控制台“我的凭证 > 访问密钥”，获取AK和SK。AK、SK最多可添加2个。

    图6 获取AK、SK
    图7 AK、SK示例

  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 apig_sdk import signer


def build_and_sign_request(sig, 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. 读取环境变量凭证
    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

    # 2. 初始化 V11 签名器
    sig = signer.Signer(algorithm="V11-HMAC-SHA256", region_id=REGION_ID)
    sig.Key = ak
    sig.Secret = sk

    session_id = str(uuid.uuid4())

    # 3. 展示当前的鉴权 Header 信息
    init_req = build_and_sign_request(sig, "hello", session_id)
    print(f"X-Sdk-Date   : {init_req.headers.get('X-Sdk-Date')}")
    print(f"Authorization: {init_req.headers.get('Authorization')}\n")

    # 4. 进入交互对话循环
    while True:
        try:
            prompt = input("【请输入您的问题】: ").strip()
            if not prompt:
                continue
            if prompt.lower() in ["exit", "quit"]:
                print("程序已退出。")
                break

            # 提问时自动在后台重新计算带最新时间戳的签名
            req = build_and_sign_request(sig, 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后按回车。

  2. 在打开的命令提示符窗口中会显示出当前的文件夹路径，输入以下命令执行脚本。 

    python main.py

    运行该脚本会返回接口的鉴权信息值，以及接口的响应结果。

    图8 运行示例

常见问题

  • 请求返回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服务器进行网络时间同步。

父主题： API调用实践

相关文档