A medida que las empresas implementan agentes de IA en equipos, proveedores e infraestructura, la gestión de la comunicación entre agentes se convierte en una carga operativa cada vez mayor. Sin una capa centralizada, cada nueva integración de agentes agrega conexiones punto a punto, credenciales separadas y lógica de enrutamiento personalizada. Los equipos pasan ciclos de ingeniería conectando la conectividad en lugar de desarrollar capacidades de los agentes. El control de acceso se fragmenta, sin un lugar único para imponer qué clientes pueden comunicarse con qué agentes. El resultado es un tiempo de comercialización más lento para los flujos de trabajo de nuevos agentes, un mayor riesgo de seguridad debido a políticas de autenticación inconsistentes y una sobrecarga operativa que escala cuadráticamente con cada nuevo agente agregado a la red.
El patrón de puerta de enlace soluciona esto colocando un único punto de entrada frente a sus agentes, independientemente de si se ejecutan en Amazon Elastic Container Service (Amazon ECS), AWS Lambda, Amazon Bedrock AgentCore Runtime, una nube que no sea de AWS o un entorno híbrido. Maneja el enrutamiento y aplica permisos detallados de manera centralizada, sin vincular a los equipos a un tiempo de ejecución, marco o capa de orquestación en particular. Este patrón se basa en el protocolo Agente a Agente (A2A), que estandariza la forma en que los agentes se comunican entre sí. Sin un orquestador central, una implementación de 20 agentes requiere hasta 190 conexiones punto a punto.
En esta publicación, aprenderá cómo crear una puerta de enlace A2A sin servidor en AWS que aloje varios agentes detrás de un único dominio mediante enrutamiento basado en rutas (/agents/{agentId}). Los clientes A2A estándar funcionan sin modificaciones. La solución tiene tres capas:
Capa de gestión: Registro de agentes centralizado con descubrimiento y búsqueda semántica. Capa de control: control de acceso detallado utilizando ámbitos JSON Web Token (JWT) y un autorizador Lambda. Capa de ejecución: enrutamiento de dominio único con autenticación de backend OAuth y soporte de transmisión de eventos enviados por el servidor (SSE).
Continúe e implementará una puerta de enlace proporcionada por Terraform a la que los agentes adherentes a A2A pueden conectarse.
Arquitectura
El siguiente diagrama muestra los componentes de la puerta de enlace y cómo fluyen las solicitudes a través del sistema.
Amazon API Gateway (REST API) sirve como punto de entrada único. La arquitectura utiliza una API REST porque las API REST admiten la transmisión de respuestas. Se requiere transmisión para respuestas de agentes en tiempo real basadas en SSE. El autorizador de Lambda inspecciona los alcances de JWT y genera políticas de AWS Identity and Access Management (IAM) que permiten el acceso a rutas de agentes específicas (/agents/agent-a/*) mientras deniegan otras.
Las funciones Lambda implementan la lógica de la puerta de enlace:
Autorizador: valida los JWT y genera políticas de IAM basadas en asignaciones de alcance a agente. Registro: enumera los agentes a los que la persona que llama puede acceder, con las URL reescritas para que apunten a la puerta de enlace. Búsqueda: descubrimiento de agentes semánticos mediante Amazon Titan Text Embeddings en Amazon Bedrock. Proxy: enruta solicitudes a agentes backend con autenticación OAuth, admite transmisión SSE a través de Lambda Web Adaptor. Administrador: Registro de agentes y gestión del ciclo de vida.
Amazon DynamoDB almacena tres tablas. El Registro de agentes asigna ID de agentes a URL de backend, configuraciones de autenticación y tarjetas de agente almacenadas en caché. La tabla Permisos asigna alcances JWT a agentes permitidos. Una tabla RateLimitCounters cuenta las solicitudes por minuto.
Amazon Cognito maneja la autenticación mediante el flujo de credenciales del cliente OAuth 2.0. Los ámbitos del token determinan a qué agentes puede acceder la persona que llama. Cuando un cliente se autentica, recibe un JWT que contiene ámbitos como facturación: lectura o soporte: escritura. El autorizador busca estos ámbitos en la tabla Permisos para determinar a qué agentes puede llegar el cliente.
AWS Secrets Manager almacena las credenciales de backend. Cuando Proxy Lambda necesita autenticarse con un agente backend, recupera el secreto del cliente OAuth por nombre de recurso de Amazon (ARN). Los secretos no se almacenan en DynamoDB.
Para la búsqueda semántica, las descripciones de los agentes se incrustan mediante Amazon Titan Text Embeddings y se almacenan en Amazon S3 Vectors. Esto permite a los clientes descubrir agentes mediante consultas en lenguaje natural en lugar de coincidencias exactas de nombres.
Diseño de puerta de enlace
Los puntos finales nativos A2A siguen la especificación del protocolo A2A y se dirigen a los agentes backend. La puerta de enlace admite ambos enlaces de protocolo definidos en la especificación. JSON-RPC utiliza un único punto final por agente con el método en el cuerpo de la solicitud:
GET /agents/{agentId}/.well-known/agent-card.json: recupera las capacidades del agente. POST /agents/{agentId} con {"method": "SendMessage", …} (para respuesta almacenada en el buffer). POST /agents/{agentId} con {"method": "SendStreamingMessage", …} (para transmisión SSE).
El enlace HTTP+JSON/REST también es compatible con clientes que prefieren URL RESTful.
Estos puntos finales están totalmente alineados con el protocolo A2A. Los clientes apuntan a la URL de la puerta de enlace en lugar de a las URL de backend individuales. Sin embargo, los puntos finales nativos A2A por sí solos no resuelven el problema de gestión. Los clientes todavía necesitan una forma de descubrir qué agentes existen, buscar agentes por capacidad y gestionar el ciclo de vida de los agentes.
Los puntos finales de puerta de enlace proporcionan esta capa:
GET /agents: enumera los agentes a los que puede acceder la persona que llama. POST /search – Búsqueda semántica de agentes. POST /admin/agents/register: registre un nuevo agente backend. POST /admin/agents/{agentId}/sync: actualiza la tarjeta del agente en caché. POST /admin/agents/{agentId}/status: activa o desactiva un agente.
Cada solicitud sigue el mismo camino. El cliente envía una solicitud con un JWT en el encabezado de Autorización. API Gateway invoca al autorizador Lambda, que valida el JWT y busca los alcances de la persona que llama en la tabla Permisos. El autorizador devuelve una política de IAM que permite o deniega el acceso a agentes específicos. Si se permite, la solicitud se enruta al Lambda apropiado: Proxy para tráfico A2A, Registro para descubrimiento de agentes, Búsqueda para consultas semánticas o Administrador para operaciones de administración. Para solicitudes A2A, Proxy Lambda se autentica con el backend mediante OAuth y reenvía la solicitud. Las solicitudes no autorizadas se rechazan en API Gateway y no llegan al backend Lambdas.
El modelo de tres capas
A medida que crecen las implementaciones de agentes, los equipos necesitan visibilidad de lo que está disponible. La capa de administración proporciona un registro centralizado donde los agentes se catalogan con sus capacidades, URL de backend y estado. Cuando se implementa un nuevo agente, se registra una vez en la puerta de enlace y los clientes autorizados pueden descubrirlo inmediatamente. El registro también almacena en caché las tarjetas de los agentes, por lo que los clientes no necesitan obtener capacidades de cada backend individualmente. Las URL de las tarjetas almacenadas en caché se reescriben para que apunten a través de la puerta de enlace, de modo que los clientes interactúen con el dominio de la puerta de enlace única en lugar de descubrir las URL de backend. Para implementaciones más grandes, la búsqueda semántica permite a los clientes encontrar agentes describiendo lo que necesitan en lugar de saber los nombres exactos.
En una empresa, no todos los clientes deberían acceder a todos los agentes. La capa de control aplica permisos detallados basados en alcances JWT. Cuando un cliente se autentica, su token contiene ámbitos como facturación: lectura o soporte: administrador. El autorizador de Lambda asigna estos ámbitos a agentes específicos en la tabla Permisos y genera políticas de IAM que permiten o deniegan el acceso en el nivel de API Gateway. Las solicitudes no autorizadas no llegan al backend de Lambdas. Además, la limitación de velocidad se aplica por usuario y por agente en el nivel de proxy. El proxy rastrea el recuento de solicitudes utilizando contadores atómicos de DynamoDB con vencimiento automático del tiempo de vida (TTL), devolviendo un 429 con un encabezado Retry-After cuando un cliente excede su cuota. Los permisos y los límites de tarifas se administran de forma centralizada: para otorgar o revocar el acceso o ajustar las cuotas, se actualiza la tabla de Permisos en lugar de modificar cada agente.
La capa de ejecución maneja el enrutamiento real de las solicitudes a los agentes de backend. Los clientes se conectan a un único dominio y la puerta de enlace se dirige al backend apropiado según la ruta. Esto simplifica la configuración de la red: en lugar de abrir la conectividad a cada agente, los clientes sólo necesitan llegar a la puerta de enlace. Proxy Lambda maneja la autenticación OAuth con backends, por lo que los clientes no administran las credenciales de backend. Recupera secretos de Secrets Manager, recupera tokens de acceso y reenvía solicitudes de forma transparente. Para casos de uso en tiempo real, el proxy admite la transmisión SSE, lo que permite a los agentes enviar respuestas incrementales a los clientes a medida que se generan.
Implementar la solución
La puerta de enlace se implementa completamente con Terraform. Primero, verifique que tenga lo siguiente.
Requisitos previos
El código de la puerta de enlace está disponible en el repositorio de GitHub de aws-samples.
Clona el repositorio y configura tus variables:
Edite terraform/terraform.tfvars con su región y preferencias de nombre:
aws_region = "us-east-1" nombre_proyecto = "a2a-gateway" entorno = "poc"
Compile el paquete Lambda e impleméntelo:
Terraform crea los recursos de una sola vez: tablas de DynamoDB, grupo de usuarios de Cognito, repositorio de Amazon Elastic Container Registry (Amazon ECR), funciones Lambda, API Gateway y roles de IAM. Terraform crea e impulsa el contenedor proxy Lambda como parte de la implementación.
Prueba la solución
Obtenga las credenciales de su puerta de enlace de las salidas de Terraform:
Obtenga un JWT:
Este repositorio incluye agentes de ejemplo A2A implementables en el directorio ejemplos/: un agente meteorológico y un agente de calculadora. Se pueden implementar utilizando su propia configuración de Terraform. Opcionalmente, impleméntelos con cd ejemplos/terraform && terraform apply, luego capture sus resultados:
Luego registre el agente con la puerta de enlace (usando $GATEWAY_URL y $JWT capturados anteriormente):
La puerta de enlace aplica un control de acceso detallado. A cada ámbito de OAuth se le debe otorgar acceso explícito a agentes específicos en la tabla de permisos de DynamoDB.
Actualice los permisos para permitir que su alcance acceda al agente registrado:
Descubra agentes registrados y envíe un mensaje a través del portal:
Limpiar
Para limpiar la solución, ejecute terraform destroy desde la carpeta /terraform. Terraform le pedirá permiso para eliminar los recursos.
Consideraciones de seguridad
Esta puerta de enlace es una implementación de referencia. Antes de pasar a producción, revise las siguientes áreas que requieren refuerzo según la postura de seguridad de su organización.
Modelo de confianza de backend
La puerta de enlace opera según un modelo de confianza después de la autenticación. Después de registrar un agente backend y validar las credenciales de OAuth, la puerta de enlace envía las respuestas directamente a los clientes sin inspección del contenido. Los mensajes A2A se envían mediante proxy sin modificaciones, por lo que los agentes backend son responsables de implementar sus propias defensas de inyección rápida y validación de entradas. En producción, implemente un flujo de trabajo de aprobación para el registro de agentes en el que los administradores revisen los agentes backend antes de que sean accesibles. Integre esto con su proceso de integración continua y entrega continua (CI/CD) para que los agentes sean examinados como parte del proceso de implementación, no después.
Limitación de tarifas y cuotas
La puerta de enlace aplica límites de tarifas por usuario y por agente en la capa de proxy. Cada solicitud incrementa un contador atómico en DynamoDB codificado por usuario, agente y ventana de minutos. Cuando un cliente excede su cuota, el proxy devuelve un 429 con un encabezado de reintento posterior y la solicitud no llega al backend. Los contadores caducan automáticamente a través de DynamoDB TTL, por lo que no hay gastos generales de limpieza. Los límites se configuran junto con los controles de acceso en la tabla Permisos, ya sea como solicitudes predeterminadas por minuto o como anulaciones por agente, lo que brinda a los administradores un control granular sobre el consumo.
Implementación privada
Para entornos que requieren infraestructura privada, la puerta de enlace admite un modo de implementación opcional de Amazon Virtual Private Cloud (Amazon VPC). Cuando habilita este modo, las funciones Lambda se ejecutan dentro de subredes privadas. API Gateway cambia a un punto final privado al que solo se puede acceder dentro de la VPC. Los puntos de enlace de VPC manejan el tráfico a los servicios de AWS sin atravesar Internet.
La puerta de enlace admite tanto la creación de una nueva VPC como la incorporación de la suya propia. Para implementar en una VPC existente, proporcione su ID de VPC, ID de subred, ID de tabla de rutas e ID de grupo de seguridad en terraform.tfvars:
enable_private_deployment = true existente_vpc_id = "vpc-0123456789abcdef0" existente_subnet_ids = ["subred-aaa", "subred-bbb", "subred-ccc"] existente_route_table_ids = ["rtb-aaa"] existente_lambda_security_group_id = "sg-aaa" existente_vpc_endpoint_security_group_id = "sg-bbb"
Tenga en cuenta que este modo hace que la infraestructura de la puerta de enlace sea privada, pero su VPC aún necesita conectividad a Internet saliente para el intercambio de tokens OAuth con Cognito u otros proveedores de identidad externos. Esto generalmente se maneja a través de una puerta de enlace de traducción de direcciones de red (NAT) o un enrutamiento de AWS Transit Gateway a una VPC de salida compartida. El tráfico de servicios de AWS (DynamoDB, Amazon S3, Secrets Manager, S3 Vectors) permanece privado a través de los puntos finales de la VPC. Sólo el intercambio de tokens de OAuth requiere conectividad saliente. Si necesita una búsqueda semántica con Amazon Bedrock, configure enable_bedrock_endpoint = true para agregar también un punto final de VPC de Amazon Bedrock Runtime.
Para los agentes que se ejecutan en las instalaciones o en otras nubes, se puede acceder a la puerta de enlace privada a través de AWS Direct Connect o AWS Interconnect (versión preliminar). Esto permite que la puerta de enlace gobierne a los agentes en todos los entornos sin exponer el tráfico a la Internet pública.
Autenticación del servidor A2A
La puerta de enlace se autentica con agentes backend mediante el flujo de credenciales de cliente OAuth 2.0. Cada agente registrado incluye su URL de token y sus credenciales, y Proxy Lambda maneja la adquisición de tokens de forma transparente. Esto significa que los agentes backend deben implementarse con la autenticación OAuth habilitada independientemente de dónde se ejecuten.
Cuando utilice Amazon Bedrock AgentCore Runtime específicamente, un detalle clave: configure customJWTAuthorizer con AllowClients configurado en su ID de cliente de Cognito, no AllowAudience. Los tokens de credenciales de cliente de Cognito incluyen un reclamo client_id pero no incluyen el reclamo estándar JWT aud. El parámetro AllowAudience valida la reclamación aud y devolverá 401 No autorizado para tokens de máquina a máquina (M2M) de Cognito. El uso de AllowClients valida contra client_id, que proporcionan los tokens de Cognito. Consulte el contrato del protocolo AgentCore A2A para conocer el conjunto completo de opciones de autenticación.
Conclusión
A medida que las organizaciones pasan de un puñado de agentes a docenas o cientos, los desafíos operativos pasan de crear agentes individuales a gestionar las conexiones entre ellos. Las integraciones punto a punto no escalan. Los equipos no deberían necesitar saber dónde vive cada agente, administrar credenciales separadas para cada uno o crear su propio control de acceso y descubrimiento desde cero.
Esta puerta de enlace le brinda un lugar único para registrar agentes, controlar quién puede acceder a ellos y enrutar el tráfico. Debido a que opera a nivel de protocolo, gobierna los agentes en todos los entornos: servicios de AWS, nubes de terceros, infraestructura local o una combinación. Los backends que hablan A2A funcionan. Registre el agente con su URL y credenciales OAuth, y la puerta de enlace se encarga del resto. El tiempo de ejecución subyacente no importa. Los nuevos agentes se vuelven reconocibles en el momento en que se registran, y los controles de acceso y los límites de velocidad se administran de forma centralizada en lugar de estar dispersos entre servidores.
El protocolo A2A estandariza la forma en que los agentes se comunican entre sí. Una puerta de enlace estandariza cómo su organización gestiona esa comunicación. El código fuente completo está disponible en el repositorio de aws-samples.
Sobre los autores
Reilly Mantón
Reilly es arquitecto de soluciones en AWS Telecoms y se especializa en IA y aprendizaje automático. Crea soluciones innovadoras de IA para clientes, con especial atención en protocolos de interoperabilidad, gobernanza y redes de agentes a gran escala. Reilly trabaja en estrecha colaboración con los clientes para poner en producción las capacidades emergentes de IA. Le apasionan los estándares abiertos y la creación de sistemas que funcionen a través de las fronteras organizacionales.
Scott Wainer
Scott es un arquitecto principal de soluciones centrado en identificar y desarrollar métodos y patrones de IA generativa que aceleren las operaciones comerciales del cliente. Tiene más de 35 años de experiencia en el diseño, construcción y operación de sistemas de información complejos. Tiene amplia experiencia en redes, telecomunicaciones, servicios gestionados y sistemas de soporte de gestión.
Wesley Petry
Wesley es arquitecto de soluciones en AWS Telecoms con sede en el área de Nueva York. Se especializa en la construcción y el diseño de IA generativa y sistemas agentes, con experiencia en informática de vanguardia y sin servidor. Wesley trabaja en estrecha colaboración con los clientes para diseñar soluciones basadas en IA y le apasiona convertir la tecnología emergente en arquitecturas listas para producción. Fuera de la interacción con los clientes, le gusta hablar en eventos de la industria y contribuir con implementaciones de referencia que ayudan a otros constructores a comenzar.