Agents网关类商品技术对接方案
简介
- Agent网关(Agent Gateway)是AI Agent生态中的关键基础设施,它充当一个集中式的“交通枢纽”,为Agent提供统一接口,使其能高效发现、访问和调用各种工具或服务。
- 商家在云商店发布Agents类商品时,需要在云商店进行Agents注册,云商店Agents网关承载了API应用的请求路由、用户鉴权、服务管理监控等。
Agents类商品计费规则
|
支持的计费项名称 |
支持的计费项解析字段 |
参数位置 |
备注 |
|
Tokens输入 |
|
response.body |
/ |
|
Tokens输出 |
|
response.body |
/ |
|
图片数 |
|
response.body |
/ |
|
视频时长(秒) |
|
response.body |
/ |
|
语音时长(秒) |
|
response.body |
/ |
|
字节数 |
|
request.body |
网关会自动统计计费项解析参数字符串的字节长度,作为用量上报 |
|
字符数 |
|
request.body |
网关会自动统计计费项解析参数字符串的字符长度(字符集编码:UTF-8),作为用量上报 |
操作步骤
- 在“AI网关服务 > Agents注册”中,单击Agents注册。

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

- 协议类型:HTTPS、HTTP
- 接口请求类型:GET、POST
- Agent访问前缀:为域名格式,端口未指定则使用默认端口,协议为HTTP,端口使用80;协议为HTTPS,端口使用443。
- 获取Agent对外公开的访问地址后,则需先通过“应用接入 > 生产地址管理”菜单界面,添加生产地址,如:https://xx.yy.com。
- 将认证通过的地址去除协议类型内容,填写到此输入框内,如:xx.yy.com。
- 填写完成后,单击“校验后端服务”。
- 提示“校验成功”,即可说明该服务具备连通性。
- Agents访问路径:以/开头,不支持动态参数路径。
- 调用方式:流式、同步。
- 流式:是一种在数据处理、网络通信等场景中常用的技术,它允许数据以流的形式进行传输和处理。
- 同步:是一种程序执行的策略,其中调用函数或方法时会按照其编写的顺序,等待当前函数或方法执行完成后才继续执行后续的代码。
- 后端超时时间:支持最大300000ms
- 认证方式:APP Key和APP Secret、自主认证,认证方式请参考AK/SK认证方式(推荐)。
- 设置“计费参数”。

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

- 定义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
- 定义请求参数:入参、请求body内容。

- 定义返回结果示例。

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

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

目前华为云云商店的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(购买客户华为云账号名称)
验签方法:
- 从jwtToken中使用base64解码解析出AK;
- 根据AK查询本地储存的SK;
- 根据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应用接口提供方自主负责。



