O problema das conexões ponto a ponto entre agentes
À medida que empresas expandem o uso de agentes de IA — distribuídos entre times, fornecedores e infraestruturas distintas — gerenciar a comunicação entre eles vira um gargalo operacional real. Sem uma camada centralizada, cada nova integração exige uma conexão direta, credenciais próprias e lógica de roteamento customizada.
O resultado é previsível: engenheiros gastam ciclos conectando agentes em vez de desenvolver capacidades. O controle de acesso fica fragmentado, sem um ponto único para definir quem pode falar com quem. E o custo operacional cresce de forma quadrática — uma rede com 20 agentes pode exigir até 190 conexões ponto a ponto.
Para resolver isso, a AWS publicou um guia mostrando como construir um gateway serverless baseado no protocolo A2A (Agente-para-Agente), que coloca um único ponto de entrada na frente de todos os agentes, independentemente de onde eles rodam: Amazon Elastic Container Service (Amazon ECS), AWS Lambda, Amazon Bedrock AgentCore Runtime, outras nuvens ou ambientes híbridos.
Arquitetura em três camadas
A solução proposta organiza o gateway em três camadas bem definidas:
- Camada de gerenciamento: registro centralizado de agentes com descoberta e busca semântica.
- Camada de controle: controle de acesso granular usando escopos de Token Web JSON (JWT) e um autorizador Lambda.
- Camada de execução: roteamento por domínio único com autenticação OAuth no backend e suporte a streaming via Eventos Enviados pelo Servidor (SSE).
O Amazon API Gateway (API REST) atua como ponto de entrada único. A escolha por API REST — em vez de HTTP API — é intencional: apenas APIs REST suportam streaming de resposta, necessário para respostas em tempo real via SSE.
Um autorizador Lambda inspeciona os escopos do JWT e gera políticas do Gerenciamento de Identidade e Acesso da AWS (IAM) que permitem ou negam acesso a caminhos específicos de agentes, como /agents/agent-a/*. Requisições não autorizadas são bloqueadas no API Gateway e nunca chegam às funções Lambda do backend.
Componentes principais
Cinco funções Lambda implementam a lógica do gateway:
- Autorizador: valida JWTs e gera políticas IAM baseadas nos mapeamentos de escopo para agente.
- Registro (Registry): lista os agentes acessíveis ao chamador, com URLs reescritas para apontar ao gateway.
- Busca (Search): descoberta semântica de agentes usando Amazon Titan Text Embeddings no Amazon Bedrock.
- Proxy: roteia requisições aos agentes de backend com autenticação OAuth, com suporte a streaming SSE via Lambda Web Adapter.
- Admin: registro e gerenciamento do ciclo de vida dos agentes.
O Amazon DynamoDB armazena três tabelas: o Registro de Agentes (mapeando IDs de agentes para URLs de backend, configurações de autenticação e cards de agentes em cache), a tabela de Permissões (mapeando escopos JWT para agentes permitidos) e a tabela de Contadores de Limite de Taxa (contando requisições por minuto).
O Amazon Cognito cuida da autenticação via fluxo de credenciais de cliente OAuth 2.0. Os escopos presentes no token determinam quais agentes o chamador pode acessar — por exemplo, billing:read ou support:write.
O AWS Secrets Manager armazena as credenciais dos backends. Quando o Lambda Proxy precisa autenticar com um agente de backend, ele recupera o segredo OAuth pelo Nome de Recurso Amazon (ARN). Credenciais nunca ficam armazenadas no DynamoDB.
Para busca semântica, as descrições dos agentes são vetorizadas com Amazon Titan Text Embeddings e armazenadas no Amazon S3 Vectors, permitindo que clientes descubram agentes por linguagem natural em vez de nomes exatos.
Design do gateway e endpoints suportados
O gateway suporta os dois bindings de protocolo definidos na especificação A2A:
- JSON-RPC: endpoint único por agente com o método no corpo da requisição:
GET /agents/{agentId}/.well-known/agent-card.json— busca as capacidades do agente.POST /agents/{agentId}com{"method": "SendMessage", ...}— resposta em buffer.POST /agents/{agentId}com{"method": "SendStreamingMessage", ...}— streaming SSE.
- HTTP+JSON/REST: para clientes que preferem URLs no estilo RESTful.
Além dos endpoints nativos A2A, o gateway oferece endpoints de gerenciamento:
GET /agents— lista os agentes acessíveis ao chamador.POST /search— busca semântica de agentes.POST /admin/agents/register— registra um novo agente de backend.POST /admin/agents/{agentId}/sync— atualiza o card de agente em cache.POST /admin/agents/{agentId}/status— ativa ou desativa um agente.
Clientes A2A padrão funcionam sem modificação — basta apontar para a URL do gateway em vez das URLs individuais dos backends.
Como implantar a solução
O gateway é provisionado inteiramente com Terraform. Os pré-requisitos são:
- Terraform >= 1.5.0
- Python 3.12
- Interface de Linha de Comando da AWS (AWS CLI) configurada com credenciais válidas
- Docker (para construir o container Lambda do proxy)
- Um bucket do Amazon Simple Storage Service (Amazon S3) para o estado do Terraform (opcional)
O código do gateway está disponível no repositório aws-samples no GitHub. Após clonar o repositório e configurar as variáveis:
cp terraform/terraform.tfvars.example terraform/terraform.tfvarsEdite o arquivo com sua região e preferências de nomenclatura:
aws_region = "us-east-1"
project_name = "a2a-gateway"
environment = "poc"Em seguida, construa o pacote Lambda e implante:
./scripts/build_lambda_package.sh
cd terraform
terraform init
terraform plan
terraform applyO Terraform cria todos os recursos de uma vez: tabelas DynamoDB, pool de usuários Cognito, repositório Amazon Elastic Container Registry (Amazon ECR), funções Lambda, API Gateway e papéis IAM.
Testando a solução
Após o deploy, obtenha as credenciais do gateway a partir dos outputs 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)O repositório inclui agentes A2A de exemplo no diretório examples/: um Agente de Clima e um Agente de Calculadora. Após implantá-los com cd examples/terraform && terraform apply, registre um agente no gateway:
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"]
}
}'Para conceder acesso ao agente registrado, atualize a tabela de permissões:
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"}
}'Em seguida, descubra os agentes registrados e envie uma mensagem pelo 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"}]
}
}'Para limpar todos os recursos criados, basta executar terraform destroy dentro da pasta /terraform.
Considerações de segurança
A AWS deixa claro que essa é uma implementação de referência. Antes de ir para produção, alguns pontos merecem atenção.
Modelo de confiança do backend
O gateway opera em um modelo de confiança pós-autenticação. Após um agente de backend ser registrado e as credenciais OAuth validadas, o gateway faz proxy das respostas diretamente para os clientes sem inspeção de conteúdo. Mensagens A2A são encaminhadas sem modificação, então 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, recomenda-se implementar um fluxo de aprovação para o registro de agentes, onde administradores revisam os backends antes que se tornem acessíveis, integrado ao pipeline de Integração e Entrega Contínua (CI/CD).
Limite de taxa e cotas
O gateway aplica limites de taxa por usuário e por agente na camada do proxy. Cada requisição incrementa um contador atômico no DynamoDB, com chave por usuário, agente e janela de um minuto. Quando um cliente excede sua cota, o proxy retorna um 429 com um cabeçalho Retry-After. Os contadores expiram automaticamente via TTL do DynamoDB, sem necessidade de limpeza manual.
Implantação privada com VPC
Para ambientes que exigem infraestrutura privada, o gateway suporta um modo de implantação opcional com Amazon Virtual Private Cloud (Amazon VPC). Nesse modo, as funções Lambda rodam em sub-redes privadas e o API Gateway usa um endpoint privado acessível apenas dentro da VPC.
Para implantar em uma VPC existente, basta fornecer os IDs no arquivo 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"Vale notar que a VPC ainda precisa de conectividade de saída para a troca de tokens OAuth com o Cognito ou outros provedores de identidade externos — tipicamente via gateway de Tradução de Endereço de Rede (NAT) ou roteamento pelo AWS Transit Gateway para uma VPC de saída compartilhada. O tráfego para serviços AWS (DynamoDB, Amazon S3, Secrets Manager, S3 Vectors) permanece privado via endpoints de VPC.
Para agentes rodando on-premises ou em outras nuvens, o gateway privado é acessível via AWS Direct Connect ou AWS Interconnect (preview), sem expor o tráfego à internet pública.
Autenticação com agentes de backend
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 Lambda Proxy cuida da obtenção do token de forma transparente.
Um detalhe importante ao usar o Amazon Bedrock AgentCore Runtime: configure o customJWTAuthorizer com allowedClients apontando para o ID do cliente Cognito, e não allowedAudience. Tokens de credenciais de cliente do Cognito incluem a claim client_id, mas não a claim padrão aud do JWT. O parâmetro allowedAudience valida a claim aud e retornará 401 Unauthorized para tokens máquina-a-máquina (M2M) do Cognito.
Conclusão
À medida que organizações passam de poucos agentes para dezenas ou centenas, o desafio deixa de ser construir agentes individuais e passa a ser gerenciar as conexões entre eles. Integrações ponto a ponto não escalam.
O gateway A2A serverless apresentado pela AWS oferece um único lugar para registrar agentes, controlar quem pode acessá-los e rotear o tráfego. Por operar no nível do protocolo, ele governa agentes em diferentes ambientes — serviços AWS, nuvens de terceiros, infraestrutura on-premises ou uma combinação de todos. Novos agentes tornam-se descobríveis no momento em que são registrados, e controles de acesso e limites de taxa são gerenciados de forma centralizada.
O código-fonte completo está disponível no repositório aws-samples.
Fonte
Building a serverless A2A gateway for agent discovery, routing, and access control (https://aws.amazon.com/blogs/machine-learning/building-a-serverless-a2a-gateway-for-agent-discovery-routing-and-access-control/)