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.

gemini-code-assist · 2026-01-16T14:53:30Z

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 "Code Quality Standards" section states that custom error types extend JSONRPCError. This seems specific to the JSON-RPC transport. Since the SDK also supports gRPC and REST, which use different error handling mechanisms (e.g., gRPC status codes for gRPC, HTTP status codes for REST), it would be beneficial to clarify the error handling strategy for each supported transport to avoid potential confusion for developers using other protocols.

gemini-code-assist · 2026-01-16T14:53:30Z

extras/README.md

+<!-- Event replication across instances -->
+<dependency>
+    <groupId>io.github.a2asdk</groupId>
+    <artifactId>a2a-java-queue-manager-replicated-core</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.github.a2asdk</groupId>
+    <artifactId>a2a-java-queue-manager-replication-mp-reactive</artifactId>
+</dependency>


The artifact IDs for the replicated queue manager modules (a2a-java-queue-manager-replicated-core and a2a-java-queue-manager-replication-mp-reactive) appear to be missing the extras prefix that is present in other modules in this directory (e.g., a2a-java-extras-task-store-database-jpa). For better consistency and discoverability, consider renaming these artifacts to include the extras prefix. This would make the naming convention for all extras modules uniform.

Suggested change



<dependency>

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

<artifactId>a2a-java-queue-manager-replicated-core</artifactId>

</dependency>

<dependency>

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

<artifactId>a2a-java-queue-manager-replication-mp-reactive</artifactId>

</dependency>



<dependency>

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

<artifactId>a2a-java-extras-queue-manager-replicated-core</artifactId>

</dependency>

<dependency>

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

<artifactId>a2a-java-extras-queue-manager-replication-mp-reactive</artifactId>

</dependency>

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

jmesnil · 2026-01-16T15:03:50Z

AGENTS.md

+**A2A Java SDK** is a comprehensive Java implementation of the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/), enabling Java applications to run as A2A servers and communicate with other A2A agents.
+
+- **Language**: Java 17+
+- **Build Tool**: Maven


Maven 3.x maybe?

jmesnil · 2026-01-16T15:04:44Z

AGENTS.md

+
+- **Language**: Java 17+
+- **Build Tool**: Maven
+- **Primary Framework**: Quarkus (for reference implementations)


We should instead state that the SDK is framework agnostic and provides a reference server based on Quarkus.
We don't want AI to bring Quarkus code in the core of the SDK

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

…ect#584) Introduce ServiceLoader-based A2AHttpClient client architecture with two implementations: - JDK HttpClient (core, always available) - Vert.x WebClient (optional, high-performance) Changes: - Create http-client-vertx module for Vert.x implementation - Add ServiceLoader infrastructure (A2AHttpClientFactory, providers) - Update dependent modules to use Vert.x client by default - Add comprehensive tests and usage examples Users can choose implementation via Maven dependencies. Priority-based selection: Vert.x (100) > JDK (0). Fixes a2aproject#583 🦕 Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>

gemini-code-assist bot reviewed Jan 16, 2026

View reviewed changes

jmesnil reviewed Jan 16, 2026

View reviewed changes

ehsavoie force-pushed the agents_md branch 3 times, most recently from 5965296 to 83e1b22 Compare January 16, 2026 17:15

ehsavoie force-pushed the agents_md branch from 83e1b22 to 313ba4e Compare January 16, 2026 17:29

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!

gemini-code-assist bot Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

jmesnil left a comment

Choose a reason for hiding this comment

Uh oh!

jmesnil 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants