跳到主要内容
AI教程

使用 AI Agent Gateway 部署并保护 AI 智能体

了解如何使用 Docker Compose 部署 AI Agent Gateway、初始化管理员、验证其三个服务平面、连接 MCP 工具、启用分析、控制出站访问、保护凭据，并为更高级的智能体和 LLM 工作流做好准备。

AI我搜编辑部阅读约 12 分钟
使用 AI Agent Gateway 部署并保护 AI 智能体

什么是 AI Agent Gateway？

AI Agent Gateway 是一项开源服务，位于 AI 代理与其调用的系统之间。它为 MCP 工具服务器和受支持的 LLM 提供商提供统一的身份验证与可观测入口，包括 Anthropic Claude、AWS Bedrock、OpenAI 和 Gemini。

无需将工具凭据和提供商设置复制到每个代理中，你可以集中管理身份验证、密钥、访问策略和请求日志。该网关以单个二进制文件分发，并内置管理控制台。

该服务提供三个监听器：

  • 8080 端口的 MCP 平面：接收来自代理的 MCP 请求，并将获准的操作转发到已注册的工具服务器。
  • 8081 端口的控制平面：提供 REST API 和管理控制台。
  • 8082 端口的 LLM 平面：代理受支持的 LLM 请求，并记录使用信息。

必须使用 PostgreSQL。Redis 兼容的会话存储为可选项，可让 MCP 平面运行多个副本；捆绑部署使用 Valkey。ClickHouse 也是可选项，可提供额外的分析功能。

主要功能

  • 每个请求都需要身份验证：网关签发的 API 密钥限定于特定租户和角色。
  • 受保护的连接器凭据：凭据存储在加密密钥存储中，并注入出站 MCP 请求，不会暴露给调用方。
  • 代理专属工具策略：配置文件可以限制代理可使用的工具。限制会在执行 tools/call 时强制实施，而不仅是在列出工具时实施。
  • 提示和资源：网关通过共享命名空间传递后端提示和资源，并应用相同的配置文件策略。
  • 技能和命令：配置文件可以包含可复用的参考文本和提示模板，并通过原生 MCP 机制提供。
  • 多提供商 LLM 代理：LLM 平面支持 Anthropic、Bedrock、OpenAI 和 Gemini，同时记录令牌用量和预估成本。
  • 集中式可观测性：启用必要的存储后，控制台可提供访问日志、LLM 日志、会话时间线和分析仪表板。
  • 出站请求保护：默认阻止内部、环回、链路本地及其他私有目标，以降低服务器端请求伪造风险。

前置条件

最快的设置方式是使用 Docker Compose。开始前，请安装或确认以下组件：

  • 带 Compose 插件的 Docker，例如 Docker Desktop、Colima 或 Docker Engine。
  • 用于健康检查的 curl，以及用于处理 API 响应的 jq。
  • 本地空闲端口 8080、8081 和 8082。
  • 如果启用分析配置文件及其 Adminer 服务，还需要端口 8090。
  • 至少 4 GB 的可用 Docker 容量；添加 ClickHouse 分析功能时需要 8 GB。

支持 macOS 和 Linux。Windows 可通过 WSL2 使用，但目前尚未在该环境中测试。

如果不使用 Docker 构建，代码仓库要求 Go 1.27、用于控制台的 Node.js 26 和 make。部分操作示例还需要 npx、Python、kind、kubectl 或提供商 API 密钥。

安装并启动网关

1. 克隆代码仓库

git clone https://github.com/Tuskira/ai-agent-gateway.git
cd ai-agent-gateway

2. 启动标准 Compose 堆栈

docker compose -f deploy/docker-compose.yml up --build -d

首次启动可能需要一些时间，因为 Docker 必须构建或下载所需组件并初始化数据库。

3. 等待控制平面就绪

until curl -sf localhost:8081/api/v1/health >/dev/null; do sleep 1; done

该循环会持续等待，直到控制平面的健康端点成功返回。

4. 检查三个平面

curl localhost:8080/health
curl localhost:8081/api/v1/health
curl localhost:8082/health

成功的响应表示 MCP、控制和 LLM 监听器均已可用。

初始化管理访问权限

新部署没有控制台用户，也没有 API 密钥。首先创建默认租户和管理员 API 密钥：

docker compose -f deploy/docker-compose.yml exec gateway /gateway bootstrap-key

该命令只会显示一次 API 密钥。请妥善保存，因为入门流程会使用它注册连接器并执行管理 API 操作。

接下来，创建第一个控制台用户：

docker compose -f deploy/docker-compose.yml exec gateway /gateway create-user -tenant default -username admin -role admin

该命令会显示一次性临时密码。打开 http://localhost:8081，使用 admin 登录，并在提示时修改临时密码。

程序通常应使用 API 密钥进行身份验证。控制台也可以在紧急情况下使用 API 密钥作为备用方式。

基本用法：添加并调用 MCP 服务器

在网关术语中，MCP 工具服务器在 API 中称为连接器，在控制台中称为MCP。登录后，打开MCP → 目录，即可查看可添加的现成 MCP 服务器。

首次使用时通常按以下流程操作：

  1. 创建并保存管理员 API 密钥。
  2. 将 MCP 服务器注册为连接器。
  3. 配置连接器所需的凭据。
  4. 创建或选择代理配置。
  5. 使该配置可以使用连接器的工具。
  6. 通过网关在 8080 端口上的 MCP 监听器调用获准的工具。
  7. 在管理控制台中检查调用。

仓库在 examples/01-quickstart 下提供了完整的可执行演示。它会启动整个技术栈，验证三个平面，初始化管理员密钥，注册示例 MCP 服务器，并调用其中一个工具。有关确切的连接器注册和工具调用请求，请参阅入门指南。

要运行不需要外部凭据的所有示例，请使用：

make examples-smoke

代理配置如何实施访问控制

配置定义了代理可用的工具、提示词、资源、技能和命令。代理调用 tools/call 时会检查工具限制，因此仅从 tools/list 中隐藏工具并不是唯一的控制措施。

如需更强的策略控制，请将 API 密钥绑定到配置。没有绑定时，调用方可以通过 X-Agent-Profile-Name 标头指定所需的配置。密钥与配置的绑定可防止调用方自由选择其他配置。

当多个 MCP 服务器提供提示词或资源时，网关会将它们保存在统一命名空间中。提示词会使用连接器名称进行限定，资源则使用由网关管理的 URI。相同的配置规则决定代理可以访问哪些条目。

使用 LLM 代理

LLM 平面为受支持的模型提供商提供集中式访问路径：Anthropic、AWS Bedrock、OpenAI 和 Gemini。这使代理应用能够通过与工具相同的受控入口发送模型流量。

对于每次代理调用，网关都可以记录令牌用量并估算成本。提供商设置、自带密钥配置、Bedrock 凭据模式、路由、记录设置和成本行为详见 LLM 平面指南。

配置客户端之前，请使用健康检查端点验证监听器：

curl localhost:8082/health

启用分析

标准部署支持不使用 ClickHouse 的 LLM 日志。要添加概览仪表板、访问日志、会话时间线以及基于 ClickHouse 的分析功能，请使用 analytics 配置启动 Compose：

GATEWAY_SINKS_CLICKHOUSE_ENABLED=true docker compose -f deploy/docker-compose.yml --profile analytics up --build -d

此配置需要更多本地资源，并可能使用 8090 端口。

保护敏感请求正文

演示技术栈会将 LLM 请求和响应正文存储在 PostgreSQL 中，每项上限为 1 MiB。使用 analytics 配置时，它还会将 LLM 和 MCP 请求及响应正文存储在 ClickHouse 中，以便在控制台中显示。这些正文不会输出到容器日志。

如果提示词、模型响应或工具负载可能包含敏感信息，请完全禁用正文存储：

GATEWAY_LLM_PROXY_CAPTURE_STORE_BODIES=false GATEWAY_CAPTURE_STORE_BODIES=false docker compose -f deploy/docker-compose.yml up --build -d

在生产数据上使用记录功能前，请阅读可观测性文档。

安全连接本地或私有 MCP 服务器

网关默认阻止环回地址、私有地址、链路本地地址及其他内部目标。它还会永久阻止云元数据地址 169.254.169.254。此策略可防止连接器、目录条目或模型目标在主机或网络上悄然访问敏感服务。

如果某个主机名在创建时仅解析到被阻止的地址，网关会返回 400 egress_blocked 并拒绝该主机名。尚未解析的主机名可能会被接受，但网关尝试连接时会再次检查。

直接运行二进制文件

使用 make run 运行时，如果 MCP 服务器运行在同一台机器上，请明确允许环回地址：

GATEWAY_EGRESS_ALLOWED_CIDRS=127.0.0.0/8,::1/128 make run

使用随附的 Compose 技术栈

随附的 Compose 配置已经允许 host.docker.internal 和环回 CIDR。因此，运行在笔记本电脑上的服务器可以通过 host.docker.internal 访问。在共享环境中，除非确有需要，否则请移除这些允许项。

使用 Kubernetes 或私有网络

对于集群内的 Kubernetes 服务，仅允许要调用的 DNS 名称，例如：

GATEWAY_EGRESS_ALLOWED_HOSTS=my-mcp-server.my-ns.svc

也可以允许相关的 Pod 或服务 CIDR。对于仅限 VPN 或私有网络的服务器，请添加特定主机名或较窄的 CIDR，不要启用所有私有地址范围。

尽可能缩小出站允许列表。不要仅为了让初始测试更容易就禁用保护措施。

高级运维提示

  • 分离人工访问与程序访问：管理员使用控制台账户，代理和自动化程序使用网关签发的 API 密钥。
  • 将密钥绑定到配置文件：绑定到配置文件的密钥比允许调用方通过请求标头选择配置文件提供更强的保障。
  • 将凭据保存在网关中：集中配置连接器凭据，避免代理获取底层机密信息。
  • 轮换连接器凭据：使用连接器和凭据管理功能，而不是分别更新每个代理。
  • 控制数据捕获：在处理机密提示词或工具结果之前，决定是否应保留请求和响应正文。
  • 为多副本部署做好规划：将 MCP 平面扩展到一个以上副本时，配置可选的 Redis 协议会话存储。
  • 使用严格的出口规则：允许单个主机或 CIDR，而不是宽泛的私有地址范围。
  • 参考完整示例：各个示例涵盖其他场景，并在各自的 README 文件中列出所需工具或供应商密钥。
  • 预期变更：该项目处于 1.0 之前的 alpha 阶段，因此 API 和配置可能会在次要版本之间发生变化。

在 Docker 外构建

如需本地开发，请安装 Go 1.27、Node.js 26 和 make。仓库提供 make build 和 make run 工作流。可选的开发和发布工具包括 golangci-lint、govulncheck 和 goreleaser。

有关开发约定、测试命令、拉取请求指南，以及存储、接收器和提供商的扩展点，请参阅贡献指南。

结语

AI Agent Gateway 通过经过身份验证的端点，集中管理对 MCP 工具和多个 LLM 提供商的访问。其配置文件强制执行、凭据注入、出站网络控制和可观测性功能，有助于避免将策略和机密信息分散在各个代理配置中。

请从 Docker Compose 快速入门开始，保存生成的管理员密钥，创建一个控制台用户，并完成第一个连接器工作流。之后，添加绑定到配置文件的 API 密钥，配置提供商访问权限，选择合适的正文捕获策略，并仅在确实需要额外可见性时启用 ClickHouse 分析。