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. And not using 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 purchasers can attain which brokers. The result’s slower time-to-market for brand spanking 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 inserting 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 setting. 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. And not using 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}). Normal A2A purchasers work with out modification. The answer has three layers:

1. Administration layer: Centralized agent registry with discovery and semantic search.
2. Management layer: Tremendous-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 assist.

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

Structure

The next diagram reveals the gateway’s elements and the way requests circulate via 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 assist response streaming. Streaming is required for SSE-based real-time agent responses. The Lambda authorizer inspects JWT scopes and generates AWS Id and Entry Administration (IAM) insurance policies that enable 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 circulate. 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 assist:write. The authorizer seems to be 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 enables purchasers to find brokers utilizing pure language queries quite than precise title 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 strategy within the request physique:

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

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

These endpoints are absolutely A2A protocol aligned. Purchasers level to the gateway URL as an alternative of particular person backend URLs. Nevertheless, A2A native endpoints alone don’t resolve the administration downside. Purchasers nonetheless want a approach 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 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 accessible. The administration layer gives 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 licensed purchasers. The registry additionally caches agent playing cards, so purchasers don’t have to fetch capabilities from every backend individually. Cached playing cards have their URLs rewritten to level via the gateway, so purchasers work together with the one gateway area quite than discovering backend URLs. For bigger deployments, semantic search lets purchasers discover brokers by describing what they want quite than realizing precise 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 accommodates scopes like billing:learn or assist:admin. The Lambda authorizer maps these scopes to particular brokers within the Permissions desk and generates IAM insurance policies that enable 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 computerized 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 modify quotas, you replace the Permissions desk quite than modifying every agent.

The execution layer handles the precise routing of requests to backend brokers. Purchasers hook up 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, purchasers solely want to succeed in the gateway. The Proxy Lambda handles OAuth authentication with backends, so purchasers 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 purchasers as they’re generated.

Deploy the answer

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

Stipulations

The gateway code is obtainable 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"
setting = "poc"

Construct the Lambda bundle 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)

Get hold of a JWT:

TOKEN_RESPONSE=$(curl -s -X POST "$TOKEN_ENDPOINT" 
  -H "Content material-Kind: 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-Kind: software/json" 
  -d '{
    "agentId": "weather-agent",
    "title": "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 via 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-Kind: 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 shifting 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 purchasers 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 personal infrastructure, the gateway helps an non-obligatory Amazon Digital Non-public Cloud (Amazon VPC) deployment mode. If you allow this mode, the Lambda capabilities run inside personal subnets. The API Gateway switches to a personal endpoint accessible solely throughout the VPC. VPC endpoints deal with visitors to AWS providers with out traversing the web.

The gateway helps each creating a brand new VPC and bringing your individual. 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"

Observe that this mode makes the gateway’s infrastructure personal, however your VPC nonetheless wants outbound web connectivity for OAuth token trade with Cognito or different exterior id suppliers. That is sometimes dealt with via a community deal with translation (NAT) gateway or AWS Transit Gateway routing to a shared egress VPC. AWS service visitors (DynamoDB, Amazon S3, Secrets and techniques Supervisor, S3 Vectors) stays personal via VPC endpoints. Solely the OAuth token trade 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 effectively.

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

A2A server authentication

The gateway authenticates with backend brokers utilizing OAuth 2.0 consumer credentials circulate. 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 embody a client_id declare however don’t embody 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 in opposition to 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 a whole bunch, 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 have to know the place each agent lives, handle separate credentials for each, 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 visitors. As a result of it operates on the protocol stage, it governs brokers throughout environments: AWS providers, third-party clouds, on-premises infrastructure, or a mix. 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 speak to one another. A gateway standardizes how your group manages that communication. The full supply code is obtainable within the aws-samples repository.

Concerning the authors