Constructing a serverless A2A gateway for agent discovery, routing, and entry management

As enterprises deploy AI brokers throughout groups, distributors, and infrastructure, managing agent-to-agent communication turns into a rising operational burden. With out a centralized layer, every new agent integration provides point-to-point connections, separate credentials, and customized routing logic. Groups spend engineering cycles wiring up connectivity as an alternative of constructing agent capabilities. Entry management turns into fragmented, with no single place to implement which shoppers can attain which brokers. The result’s slower time-to-market for brand new agent workflows, elevated safety danger from inconsistent auth insurance policies, and operational overhead that scales quadratically with every new agent added to the community.

The gateway sample addresses this by putting a single entry level in entrance of your brokers, no matter whether or not they run on Amazon Elastic Container Service (Amazon ECS), AWS Lambda, Amazon Bedrock AgentCore Runtime, a non-AWS cloud, or a hybrid atmosphere. It handles routing and enforces fine-grained permissions centrally, with out binding groups to a specific runtime, framework, or orchestration layer. This sample builds on the Agent-to-Agent (A2A) protocol, which standardizes how brokers talk with one another. With out a central orchestrator, a deployment of 20 brokers requires as much as 190 point-to-point connections.

On this put up, you’ll discover ways to construct a serverless A2A gateway on AWS that hosts a number of brokers behind a single area utilizing path-based routing (/brokers/{agentId}). Commonplace A2A shoppers work with out modification. The answer has three layers:

1. Administration layer: Centralized agent registry with discovery and semantic search.
2. Management layer: Nice-grained entry management utilizing JSON Internet Token (JWT) scopes and a Lambda authorizer.
3. Execution layer: Single-domain routing with OAuth backend authentication and Server-Despatched Occasions (SSE) streaming help.

Observe alongside, and you’ll deploy a Terraform-provisioned gateway that A2A-adherent brokers can connect with.

Structure

The next diagram reveals the gateway’s parts and the way requests movement by the system.

Amazon API Gateway (REST API) serves because the single-entry level. The structure makes use of a REST API as a result of REST APIs help response streaming. Streaming is required for SSE-based real-time agent responses. The Lambda authorizer inspects JWT scopes and generates AWS Identification and Entry Administration (IAM) insurance policies that permit entry to particular agent paths (/brokers/agent-a/*) whereas denying others.

Lambda capabilities implement the gateway logic:

1. Authorizer: Validates JWTs and generates IAM insurance policies based mostly on scope-to-agent mappings.
2. Registry: Lists brokers the caller can entry, with URLs rewritten to level to the gateway.
3. Search: Semantic agent discovery utilizing Amazon Titan Textual content Embeddings in Amazon Bedrock.
4. Proxy: Routes requests to backend brokers with OAuth authentication, helps SSE streaming through Lambda Internet Adapter.
5. Admin: Agent registration and lifecycle administration.

Amazon DynamoDB shops three tables. The Agent Registry maps agent IDs to backend URLs, auth configs, and cached agent playing cards. The Permissions desk maps JWT scopes to allowed brokers. A RateLimitCounters desk counts requests per minute.

Amazon Cognito handles authentication utilizing OAuth 2.0 consumer credentials movement. Scopes within the token decide which brokers the caller can entry. When a consumer authenticates, they obtain a JWT containing scopes like billing:learn or help:write. The authorizer appears up these scopes within the Permissions desk to find out which brokers the consumer can attain.

AWS Secrets and techniques Supervisor shops backend credentials. When the Proxy Lambda must authenticate with a backend agent, it retrieves the OAuth consumer secret by Amazon Useful resource Identify (ARN). Secrets and techniques aren’t saved in DynamoDB.

For semantic search, agent descriptions are embedded utilizing Amazon Titan Textual content Embeddings and saved in Amazon S3 Vectors. This permits shoppers to find brokers utilizing pure language queries quite than actual identify matches.

Gateway design

A2A native endpoints observe the A2A protocol specification and path to backend brokers. The gateway helps each protocol bindings outlined within the spec. JSON-RPC makes use of a single endpoint per agent with the tactic within the request physique:

1. GET /brokers/{agentId}/.well-known/agent-card.json – Fetch agent capabilities.
2. POST /brokers/{agentId} with {"methodology": "SendMessage", ...} (for buffered response).
3. POST /brokers/{agentId} with {"methodology": "SendStreamingMessage", ...} (for SSE streaming).

The HTTP+JSON/REST binding can be supported for shoppers that choose RESTful URLs.

These endpoints are totally A2A protocol aligned. Shoppers level to the gateway URL as an alternative of particular person backend URLs. Nonetheless, A2A native endpoints alone don’t remedy the administration downside. Shoppers nonetheless want a option to uncover which brokers exist, seek for brokers by functionality, and handle the agent lifecycle.

Gateway endpoints present this layer:

1. GET /brokers – Record brokers the caller can entry.
2. POST /search – Semantic seek for brokers.
3. POST /admin/brokers/register – Register a brand new backend agent.
4. POST /admin/brokers/{agentId}/sync – Refresh cached agent card.
5. POST /admin/brokers/{agentId}/standing – Activate or deactivate an agent.

Each request follows the identical path. The consumer sends a request with a JWT within the Authorization header. API Gateway invokes the Lambda authorizer, which validates the JWT and appears up the caller’s scopes within the Permissions desk. The authorizer returns an IAM coverage permitting or denying entry to particular brokers. If allowed, the request routes to the suitable Lambda: Proxy for A2A site visitors, Registry for agent discovery, Seek for semantic queries, or Admin for administration operations. For A2A requests, the Proxy Lambda authenticates with the backend utilizing OAuth and forwards the request. Unauthorized requests are rejected at API Gateway and don’t attain the backend Lambdas.

The three-layer mannequin

As agent deployments develop, groups want visibility into what’s obtainable. The administration layer offers a centralized registry the place brokers are cataloged with their capabilities, backend URLs, and standing. When a brand new agent is deployed, it’s registered as soon as within the gateway and instantly discoverable by approved shoppers. The registry additionally caches agent playing cards, so shoppers don’t must fetch capabilities from every backend individually. Cached playing cards have their URLs rewritten to level by the gateway, so shoppers work together with the only gateway area quite than discovering backend URLs. For bigger deployments, semantic search lets shoppers discover brokers by describing what they want quite than understanding actual names.

In an enterprise, not each consumer ought to entry each agent. The management layer enforces fine-grained permissions based mostly on JWT scopes. When a consumer authenticates, their token comprises scopes like billing:learn or help:admin. The Lambda authorizer maps these scopes to particular brokers within the Permissions desk and generates IAM insurance policies that permit or deny entry on the API Gateway stage. Unauthorized requests don’t attain backend Lambdas. Moreover, charge limiting is enforced per-user, per-agent on the proxy stage. The proxy tracks request counts utilizing atomic DynamoDB counters with automated time-to-live (TTL) expiration, returning a 429 with a Retry-After header when a consumer exceeds its quota. Permissions and charge limits are centrally managed: to grant or revoke entry or regulate quotas, you replace the Permissions desk quite than modifying every agent.

The execution layer handles the precise routing of requests to backend brokers. Shoppers connect with a single area, and the gateway routes to the suitable backend based mostly on the trail. This simplifies community configuration: as an alternative of opening connectivity to each agent, shoppers solely want to succeed in the gateway. The Proxy Lambda handles OAuth authentication with backends, so shoppers don’t handle backend credentials. It retrieves secrets and techniques from Secrets and techniques Supervisor, fetches entry tokens, and forwards requests transparently. For real-time use circumstances, the proxy helps SSE streaming, permitting brokers to ship incremental responses again to shoppers as they’re generated.

Deploy the answer

The gateway deploys completely with Terraform. First, confirm that you’ve got the next.

Stipulations

The gateway code is offered on the aws-samples GitHub repository.

Clone the repository and configure your variables:

cp terraform/terraform.tfvars.instance terraform/terraform.tfvars

Edit terraform/terraform.tfvars together with your area and naming preferences:

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

Construct the Lambda package deal and deploy:

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

Terraform creates the sources in a single go: DynamoDB tables, Cognito person pool, Amazon Elastic Container Registry (Amazon ECR) repository, Lambda capabilities, API Gateway, and IAM roles. Terraform builds and pushes the proxy Lambda container as a part of the deployment.

Take a look at the answer

Get your gateway credentials from Terraform outputs:

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)

Acquire a JWT:

TOKEN_RESPONSE=$(curl -s -X POST "$TOKEN_ENDPOINT" 
  -H "Content material-Sort: software/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)

This repository contains deployable A2A instance brokers within the examples/ listing: a Climate Agent and a Calculator Agent. They are often deployed utilizing their very own Terraform configuration. Optionally, deploy them with cd examples/terraform && terraform apply, then seize their outputs:

# From examples/terraform after deploying the instance brokers
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)

Then register the agent with the gateway (utilizing the $GATEWAY_URL and $JWT captured earlier):

curl -X POST "$GATEWAY_URL/admin/brokers/register" 
  -H "Authorization: Bearer $JWT" 
  -H "Content material-Sort: software/json" 
  -d '{
    "agentId": "weather-agent",
    "identify": "Climate Agent",
    "backendUrl": "'"$WEATHER_BACKEND"'",
    "agentCardUrl": "'"$WEATHER_CARD"'",
    "authConfig": {
      "kind": "oauth2_client_credentials",
      "tokenUrl": "'"$AGENT_TOKEN_ENDPOINT"'",
      "clientId": "'"$AGENT_CLIENT_ID"'",
      "clientSecret": "'"$AGENT_CLIENT_SECRET"'",
      "scopes": ["a2a-gateway/weather:read"]
    }
  }'

The gateway enforces fine-grained entry management. Every OAuth scope have to be explicitly granted entry to particular brokers within the DynamoDB permissions desk.

Replace permissions to permit your scope to entry the registered agent:

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

Uncover registered brokers and ship a message by the gateway:

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

curl -X POST "$GATEWAY_URL/brokers/weather-agent/message:ship" 
  -H "Authorization: Bearer $JWT" 
  -H "Content material-Sort: software/json" 
  -d '{
    "message": {
      "messageId": "msg-001",
      "function": "person",
      "components": [{"text": "What is the weather in New York"}]
    }
  }'

Clear up

To wash up the answer, run terraform destroy from the /terraform folder. Terraform will ask to your permission to delete the sources.

Safety issues

This gateway is a reference implementation. Earlier than transferring to manufacturing, evaluation the next areas that require hardening based mostly in your group’s safety posture.

Backend belief mannequin

The gateway operates on a trust-after-authentication mannequin. After a backend agent is registered and OAuth credentials are validated, the gateway proxies the responses on to shoppers with out content material inspection. A2A messages are proxied with out modification, so backend brokers are accountable for implementing their very own immediate injection defenses and enter validation. In manufacturing, implement an approval workflow for agent registration the place directors evaluation backend brokers earlier than they grow to be accessible. Combine this together with your steady integration and steady supply (CI/CD) pipeline so brokers are vetted as a part of the deployment course of, not after.

Charge limiting and quotas

The gateway enforces per-user, per-agent charge limits on the proxy layer. Every request increments an atomic counter in DynamoDB keyed by person, agent, and minute window. When a consumer exceeds its quota, the proxy returns a 429 with a retry-after header and the request doesn’t attain the backend. Counters expire mechanically through DynamoDB TTL, so there’s no cleanup overhead. Limits are configured alongside entry controls within the Permissions desk, both as a default requests-per-minute or as per-agent overrides, giving directors granular management over consumption.

Non-public deployment

For environments that require non-public infrastructure, the gateway helps an optionally available Amazon Digital Non-public Cloud (Amazon VPC) deployment mode. If you allow this mode, the Lambda capabilities run inside non-public subnets. The API Gateway switches to a non-public endpoint accessible solely inside the VPC. VPC endpoints deal with site visitors to AWS companies with out traversing the web.

The gateway helps each creating a brand new VPC and bringing your personal. To deploy into an present VPC, present your VPC ID, subnet IDs, route desk IDs, and safety group IDs in 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"

Be aware that this mode makes the gateway’s infrastructure non-public, however your VPC nonetheless wants outbound web connectivity for OAuth token change with Cognito or different exterior identification suppliers. That is usually dealt with by a community handle translation (NAT) gateway or AWS Transit Gateway routing to a shared egress VPC. AWS service site visitors (DynamoDB, Amazon S3, Secrets and techniques Supervisor, S3 Vectors) stays non-public by VPC endpoints. Solely the OAuth token change requires outbound connectivity. For those who want semantic search with Amazon Bedrock, set enable_bedrock_endpoint = true so as to add an Amazon Bedrock Runtime VPC endpoint as nicely.

For brokers operating on-premises or on different clouds, the non-public gateway is reachable over AWS Direct Join or AWS Interconnect (preview). This lets the gateway govern brokers throughout environments with out exposing site visitors to the general public web.

A2A server authentication

The gateway authenticates with backend brokers utilizing OAuth 2.0 consumer credentials movement. Every registered agent contains its token URL and credentials, and the Proxy Lambda handles token acquisition transparently. This implies backend brokers have to be deployed with OAuth authentication enabled no matter the place they run.

When utilizing Amazon Bedrock AgentCore Runtime particularly, a key element: configure the customJWTAuthorizer with allowedClients set to your Cognito consumer ID, not allowedAudience. Cognito consumer credentials tokens embrace a client_id declare however don’t embrace the usual JWT aud declare. The allowedAudience parameter validates the aud declare and can return 401 Unauthorized for Cognito machine-to-machine (M2M) tokens. Utilizing allowedClients validates towards client_id, which Cognito tokens present. See the AgentCore A2A protocol contract for the complete set of authentication choices.

Conclusion

As organizations transfer from a handful of brokers to dozens or tons of, the operational challenges shift from constructing particular person brokers to managing the connections between them. Level-to-point integrations don’t scale. Groups shouldn’t must know the place each agent lives, handle separate credentials for every one, or construct their very own discovery and entry management from scratch.

This gateway provides you a single place to register brokers, management who can entry them, and route site visitors. As a result of it operates on the protocol stage, it governs brokers throughout environments: AWS companies, third-party clouds, on-premises infrastructure, or a mixture. Backends that talk A2A work. Register the agent with its URL and OAuth credentials, and the gateway handles the remainder. The underlying runtime doesn’t matter. New brokers grow to be discoverable the second they’re registered, and entry controls and charge limits are managed centrally quite than scattered throughout backends.

The A2A protocol standardizes how brokers discuss to one another. A gateway standardizes how your group manages that communication. The full source code is offered within the aws-samples repository.

In regards to the authors