Content
# A2A Spring Boot 3.5.3 Multi-Module Project
This project is set up under `e:\project\GPT\A2A-0.3.0` and includes:
- `a2a-server`: A Spring Boot server example that integrates the basic skeleton of A2A AgentCard and AgentExecutor, providing a JSON-RPC endpoint.
- `a2a-client`: A Spring Boot client example that demonstrates JSON-RPC calls.
- `spec-grpc`: The A2A gRPC specification module, responsible for generating gRPC Java classes.
## Version and Dependencies
- Spring Boot: `3.5.3`
- Java: `17`
- A2A Java SDK reference implementation dependency version: `0.3.0.Beta2` (release information can be found at https://github.com/a2aproject/a2a-java/releases)
> Note: The reference implementation module is currently based on Quarkus, but it includes A2A specifications and common classes for easy reference and subsequent adaptation in a Spring environment.
## Quick Start
1. (Optional) Copy the A2A gRPC specification:
- Obtain the latest `a2a.proto` from `https://github.com/a2aproject/A2A/blob/main/specification/grpc/a2a.proto`
- Overwrite it in `spec-grpc/src/main/proto/a2a.proto`
- Ensure the proto file has the following setting:
```
option java_package = "io.a2a.grpc";
```
2. Generate gRPC classes (if using gRPC):
- Execute the following in the project root directory:
- `mvn clean install -Pproto-compile`
3. Build the project:
- Execute in the root directory: `mvn clean install`
4. Run the server:
- Navigate to `a2a-server`: `mvn spring-boot:run`
- Default server port: `10001`
- Health check: `http://localhost:10001/actuator/health`
- HarmonyOS Agent JSON-RPC endpoint: `POST http://localhost:10001/agent/message`
- The server will return a standard JSON-RPC response based on the request method or push SSE messages via `Content-Type: text/event-stream`.
- `initialize` / `notifications/initialized`: Establish a session and return `agentSessionId`.
- `message/stream`: Return `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` event streams during the conversation.
- `tasks/cancel`, `clearContext`, `authorize`, `deauthorize`: Synchronous JSON-RPC responses.
5. Run the client:
- Navigate to `a2a-client`: `mvn spring-boot:run`
- The console will print the text content returned from the JSON-RPC call.
## Code Structure Explanation
- Server Example:
- `com.example.a2a.server.agent.WeatherAgent`: Example Agent that provides a pseudo weather query.
- `com.example.a2a.server.agent.WeatherAgentConfig`:
- `@Bean @PublicAgentCard` exposes the `AgentCard`.
- `@Bean` exposes the `AgentExecutor`, with an example implementation that extracts text from task input and returns a message.
- `com.example.a2a.server.transport.agent.AgentMessageController`: HarmonyOS Agent specification `/agent/message` controller.
- `com.example.a2a.server.transport.agent.dto.AgentJsonRpcDtos`: HarmonyOS Agent specification JSON-RPC request/response DTO.
- `com.example.a2a.server.transport.JsonRpcController`: JSON-RPC controller.
- `com.example.a2a.server.transport.JsonRpcDtos`: JSON-RPC request/response DTO.
- Client Example:
- `com.example.a2a.client.ClientService`: Uses JSON-RPC to call the server's `/jsonrpc` interface.
- `com.example.a2a.client.jsonrpc.JsonRpcDtos`: Client JSON-RPC DTO.
- gRPC Specification:
- The `spec-grpc` module uses `protobuf-maven-plugin` and `grpc-java` plugin to generate Java classes in a Windows environment.
## Suggestions for Future Integration
- Transport Layer Options:
- JSON-RPC: Depends on `a2a-java-sdk-reference-jsonrpc` (currently provides a simplified JSON-RPC endpoint for demonstration).
- gRPC: Depends on `a2a-java-sdk-reference-grpc` and uses classes generated by `spec-grpc`.
- REST: Depends on `a2a-java-sdk-reference-rest`.
- Adapting A2A in a Spring Environment:
- Adaptation Points: Routing and controllers (exposing A2A task processing flows as REST/JSON-RPC/gRPC endpoints).
- Use `AgentExecutor` and `TaskUpdater` to manage task status and event queues (the current JSON-RPC example directly calls the example Agent).
- HarmonyOS Agent RPC Compatibility Notes:
- `initialize`, `notifications/initialized`: Establish and maintain a session with a seven-day validity period through `AgentMessageController` and `AgentSessionService`.
- `message/stream`: `StreamingTaskService` uses `SseEmitter` to push `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`, conforming to SSE format.
- `tasks/cancel`, `clearContext`: Manage tasks and context in conjunction with `StreamingTaskService` and `ConversationContextService`.
- `authorize`, `deauthorize`: `AuthorizationService` supports generating/revoking `agentLoginSessionId`.
## Notes
- If the build fails, please ensure:
- JDK 17+ is installed and `JAVA_HOME` is configured correctly.
- Maven is installed and can execute `mvn -v`.
- `spec-grpc` has been replaced with the actual `a2a.proto` before executing `-Pproto-compile`.
