# How to Set Up A2A Protocol Communication with Embabel: Complete Configuration Guide

> Easily set up A2A protocol communication with Embabel. Integrate the embabel-agent-a2a module in your Spring Boot app for automatic configuration and instant JSON-RPC endpoint access.

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

---

**To set up A2A protocol communication with Embabel, include the `embabel-agent-a2a` module in your Spring Boot application and rely on auto-configuration to instantiate the `AgentCardHandler` bean, which exposes the JSON-RPC endpoint at `/a2a` and publishes the Agent Card at [`.well-known/agent.json`](https://github.com/embabel/embabel-agent/blob/main/.well-known/agent.json).**

The **A2A (Agent-to-Agent)** protocol enables your Embabel agents to communicate via standardized HTTP JSON-RPC endpoints that external systems can query. By integrating the `embabel-agent-a2a` module from the [embabel/embabel-agent](https://github.com/embabel/embabel-agent) repository, you expose any Embabel agent to interoperable workflows without writing custom controller logic.

## Core Architecture of the A2A Implementation

The A2A protocol implementation consists of three coordinated components that wire automatically via Spring Boot auto-configuration. Understanding these classes helps you debug connectivity issues and extend default behaviors.

### A2AConfiguration and AgentCardHandler

The `A2AConfiguration` class located at [`embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/config/A2AConfiguration.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/config/A2AConfiguration.kt) declares the primary `AgentCardHandler` bean. This handler registers the base endpoint under the path `/a2a` and publishes the **Agent Card**—a JSON metadata document describing the agent's name, capabilities, and provider information—at `GET /a2a/.well-known/agent.json`.

### AutonomyA2ARequestHandler

Found in [`embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/support/AutonomyA2ARequestHandler.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/support/AutonomyA2ARequestHandler.kt), this class receives the JSON-RPC payload from incoming HTTP requests. It forwards the deserialized message to the Embabel core `AgentPlatform` for processing, then constructs the appropriate response for both synchronous and streaming operations.

### A2AEndpointRegistrar

The `A2AEndpointRegistrar` class in [`embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/support/A2AEndpointRegistrar.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-a2a/src/main/kotlin/com/embabel/agent/a2a/server/support/A2AEndpointRegistrar.kt) maps HTTP routes to Spring MVC controllers. It registers the main endpoint at `/a2a` along with task-specific sub-routes (`/a2a/tasks/*`), enabling the server to handle normal JSON-RPC calls and streaming connections through the same infrastructure.

## Enabling Auto-Configuration

No manual bean definitions are required if you use Spring Boot's component scanning. Ensure your application or test class scans the `com.embabel.agent.a2a` package and enables auto-configuration:

```kotlin
@SpringBootApplication
@ComponentScan(basePackages = ["com.embabel.agent.a2a"])
@EnableAutoConfiguration
class MyEmbabelApplication

```

When the application context initializes, the `A2AEndpointRegistrar` automatically binds the routes. The `AgentCardHandler` becomes available immediately, exposing both the metadata endpoint and the message processing interface.

## Testing A2A Communication

The `A2AWebIntegrationTest` class in [`embabel-agent-a2a/src/test/kotlin/com/embabel/agent/a2a/server/A2AWebIntegrationTest.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-a2a/src/test/kotlin/com/embabel/agent/a2a/server/A2AWebIntegrationTest.kt) demonstrates the complete interaction pattern using `MockMvc`.

### Retrieving the Agent Card

Verify your setup by fetching the Agent Card to inspect capabilities and endpoint metadata:

```kotlin
@Test
fun `get agent card`() {
    val result = mockMvc.get("/a2a/.well-known/agent.json")
        .andExpect { status { isOk() } }
        .andReturn()
    
    val card = objectMapper.readValue(
        result.response.contentAsString, 
        AgentCard::class.java
    )
    println(card) // Contains name, description, capabilities, supported I/O modes
}

```

### Sending Standard Messages

Construct a `Message` object, wrap it in a `SendMessageRequest`, and POST to `/a2a`:

```kotlin
@Test
fun `send message`() {
    val message = Message.Builder()
        .role(Message.Role.USER)
        .parts(listOf(TextPart("Hello!")))
        .messageId("msg-1")
        .taskId("task-1")
        .contextId("ctx-1")
        .build()
    
    val params = MessageSendParams.Builder()
        .message(message)
        .build()
    
    val request = SendMessageRequest.Builder()
        .jsonrpc(JSONRPCRequest.JSONRPC_VERSION)
        .method(SendMessageRequest.METHOD)
        .id("msg-1")
        .params(params)
        .build()

    val result = mockMvc.post("/a2a") {
        contentType = MediaType.APPLICATION_JSON
        content = objectMapper.writeValueAsString(request)
    }.andExpect { status { isOk() } }
      .andReturn()

    val response = objectMapper.readValue(
        result.response.contentAsString, 
        SendMessageResponse::class.java
    )
    println(response.result) // Task with completed status and conversation history
}

```

### Handling Streaming Requests

For streaming scenarios, submit a `SendStreamingMessageRequest` to the same endpoint:

```kotlin
@Test
fun `send streaming message`() {
    val request = SendStreamingMessageRequest.Builder()
        .jsonrpc(JSONRPCRequest.JSONRPC_VERSION)
        .method(SendStreamingMessageRequest.METHOD)
        .id("stream-1")
        .params(/* MessageSendParams containing the message */)
        .build()

    mockMvc.post("/a2a") {
        contentType = MediaType.APPLICATION_JSON
        content = objectMapper.writeValueAsString(request)
    }.andExpect { status { isOk() } }
}

```

The server accepts the streaming payload immediately. Server-Sent Events (SSE) transport is handled separately by the underlying Spring MVC infrastructure once the request is accepted.

## Summary

- The **A2A protocol** exposes Embabel agents as JSON-RPC HTTP endpoints mounted at `/a2a`.
- **Auto-configuration** via `A2AConfiguration` creates the `AgentCardHandler` bean automatically when the `embabel-agent-a2a` module is detected on the classpath.
- The **Agent Card** publishes service metadata at [`/a2a/.well-known/agent.json`](https://github.com/embabel/embabel-agent/blob/main//a2a/.well-known/agent.json), enabling discovery by other agents.
- **Request processing** is handled by `AutonomyA2ARequestHandler`, which delegates to the core `AgentPlatform` for business logic execution.
- Both **standard** (`SendMessageRequest`) and **streaming** (`SendStreamingMessageRequest`) interaction patterns are supported without additional configuration.

## Frequently Asked Questions

### What is the default URL path for the A2A endpoint in Embabel?

The A2A endpoint mounts at `/a2a` for all JSON-RPC message traffic. The Agent Card describing the agent's capabilities is available at `GET /a2a/.well-known/agent.json`. These paths are registered automatically by the `A2AEndpointRegistrar` class during application startup.

### Does Embabel support streaming messages via A2A?

Yes. The `AutonomyA2ARequestHandler` accepts `SendStreamingMessageRequest` payloads at the same `/a2a` endpoint. While the request body initiates the stream, the actual Server-Sent Events (SSE) transport is handled separately by the underlying Spring MVC infrastructure.

### How do I verify my A2A setup is working correctly?

Run the `A2AWebIntegrationTest` suite located in [`embabel-agent-a2a/src/test/kotlin/com/embabel/agent/a2a/server/A2AWebIntegrationTest.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-a2a/src/test/kotlin/com/embabel/agent/a2a/server/A2AWebIntegrationTest.kt). This test validates Agent Card retrieval, standard message processing, and streaming request acceptance using `MockMvc` to simulate HTTP traffic against the full endpoint stack.

### What dependencies are required to enable A2A protocol support?

You must include the `embabel-agent-a2a` module in your classpath. Spring Boot's auto-configuration detects the presence of this module and instantiates the required beans—including `AgentCardHandler`, `AutonomyA2ARequestHandler`, and `A2AEndpointRegistrar`—without requiring explicit configuration in your application code.