Agent API Gateway · 深潜教程 · 概念向

Agent 网关:给 agentic 流量的数据平面

面向已经在调 LLM、已经在用工具的工程师。这份教程不教你写网关代码,而是把「为什么 agent 流量需要一个新品类的网关」讲到能向同事复述的程度。基线:截至 2026-06。

·适合谁

三条前置能力。任何一条没有,先补再读会顺很多:

  • 读过或写过 HTTP 反向代理配置——见到 listener / route / upstream 这类词大致知道指什么(Nginx、Envoy、任意 API 网关都行)。
  • 用代码调用过至少一个 LLM API(OpenAI、Anthropic 等),知道什么是 streaming 响应、知道按 token 计费这回事。
  • 知道 agent「调用工具」的基本概念(function calling / tool use)——不需要写过 MCP server,知道 agent 会在对话中触发外部调用即可。

·不适合谁

  • 完全没碰过 LLM API → 先跟一遍 Anthropic 或 OpenAI 的 quickstart,跑通一次带 streaming 的调用再回来。
  • 只想要一句「什么是 AI 网关」 → 直接看下面的 现状速览 一段就够,不必读全篇。
  • 想照着写一个网关的源码实现 → 这是概念向教程。要动手部署,去 agentgateway 或 Envoy AI Gateway 的官方 quickstart。

·读完之后你能做到什么

核心收获,一句话:你能向同事讲清楚——为什么 agent 流量需要一个新品类的网关,而不是给 Kong 装个插件就行;并能说出 Solo.io 为此用 Rust 从零重写、而非扩展 Envoy 的技术理由。这句话,官方文档不会直接给你,需要把机制看到比 API 表面深一层才讲得出。

具体到可验证的能力,读完你能:

  • 在 LLM 网关 / MCP 网关 / agent-native 网关 / 经典 API 网关 / service mesh 五者之间,给定场景做出选型,并讲清「为什么不是另一个」。
  • 画出一条 agent 请求穿过网关的完整生命周期,标出 body 解析、策略闸口、token usage 提取分别发生在哪一步。
  • 识别 7 类生产失败模式(streaming 缓冲、token 计数偏差、语义缓存误命中、MCP 工具名冲突、凭据透传、重试风暴、A2A 失控扇出),并各说出根因。
  • 判断本领域哪些是 2026 年的定论、哪些还在快速变(MCP 传输、A2A v1.0、Streamable HTTP),不把已被取代的旧做法学进去。

一句话本质

  • ① Agent 网关在 L7 之上「多读了一层」:它把请求体(body)里的 model 名、prompt 文本、token 数、tool 调用当作一等的路由与策略依据。经典 API 网关只读 header、把 body 当不透明信封——而 agent 流量的关键信息全在 body 里。这是它必须是新品类、而非旧网关一个插件的根本原因。
  • ② 「Agent 网关」不是一个新协议,而是一个数据平面同时讲三种协议:LLM(agent→模型)、MCP(agent→工具)、A2A(agent→agent)。三者统一在一个平面里治理,才是 "agent-native" 的定义性特征。
现状速览 · 截至 2026-06-02

三大协议支柱已成型:A2A v1.0(2026-01 发布、03 公布,已由 Google 捐给 Linux Foundation,150+ 组织采用);MCP 已到 2025-11-25 修订(引入异步 Tasks、联邦 Registry 预览);远程标准传输是 Streamable HTTP——旧的独立 SSE transport 已于 2025-03-26 弃用(仅向后兼容,别再照它学新东西)。

实现还很年轻:开源旗舰 agentgateway(Rust 编写)v1.0 于 2026-03-12 发布,LF 治理;Envoy AI Gateway 直到 v0.6.0(2026-05-05)才达生产级 API 面(v1.0 GA 目标 2026-06-30)。"重营销、轻 GA" 是这个品类此刻的常态。

品类正在收敛:LLM 网关在加 MCP、经典网关在加 AI、agent-native 在吞并三者。此刻的分类更多是成熟度与定位差异,而非永久架构。还有一轮传输层大改(stateless + Server Cards)预计 2026-06 落地——属「在变」区,正文会标注。

读之前 · 三种错觉

这类基础设施教程读起来「顺」是常态,而顺往往是错觉。拿三句话自查:

『我读得很顺』——往往是你在跟着字面滑过,没有在脑子里重建一条请求真实走过的路径。

『我做题很快』——判别题答得快,常常只是题型眼熟,不是真会选型。

『我没卡壳』——没卡壳常常意味着没碰到边界:本教程的边界在「为什么是新品类」和「什么时候不该用它」。

对策:每章末尾的 self-check,先合上页面在纸上写,再展开对答案。

图概念地图

先把全局挂在一张图上。后面每个细节都挂回这里的某个节点。

Control Plane 下发 config / policy 配置 Agent 应用 发起请求 body Agent Gateway data plane listener → route → backend 模型供应商 MCP 工具 servers 其他 agent LLM MCP A2A 横切策略 guardrails · auth · 可观测性 贯穿三类流量
图 0一个 data plane,把三种 upstream(模型 / 工具 / 其他 agent)接到同一组 agent 应用上。 注意:左边进来的箭头标的是 body 而非 header——路由与策略的依据藏在请求体里,这正是它区别于经典网关的根本点。

·学习路径建议

四章是线性的,但按目的可以走不同密度:

  • 只想建立心智模型(约 1 小时):01 概念 → 02 原理 的前两节(生命周期 + 为什么经典网关做不到)→ 04 自测 的概念层。
  • 要做技术选型 / 写方案(约 2 小时):全读,重点压在 03 生产 的选型对比与部署拓扑,以及 04 自测的应用判别层。
  • 带读别人的网关配置 / 排障(约半天):全读,02 原理逐节啃,03 的失败模式当 checklist 反复对照。

·目录

·学完之后

四个自然的下一步,每个都在你已建立的 schema 上加一块:

  • MCP 协议本体——本教程只讲网关必须会说的那部分;深入 server primitives(Tools/Resources/Prompts)、Sampling、Elicitation 能补全工具侧全貌。
  • A2A 协议本体——Agent Card、Task 生命周期、Artifact,补全 agent 间协作的细节。
  • Envoy / Gateway API——agent 网关的 K8s 形态建立在 Gateway API CRD 上;懂它才看得懂生产部署。
  • LLM 可观测性——OpenTelemetry 的 GenAI 语义约定,把网关采的 trace/metric 接到监控体系。