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

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, the configuration class declares strict activation conditions:

@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 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. 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.

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, 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, 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, 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. This card typically follows this structure:

{
  "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:

{
  "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:

@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:

@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 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 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, 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}