How MoEngage turned over 400 APIs into agent tools with AgentCore Gateway

MoEngage如何利用AgentCore网关将400个API转化为智能体工具 | 人工智能

MoEngage如何利用AgentCore网关将400个API转化为智能体工具

本文由MoEngage的Nikhil Kumar和Shakir Khan联合撰写。

当工程团队开始构建AI智能体时，这些智能体所需的功能通常已经以内部API的形式存在。活动创建、用户分群查询、投递数据统计等功能都属于此类。真正的挑战不是开发新功能，而是如何在不暴露API到公网、不赋予模型身份控制权、不使上下文窗口被数百个工具定义淹没的前提下，安全地让智能体访问这些私有API。

作为拥有1350多家消费品牌客户、通过推送、邮件、应用内消息、短信、WhatsApp和RCS等渠道提供个性化体验的智能体客户互动平台，MoEngage正面临这一难题。其产品背后约有400个内部REST API，由25个工程团队构建，部署在横跨7个AWS区域的私有虚拟私有云（VPC）中。为满足数据驻留要求，MoEngage将这些API按区域隔离且不对外开放。所需能力已在生产环境中运行，但如何安全地实现访问才是真正的难点。

在本文中，我们将介绍MoEngage如何通过Amazon Bedrock AgentCore的AgentCore网关功能，将这些私有API转化为具有权限范围的智能体工具。该方案为MoEngage节省了约6个月的平台工程开发时间，新API的接入时间从数天缩短至数小时。无需任何产品团队编写模型上下文协议（MCP）服务端代码，无需为每个集成单独配置网络，整个路径中也不存在任何公网接口。

为何部署20个MCP服务器是错误的选择

模型上下文协议（MCP）为智能体提供了标准的工具发现和调用方式。最直接的采用路径是让每个团队部署自己的MCP服务器，但MoEngage经过成本评估后否决了这一方案。

部署超过20个MCP服务器意味着需要维护20多个部署实例，随着MCP协议演进需要持续监控、补丁更新和协议兼容性维护。跨域智能体（如能读取活动、检查用户分群、查看投递数据的智能体）需要连接多个服务器并进行数据对齐。每个团队都需要投入与产品开发无关的MCP专业知识。

因此MoEngage确立了后续所有工作的核心原则：工程团队不直接实现MCP。各团队只需构建REST API并声明哪些操作应作为工具。AI平台团队负责MCP层的端到端实现。每个团队的责任仅限于提供描述良好的OpenAPI规范。

这一原则立即催生了三个需求：智能体只需连接一次的中心化工具接口、通过服务端强制实施的按智能体授权机制、无需为每个新API重复构建的私有连接方案。

从零开始构建所有功能也是一个选项。自建中心MCP服务器虽能解决20服务器问题，但需要MoEngage自行构建工具生成流水线、策略文件格式、工具别名注册表（用于重命名）和熔断器。所有自研代码均由单一团队维护，这些工作本质上属于无法差异化且无法提升智能体能力或客户活动效果的重复劳动。

在评估任何解决方案之前，MoEngage 设定了四个约束条件。这四个条件必须同时满足。即使某个方案解决了其中两个问题，但破坏了第三和第四个条件，也无法被采纳。

绝不允许公开端点。根据政策，MoEngage 的内部 API 默认使用 VPC 私有网络。任何需要暴露这些 API 的方案，即使通过额外的认证机制，也无法被接受。常规的变通方法是为每个集成设置独立的网络：这里使用 NAT 网关，那里部署反向代理，第三个使用 VPN 隧道。当扩展到七个区域时，运维复杂度的增长速度远超代理数量的增长。每新增一个 API 都意味着需要提交新的网络变更请求、进行额外的安全审查，并维护更多基础设施。

身份信息不能由代理自行决定。每个内部 API 调用都携带租户、用户、角色和数据库上下文信息。如果这些上下文信息以大语言模型（LLM）可见的参数形式暴露，模型可能会误判或被诱导修改这些信息。MoEngage 需要确保身份信息在结构上完全超出模型的访问范围，由调用服务注入，且不能被模型设置或覆盖。

400 个工具的目录无法适应上下文窗口。每个工具大约需要 50 个 JSON Schema 令牌，完整工具列表的传输量在每次连接时会超过 20,000 个令牌。在代理执行任何实际操作之前，这些令牌预算就已经耗尽，导致代理真正需要的上下文信息被挤占。客户端过滤（ADK 或 MCP SDK 中的 tool_filter）无法解决这个问题。完整的工具目录已经传输完成，而基于客户端约定的过滤并不能构成授权边界。一个不应该看到写操作的代理，从一开始就不应该接收到这些操作。

最后一个约束条件排除了显而易见的替代方案。自定义的中央 MCP 服务器可以解决 20 个服务器的问题，但 MoEngage 仍需构建工具生成流水线、制定策略文件格式、维护工具别名注册表（用于重命名）以及实现熔断器。所有这些都需要自定义代码，由单一团队维护，且无法提升 MoEngage 产品的价值。

AgentCore Gateway 如何对应这些约束

Amazon Bedrock AgentCore Gateway 是一个完全托管的 MCP 服务器。您只需注册 OpenAPI 规范作为目标，网关会自动生成 MCP 工具并将其路由到后端服务。这四个特性直接对应了 MoEngage 的四个约束条件。

OpenAPI 输入，MCP 工具输出。无需构建或运营 MCP 服务器，也无需维护与 API 同步的独立工件。团队现有的 OpenAPI 规范本身就是工具定义。每个操作都会生成一个以 Target___operationId 命名的工具，例如 CampaignsAPI___searchCampaigns。当规范变更时，工具会自动更新。当团队新增端点时，工具会自动出现；当团队删除端点时，工具会自动消失。无需部署，无需协议专业知识，无需与 AI 平台团队协调。

Cedar 策略在目录序列化前进行评估。AgentCore 策略引擎使用部分求值技术，根据主体身份过滤工具列表。每个代理以自身的 IAM 角色进行身份验证，其 Cedar 策略决定了它能访问和调用哪些工具。这正是让 400 个工具变得可管理的关键。这不是事后通过客户端进行过滤，而是在响应构建前通过服务器端进行范围限定。

例如，一个活动 QA 机器人只能获得活动和分段工具的只读访问权限，但无法调用写操作：

permit(
    principal == Agent::"campaign-qa-bot-v1",
    action == Action::"tools/call",
    resource in ToolGroup::"campaigns-read"
);

forbid(
    principal == Agent::"campaign-qa-bot-v1",
    action == Action::"tools/call",
    resource in ToolGroup::"write-actions"
);

该机器人在其工具列表响应中看不到写入工具。由于工具未被发送，客户端侧无需进行任何过滤。

通过 Amazon VPC Lattice 的托管出站流量。网关通过 AgentCore 管理的出站连接访问 MoEngage 的内部服务，而非通过 MoEngage 自建和运营的网络。入站方向，网关仅可通过带有私有 DNS 的 VPC 接口端点访问。没有公共访问路径。新增 API 仅需添加目标，而不会改变网络拓扑结构。这一特性解决了七区域重复问题。网络基础设施只需构建一次，所有 API 均可复用。

语义搜索作为网关功能。通过 x_amz_bedrock_agentcore_search 能力，代理可通过描述任务而非命名工具来查找工具。这消除了对自定义发现层的需求。同时作为副作用，解决了重命名脆弱性问题：当 get_segment_user_count 变为 get_segment_size 时，代理搜索“segment user count”仍能找到对应工具，因为匹配基于描述而非标识符。

实际中的架构

从代理到内部 API 的请求流程简短，每一层都有明确职责。代理服务通过 VPC 接口端点连接到 AgentCore 网关，网关评估 Cedar 策略，并通过 Amazon VPC Lattice 的托管出站连接将工具调用路由到内部 API。

下图展示了组件的连接方式。

图 1：MoEngage AgentCore 网关架构

运行在 Amazon 弹性计算云（Amazon EC2）或容器中的代理服务会调用 MCP 客户端。客户端可以是官方 MCP SDK、LangChain、Google ADK 或 MoEngage 自研的代理运行器。客户端使用服务已有的 AWS 身份和访问管理（IAM）角色，通过 SigV4 对请求进行签名。请求通过 HTTPS 发送到带有私有 DNS 的 VPC 接口端点，没有公共跳转。AgentCore 网关接收请求并评估 Cedar 策略，确定该主体可访问或调用的内容。随后通过 Amazon VPC Lattice 的托管出站连接将工具调用路由到内部 API。

MoEngage 在认证方面做出了两个值得关注的决策。

首先，他们选择使用 SigV4 而非 JWT 作为内部网关的认证方式。此处的代理都是已有 IAM 角色的服务。使用 SigV4 可直接使用已有凭证进行签名，无需新增、轮换或存储任何内容。MoEngage 独立的公共 MCP 服务器（服务于 Claude 等客户端的人工认证会话）在 AgentCore 运行时使用 OIDC JWT，这是另一种具有不同需求的场景。

其次，身份信息通过请求头而非工具参数传递。租户、用户、角色和数据库上下文信息由客户端库从 Identity 对象转换为 X-MOE-* 请求头。模型无法看到这些信息，也无法设置它们。一个关键细节对构建类似系统的人很重要：由于 SigV4 签名占用了 Authorization 请求头，转发的 bearer token 必须转移到其他位置。MoEngage 通过专用的 MoEngage 前缀请求头传递该信息。请求头传播也有限制，因此请求头集合是经过明确设计的，而非不断累积。

发现和执行具有不同的身份要求。列出和搜索工具不需要租户身份，只有工具/调用需要。这种分离使发现过程保持低成本，并使审计轨迹明确无误。每个带有身份的请求都是实际的数据访问。

即使 Cedar 将代理限制在目录的子集，该子集也可能很大。MoEngage 的客户端库向模型暴露了一个单一的元工具 search_tools。模型描述其需求，网关的语义搜索返回候选工具，且只有这些候选工具在后续对话中可被调用。完整目录不会进入上下文。代理的上下文在搜索前仅包含一个工具定义，搜索后包含少量相关工具定义，而不是数百个从不会使用的定义。

新增 API 的接入流程

将 API 作为代理工具暴露的团队需要在其现有的 OpenAPI 规范中添加一个区块：

paths:
  /campaigns:
    get:
      operationId: listCampaigns
      description: |
        返回分页的活动列表，支持按状态、渠道、日期范围和标签筛选。
      x-moe-mcp:
        expose:
          external: false
          internal: true
        tool_description: |
          按状态或渠道查找活动。返回活动 ID、名称、状态和渠道。使用返回的 campaign_id 与 get_campaign 获取详细信息，或使用 send_campaign 启动活动。
        param_overrides:
          status:
            description: |
              按活动状态筛选。使用 'active' 表示运行中的活动，'scheduled' 表示即将开始的活动。省略此参数表示返回所有活动。

该区块中的四个设计选择值得解释。

暴露工具需要显式授权。没有 x-moe-mcp 块的端点不会被视作工具。持续集成（CI）不会因缺少该块发出警告，因为对于大多数端点来说，缺失是正常状态。缓存预热路由和迁移触发器不是代理工具，任何团队都不应被引导将其作为工具处理。通过 internal 和 external 标志，团队可以独立选择将操作暴露给内部代理、公共 MCP 服务器或两者。

工具描述不同于 API 描述。API 描述告诉阅读文档的开发者端点返回什么内容。工具描述则告诉模型何时使用该工具以及传递什么参数。MoEngage 发现直接复用 API 描述会导致工具选择不佳。模型会根据实现细节（"返回分页列表"）而非意图（"按状态或渠道查找活动"）选择工具。tool_description 和 param_overrides 字段专门用于为团队提供编写面向模型的文本的空间，而无需修改面向开发者的文档。

CI 流水线处理从规范到工具运行的全流程。当团队推送规范变更时，流水线会验证 x-moe-mcp 块，向 AgentCore Gateway 注册目标，并应用 Cedar 策略。无需人工操作，无需向 AI 平台团队提交工单。即使团队从未接触过 MCP，也能在流水线运行时间内将操作作为代理工具使用。

客户端库提供两种模式。插件模式将 AgentCore Gateway MCP 服务器封装在 LangChain、Google ADK 或 MCP 兼容框架中作为工具提供者。代理运行模式则为希望使用独立代理而无需采用框架的团队运行完整的代理循环。

MoEngage 当前的运行情况

MoEngage 的 AgentCore 网关部署目前在七个 AWS 区域运行。该网关目前为 10 个内部代理提供约 400 个已注册的 API 操作。没有任何产品团队编写过 MCP 服务器代码，没有任何产品团队为代理集成配置过网络，也没有任何产品团队实现过 Cedar 策略。所有这些工作均由 AI 平台团队负责，新增 API 的接入成本仅需一个规格注解和一次 CI 运行。AgentCore 功能的可用性因区域而异。有关支持的区域，请参阅 Amazon Bedrock AgentCore 文档。

该系统已在生产环境中运行三个月。这些代理覆盖了营销团队成员每天接触的工作流程。一个活动 QA 代理会在发布前验证目标规则和内容。一个交付健康代理会监控各渠道的发送速率和退信模式。一个细分构建器代理会将自然语言受众描述转换为细分查询。每个代理都使用自己的 IAM 角色进行身份验证，仅能看到 Cedar 策略允许的工具，并通过描述任务而非记忆工具名称来发现工具。通过消除构建和运营 20 个独立 MCP 服务器的需求，以及在七个区域为每个 API 配置网络的需要，MoEngage 估计这种方法节省了大约六个月的工程工作量。现在新增 API 的接入只需数小时的规格注解，而非数天的网络配置和安全审查。

以搜索优先的模式改变了 MoEngage 对代理设计的思考方式。新代理从零个硬编码工具引用开始，它们描述意图、接收候选工具，并调用找到的工具。当团队重命名一个操作或发布新操作时，现有代理无需代码更改即可自动识别。

结论

MoEngage 方法背后的关键洞察是将关注点分离，这种分离方式与工程组织的实际运作方式相匹配。产品团队负责 API 并能很好地描述它们。平台团队负责协议层、策略层和连接层。AgentCore 网关通过消除中间的非差异化工作（无需 MCP 服务器代码、无需每个 API 的网络配置、无需客户端过滤伪装成授权），使这种分离变得切实可行。

其结果是一个代理系统，新增工具只需修改规格，限制访问只需更改策略，且无需另一团队参与。

要开始使用 AgentCore 网关，请参阅 Amazon Bedrock AgentCore 文档。要编写 Cedar 策略，请参阅 Cedar 策略语言参考。要了解私有连接模式，请参阅 Amazon VPC Lattice 文档。

如需讨论适用于您组织的类似架构，请联系您的 AWS 账户团队或通过 AWS 联系我们。

作者简介

'"`