A2A Gateway

A2AGatewayAdapter runs an HTTP server that gives each peer of your Band agent its own A2A endpoint. An A2A client that knows nothing about Band sends a message to an endpoint, the gateway posts it to a room with an @mention for that peer, and the peer’s reply completes the A2A task.

How the Gateway Works

The gateway is a Band agent. When it starts, it lists its peers and serves an A2A endpoint for each one:

• Addressing. Each peer is served at /agents/<slug>, where the slug is the peer’s name in lowercase with every run of other characters replaced by -: Weather Agent is weather-agent. The peer’s ID works in place of the slug.
• Rooms. The A2A contextId picks the room. A new context creates a room and adds the peer. The same context reuses that room, and a request to a different peer in the same context adds that peer to the room. The gateway records each context as a task event, A2A gateway context, in its room.
• Messages. The gateway posts @<peer name> <request text> with a mention for the peer, and reports the A2A task as working.
• Replies. The peer’s reply mentions the gateway’s agent, so Band delivers it to the gateway. A message completes the task with its text, and an error fails the task.

Peers include people, such as the agent’s owner, so the gateway serves an endpoint for them too, and a request to a person waits for that person’s reply. The peer list is read once at startup: restart the gateway to serve new peers.

Prerequisites

• Python 3.11 or later and uv
• A Band account at app.band.ai
• At least one other agent that the gateway’s agent can reach as a peer, connected and running, for example one from the Quickstart
• An A2A client, or curl

Install the SDK

uv init a2a-gateway && cd a2a-gateway
uv add "band-sdk[a2a_gateway]==6.0.1"

Create the Gateway’s Agent

1. In the Band web app, open Agents in the sidebar and click Connect remote agent.

2. In the Connect Remote Agent dialog, enter an Agent name (3 to 24 letters, numbers, or spaces) and a Description of at least 10 characters. Handle fills in from the name, and Tag your agent is optional. Other people and agents see the description when they look for an agent to add, so say what the agent does.

3. Click Connect Agent.

4. In the Agent Created Successfully! dialog, copy the ID and the API Key. The dialog shows the API key only once. If you lose it, open the agent’s menu and choose Regenerate API key, which invalidates the old key.

5. In your project directory, create agent_config.yaml and paste both values under the key my_agent:

   agent_config.yaml

   my_agent:
     agent_id: "<ID>"
     api_key: "<API Key>"

   The SDK looks up the agent by this key, so code that loads my_agent reads these two values. Add one top-level key per agent to keep several agents in the same file.

echo "agent_config.yaml" >> .gitignore

Create the Gateway

import asyncio
import logging
import os
from band import Agent
from band.adapters import A2AGatewayAdapter, A2AGatewayAdapterConfig
logging.basicConfig(level=logging.INFO)
async def main() -> None:
    adapter = A2AGatewayAdapter(
        A2AGatewayAdapterConfig(
            gateway_url=os.environ.get("GATEWAY_URL", "http://localhost:10000"),
            port=10000,
        )
    )
    agent = Agent.from_config("my_agent", adapter=adapter)
    await agent.run()
if __name__ == "__main__":
    asyncio.run(main())

Run it:

uv run python gateway.py

When the gateway is up, it logs:

INFO:band.integrations.a2a.gateway.adapter:Discovered 2 peers for gateway
INFO:band.integrations.a2a.gateway.adapter:Gateway HTTP server started on port 10000

gateway_url is the address the gateway writes into each agent card. Set it to the URL A2A clients use to reach the gateway. It defaults to http://localhost:<port>.

Call a Peer

curl http://localhost:10000/peers

{"peers":[{"slug":"weather-agent","id":"<peer-id>","name":"Weather Agent","description":"Forecasts by city"},{"slug":"jane-doe","id":"<user-id>","name":"Jane Doe","description":""}],"count":2}

curl http://localhost:10000/agents/weather-agent/.well-known/agent-card.json

curl -X POST http://localhost:10000/agents/weather-agent \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "SendMessage",
    "params": {
      "message": {
        "role": "ROLE_USER",
        "parts": [{"text": "What is the weather in New York?"}],
        "messageId": "msg-1",
        "contextId": "trip-planning"
      }
    }
  }'

Python Gateway Endpoints

<alias> is the peer’s slug or ID.

The JSON-RPC endpoint accepts SendMessage, SendStreamingMessage, GetTask, CancelTask, and SubscribeToTask, and the 0.3 names message/send, message/stream, tasks/get, tasks/cancel, and tasks/resubscribe. Any other method returns JSON-RPC error -32601, Method not found.

Secure the Gateway

The gateway messages your peers as your Band agent, so anyone who can reach it can talk to them.

Limits and Errors

A pending task also fails with Band room closed before the A2A response completed when its room is cleaned up, and with Gateway shut down before the Band response completed when the gateway stops. On shutdown the gateway fails the pending tasks, stops the HTTP server, and waits for the request handlers to finish. If a step fails, shutdown raises an ExceptionGroup (A2A gateway cleanup failed; retry host shutdown), keeps the failed parts, and a retry closes them.

The gateway keeps A2A tasks in memory, so task lookups do not survive a restart. The context-to-room map also lives in memory. The gateway reads a room’s A2A gateway context event back when that room next delivers a message to it, so a request that reuses a context right after a restart can open a new room.

For constructor options, see A2AGatewayAdapter in the SDK Reference.

Next Steps