Docs
文档目录

AI Gateway(统一 AI 数据面)

这是什么 / 何时用

AI Gateway 是 2.6.0 新增的统一 AI 数据面与控制面(services/ai-gateway),承载 Target 接入、Tool/MCP、A2A、HTTP Agent、身份(Consumer/Key)、策略(Policy)、预算、缓存与审计。资源模型:Gateway / Target / Tool / Consumer / Policy / Snapshot——Target 与 Tool 是项目级资产,经挂载关系进入一个或多个 Gateway Snapshot。

与既有 LLM Gateway 并存:不迁移旧资源、不接管旧生产路径、不提供无 gatewayId 的兼容别名。只要现有 Provider/Gateway Key/Chat/Embeddings/Rerank/VLM,继续用 llm-gateway.md;涉及 Gateway/Target/Tool/Consumer/Policy/MCP/A2A 才用本页。两者名称、凭据、路径互不互换。

前置

使用骨架

数据面入口(HTTP,2.6.0 新增;SDK 不封装这些路径):

控制面(SDK AiGateway 服务):

  1. 建 Gateway 并管理策略:createPolicyEngine / listPolicyEngines / getPolicyEngine;updateGatewayPolicy({ gatewayId, ... });策略包 createRevision/publishPolicyBundle/listPolicyBundles/getPolicyBundle;上线前 dryRunPolicy 验证;发布语义用 Snapshot:sealSnapshot / getSnapshotStatus。

  2. 接入 Target:createResource / listResources / getResource / replaceResource(kind 为资源类别路径参数);修订管理 createRevision / getRevision / transitionRevision(/resources/{kind}/{id}/revisions/{revisionId}/{action});健康检查 checkTargetHealth;挂载 listTargetMounts / replaceTargetMounts。

  3. 模型推理、模型部署与标准模型管理在 v2.12.0 不可用。

  4. Tool/MCP 连接:createToolConnection / discoverToolConnection / updateToolConnection / deleteToolConnection。

  5. Consumer 凭据:createKey / listKeys / getKey / updateKeyStatus(abk_ 的签发与启停)。

  6. 观测与审计:getObservabilityOverview / listInvocations / getInvocation。

2.7.0 增量(appbase release-2.7.0 PR 526):

2.8.0 增量:

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

工具数据面入口(MCP / A2A / HTTP Agent)

MCP / A2A / HTTP Agent 是 HTTP 数据面入口,各语言 SDK(含 Web)均不封装这些路径,故本卡仅 REST 页签;公开 listener 用目标 Gateway 签发的 abk_ Key(Authorization: Bearer 携带),LLM Gateway Key、项目 API Key、上游 Provider Key 都不能当 abk_ 用。

# MCP:/ai-gateway/g/<GATEWAY_ID>/mcp(Tool 列表/搜索/调用共用 Agent allowlist 与 OPA 授权,副作用受幂等门禁保护)
# A2A:/ai-gateway/g/<GATEWAY_ID>/a2a/<targetSlug>(Task/Context 按调用者 + Target Revision 隔离)
# HTTP Agent:/ai-gateway/g/<GATEWAY_ID>/http/<targetSlug>[/{path...}](只转发 Target 允许的方法/相对路径/query/body,
#   不重放调用方认证 Header,凭据从受控 Credential 解析)

建 Gateway 并管理策略(策略引擎 / 策略包 / Snapshot)

策略引擎创建后把策略包经 dry-run 验证再 publish、经 updateGatewayPolicy 挂到 Gateway;sealSnapshot 封存当前配置(异步),Target / Consumer / Tool allowlist / Policy 变更只在已发布且一致的 Snapshot 上对公开流量生效。

await aiGateway.listPolicyEngines();                             // 策略引擎列表
await aiGateway.updateGatewayPolicy({ gatewayId: '<gatewayId>' }); // 挂接策略(字段见 SDK 类型定义)
await aiGateway.sealSnapshot({ gatewayId: '<gatewayId>' });      // 封存为 Snapshot(异步)
await aiGateway.getSnapshotStatus({ gatewayId: '<gatewayId>' }); // 轮询封存结果
// 策略引擎创建/详情:createPolicyEngine / getPolicyEngine
// 策略包:createRevision / publishPolicyBundle / listPolicyBundles / getPolicyBundle;上线前 dryRunPolicy 验证(只评估不执行)

接入 Target(资源 / 修订 / 挂载)

Target 走统一资源端点(kind 为路径参数)与修订状态机上线;健康检查与挂载整体替换为资源专有操作。

// 统一资源面:listResources / createResource / getResource / replaceResource / deleteResource
//   kind 为资源类别路径参数;请求体为泛化 schema,以 SDK 类型定义为准
// 修订:createRevision / getRevision / transitionRevision(资源上线走修订状态机)
// Target 运维:checkTargetHealth;挂载:listTargetMounts / replaceTargetMounts

模型部署与标准模型

v2.12.0 禁用 AI Gateway 的模型部署、发现和标准模型管理;请使用 LLM Gateway 接入模型。

Tool/MCP 连接

Tool 连接是 Tool/MCP 数据面调用的上游接入:创建后可触发工具发现、测试连通性、更新配置与删除(删除需要 region 参数,活动连接须先停用;删除后应验证相关工具调用的实际结果)。2.8.0 起支持连通性测试:testToolConnection(id, toolId)(toolId 可选)(POST /ai-gateway/tool-connections/{id}/test),返回诊断结果(目标可达性、凭据检查与逐工具状态),Console 连接诊断面板同源。

// createToolConnection / discoverToolConnection / updateToolConnection / deleteToolConnection
// 2.8.0 连通性测试:aiGateway.testToolConnection('<id>');可选第二参 toolId 只测单个工具
// payload 由目标资源定义,字段见 SDK 类型定义

Consumer 凭据(abk_ Key)签发与启停

createKey 签发 abk_ 凭据,用 gatewayIds 圈定可调用网关,allowedModels / allowedTools / allowedAgents 圈定模型、工具与 Agent Target。停用会尝试清除认证缓存;若清除失败,旧缓存可能短暂有效,已在途请求也可能继续。应验证实际调用被拒绝,不能只依赖成功响应。

省略 allowedModels、allowedTools 或 allowedAgents 时,该项默认为 ["*"];空数组表示拒绝该类型。以下示例仅允许指定工具,不允许模型或 Agent,仍受快照和策略约束。

import { AiGateway } from 'agentbase-node-sdk';

const aiGateway = new AiGateway(client);   // 控制面:aiGateway.read / aiGateway.write

await aiGateway.listKeys();                // abk_ 元数据视图
await aiGateway.createKey({
    name: 'agent-consumer',
    gatewayIds: ['<gatewayId>'],
    allowedModels: [], allowedTools: ['<TOOL_ID>'], allowedAgents: [] // allowlist 与 principal 字段见 SDK 类型定义
});
// 启停:aiGateway.updateKeyStatus(...);验证停用后的实际调用结果

观测与审计

调用记录与观测总览按 aiGateway.read scope 查询,用于网关调用的排障与审计。

await aiGateway.getObservabilityOverview();   // 观测总览
await aiGateway.listInvocations();            // 调用记录列表(过滤参数见 SDK 类型定义)
// 单条调用记录:getInvocation

示例指引

2.12.0 — 审批、初始化与工具向量

新增 listApprovalRequests/getApprovalRequest/approveApprovalRequest/rejectApprovalRequest、getInitializationStatus、listToolEmbeddings/createToolEmbeddings。读取与写入分别需要 aiGateway.read / aiGateway.write。先查看请求所属工具、调用与当前状态,再明确批准或拒绝;不能为了重试读取而重复批准。工具向量化可能调用模型,查询初始化状态不等于所有资源已就绪。