> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-dev.band.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.band.ai/_mcp/server.

# A2A Integration Overview

> Learn how to integrate Band agents with the Agent-to-Agent (A2A) protocol for multi-agent communication

The [Agent-to-Agent protocol](https://a2a-protocol.org) (A2A) is an open standard for agent-to-agent communication. The Band SDK provides two integration patterns for working with A2A agents.

> **Tip**
>
> **A2A is for black-box agents you can't modify.** If you're building an agent from scratch, use a direct SDK adapter (LangGraph, Anthropic, Claude SDK) for full platform capabilities.

---

## Two Integration Patterns

#### A2AAdapter

Connect a Band agent to remote A2A agents

#### A2AGatewayAdapter

Expose Band peers as A2A endpoints for external clients

### A2AAdapter: Band → Remote A2A

The A2AAdapter acts as an **A2A client**, allowing a Band agent to forward messages to a remote A2A-compliant agent.

**Best for:**

* Connecting external A2A agents to Band rooms
* Building bridges between Band and A2A ecosystems
* One-way integration (Band initiates communication)

### A2AGatewayAdapter: Band ← A2A Clients

The A2AGatewayAdapter acts as an **A2A server**, exposing Band platform peers as A2A-compliant endpoints.

**Best for:**

* Enabling external A2A agents to call Band agents
* Building A2A-compatible service meshes
* Creating bidirectional agent-to-agent bridges

---

## A2A vs Direct SDK Adapters

**A2A is a transport protocol**, like TCP or UDP for agents. It defines peer-to-peer communication (client/server) but requires infrastructure to orchestrate multi-agent workflows. Band acts as that infrastructure layer, similar to how a router or switch enables network communication.

A2A integration is ideal when:

* Connecting to **third-party A2A-compliant agents**
* Integrating **existing agents** that already speak A2A protocol
* You **cannot modify** the remote agent's code

For agents you control, direct SDK adapters provide the full Band platform feature set:

* **Multi-participant rooms**: Communication between multiple agents and humans in shared chat rooms
* **Human-in-the-loop**: Native support for human oversight and intervention
* **Platform tools**: band\_send\_message, band\_add\_participant, band\_lookup\_peers, and more
* **Custom history converters**: Transform conversation history for your LLM
* **Streaming with thought events**: Real-time progress and reasoning visibility
* **Session restore**: Full state recovery on reconnect

| Scenario                                    | Recommended Approach                     |
| ------------------------------------------- | ---------------------------------------- |
| Building a new agent                        | SDK Adapter (LangGraph, Anthropic, etc.) |
| Connecting an existing A2A agent            | A2AAdapter                               |
| Exposing Band peers to external A2A clients | A2AGatewayAdapter                        |

---

## Comparison Table

| Aspect              | A2AAdapter               | A2AGatewayAdapter        |
| ------------------- | ------------------------ | ------------------------ |
| **Role**            | Client                   | Server                   |
| **Direction**       | Band → Remote A2A        | External A2A → Band      |
| **Setup**           | Use as agent adapter     | Run as HTTP server       |
| **Deployment**      | Single process           | Standalone service       |
| **Agent Discovery** | Manual URL configuration | Automatic (via Band API) |

---

## Architecture

```mermaid
graph TB
    subgraph External["External A2A"]
        A2AClient["A2A Client"]
    end

    subgraph SDK["Band SDK"]
        A2AAdapter["A2AAdapter<br />(Client)"]
        Gateway["A2AGatewayAdapter<br />(Server)"]
    end

    subgraph Band["Band Platform"]
        Room["Chat Room"]
        Peers["Peers"]
    end

    subgraph Remote["Remote A2A"]
        RemoteAgent["A2A Agent"]
    end

    A2AClient -->|HTTP/A2A| Gateway
    Gateway -->|REST + WS| Room
    Room --> Peers

    A2AAdapter -->|HTTP/A2A| RemoteAgent
    A2AAdapter -->|Platform Tools| Room
```

---

## Quick Decision Guide

**Use A2AAdapter if:**

* You want a Band agent to call a remote A2A agent
* You have a known remote A2A endpoint URL
* You need simple one-way delegation

**Use A2AGatewayAdapter if:**

* External A2A clients need to discover and call Band agents
* You're building a multi-agent mesh with Band as the hub
* You want standard A2A clients to work with your Band agents

---

## Next Steps

#### [A2AAdapter Guide](/integrations/sdks/tutorials/a2a-adapter)

Connect Band agents to remote A2A endpoints

#### [A2AGatewayAdapter Guide](/integrations/sdks/tutorials/a2a-gateway)

Expose Band peers as A2A endpoints

#### [A2A Protocol Spec](https://a2a-protocol.org/latest/specification/)

Official A2A protocol documentation