DOCSEARCHbyAlgolia
Submit Docs

A2A Java SDK

repository·main·Indexed 19 days ago

https://github.com/a2aproject/a2a-java

A multi-module Maven library that enables Java applications to function as A2A (Agent2Agent) servers or clients. It facilitates agentic communication using the A2A protocol over JSON-RPC, gRPC, and REST transports. The SDK provides various BOMs for core functionality, database and queue extras (such as JPA task stores), and Quarkus-based reference implementations.

Tokens
57.3K
Snippets
145
Records
214
Agent score
64%

What's inside a2a-java

  1. Overview of A2A Java SDK capabilities

    main

    The A2A Java SDK is a multi-module Maven library designed to implement the Agent2Agent (A2A) Protocol in Java. It supports communication via JSON-RPC, gRPC, and REST transports.

    Developers can use the SDK to build:

    • A2A Servers: Services that expose a Java agent as an A2A-compliant endpoint for discovery and communication by other agents and clients.
    • A2A Clients: Clients that connect to A2A-compliant agents to utilize streaming, push notifications, and task management.

  2. Overview of JPA Database TaskStore

    main

    The a2a-java-extras-task-store-database-jpa module provides a JPA-based implementation of the TaskStore interface. Unlike the default InMemoryTaskStore, this implementation persists tasks to a relational database using the Jakarta Persistence API (JPA 3.0+).

    Important Usage Note: Tasks are serialized to JSON before being stored in the database and deserialized from JSON when loaded. This implementation is intended for the lifetime of a Task (e.g., to allow access in load-balanced environments) rather than as a long-term archival store. Because tasks are stored as JSON based on the current A2A specification version, you may need to implement data migration if you intend to persist tasks across different protocol versions.

  3. Use the A2A Java SDK Reference Server for testing and examples

    main
    The A2A Java SDK Reference Server is a demonstration and testing implementation of the A2A SDK. It is built using Quarkus and utilizes the Vert.x Web Router for HTTP route registration. This server is ideal for developers who are already using the Quarkus framework and want a compatible environment to run tests or explore SDK examples.

  4. Integrate OpenTelemetry with A2A Java SDK

    main

    The A2A Java SDK provides OpenTelemetry integration to add distributed tracing, metrics, and context propagation to both servers and clients.

    Available Modules

    ModuleArtifact IDDescription
    Commona2a-java-sdk-opentelemetry-commonShared utilities and constants
    Servera2a-java-sdk-opentelemetry-serverServer-side tracing
    Clienta2a-java-sdk-opentelemetry-clientClient-side instrumentation
    Client Propagationa2a-java-sdk-opentelemetry-client-propagationContext propagation for async client operations

  5. OpenTelemetry Module Overview

    main

    The OpenTelemetry integration for the A2A Java SDK provides distributed tracing, metrics, and context propagation for both servers and clients. It is composed of several modules:

    ModuleArtifact IDDescription
    Commona2a-java-sdk-opentelemetry-commonShared utilities and constants
    Servera2a-java-sdk-opentelemetry-serverServer-side tracing
    Clienta2a-java-sdk-opentelemetry-clientClient-side instrumentation
    Client Propagationa2a-java-sdk-opentelemetry-client-propagationContext propagation for async client operations

  6. Use JPA Database PushNotificationConfigStore

    main

    The JpaDatabasePushNotificationConfigStore provides a JPA-based implementation of the PushNotificationConfigStore interface. It persists push notification configurations to a relational database using the Jakarta Persistence API (JPA 3.0+), making it suitable for load-balanced environments where configurations must be shared across multiple instances.

    Important Considerations:

    • Serialization: PushNotificationConfig instances are serialized to JSON before storage and deserialized from JSON when loaded.
    • Lifecycle: This is not intended as a long-term storage solution. It is designed to persist data for the lifetime of an associated Task to ensure availability in load-balanced environments.
    • Version Compatibility: Because data is stored as JSON based on the current A2A specification version, you may need to implement data migration if you wish to persist configurations across different protocol versions.

  7. Understand the A2A Java SDK Project Structure

    main

    The repository is organized into several modules based on their role in the SDK:

    ModulePurpose
    spec/A2A specification types (Java records for the protocol)
    spec-grpc/gRPC protobuf definitions and generated classes
    common/Shared utilities
    client/base/Core client API
    client/transport/spi/Transport SPI
    client/transport/jsonrpc/, grpc/, rest/Transport implementations
    server-common/Server-side core (AgentExecutor, TaskStore, QueueManager)
    transport/Server transport layer
    reference/Reference server implementations (Quarkus)
    tck/Technology Compatibility Kit
    extras/Optional add-ons (OpenTelemetry, JPA stores, Kafka queue, Vert.x, Android)
    compat-0.3/Backward compatibility layer for A2A protocol v0.3
    boms/Bill of Materials POMs
    examples/Sample applications

  8. A2A Server Integration Frameworks

    main

    The A2A Java SDK is designed to integrate with common Java application frameworks:

    • Quarkus: The official reference implementations for JSON-RPC, gRPC, and REST are built on Quarkus.
    • Jakarta EE: You can use the a2a-jakarta module to work with any Jakarta EE Web Profile runtime.

  9. Manage Vert.x HTTP Client lifecycle and CDI integration

    main

    CDI / Quarkus Integration

    In CDI environments, VertxA2AHttpClient automatically discovers and reuses the managed Vertx instance.

    Manual Lifecycle Management

    If you are not in a CDI environment, you must manage the Vertx instance manually.

    Warning: Always use try-with-resources to avoid leaking instances.

    UsageBehavior on close
    Standalone (new VertxA2AHttpClient())Both WebClient and Vertx are closed
    CDI/Quarkus (new VertxA2AHttpClient(injectedVertx))Only WebClient is closed; Vertx remains open

    Thread Safety

    • Client instances: Thread-safe; multiple threads can share one client.
    • Builder instances: NOT thread-safe; create separate builders per thread.
    // Manual management in non-CDI environments
Vertx vertx = Vertx.vertx();

try {
    try (VertxA2AHttpClient client = new VertxA2AHttpClient(vertx)) {
        A2AHttpResponse response = client.createGet()
            .url("https://example.com")
            .get();
    }
} finally {
    vertx.close();
}

  10. Understand the OpenTelemetry integration architecture

    main

    The integration test module uses a Quarkus-based architecture to validate real-world tracing. The key components are:

    • SimpleAgent: A basic A2A agent implementation that stores tasks in memory and provides echo responses.
    • AgentResource: A JAX-RS REST resource that exposes HTTP endpoints (e.g., /a2a/tasks, /a2a/messages) and delegates to the RequestHandler.
    • InstrumentedRequestHandler: A CDI Alternative that wraps the SimpleAgent with an OpenTelemetry decorator to ensure spans are created for every operation.
    • OpenTelemetryProducer: A CDI bean producer that integrates with the Quarkus OpenTelemetry extension to provide the Tracer and the OpenTelemetryRequestHandlerDecorator.

  11. How A2A Java SDK Extras work

    main

    The A2A Java SDK provides sensible in-memory defaults for task storage, push notification configuration, queue management, and HTTP communication. The extras modules are designed as drop-in replacements for these defaults to support production-grade requirements (e.g., persistence, high throughput, or multi-instance replication).

    Most extras use Java SPI or CDI alternative discovery. This means that in many cases, simply adding the specific extra dependency to your classpath is sufficient to swap the default implementation with the production-grade one, requiring no manual code changes.

  12. Use Vert.x HTTP Client for reactive applications

    main

    The VertxA2AHttpClient replaces the default JDK 11+ implementation with a Vert.x WebClient-based implementation. It is designed for reactive, non-blocking I/O and is highly recommended for Quarkus applications, high-throughput scenarios, and applications requiring efficient Server-Sent Events (SSE) streaming.

    Key Benefits

    • I/O Model: Uses an event loop (non-blocking) instead of platform threads (blocking).
    • Memory: Lower memory footprint due to a shared event loop.
    • HTTP/2: Automatic ALPN negotiation.
    • Reactive Integration: Native support for reactive frameworks.
    <!-- Add the Vert.x implementation dependency -->
<dependency>
    <groupId>org.a2aproject.sdk</groupId>
    <artifactId>a2a-java-sdk-http-client-vertx</artifactId>
</dependency>

<!-- For non-Quarkus environments, also add vertx-web-client -->
<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web-client</artifactId>
</dependency>