人工智能
MoEngage 如何用 Agent Core Gateway 将 400 个API 转换为 agent 工具
这篇文章与来自MoEngage的Nikhil Kumar和Shakir Khan共同撰写。
当工程团队开始建设AI agents时，这些agents需要的能力通常已经作为内部API存在。 运动创建，分部查询，交付统计。 挑战不是建立新的功能。 挑战在于让数以百计的私人API安全地被agents所接通，而不会暴露于公共互联网，不会给模式控制身份，也不会淹没带有数百个工具定义的上下文windows.
MoEngage是超过1 350个消费者品牌使用的代理客户参与平台，通过推、电子邮件、在线、短信、WhatsApp和RCS提供个性化的经验，它正面临着这一问题。 产品后方坐落了大约400个由25个工程团队所建造的内部REST API，运行于私人虚拟私人云层(VPC)中，跨越了7个AWS区域。 MoEngage将这些API区域隔离，agents所需的能力已在生产中运行。 让它可以安全到达才是最难的
在这个帖子中，我们走过MoEngage如何使用Agent Core Gateway，这是Amazon Bedrock Agent Core的一种能力，将这些私人API变成许可范围agent工具。 这种方法节省了MoEngage大约六个月的平台工程工作，现在登上一个新的API需要几个小时而不是几天。 没有产品团队写出Model Context Protocol(MCP)服务器代码，没有提供每个集成的网络，在路径的任何地方也没有公共终点。
为什么20个MCP服务器是错误的答案
模式上下文协议(MCP)为agents提供了发现和调用工具的标准方法。 采用它的直截了当的路径是每个团队都暴露自己的MCP服务器。 MoEngage将这笔费用计算出来并拒绝。
超过20个MCP服务器意味着随着MCP的演化，超过20个部署来监测，补丁，并保持协议兼容性。 跨域的agents，即读取运动，检查其部分，并检查发送数据，需要连接到多台服务器并进行调节。 而每个团队都需要与实际产品工作无关的MCP专业知识。
因此，MoEngage确立了塑造随后一切的原则：单个工程团队不执行MCP. 团队建立REST API，并声明哪些操作应该是工具。 AI平台团队拥有MCP地层端到端。 团队的责任以精心描述的OpenAPI spec结束。
这一原则立即产生了三项要求：agents连接一次而不是每次服务的中央工具表面，每agent授权执行服务器侧而非常规，以及不需要为每个新的API重建的私人连接。
从头开始建设这一切是一个选择。 一个自定义的中央 MCP 服务器可以解决20服务器的问题，但离开 MoEngage 构建一个工具生成管道，一个政策文件格式，一个重命名的工具化名注册，以及断路器。 所有自定义代码，都归一个团队所有
塑造建筑结构的四个制约因素
在评估任何解决方案之前，MoEngage界定了四个制约因素。 四者必须同时相会。 解决两个问题但打破了第三和第四个问题的解决办法是不可行的。
没有什么会得到一个公开的终点。 MoEngage内部的API从政策上讲是VPC-私人的。 任何需要披露这些内容的解决办法，即使是在额外认证之后，都是不启动的。 常规的工作轮廓是每个集成网络：这里有一个NAT网关，那里有一个倒置的代理，第三个是VPN隧道。 乘以七大区和作战地表的增速快于agents集。 每个新的API将意味着另一个网络变更请求，另一套安全审查，另一套需要维护的基础设施。
不能由agent决定身份。 每个内部API呼叫都包含租户，用户，角色，和数据库背景。 如果上下文是一个大型语言模型(LLM)-可见工具参数，则一个模型可能会弄错或者被劝说去改变。 MoEngage需要身份才能在结构上超出模型的能及范围
一个400个工具的目录并不适合上下文窗口。 大约每个工具有50个JSON schema符号，一个完整的工具/清单横跨整个地产，在每个连接上传输超过20,000个符号。 这个象征性的预算是在agent做任何有用的事情之前花费的，它挤出上下文agent实际上需要解释任务。 客户端过滤( ADK 或 MCP SDK 中的工具过滤器) 并不修复此功能。 完整目录已经越过了电线，agent不该看到写操作
最后的制约是避免明显替代办法的制约。 一个自定义中心MCP服务器解决了20服务器的问题，但仍留下了MoEngage构建一个工具生成管道，一个政策文件格式，一个重命名的工具化名注册，以及断路器。 所有自定义代码，都归一个团队所有，没有一部让MoEngage的产品更好。
Agent Core Gateway 如何绘制这些制约因素的地图
Amazon Bedrock Agent Core Gateway是一个完全管理的MCP服务器。 您将 OpenAPI 规格注册为目标，网关从它们中生成 MCP 工具，然后路由调用到支持服务。 四个属性直接映射到MoEngage的制约因素上。
OpenAPI in, MCP 工具出局。 没有MCP服务器可以构建或运行，也没有单独的文物可以与API同步。 已经维护的光谱小组是工具定义。 每个操作都成为一个名为"目标-OperationId"的工具，例如"CampersAPI-SearchCampaigns". 当光谱改变时，工具会改变。 当一个团队新增作为终点时，工具会出现。 当一个团队移除一个时，工具会消失。 没有部署，没有协议专业知识，没有与AI平台团队的协调。
锡达政策，在目录被序列化前进行评估。 Agent Core政策引擎使用部分评价来过滤每个主机的工具/列表。 每个agent认证为它自己的IAM角色，它的Cedar政策决定它能看到和调用哪些工具。 这使得400个工具可以被牵引。 这不是事后客户端过滤
例如，一个运动QA机器人可以读取运动和分区工具，但不能称为写作操作：
机器人不在其工具/列表响应中看到写作工具。 因为工具没有发送
管理着Amazon VPC Lattice上空的入侵。 该网关通过Core代理公司管理的Egress，而不是通过MoEngage的网络建设和运行，进入MoEngage的内部服务。 入站，出站网关只能通过与私人DNS的VPC接口端点到达。 没有公开途径。 登上一个新的API 新增目标，而非网络地貌变化。 这块地产打破了7个大区的问题。 网络存在一次，每个API都使用它。
语义搜索作为网关能力。 以x amz bedrock agentcore search能力，agent可以通过描述任务而不是给工具取名来找到工具。 它取消了对自定义发现层的需求。 它还移除了将脆弱重命名为副作用：如果 get segment user counts变成 get segment size, agent 搜索分区用户计数仍为发现它，因为匹配发生在描述而不是标识符上。
实际结构
从agent到内部API的请求流很短，每层都有特定的工作。 Agent服务通过一个VPC接口端点连接到Agent Core Gateway，该端点通过在Amazon VPC Lattice至内部API的受管 Egress上对Cedar政策和路由工具呼叫进行评价。
下图显示组件如何连接。
agent服务运行在Amazon弹性计算云(Amazon EC2)上，或在一个容器中称为MCP客户端。 客户端可以是官方MCP SDK,LangChain,Google ADK，也可以是MoEngage自己的agent跑道。 客户端使用服务已经具备的AWS身份和访问管理(IAM)角色与SigV4一起签名请求。 请求通过HTTPS前往与私人DNS的VPC接口端点。 没有公开的跳跃。 Agent Core Gateway接收请求并评价了Cedar政策，以确定本主能看到或调用什么。 然后它通过在Amazon VPC Lattice上空的有管理的 Egress 向内部API传递工具引用。
MoEngage做出了两个值得召唤的认证决定。
首先，他们选择了SigV4而不是JWT作为内部网关。 Agents是已经具有IAM角色的服务。 有了SigV4，他们可以签了他们已经拥有的证书。 没有任何新东西可以发行、旋转或储存。 MoEngage的单独的公共MCP服务器服务于来自Claude和其他客户端的由人认证的会话，在AgentCore运行时使用OIDC JWTs. 这是一个不同的表面，有不同的要求。
第二，身份旅行是作为标题，而不是作为工具参数。 租户，用户，角色，和数据库上下文由客户端库从一个小身份对象转换为X-MOE-*头。 这个模型看不到它们，SigV4的签名占据了授权信头，MoEngage将它宣传为专用的MoEngage前置标题。 信头传播也被封顶，所以这组信头是故意的而不是积累的。
发现和执行有不同的身份要求。 列名和查询工具没有租户身份。 只有工具/电话才是这种分离使发现变得便宜，使审计线索变得毫不含糊。 每个具有身份的请求都是实际的数据访问。
即使Cedar将 agent 范围定义为目录的一个子集，子集也可以是大的。 MoEngage的客户端库将单个meta-工具，search tools，曝光到模型上。 这个模式描述了它需要什么，网关的语义搜索返回候选人，完整目录不输入上下文。 agent的上下文包含了一个初始的工具定义，以及搜索后的少数相关定义，而不是它永远不会使用的几百个定义。
装入新的 API
一个团队将一个API作为agent工具新增一个块暴露在它现有的OpenAPI光谱上：
该区块的四个设计选择值得解释。
接触是明确的选择。 没有x-moe-mcp块的终点不是工具。 持续整合(CI)并不警告其缺失，因为对于大多数端点缺失都是正确的状态。 Cache-warmup的路线和迁移触发器不是agent的工具，没有任何东西可以促使一个团队把它们变成一个工具。 使用内外旗帜，一个团队可以将操作暴露给内部的agents，公共的MCP服务器，或者两者独立地曝光。
工具描述不是 API 描述。 API描述告诉开发者读取docs时，端点返回什么。 一个工具描述讲述一个模型何时可以到达这个工具以及要通过什么。 MoEngage发现，重新使用API描述逐字导致工具选择不佳。 模型选择了基于实施细节的工具(“退回一个标注清单”)，而不是意图(“按地位或渠道寻找活动”)。 工具 description and param overrips 字段是特别存在的，可以给团队一个写模型-facting文本的位置，而无需更改其开发者-facing docs.
CI管线也处理所有事务
本文由 AI宝库自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
Artificial Intelligence
How MoEngage turned over 400 APIs into agent tools with AgentCore Gateway
This post was co-written with Nikhil Kumar and Shakir Khan from MoEngage.
When engineering teams start building AI agents, the capabilities those agents need usually already exist as internal APIs. Campaign creation, segment queries, delivery stats. The challenge isn’t building new functionality. The challenge is making hundreds of private APIs safely reachable by agents without exposing them to the public internet, without giving models control over identity, and without flooding context windows with hundreds of tool definitions.
MoEngage, the agentic customer engagement platform that more than 1,350 consumer brands use to deliver personalized experiences across push, email, in-app, SMS, WhatsApp, and RCS, faced exactly this problem. Behind the product sit roughly 400 internal REST APIs, built by 25 engineering teams, running in private virtual private clouds (VPCs) across seven AWS Regions. MoEngage isolates these APIs regionally to meet data residency commitments and doesn’t expose them to the public internet. The capability the agents needed was already running in production. Making it reachable, safely, was the hard part.
In this post, we walk through how MoEngage used AgentCore Gateway, a capability of Amazon Bedrock AgentCore, to turn those private APIs into permission-scoped agent tools. The approach saved MoEngage an estimated six months of platform engineering effort, and onboarding a new API now takes hours instead of days. No product team wrote Model Context Protocol (MCP) server code, no networking was provisioned per integration, and no public endpoint exists anywhere in the path.
Why 20 MCP servers was the wrong answer
The Model Context Protocol (MCP) gives agents a standard way to discover and call tools. The straightforward path to adopting it is for each team to expose its own MCP server. MoEngage costed that out and rejected it.
Over 20 MCP servers means over 20 deployments to monitor, patch, and keep protocol-compatible as MCP evolves. Cross-domain agents, the useful ones that read a campaign, check its segment, and inspect delivery stats, would need to connect to several servers and reconcile them. And every team would need MCP expertise unrelated to its actual product work.
So MoEngage established the principle that shaped everything that followed: Individual engineering teams do not implement MCP. Teams build REST APIs and declare which operations should be tools. The AI Platform team owns the MCP layer end to end. A team’s responsibility ends at a well-described OpenAPI spec.
That principle immediately created three requirements: a central tool surface that agents connect to once rather than per-service, per-agent authorization enforced server-side rather than by convention, and private connectivity that does not need to be rebuilt for every new API.
Building all of this from scratch was an option. A custom central MCP server would solve the 20-servers problem but leave MoEngage building a tool-generation pipeline, a policy file format, a tool-alias registry for renames, and circuit breakers. All custom code, all owned by one team, all of it undifferentiated work that does not make MoEngage’s agents smarter or its customers’ campaigns better.
Four constraints that shaped the architecture
Before evaluating any solution, MoEngage defined four constraints. All four had to be met simultaneously. A solution that addressed two but broke the third and fourth was not viable.
Nothing gets a public endpoint. MoEngage’s internal APIs are VPC-private by policy. Any solution that required exposing them, even behind additional authentication, was a non-starter. The conventional workaround is per-integration networking: a NAT gateway here, a reverse proxy there, a VPN tunnel for the third one. Multiply that by seven Regions and the operational surface grows faster than the set of agents does. Every new API would mean another networking change request, another set of security reviews, another piece of infrastructure to maintain.
Identity can’t be an agent’s decision. Every internal API call carries tenant, user, role, and database context. If that context is a large language model (LLM)-visible tool parameter, a model can get it wrong or be talked into changing it. MoEngage needed identity to be structurally out of the model’s reach, injected by the calling service and not surfaced as something the model can set or override.
A 400-tool catalog doesn’t fit in a context window. At roughly 50 tokens of JSON schema per tool, a full tools/list across the estate is over 20,000 tokens transmitted on every connection. That token budget is spent before the agent does anything useful, and it crowds out the context the agent actually needs to reason about the task. Client-side filtering (tool_filter in ADK or the MCP SDK) doesn’t fix this. The full catalog has already crossed the wire, and filtering by client convention isn’t an authorization boundary. An agent that is not supposed to see write operations shouldn’t receive them in the first place.
That last constraint is the one that avoided the obvious alternatives. A custom central MCP server solves the 20-servers problem but still leaves MoEngage building a tool-generation pipeline, a policy file format, a tool-alias registry for renames, and circuit breakers. All custom code, all owned by one team, none of it making MoEngage’s product better.
How AgentCore Gateway maps to those constraints
Amazon Bedrock AgentCore Gateway is a fully managed MCP server. You register OpenAPI specs as targets and the gateway generates MCP tools from them, then routes calls to the backing services. Four properties mapped directly onto MoEngage’s constraints.
OpenAPI in, MCP tools out. There’s no MCP server to build or operate, and no separate artifact to keep in sync with the API. The spec teams already maintain is the tool definition. Each operation becomes a tool named Target___operationId, for example CampaignsAPI___searchCampaigns. When the spec changes, the tool changes. When a team adds an endpoint, the tool appears. When a team removes one, the tool disappears. No deployment, no protocol expertise, no coordination with the AI Platform team.
Cedar policies, evaluated before the catalog is serialized. The AgentCore policy engine uses partial evaluation to filter tools/list per principal. Each agent authenticates as its own IAM role, and its Cedar policy determines which tools it can see and call. This is what makes 400 tools tractable. It isn’t client-side filtering after the fact, but server-side scoping before the response is built.
A campaign QA bot, for example, gets read access to campaign and segment tools but can’t call a write operation:
The bot doesn’t see write tools in its tools/list response. There’s nothing to filter on the client side because the tools weren’t sent.
Managed egress over Amazon VPC Lattice. The gateway reaches MoEngage’s internal services through AgentCore managed egress rather than through networking MoEngage builds and operates. Inbound, the gateway is reachable only through a VPC interface endpoint with private DNS. There’s no public path to it. Onboarding a new API adds a target, not a network topology change. This is the property that broke the multiply by seven Regions problem. The networking exists once and every API uses it.
Semantic search as a gateway capability. With the x_amz_bedrock_agentcore_search capability, an agent can find tools by describing the task instead of naming the tool. It removed the need for a custom discovery layer. It also removed rename fragility as a side effect: if get_segment_user_count becomes get_segment_size, an agent searching for segment user count still finds it, because matching happens on description rather than identifier.
The architecture in practice
The request flow from agent to internal API is short, and every layer has a specific job. Agent services connect through a VPC interface endpoint to AgentCore Gateway, which evaluates Cedar policies and routes tool calls through managed egress over Amazon VPC Lattice to internal APIs.
The following diagram shows how the components connect.
An agent service running on Amazon Elastic Compute Cloud (Amazon EC2) or in a container calls the MCP client. The client can be the official MCP SDK, LangChain, Google ADK, or MoEngage’s own agent runner. The client signs the request with SigV4 using the AWS Identity and Access Management (IAM) role the service already has. The request travels over HTTPS to a VPC interface endpoint with private DNS. There’s no public hop. AgentCore Gateway receives the request and evaluates Cedar policies to determine what this principal can see or call. It then routes tool invocations through managed egress over Amazon VPC Lattice to the internal API.
MoEngage made two authentication decisions worth calling out.
First, they chose SigV4 over JWT for the internal gateway. Agents here are services that already have IAM roles. With SigV4, they can sign with credentials they already have. Nothing new to issue, rotate, or store. MoEngage’s separate public MCP server, which serves human-authenticated sessions from Claude and other clients, uses OIDC JWTs on AgentCore runtime. That is a different surface with different requirements.
Second, identity travels as headers, not as tool arguments. Tenant, user, role, and database context are converted by the client library from a small Identity object into X-MOE-* headers. The model doesn’t see them and can’t set them. One detail matters for anyone building something similar: Because SigV4 signing occupies the Authorization header, caller-forwarded bearer tokens must move elsewhere. MoEngage propagates it as a dedicated MoEngage-prefixed header. Header propagation is also capped, so the set of headers is deliberate rather than accumulated.
Discovery and execution have different identity requirements. Listing and searching tools carries no tenant identity. Only tools/call does. That separation keeps discovery cheap and makes the audit trail unambiguous. Every identity-bearing request is an actual data access.
Even with Cedar scoping an agent to a subset of the catalog, the subset can be large. MoEngage’s client library exposes a single meta-tool, search_tools, to the model. The model describes what it needs, the gateway’s semantic search returns candidates, and only those candidates become callable for the rest of the turn. The full catalog doesn’t enter context. The agent’s context contains one tool definition at the start and a handful of relevant ones after a search, instead of several hundred definitions it will never use.
Onboarding a new API
A team exposing an API as an agent tool adds a block to its existing OpenAPI spec:
Four design choices in that block are worth explaining.
Exposure is explicit opt-in. An endpoint with no x-moe-mcp block is not a tool. Continuous integration (CI) does not warn about its absence, because for most endpoints absence is the correct state. Cache-warmup routes and migration triggers are not agent tools, and nothing should nudge a team toward making them one. With the internal and external flags, a team can expose an operation to internal agents, to the public MCP server, or to both, independently.
Tool descriptions aren’t API descriptions. An API description tells a developer reading docs what an endpoint returns. A tool description tells a model when to reach for this tool and what to pass. MoEngage found that reusing API descriptions verbatim led to poor tool selection. Models picked tools based on implementation detail (“Returns a paginated list”) rather than intent (“Find campaigns by status or channel”). The tool_description and param_overrides fields exist specifically to give teams a place to write model-facing text without changing their developer-facing docs.
The CI pipeline handles everything from spec to running too
Auto-fetched and translated by AI Gem Box. All rights belong to the original author.