更新时间:2025-12-30 GMT+08:00
分享

Agents网关类商品技术对接方案

简介

  • Agent网关(Agent Gateway)是AI Agent生态中的关键基础设施,它充当一个集中式的“交通枢纽”,为Agent提供统一接口,使其能高效发现、访问和调用各种工具或服务。
  • 商家在云商店发布Agents类商品时,需要在云商店进行Agents注册,云商店Agents网关承载了API应用的请求路由、用户鉴权、服务管理监控等。

Agents类商品计费规则

该类商品的计费依赖商家填写的计费项解析字段返回的用量,部分特殊计费项如请求里的计费项解析字段:字节、字符数,则由Agents网关进行计算,请确认商品是否满足对接要求。

支持的计费项名称

支持的计费项解析字段

参数位置

备注

Tokens输入

  • usage.prompt_tokens
  • usage.input_tokens
  • 自定义

response.body

/

Tokens输出

  • usage.completion_tokens
  • usage.output_tokens
  • 自定义

response.body

/

图片数

  • usage.image_count
  • 自定义

response.body

/

视频时长(秒)

  • usage.video_duration
  • 自定义

response.body

/

语音时长(秒)

  • transcripts.content_duration_in_milliseconds
  • 自定义

response.body

/

字节数

  • input
  • 自定义

request.body

网关会自动统计计费项解析参数字符串的字节长度,作为用量上报

字符数

  • input
  • 自定义

request.body

网关会自动统计计费项解析参数字符串的字符长度(字符集编码:UTF-8),作为用量上报

操作步骤

  1. 在“AI网关服务 > Agents注册”中,单击Agents注册。

  2. 定义Agent后端信息,设置接口请求类型、Agents访问前缀、Agents访问路径、调用方式、后端超时时间、APP Key和APP Secret等信息,确认信息无误后,单击“下一步”。

    • 协议类型:HTTPS、HTTP
    • 接口请求类型:GET、POST
    • Agent访问前缀:为域名格式,端口未指定则使用默认端口,协议为HTTP,端口使用80;协议为HTTPS,端口使用443。
    1. 获取Agent对外公开的访问地址后,则需先通过“应用接入 > 生产地址管理”菜单界面,添加生产地址,如:https://xx.yy.com。
    2. 将认证通过的地址去除协议类型内容,填写到此输入框内,如:xx.yy.com。

    1. 填写完成后,单击“校验后端服务”。

    2. 提示“校验成功”,即可说明该服务具备连通性。

      • Agents访问路径:以/开头,不支持动态参数路径。
      • 调用方式:流式、同步。
        1. 流式:是一种在数据处理、网络通信等场景中常用的技术,它允许数据以流的形式进行传输和处理。
        2. 同步:是一种程序执行的策略,其中调用函数或方法时会按照其编写的顺序,等待当前函数或方法执行完成后才继续执行后续的代码。
      • 后端超时时间:支持最大300000ms
      • 认证方式:APP Key和APP Secret、自主认证,认证方式请参考AK/SK认证方式(推荐)

  3. 设置“计费参数”。

  4. 定义Agent基本信息:Agent名称、模型名称、描述。

  5. 定义Agent请求信息:请求路径。

    • 该请求路径为客户购买后提供调用的接口URL,格式为:请求访问前缀/请求路径,例如:https://agentstore-mkt.myhuaweicloud.com/v1/aimodelservice/chat/completions
    • 若需兼容openai接口规范,请以/xxx/xxx/chat/completions结尾
    • 不允许与其他商家定义的请求路径重复
    • 同商家的不同模型规格请求路径可相同,会根据body中model参数区分
    • 接口路径(path)限制2至6段,例如:{company_name}/chat/completions

  6. 定义请求参数:入参、请求body内容。

  7. 定义返回结果示例。

  8. 单击右下方“完成”,即完成Agtens创建。
  9. 创建Agents后,需要进行“调测”。

  10. 调测成功后,并且业务处理与预期一致,才能进行发布商品上架,避免用户购买后无法使用。

    目前华为云云商店的Agents网关默认在华北-北京四,其他区域暂不支持。

Agents后端应用接口的基本要求

协议类型:http、https

接口类型:get、post

响应类型:同步、流式

返回类型:json、stream

鉴权方式:AK/SK认证(推荐)、自主认证

返回必须要携带使用量usage对象,放在一级结构

响应示例如下:

{
  "data": "南京,全名南京市,是江苏省的省会,位于中国南部的长江中游,是长江三大口的一个,也是中国古代文化的发祥地。",    //可替换成自己的任意对象结构
  "usage": {                            //usage的对象结构必须一样
      "completion_tokens": 217,   //大模型输出的token数量
      "prompt_tokens": 31,     //用户输入的tokens数量
      "total_tokens": 248      //总tokens数量
  }
}

用户使用过程中,实际的费用依赖请求响应的使用量usage对象来计算。

Agents商品调用流程介绍

参数说明:

Agents网关会增加三个请求头信息返回给后端接口,可按需接收和使用:

X-Request-Id:uuid(接口请求唯一编号)

X-Customer-Id:domain id(购买客户华为云账号ID)

X-Customer-Name:domain_name(购买客户华为云账号名称)

AK/SK认证方式(推荐)

验签方法:

  1. 从jwtToken中使用base64解码解析出AK;
  2. 根据AK查询本地储存的SK;
  3. 根据SK使用jwt工具类验签。

引入依赖:

<dependency>

<groupId>com.auth0</groupId>

<artifactId>java-jwt</artifactId>

<version>4.2.1</version>

</dependency>

示例代码如下

public class JWTtokenUtil {

      //生成token
     public static String createJwt() {
         Map<String, Object> signHeaders = new HashMap<>();
         signHeaders.put("alg", "HS256"); // 设置签名算法为HS256
         signHeaders.put("sign_type", "SIGN"); // 设置签名类型为SIGN
         Map<String, Object> payload = new HashMap<>();
         payload.put("api_key", "d44cd9aa-e48e-be17-27f4-5ef3474797a1"); // 设置API密钥
         long timestamp = System.currentTimeMillis(); // 获取当前时间戳
         payload.put("timestamp", timestamp); // 将时间戳添加到payload中
         // 失效时间5分钟
         payload.put("exp", timestamp + 300000); // 设置令牌的过期时间,这里设置为当前时间戳加上300000毫秒(即5分钟
         String sk ="f980be69-88e6-4f02-9d09-e47326488df2"; // 密钥         // 创建JWT,包含header和payload,并使用秘密钥行签名
         String jwtToken =

JWT.create().withHeader(signHeaders).withPayload(payload).sign(Algorithm.HMAC256(sk)); 

         System.out.println(jwtToken); // 打印生成的JWT

          return jwtToken; // 返回生成的JWT
     }
       //验证Token的有效性
     public static boolean checkToken(String token) {
         //解析出ak
         String payloadBase64=token.split("\\.")[1]; // 使用"."分隔token,获取第二部分
         byte[] decodedBytes = DatatypeConverter.parseBase64Binary(payloadBase64); // 将获取到的部分进行Base64解码
         String payloadJson = new String(decodedBytes); // 将解码后的字节数组转换为字符串 
        JSONObject json_test=JSONObject.fromObject(payloadJson); // 将字符串转换为JSON对象
         String ak=json_test.get("api_key").toString(); // 从JSON对象中获取"api_key"对应的值
         System.out.println(ak); // 打印ak

          //根据ak查询sk,按照自己的数据规则查询
         String sk ="f980be69-88e6-4f02-9d09-e47326488df2"; // 这里直接赋值为一个固定的字符串,实际应用中应根据ak查询获取

          //验证Token(验证失败,会引发异常)
         boolean result=false; // 初始化验证结果为false
         try {
             JWTVerifier jwtVerifier = JWT.require(Algorithm.HMAC256(sk)).build(); // 创建JWTVerifier对象,使用HMAC256算法和sk进行构建
             DecodedJWT verify = jwtVerifier.verify(token); // 使用JWTVerifier对象验证token
             result=true; // 验证成功,将结果设为true
         } catch (Exception e) {
             System.out.println("捕获到异常:" + e.getMessage());// 验证失败,抛出异常
         }
         return result; // 返回验证结果
     }

      public static void main(String[] args) {
         String jwtToken = createJwt();

          System.out.println(checkToken(jwtToken));
     }

  }

自主认证推荐方式

如果选择自主认证方式,则不需要填写AK/SK,建议将自己的认证密钥配置到请求头的常量参数中(网关会加密保存),网关将不再进行加签行为直接转发。

自主认证方式因为没有加签行为,可能会有一定的安全风险,安全认证方式agents应用接口提供方自主负责。

相关文档