https://github.com/a2ap/a2a4j

A2A4J is a comprehensive Java implementation of the Agent2Agent Protocol, including server, client, examples, and starters.
https://github.com/a2ap/a2a4j

a2a a2a-client a2a-protocol a2a-server ai java llm mcp spring springboot

Last synced: 4 months ago
JSON representation

A2A4J is a comprehensive Java implementation of the Agent2Agent Protocol, including server, client, examples, and starters.

Host: GitHub
URL: https://github.com/a2ap/a2a4j
Owner: a2ap
License: apache-2.0
Created: 2025-05-18T01:16:25.000Z (12 months ago)
Default Branch: main
Last Pushed: 2025-06-24T14:57:27.000Z (11 months ago)
Last Synced: 2025-06-24T15:52:44.866Z (11 months ago)
Topics: a2a, a2a-client, a2a-protocol, a2a-server, ai, java, llm, mcp, spring, springboot
Language: Java
Homepage:
Size: 760 KB
Stars: 34
Watchers: 1
Forks: 15
Open Issues: 3
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

awesome-a2a - a2a4j - A2A4J is a comprehensive Java implementation of the Agent2Agent Protocol, including server, client, examples, and a starter — ready to use out of the box. (⚙️ Implementations & Libraries)
awesome-java - A2A4J

README

          # A2A4J - Agent2Agent Protocol for Java

[![Maven Central](https://img.shields.io/maven-central/v/io.github.a2ap/a2a4j)](https://search.maven.org/artifact/io.github.a2ap/a2a4j)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[![Java Version](https://img.shields.io/badge/Java-17%2B-green.svg)](https://openjdk.org/projects/jdk/17/)

📖 **[中文文档](README_CN.md)**

[Agent2Agent (A2A)](https://github.com/google-a2a/A2A) providing an open standard for communication and interoperability between independent AI agent systems.

[A2A4J](https://github.com/a2ap/a2a4j) A2A4J is a comprehensive Java implementation of the Agent2Agent (A2A) Protocol, including server, client, examples, and starters. Built on Reactor for reactive programming support, A2A4J enables agents to discover each other's capabilities, collaborate on tasks, and securely exchange information without needing access to each other's internal state.

## 🚀 Features

- ✅ **Complete A2A Protocol Support** - Full implementation of the Agent2Agent specification

- ✅ **JSON-RPC 2.0 Communication** - Standards-based request/response messaging

- ✅ **Server-Sent Events Streaming** - Real-time task updates and streaming responses

- ✅ **Task Lifecycle Management** - Comprehensive task state management and monitoring

- ✅ **Spring Boot Integration** - Easy integration with Spring Boot applications

- ✅ **Reactive Programming Support** - Built on Reactor for scalable, non-blocking operations

- ✅ **Multiple Content Types** - Support for text, files, and structured data exchange

- ⚪️ **Agent Card Discovery** - Dynamic capability discovery mechanism

- ⚪️ **Push Notification Configuration** - Asynchronous task updates via webhooks

- ⚪️ **Enterprise Security** - Authentication and authorization support

## 📋 Prerequisites

- **Java 17+** - Required for running the application

- **Maven 3.6+** - Build tool

## 🏗️ Project Structure

```

a2a4j/

├── a2a4j-bom/                     # A2A4J dependency management

├── a2a4j-core/                    # Core A2A protocol implementation

├── a2a4j-spring-boot-starter/     # Spring Boot auto-configuration

│   ├── a2a4j-server-spring-boot-starter/   # Server-side starter

│   └── a2a4j-client-spring-boot-starter/   # Client-side starter

├── a2a4j-samples/                 # Example implementations

│   └── server-hello-world/        # Hello World server example

│   └── client-hello-world/        # Hello World client example

├── specification/                 # A2A protocol specification

├── tools/                        # Development tools and configuration

```

## 🚀 Quick Start

### 1. Use A2Aj Build Agent

#### Integrate A2A4j SDK

If you’re building on the `SpringBoot` framework, it is recommended to use `a2a4j-server-spring-boot-starter`.

```xml

    io.github.a2ap

    a2a4j-server-spring-boot-starter

    0.0.1

```

For other frameworks, it is recommended to use `a2a4j-core`.

```xml

    io.github.a2ap

    a2a4j-core

    0.0.1

```

#### Expose an External Endpoint

```java

@RestController

public class MyA2AController {

    @Autowired

    private A2AServer a2aServer;

    @Autowired

    private final Dispatcher a2aDispatch;

    @GetMapping(".well-known/agent.json")

    public ResponseEntity getAgentCard() {

        AgentCard card = a2aServer.getSelfAgentCard();

        return ResponseEntity.ok(card);

    }

    @PostMapping(value = "/a2a/server", produces = MediaType.APPLICATION_JSON_VALUE)

    public ResponseEntity handleA2ARequestTask(@RequestBody JSONRPCRequest request) {

        return ResponseEntity.ok(a2aDispatch.dispatch(request));

    }

    @PostMapping(value = "/a2a/server", produces = MediaType.TEXT_EVENT_STREAM_VALUE)

    public Flux> handleA2ARequestTaskSubscribe(@RequestBody JSONRPCRequest request) {

        return a2aDispatch.dispatchStream(request).map(event -> ServerSentEvent.builder()

                .data(event).event("task-update").build());

    }

}

```

#### Implementing the `AgentExecutor` Interface for Agent Task Execution

```java

@Component

public class MyAgentExecutor implements AgentExecutor {

    @Override

    public Mono execute(RequestContext context, EventQueue eventQueue) {

        // your agent logic code

        TaskStatusUpdateEvent completedEvent = TaskStatusUpdateEvent.builder()

                .taskId(taskId)

                .contextId(contextId)

                .status(TaskStatus.builder()

                        .state(TaskState.COMPLETED)

                        .timestamp(String.valueOf(Instant.now().toEpochMilli()))

                        .message(createAgentMessage("Task completed successfully! Hi you."))

                        .build())

                .isFinal(true)

                .metadata(Map.of(

                        "executionTime", "3000ms",

                        "artifactsGenerated", 4,

                        "success", true))

                .build();

        eventQueue.enqueueEvent(completedEvent);

        return Mono.empty();

    }

}

```

#### Done

That’s it — these are the main steps. For detailed implementation, please refer to our [Agent Demo example](./a2a4j-samples/server-hello-world).

### 2. Test Run Agent Example

#### Run the Server Hello World

```bash

git clone https://github.com/a2ap/a2a4j.git

cd a2a4j

mvn clean install

cd a2a4j-samples/server-hello-world

mvn spring-boot:run

```

The server will start at `http://localhost:8089`.

#### Get Agent Card

```bash

curl http://localhost:8089/.well-known/agent.json

```

#### Send a Message

```bash

curl -X POST http://localhost:8089/a2a/server \

  -H "Content-Type: application/json" \

  -d '{

    "jsonrpc": "2.0",

    "method": "message/send",

    "params": {

      "message": {

        "role": "user",

        "parts": [

          {

            "kind": "text",

            "text": "Hello, A2A!"

          }

        ],

        "messageId": "9229e770-767c-417b-a0b0-f0741243c589"

      }

    },

    "id": "1"

  }'

```

#### Stream Messages

```bash

curl -X POST http://localhost:8089/a2a/server \

  -H "Content-Type: application/json" \

  -H "Accept: text/event-stream" \

  -d '{

    "jsonrpc": "2.0",

    "method": "message/stream",

    "params": {

      "message": {

        "role": "user",

        "parts": [

          {

            "kind": "text",

            "text": "Hello, streaming A2A!"

          }

        ],

        "messageId": "9229e770-767c-417b-a0b0-f0741243c589"

      }

    },

    "id": "1"

  }'

```

## 📚 Core Modules

### A2A4J Core (`a2a4j-core`)

The core module provides the fundamental A2A protocol implementation:

- **Models**: Data structures for Agent Cards, Tasks, Messages, and Artifacts

- **Server**: Server-side A2A protocol implementation

- **Client**: Client-side A2A protocol implementation

- **JSON-RPC**: JSON-RPC 2.0 request/response handling

- **Exception Handling**: Comprehensive error management

[📖 View Core Documentation](a2a4j-core/README.md)

### Spring Boot Starters

#### Server Starter (`a2a4j-server-spring-boot-starter`)

Auto-configuration for A2A servers with Spring Boot, providing:

- Automatic endpoint configuration

- Agent Card publishing

- Task management

- SSE streaming support

#### Client Starter (`a2a4j-client-spring-boot-starter`)

Auto-configuration for A2A clients with Spring Boot, providing:

- Agent discovery

- HTTP client configuration

- Reactive client support

### Examples (`a2a4j-samples`)

Complete working examples demonstrating A2A4J usage:

- **[Hello World Server](./a2a4j-samples/server-hello-world)**: Basic A2A4j server implementation

- **[Hello World Client](./a2a4j-samples/client-hello-world)**: Basic A2A4j client implementation

## 📊 JSON-RPC Methods

### Core Methods

- `message/send` - Send a message and create a task

- `message/stream` - Send a message with streaming updates

### Task Management

- `tasks/get` - Get task status and details

- `tasks/cancel` - Cancel a running task

- `tasks/resubscribe` - Resubscribe to task updates

### Push Notifications

- `tasks/pushNotificationConfig/set` - Configure push notifications

- `tasks/pushNotificationConfig/get` - Get notification configuration

## 📖 Documentation

- [A2A Protocol Specification](specification/specification.md)

- [Core Module Documentation](a2a4j-core/README.md)

- [API Reference](a2a4j-core/API_REFERENCE.md)

- [Hello World Example](a2a4j-samples/server-hello-world/README.md)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

1. Fork the repository

2. Create a feature branch: `git checkout -b feature/my-feature`

3. Commit your changes: `git commit -am 'Add new feature'`

4. Push to the branch: `git push origin feature/my-feature`

5. Submit a Pull Request

## 📄 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## 🌟 Support

- **Issues**: [GitHub Issues](https://github.com/a2ap/a2a4j/issues)

- **Discussions**: [GitHub Discussions](https://github.com/a2ap/a2a4j/discussions)

- **CI/CD**: [GitHub Actions](https://github.com/a2ap/a2a4j/actions)

## 🔗 Refer Projects

- [A2A Protocol Specification](https://google-a2a.github.io/A2A/specification/)

- [A2A Protocol Website](https://google-a2a.github.io)

---

Built with ❤️ by the A2AP Community

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/a2ap/a2a4j

Awesome Lists containing this project

README