docs: add AGENTS.md coding guide #596

ehsavoie · 2026-01-16T14:48:02Z

Provides examples and guidelines for AI-assisted coding.

Fixes #595 🦕

gemini-code-assist · 2026-01-16T14:48:19Z

Summary of Changes

Hello @ehsavoie, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new, detailed guide for AI agents to understand and interact with the A2A Java SDK, covering its core components, development practices, and architectural patterns. Simultaneously, it vastly improves the documentation for the 'extras' modules, offering in-depth explanations and usage scenarios for implementing production-grade persistence and distributed event management solutions, thereby enabling developers to build more scalable and resilient A2A applications.

Highlights

New AI Agent Guide: A comprehensive AGENTS.md file has been added, providing essential context, quick start instructions, architectural overview, development guidelines, and common patterns for AI agents working with the A2A Java SDK.
Enhanced Extras Module Documentation: The extras/README.md has been significantly expanded to detail optional modules for production-ready persistence and distributed capabilities, including JPA-based TaskStore and PushNotificationConfigStore, and a Replicated Queue Manager, complete with use cases, features, and recommended configurations.
Gitignore Updates: The .gitignore file has been updated to include nbactions.xml and .bob, ensuring these build-related and configuration files are not tracked by Git.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces an excellent AGENTS.md coding guide, which will be a great resource for developers and AI agents working on this project. The guide is comprehensive and well-structured. Additionally, the extras/README.md has been significantly improved, providing much-needed clarity on the purpose and usage of the extras modules. My review includes a couple of suggestions to further enhance the documentation's clarity and consistency.

AGENTS.md

extras/README.md

jmesnil

I'm not a big agent user so take everything I commented with a grain of salt.

But this file looks like a SNAPSHOT of the content of this repo at this current time instead of explanation of what is the intent of that repo

AGENTS.md

jmesnil · 2026-01-16T15:05:43Z

AGENTS.md

+- **License**: Apache 2.0
+- **Repository**: https://github.com/a2aproject/a2a-java
+
+## Quick Start Guide


is that required in the AGENTS.md? It seems to be user doc (that should be in the README)

Claude seemed to think so

jmesnil · 2026-01-16T15:07:33Z

AGENTS.md

+
+## Architecture
+
+### Multi-Module Maven Project Structure


I'm not sure this file should contain a snapshot of the layout. The AI can figure it out.
It'd be better to state that the project uses a multi-module mven project structure and separates its different components based on their targets (server-side, client-side), transport and goals (eg reference server for tck)

AGENTS.md

ehsavoie · 2026-01-19T09:56:14Z

/Gemini review

gemini-code-assist

Code Review

This pull request introduces a new AGENTS.md guide, which is a valuable addition for AI agents working with the codebase, providing essential context and coding guidelines. The extras/README.md has been significantly updated to offer a more comprehensive overview of the optional modules, greatly improving clarity for developers. The .gitignore updates are minor but correct. Overall, these changes enhance the project's documentation and maintainability.

gemini-code-assist · 2026-01-19T09:57:48Z

AGENTS.md

+### Code Quality Standards
+
+- **Null Safety**: Uses JSpecify annotations and NullAway for compile-time null checking
+- **Error Handling**: Custom error types extending `JSONRPCError`


The guide states that "Error Handling: Custom error types extending JSONRPCError". While JSONRPCError is a valid error type, the general rules for this project suggest that application-level errors should extend Exception or RuntimeException. The examples in the "Common Patterns in Codebase" section correctly show custom errors extending A2AError (which extends RuntimeException). Please clarify this statement to align with the general rules and the provided examples, emphasizing that A2AError should be the base for custom application-level errors, and JSONRPCError is for protocol-specific issues.

References

Application-level errors should extend Exception or RuntimeException, not java.lang.Error.

gemini-code-assist · 2026-01-19T09:57:48Z

AGENTS.md

+// BAD - Over-engineered
+public String extractText(Message msg) {
+    return Optional.ofNullable(msg.parts())
+        .orElse(Collections.emptyList())
+        .stream()
+        .filter(TextPart.class::isInstance)
+        .map(TextPart.class::cast)
+        .map(TextPart::text)
+        .collect(Collectors.joining());
+}


In the "KISS (Keep It Simple, Stupid)" section, the "BAD - Over-engineered" example uses Optional.ofNullable and streams. While the "GOOD" example is indeed simpler for this specific case, labeling the stream-based approach as universally "BAD" might be too strong. This style can be beneficial and more readable in other, more complex scenarios. Consider rephrasing the comment to emphasize clarity for simple cases, rather than implying that stream-based operations are inherently over-engineered or bad practice.

gemini-code-assist · 2026-01-19T09:57:48Z

extras/README.md

-[`queue-manager-replicated`](./queue-manager-replicated/README.md) - Replaces the default `InMemoryQueueManager` with a `QueueManager` supporting replication to other A2A servers implementing the same agent. Required for multi-instance deployments. You can write your own `ReplicationStrategy`, or use the provided MicroProfile Reactive Messaging implementation with Apache Kafka, Pulsar, or AMQP.
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        a2a-java-sdk-parent                                      │


The ASCII art diagram for "Module Dependencies" is a great visual aid. However, there's a minor typo in the parent POM name: a2a-java-sdk-parent should be a2a-java-sdk-parent. Also, the ◄─────SPI arrows are not standard ASCII characters and might not render correctly in all environments. Consider replacing them with standard ASCII characters or using a tool that generates diagrams directly from text (e.g., PlantUML, Mermaid) for better maintainability and consistent rendering.

Suggested change

│ a2a-java-sdk-parent │

┌─────────────────────────────────────────────────────────────────────┐

│ a2a-java-sdk-parent │

gemini-code-assist · 2026-01-19T09:57:48Z

extras/README.md

+- **`task-store-database-jpa`**: Depends on `server-common`, `jsonrpc-common`, and `extras/common`
+- **`push-notification-config-store-database-jpa`**: Depends on `server-common` and `extras/common`
+- **`queue-manager-replicated-core`**: Depends on `server-common`, `jsonrpc-common`, and `extras/common`
+- **`replication-mp-reactive`**: Depends on `queue-manager-replicated-core` and MicroProfile Reactive Messaging


The dependency descriptions for task-store-database-jpa and queue-manager-replicated-core list jsonrpc-common as a dependency. It seems unusual for persistence and queue management modules to directly depend on a protocol-specific common module unless there's a clear, shared utility or data format requirement. This could introduce unnecessary coupling. Please verify if jsonrpc-common is strictly necessary for these modules. If not, consider refactoring to remove the dependency or move any truly shared utilities to a more general common module.

gemini-code-assist · 2026-01-19T09:57:48Z

extras/README.md

+    <groupId>io.github.a2asdk</groupId>
+    <artifactId>a2a-java-sdk-http-client-vertx</artifactId>
+</dependency>


The main README.md explicitly states that the groupId io.github.a2asdk is temporary and will likely change. This extras/README.md also uses this groupId in its examples but lacks the same temporary note. To maintain consistency and avoid confusion for users, please add a similar note about the temporary groupId here.

Suggested change

<groupId>io.github.a2asdk</groupId>

<artifactId>a2a-java-sdk-http-client-vertx</artifactId>

</dependency>





<dependency>

Complete AI agent guide with quick start, architecture overview, coding principles (KISS/DRY), and enhanced extras module documentation. Fixes a2aproject#595 🦕 Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>

gemini-code-assist bot reviewed Jan 16, 2026

View reviewed changes

AGENTS.md Show resolved Hide resolved

extras/README.md Show resolved Hide resolved

jmesnil reviewed Jan 16, 2026

View reviewed changes

ehsavoie force-pushed the agents_md branch 5 times, most recently from 313ba4e to fd142c9 Compare January 19, 2026 09:55

gemini-code-assist bot reviewed Jan 19, 2026

View reviewed changes

docs: Add AGENTS.md guide and enhance extras documentation

cf28aee

Complete AI agent guide with quick start, architecture overview, coding principles (KISS/DRY), and enhanced extras module documentation. Fixes a2aproject#595 🦕 Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>

ehsavoie force-pushed the agents_md branch from fd142c9 to cf28aee Compare January 19, 2026 10:11

	│ a2a-java-sdk-parent │
	┌─────────────────────────────────────────────────────────────────────┐
	│ a2a-java-sdk-parent │

docs: add AGENTS.md coding guide #596

Are you sure you want to change the base?

docs: add AGENTS.md coding guide #596

Uh oh!

Conversation

ehsavoie commented Jan 16, 2026

Uh oh!

gemini-code-assist bot commented Jan 16, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

jmesnil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jmesnil Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

ehsavoie Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

jmesnil Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ehsavoie commented Jan 19, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants