# How to Use the A2A Protocol for Agent Federation in Spring Boot

> Learn to use the A2A protocol for agent federation in Spring Boot. Auto-configure JSON-RPC endpoints and discovery cards with Embabel. Get started today.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: how-to-guide
- Published: 2026-08-08

---

**The Embabel A2A protocol enables agent federation through auto-configured JSON-RPC endpoints and discovery cards that activate automatically in servlet-based Spring Boot applications.**

The Embabel A2A (Agent-to-Agent) protocol standardizes how distributed agents discover and communicate with each other using JSON-RPC. According to the embabel/embabel-agent source code, the protocol activates automatically when specific conditions are met, exposing well-known endpoints that allow agents to federate seamlessly across a network.

## Understanding the A2A Auto-Configuration

The A2A protocol relies on Spring Boot's auto-configuration mechanism to register its core components. In [`embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/a2a/AgentA2AAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/a2a/AgentA2AAutoConfiguration.java), the configuration class declares strict activation conditions:

```java
@AutoConfiguration
@ConditionalOnClass({AgentCardHandler.class, RequestMappingHandlerMapping.class})
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@ComponentScan(basePackages = "com.embabel.agent.a2a")
public class AgentA2AAutoConfiguration { }

```

The `@ConditionalOnWebApplication(type = SERVLET)` annotation ensures the A2A protocol only activates in servlet-based web applications. The test suite in [`AgentA2AAutoConfigurationTest.java`](https://github.com/embabel/embabel-agent/blob/main/AgentA2AAutoConfigurationTest.java) confirms that in non-web contexts, the beans are **not** created, while in servlet web contexts, `AgentCardHandler` and `A2AEndpointRegistrar` are registered automatically.

## Core Components of the A2A Protocol

When the auto-configuration conditions are satisfied, four primary beans establish the federation infrastructure:

### AgentCardHandler

The `AgentCardHandler` serves the **agent card** at the well-known endpoint [`/.well-known/agent.json`](https://github.com/embabel/embabel-agent/blob/main//.well-known/agent.json). This JSON document describes an agent's capabilities and endpoint URLs, enabling other agents to discover and interact with it. The implementation resides in [`embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/AgentCardHandler.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/AgentCardHandler.java).

### A2AEndpointRegistrar

The `A2AEndpointRegistrar` registers the JSON-RPC endpoint at `/{path}` that receives remote calls from federated agents. Located in [`embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/support/A2AEndpointRegistrar.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/support/A2AEndpointRegistrar.java), this component handles the mapping of incoming requests to the appropriate handlers.

### A2AStreamingHandler

For long-running or chunked operations, the `A2AStreamingHandler` manages streamed JSON-RPC responses. This bean, found in [`embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/support/A2AStreamingHandler.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/support/A2AStreamingHandler.java), ensures agents can handle asynchronous, multi-part data exchanges.

### AutonomyA2ARequestHandler

The `AutonomyA2ARequestHandler` bridges incoming JSON-RPC requests to the **Autonomy** service, which contains the core agent logic. Implemented in [`embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/support/AutonomyA2ARequestHandler.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-a2a-autoconfigure/src/main/java/com/embabel/agent/a2a/server/support/AutonomyA2ARequestHandler.java), this handler translates external protocol calls into internal service invocations.

## Implementing A2A Protocol for Agent Federation

### Prerequisites and Dependencies

To enable A2A protocol support, ensure the `embabel-agent-a2a-autoconfigure` module is present on your classpath. This is typically included via the broader `embabel-agent` BOM. The application must run as a **Spring Boot servlet web application** (using Tomcat, Jetty, or Undertow); standalone or reactive (WebFlux) contexts will not trigger the auto-configuration.

### Exposing the Agent Card

Once activated, the `AgentCardHandler` automatically publishes the discovery document at [`/.well-known/agent.json`](https://github.com/embabel/embabel-agent/blob/main//.well-known/agent.json). This card typically follows this structure:

```json
{
  "name": "MyAgent",
  "description": "Provides XYZ functionality",
  "endpoints": {
    "jsonRpc": "/myagent"
  }
}

```

Other agents in the federation can retrieve this card to determine available capabilities and the correct endpoint URL for JSON-RPC communication.

### Calling Remote Agents

To invoke functionality on a federated agent, send a standard JSON-RPC 2.0 POST request to the remote's endpoint:

```json
{
  "jsonrpc":"2.0",
  "method":"myFunction",
  "params":{"foo":"bar"},
  "id":1
}

```

The `AutonomyA2ARequestHandler` receives this payload, delegates execution to the Autonomy service, and returns the appropriate JSON-RPC response.

### Customizing Default Beans

Because `AgentA2AAutoConfiguration` includes `@ComponentScan(basePackages = "com.embabel.agent.a2a")`, you can override default behaviors by providing your own bean implementations. For example, to customize streaming behavior:

```java
@Bean
public A2AStreamingHandler customStreamingHandler() {
    return new MyCustomStreamingHandler();
}

```

Spring's auto-configuration will back off and use your custom implementation instead of the default.

## Minimal Spring Boot Example

Create a basic agent application with A2A federation support:

```java
@SpringBootApplication
public class MyAgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyAgentApplication.class, args);
    }

    // Optional: provide a custom Autonomy implementation
    @Bean
    public Autonomy myAutonomy() {
        return new MyAutonomyImpl();
    }
}

```

When this application starts in a servlet container, the A2A auto-configuration registers the agent card endpoint at [`/.well-known/agent.json`](https://github.com/embabel/embabel-agent/blob/main//.well-known/agent.json) and the JSON-RPC handler at the configured path automatically.

## Summary

- The A2A protocol requires a **servlet-based Spring Boot application**; it will not activate in non-web or reactive contexts.
- `AgentA2AAutoConfiguration` conditionally registers four core beans: `AgentCardHandler`, `A2AEndpointRegistrar`, `A2AStreamingHandler`, and `AutonomyA2ARequestHandler`.
- Agents expose capabilities via [`/.well-known/agent.json`](https://github.com/embabel/embabel-agent/blob/main//.well-known/agent.json) and communicate through standardized JSON-RPC endpoints.
- You can customize federation behavior by overriding beans in the `com.embabel.agent.a2a` package using standard Spring `@Bean` definitions.

## Frequently Asked Questions

### What triggers the A2A protocol auto-configuration?

The auto-configuration triggers only when `AgentCardHandler` and `RequestMappingHandlerMapping` classes are present on the classpath **and** the application runs as a servlet web application. The `@ConditionalOnWebApplication(type = SERVLET)` annotation enforces this requirement strictly.

### Can I use the A2A protocol in a reactive Spring Boot application?

No. According to the source code in [`AgentA2AAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/AgentA2AAutoConfiguration.java), the configuration explicitly requires `ConditionalOnWebApplication.Type.SERVLET`. Reactive (WebFlux) applications will not trigger the auto-configuration, and the A2A beans will not be registered.

### How do agents discover each other using the A2A protocol?

Agents discover peers by retrieving the **agent card** from the well-known endpoint [`/.well-known/agent.json`](https://github.com/embabel/embabel-agent/blob/main//.well-known/agent.json). The `AgentCardHandler` serves this JSON document, which contains the agent's name, description, and JSON-RPC endpoint URL, allowing other agents to establish communication channels.

### Can I customize the JSON-RPC endpoint path or streaming behavior?

Yes. You can provide custom implementations of `A2AEndpointRegistrar` or `A2AStreamingHandler` as Spring beans. Because the auto-configuration uses `@ComponentScan("com.embabel.agent.a2a")`, your custom beans in that package or explicit `@Bean` methods will override the default components while maintaining the rest of the federation infrastructure.