O blog da AWS

Construindo um gateway A2A Serverless para descoberta, roteamento e controle de acesso de agentes

Por Reilly Manton, Scott Wainner e Wesley Petry, AWS.

À medida que as empresas implantam agentes de IA em equipes, fornecedores e infraestrutura, gerenciar a comunicação entre agentes torna-se uma carga operacional crescente. Sem uma camada centralizada, cada nova integração de agente adiciona conexões ponto a ponto, credenciais separadas e lógica de roteamento personalizada. As equipes gastam ciclos de engenharia conectando a conectividade em vez de construir capacidades de agentes. O controle de acesso torna-se fragmentado, sem um único lugar para impor quais clientes podem alcançar quais agentes. O resultado é um tempo de lançamento mais lento para novos fluxos de trabalho de agentes, maior risco de segurança devido a políticas de autenticação inconsistentes e sobrecarga operacional que escala quadraticamente com cada novo agente adicionado à rede.

O padrão de gateway aborda isso colocando um único ponto de entrada na frente de seus agentes, independentemente de eles serem executados no Amazon Elastic Container Service (Amazon ECS), AWS Lambda, Amazon Bedrock AgentCore Runtime, uma nuvem não-AWS ou um ambiente híbrido. Ele lida com o roteamento e impõe permissões refinadas centralmente, sem vincular as equipes a um runtime, framework ou camada de orquestração específicos. Este padrão baseia-se no protocolo Agent-to-Agent (A2A), que padroniza como os agentes se comunicam entre si. Sem um orquestrador central, uma implantação de 20 agentes requer até 190 conexões ponto a ponto.

Neste post, você aprenderá como construir um gateway A2A Serverless na AWS que hospeda múltiplos agentes atrás de um único domínio usando roteamento baseado em caminho (/agents/{agentId}). Clientes A2A padrão funcionam sem modificação. A solução tem três camadas:

  1. Camada de gerenciamento: Registro centralizado de agentes com descoberta e busca semântica.
  2. Camada de controle: Controle de acesso refinado usando escopos JSON Web Token (JWT) e um autorizador Lambda.
  3. Camada de execução: Roteamento de domínio único com autenticação OAuth de backend e suporte a streaming Server-Sent Events (SSE).

Acompanhe e você implantará um gateway provisionado por Terraform ao qual agentes compatíveis com A2A podem se conectar.

Arquitetura

O diagrama a seguir mostra os componentes do gateway e como as solicitações fluem pelo sistema.

Diagrama de arquitetura para o gateway A2A Serverless mostrando o fluxo de solicitação de clientes para agentes de backend

O Amazon API Gateway (REST API) serve como o ponto de entrada único. A arquitetura usa uma REST API porque as REST APIs suportam streaming de resposta. O streaming é necessário para respostas de agentes em tempo real baseadas em SSE. O autorizador Lambda inspeciona os escopos JWT e gera políticas AWS Identity and Access Management (IAM) que permitem acesso a caminhos de agentes específicos (/agents/agent-a/*) enquanto nega outros.

Funções Lambda implementam a lógica do gateway:

  1. Authorizer: Valida JWTs e gera políticas IAM com base em mapeamentos de escopo para agente.
  2. Registry: Lista agentes que o chamador pode acessar, com URLs reescritas para apontar para o gateway.
  3. Search: Descoberta semântica de agentes usando Amazon Titan Text Embeddings no Amazon Bedrock.
  4. Proxy: Roteia solicitações para agentes de backend com autenticação OAuth, suporta streaming SSE via Lambda Web Adapter.
  5. Admin: Registro de agentes e gerenciamento de ciclo de vida.

O Amazon DynamoDB armazena três tabelas. O Agent Registry mapeia IDs de agentes para URLs de backend, configurações de autenticação e cartões de agentes em cache. A tabela Permissions mapeia escopos JWT para agentes permitidos. Uma tabela RateLimitCounters conta solicitações por minuto.

O Amazon Cognito lida com autenticação usando o fluxo de credenciais de cliente OAuth 2.0. Os escopos no token determinam quais agentes o chamador pode acessar. Quando um cliente se autentica, ele recebe um JWT contendo escopos como billing:read ou support:write. O autorizador consulta esses escopos na tabela Permissions para determinar quais agentes o cliente pode alcançar.

O AWS Secrets Manager armazena credenciais de backend. Quando o Proxy Lambda precisa autenticar com um agente de backend, ele recupera o segredo do cliente OAuth por Amazon Resource Name (ARN). Os segredos não são armazenados no DynamoDB.

Para busca semântica, as descrições de agentes são incorporadas usando Amazon Titan Text Embeddings e armazenadas no Amazon S3 Vectors. Isso permite que os clientes descubram agentes usando consultas em linguagem natural em vez de correspondências exatas de nomes.

Design do gateway

Os endpoints nativos A2A seguem a especificação do protocolo A2A e roteiam para agentes de backend. O gateway suporta ambas as vinculações de protocolo definidas na especificação. JSON-RPC usa um único endpoint por agente com o método no corpo da solicitação:

  1. GET /agents/{agentId}/.well-known/agent-card.json – Buscar capacidades do agente.
  2. POST /agents/{agentId} com {"method": "SendMessage", ...} (para resposta em buffer).
  3. POST /agents/{agentId} com {"method": "SendStreamingMessage", ...} (para streaming SSE).

A vinculação HTTP+JSON/REST também é suportada para clientes que preferem URLs RESTful.

Esses endpoints estão totalmente alinhados com o protocolo A2A. Os clientes apontam para a URL do gateway em vez de URLs de backend individuais. No entanto, os endpoints nativos A2A sozinhos não resolvem o problema de gerenciamento. Os clientes ainda precisam de uma maneira de descobrir quais agentes existem, pesquisar agentes por capacidade e gerenciar o ciclo de vida do agente.

Endpoints do gateway fornecem esta camada:

  1. GET /agents – Listar agentes que o chamador pode acessar.
  2. POST /search – Busca semântica de agentes.
  3. POST /admin/agents/register – Registrar um novo agente de backend.
  4. POST /admin/agents/{agentId}/sync – Atualizar cartão de agente em cache.
  5. POST /admin/agents/{agentId}/status – Ativar ou desativar um agente.

Cada solicitação segue o mesmo caminho. O cliente envia uma solicitação com um JWT no cabeçalho Authorization. O API Gateway invoca o autorizador Lambda, que valida o JWT e consulta os escopos do chamador na tabela Permissions. O autorizador retorna uma política IAM permitindo ou negando acesso a agentes específicos. Se permitido, a solicitação é roteada para o Lambda apropriado: Proxy para tráfego A2A, Registry para descoberta de agentes, Search para consultas semânticas ou Admin para operações de gerenciamento. Para solicitações A2A, o Proxy Lambda autentica com o backend usando OAuth e encaminha a solicitação. Solicitações não autorizadas são rejeitadas no API Gateway e não alcançam os Lambdas de backend.

O modelo de três camadas

À medida que as implantações de agentes crescem, as equipes precisam de visibilidade sobre o que está disponível. A camada de gerenciamento fornece um registro centralizado onde os agentes são catalogados com suas capacidades, URLs de backend e status. Quando um novo agente é implantado, ele é registrado uma vez no gateway e imediatamente descoberto por clientes autorizados. O registro também armazena em cache os cartões de agentes, para que os clientes não precisem buscar capacidades de cada backend individualmente. Os cartões em cache têm suas URLs reescritas para apontar através do gateway, para que os clientes interajam com o domínio único do gateway em vez de descobrir URLs de backend. Para implantações maiores, a busca semântica permite que os clientes encontrem agentes descrevendo o que precisam em vez de conhecer nomes exatos.

Em uma empresa, nem todo cliente deve acessar todos os agentes. A camada de controle impõe permissões refinadas com base em escopos JWT. Quando um cliente se autentica, seu token contém escopos como billing:read ou support:admin. O autorizador Lambda mapeia esses escopos para agentes específicos na tabela Permissions e gera políticas IAM que permitem ou negam acesso no nível do API Gateway. Solicitações não autorizadas não alcançam os Lambdas de backend. Além disso, a limitação de taxa é imposta por usuário, por agente no nível do proxy. O proxy rastreia contagens de solicitações usando contadores atômicos do DynamoDB com expiração automática de time-to-live (TTL), retornando um 429 com um cabeçalho Retry-After quando um cliente excede sua cota. Permissões e limites de taxa são gerenciados centralmente: para conceder ou revogar acesso ou ajustar cotas, você atualiza a tabela Permissions em vez de modificar cada agente.

A camada de execução lida com o roteamento real de solicitações para agentes de backend. Os clientes se conectam a um único domínio, e o gateway roteia para o backend apropriado com base no caminho. Isso simplifica a configuração de rede: em vez de abrir conectividade para cada agente, os clientes só precisam alcançar o gateway. O Proxy Lambda lida com a autenticação OAuth com backends, para que os clientes não gerenciem credenciais de backend. Ele recupera segredos do Secrets Manager, busca tokens de acesso e encaminha solicitações de forma transparente. Para casos de uso em tempo real, o proxy suporta streaming SSE, permitindo que os agentes enviem respostas incrementais de volta aos clientes conforme são geradas.

Implantar a solução

O gateway é implantado inteiramente com Terraform. Primeiro, verifique se você tem o seguinte.

Pré-requisitos

O código do gateway está disponível no repositório GitHub aws-samples.

Clone o repositório e configure suas variáveis:

cp terraform/terraform.tfvars.example terraform/terraform.tfvars

Edite terraform/terraform.tfvars com sua região e preferências de nomenclatura:

aws_region = "us-east-1"
project_name = "a2a-gateway"
environment = "poc"

Construa o pacote Lambda e implante:

./scripts/build_lambda_package.sh
cd terraform
terraform init
terraform plan
terraform apply

O Terraform cria os recursos de uma só vez: tabelas DynamoDB, pool de usuários Cognito, repositório Amazon Elastic Container Registry (Amazon ECR), funções Lambda, API Gateway e funções IAM. O Terraform constrói e envia o contêiner Lambda do proxy como parte da implantação.

Testar a solução

Obtenha suas credenciais do gateway das saídas do Terraform:

GATEWAY_URL=$(terraform output -raw api_gateway_url)
TOKEN_ENDPOINT=$(terraform output -raw cognito_token_endpoint)
CLIENT_ID=$(terraform output -raw cognito_client_id)
CLIENT_SECRET=$(terraform output -raw cognito_client_secret)
PERMISSIONS_TABLE=$(terraform output -raw permissions_table_name)

Obtenha um JWT:

TOKEN_RESPONSE=$(curl -s -X POST "$TOKEN_ENDPOINT" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET")
export JWT=$(echo $TOKEN_RESPONSE | jq -r .access_token)

Este repositório inclui agentes A2A de exemplo implantáveis no diretório examples/: um Weather Agent e um Calculator Agent. Eles podem ser implantados usando sua própria configuração Terraform. Opcionalmente, implante-os com cd examples/terraform && terraform apply, depois capture suas saídas:

# De examples/terraform após implantar os agentes de exemplo
WEATHER_BACKEND=$(terraform output -raw weather_agent_backend_url)
WEATHER_CARD=$(terraform output -raw weather_agent_card_url)
AGENT_TOKEN_ENDPOINT=$(terraform output -raw cognito_token_endpoint)
AGENT_CLIENT_ID=$(terraform output -raw cognito_client_id)
AGENT_CLIENT_SECRET=$(terraform output -raw cognito_client_secret)

Em seguida, registre o agente com o gateway (usando o $GATEWAY_URL e $JWT capturados anteriormente):

curl -X POST "$GATEWAY_URL/admin/agents/register" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "weather-agent",
    "name": "Weather Agent",
    "backendUrl": "'"$WEATHER_BACKEND"'",
    "agentCardUrl": "'"$WEATHER_CARD"'",
    "authConfig": {
      "type": "oauth2_client_credentials",
      "tokenUrl": "'"$AGENT_TOKEN_ENDPOINT"'",
      "clientId": "'"$AGENT_CLIENT_ID"'",
      "clientSecret": "'"$AGENT_CLIENT_SECRET"'",
      "scopes": ["a2a-gateway/weather:read"]
    }
  }'

O gateway impõe controle de acesso refinado. Cada escopo OAuth deve receber explicitamente acesso a agentes específicos na tabela de permissões do DynamoDB.

Atualize as permissões para permitir que seu escopo acesse o agente registrado:

aws dynamodb put-item \
  --table-name "$PERMISSIONS_TABLE" \
  --item '{
    "scope": {"S": "gateway:admin"},
    "allowedAgents": {"L": [{"S": "weather-agent"}]},
    "description": {"S": "Admin scope with access to weather agent"}
  }'

Descubra agentes registrados e envie uma mensagem através do gateway:

curl "$GATEWAY_URL/agents" -H "Authorization: Bearer $JWT"

curl -X POST "$GATEWAY_URL/agents/weather-agent/message:send" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-001",
      "role": "user",
      "parts": [{"text": "What is the weather in New York"}]
    }
  }'

Limpeza

Para limpar a solução, execute terraform destroy da pasta /terraform. O Terraform pedirá sua permissão para excluir os recursos.

terraform destroy

Considerações de segurança

Este gateway é uma implementação de referência. Antes de passar para produção, revise as seguintes áreas que requerem reforço com base na postura de segurança da sua organização.

Modelo de confiança de backend

O gateway opera em um modelo de confiança após autenticação. Depois que um agente de backend é registrado e as credenciais OAuth são validadas, o gateway encaminha as respostas diretamente para os clientes sem inspeção de conteúdo. As mensagens A2A são encaminhadas sem modificação, portanto, os agentes de backend são responsáveis por implementar suas próprias defesas contra injeção de prompt e validação de entrada. Em produção, implemente um fluxo de trabalho de aprovação para registro de agentes onde os administradores revisam os agentes de backend antes que eles se tornem acessíveis. Integre isso com seu pipeline de integração contínua e entrega contínua (CI/CD) para que os agentes sejam verificados como parte do processo de implantação, não depois.

Limitação de taxa e cotas

O gateway impõe limites de taxa por usuário, por agente na camada de proxy. Cada solicitação incrementa um contador atômico no DynamoDB com chave por usuário, agente e janela de minuto. Quando um cliente excede sua cota, o proxy retorna um 429 com um cabeçalho retry-after e a solicitação não alcança o backend. Os contadores expiram automaticamente via TTL do DynamoDB, portanto não há sobrecarga de limpeza. Os limites são configurados junto com os controles de acesso na tabela Permissions, seja como um padrão de solicitações por minuto ou como substituições por agente, dando aos administradores controle granular sobre o consumo.

Implantação privada

Para ambientes que requerem infraestrutura privada, o gateway suporta um modo de implantação Amazon Virtual Private Cloud (Amazon VPC) opcional. Quando você habilita este modo, as funções Lambda são executadas dentro de sub-redes privadas. O API Gateway muda para um endpoint privado acessível apenas dentro da VPC. Os endpoints da VPC lidam com o tráfego para os serviços AWS sem atravessar a internet.

O gateway suporta tanto a criação de uma nova VPC quanto trazer a sua própria. Para implantar em uma VPC existente, forneça seu ID de VPC, IDs de sub-rede, IDs de tabela de rotas e IDs de grupo de segurança em terraform.tfvars:

enable_private_deployment = true
existing_vpc_id = "vpc-0123456789abcdef0"
existing_subnet_ids = ["subnet-aaa", "subnet-bbb", "subnet-ccc"]
existing_route_table_ids = ["rtb-aaa"]
existing_lambda_security_group_id = "sg-aaa"
existing_vpc_endpoint_security_group_id = "sg-bbb"

Observe que este modo torna a infraestrutura do gateway privada, mas sua VPC ainda precisa de conectividade de saída para a internet para troca de tokens OAuth com o Cognito ou outros provedores de identidade externos. Isso é normalmente tratado através de um gateway de tradução de endereços de rede (NAT) ou roteamento AWS Transit Gateway para uma VPC de saída compartilhada. O tráfego de serviços AWS (DynamoDB, Amazon S3, Secrets Manager, S3 Vectors) permanece privado através de endpoints da VPC. Apenas a troca de tokens OAuth requer conectividade de saída. Se você precisar de busca semântica com Amazon Bedrock, defina enable_bedrock_endpoint = true para adicionar um endpoint de VPC do Amazon Bedrock Runtime também.

Para agentes executando on-premises ou em outras nuvens, o gateway privado é acessível através do AWS Direct Connect ou AWS Interconnect (preview). Isso permite que o gateway governe agentes em ambientes sem expor o tráfego à internet pública.

Autenticação de servidor A2A

O gateway autentica com agentes de backend usando o fluxo de credenciais de cliente OAuth 2.0. Cada agente registrado inclui sua URL de token e credenciais, e o Proxy Lambda lida com a aquisição de token de forma transparente. Ou seja, os agentes de backend devem ser implantados com autenticação OAuth habilitada, independentemente de onde sejam executados.

Ao usar o Amazon Bedrock AgentCore Runtime especificamente, um detalhe importante: configure o customJWTAuthorizer com allowedClients definido para o ID do cliente Cognito, não allowedAudience. Os tokens de credenciais de cliente do Cognito incluem uma reivindicação client_id, mas não incluem a reivindicação JWT padrão aud. O parâmetro allowedAudience valida a reivindicação aud e retornará 401 Unauthorized para tokens máquina-para-máquina (M2M) do Cognito. Usar allowedClients valida contra client_id, que os tokens do Cognito fornecem. Consulte o contrato de protocolo A2A do AgentCore para o conjunto completo de opções de autenticação.

Conclusão

À medida que as organizações passam de alguns agentes para dezenas ou centenas, os desafios operacionais mudam de construir agentes individuais para gerenciar as conexões entre eles. Integrações ponto a ponto não escalam. As equipes não devem precisar saber onde cada agente está, gerenciar credenciais separadas para cada um ou construir sua própria descoberta e controle de acesso do zero.

Este gateway oferece um único lugar para registrar agentes, controlar quem pode acessá-los e rotear o tráfego. Como opera no nível do protocolo, ele governa agentes em ambientes: serviços AWS, nuvens de terceiros, infraestrutura on-premises ou uma combinação. Backends que falam A2A funcionam. Registre o agente com sua URL e credenciais OAuth, e o gateway cuida do resto. O runtime subjacente não importa. Novos agentes tornam-se descobríveis no momento em que são registrados, e os controles de acesso e limites de taxa são gerenciados centralmente em vez de espalhados pelos backends.

O protocolo A2A padroniza como os agentes conversam entre si. Um gateway padroniza como sua organização gerencia essa comunicação. O código-fonte completo está disponível no repositório aws-samples.

Sobre os autores

Reilly Manton

Reilly é um Solutions Architect na AWS Telecoms especializado em AI & ML. Ele constrói soluções inovadoras de IA para clientes, com foco particular em protocolos de interoperabilidade, governança e redes agênticas em larga escala. Reilly trabalha em estreita colaboração com os clientes para trazer capacidades emergentes de IA para produção. Ele é apaixonado por padrões abertos e construção de sistemas que funcionam através de fronteiras organizacionais.

Este conteúdo foi traduzido do post original do blog, que pode ser encontrado aqui.

Biografia do Autores

Reilly Manton é Solutions Architect na Amazon Web Services.
Scott Wainner é Principal Solutions Architect na Amazon Web Services.
Wesley Petry é Solutions Architect na Amazon Web Services.

Tradutores

Nicolas Tarzia é Senior Technical Account Manager na AWS, com mais de 13 anos de experiência, com ampla experiência em arquitetura cloud, engenharia e design de software. Atualmente apoia clientes do ramo financeiro. Sua área de interesse são tecnologias serverless.
https://www.linkedin.com/in/nicolastarzia
Daniel Abib é Arquiteto de Soluções Sênior e Especialista em Amazon Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem.
https://www.linkedin.com/in/danielabib/