Skip to content

feat: jsonrpc and agentcard v0.3 compat code#225

Merged
yarolegovich merged 13 commits intorelease/spec-v1from
yarolegovich/compat-test
Feb 20, 2026
Merged

feat: jsonrpc and agentcard v0.3 compat code#225
yarolegovich merged 13 commits intorelease/spec-v1from
yarolegovich/compat-test

Conversation

@yarolegovich
Copy link
Copy Markdown
Member

  • Added a2asrv.AgentCardJSONProducer so that users can influence how agent card gets serialized to JSON.
  • Added agentcard.Parser so that that users can influence how agent card gets parsed.
  • Added a2acompat/a2av0 package which implements serving a union of v0.3 and v1.0 cards so that these can be understand by both new and old clients.
  • Added implementations for v0.3 jsonrpc client transport and server handler.
  • Added a test which build a simple server and client which depends on the release v0.3.6 and tests the latest code against it to verify compatibility.

@gemini-code-assist
Copy link
Copy Markdown
Contributor

Summary of Changes

Hello @yarolegovich, I'm Gemini Code Assist1! 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 significantly enhances the interoperability of the A2A Go SDK by introducing a dedicated compatibility layer for protocol version 0.3. It allows agents and clients to communicate regardless of whether they are using the latest protocol version or the older v0.3. This is achieved through flexible parsing and serialization mechanisms for AgentCards and specific JSON-RPC client/server implementations for the older protocol, all validated by comprehensive end-to-end tests.

Highlights

  • v0.3 Compatibility Package: Introduced a new a2acompat/a2av0 package to provide comprehensive compatibility with v0.3 of the A2A protocol, enabling seamless interaction between agents and clients running different protocol versions.
  • Customizable AgentCard Parsing: Added an agentcard.Parser interface and a default implementation, allowing users to define custom logic for parsing AgentCards from various formats, including older protocol versions.
  • Customizable AgentCard JSON Serialization: Implemented a2asrv.AgentCardJSONProducer to give developers control over how AgentCards are serialized to JSON, facilitating the creation of AgentCards compatible with older clients.
  • v0.3 JSON-RPC Client and Server: Provided dedicated JSON-RPC client transport and server handler implementations within the a2acompat/a2av0 package, specifically designed to handle v0.3 protocol messages and conversions.
  • End-to-End Compatibility Tests: Added a robust end-to-end test suite to verify compatibility between new and old clients/servers, ensuring that agents can communicate effectively across v0.3 and v1.0 protocol boundaries.
Changelog
  • .vscode/settings.json
    • Added a directory filter to exclude the new compatibility test directory from gopls UI.
  • a2aclient/agentcard/resolver.go
    • Introduced a Parser type and DefaultCardParser for custom AgentCard unmarshaling.
    • Updated DefaultResolver and Resolver struct to include the new CardParser field.
    • Modified the Resolve method to utilize the configurable CardParser for processing AgentCard responses.
  • a2aclient/jsonrpc.go
    • Removed internal jsonrpcRequest and jsonrpcResponse structs.
    • Updated client-side JSON-RPC request and response handling to use centralized types from internal/jsonrpc.
  • a2aclient/jsonrpc_test.go
    • Updated test helper functions and test cases to reflect the use of jsonrpc.ClientRequest and jsonrpc.ClientResponse.
  • a2acompat/a2av0/agentcard.go
    • Added NewAgentCardParser to convert v0.3 AgentCards to v1.0 format.
    • Added NewStaticAgentCardProducer and NewAgentCardProducer to serialize v1.0 AgentCards into a union of v1.0 and v0.3 formats.
    • Implemented extensive mapping functions for converting between v0.3 and v1.0 AgentCard structures, including security schemes, interfaces, and skills.
    • Defined v0.3 specific agentCard and related structs for compatibility.
  • a2acompat/a2av0/agentcard_test.go
    • Added unit tests for AgentCard compatibility, covering conversions from new-to-new, compat-to-new, and old-to-new formats.
  • a2acompat/a2av0/conversions.go
    • Added comprehensive conversion functions between v1.0 (a2a) and v0.3 (a2av0) types for tasks, messages, events, and push configurations.
  • a2acompat/a2av0/doc.go
    • Updated copyright year to 2026.
    • Removed the ProtocolVersion type alias, directly using a2a.ProtocolVersion.
  • a2acompat/a2av0/jsonrpc.go
    • Added constants for JSON-RPC method names specific to the v0.3 protocol.
  • a2acompat/a2av0/jsonrpc_client.go
    • Added a new JSON-RPC client transport implementation for v0.3, including methods for sending messages, streaming, task management, and push notification configuration.
    • Integrated conversion functions to translate between v1.0 and v0.3 data structures for client requests and responses.
  • a2acompat/a2av0/jsonrpc_server.go
    • Added a new JSON-RPC server handler for v0.3, capable of processing various A2A methods and streaming requests.
    • Incorporated conversion logic to handle incoming v0.3 requests and outgoing v0.3 responses.
  • a2acompat/a2av0/types.go
    • Defined v0.3 specific data structures for messages, tasks, events, content parts, and various request/response parameters.
    • Implemented custom JSON marshaling and unmarshaling logic for these v0.3 types to ensure proper serialization and deserialization.
  • a2asrv/agentcard.go
    • Introduced AgentCardJSONProducer interface for producers that return raw JSON.
    • Modified NewAgentCardHandler to prioritize AgentCardJSONProducer for direct JSON output, falling back to standard AgentCardProducer if not implemented.
  • a2asrv/jsonrpc.go
    • Removed internal jsonrpcRequest and jsonrpcResponse structs.
    • Updated server-side JSON-RPC request and response handling to use centralized types from internal/jsonrpc.
    • Replaced internal isValidID function with jsonrpc.IsValidID.
  • a2asrv/jsonrpc_test.go
    • Updated test cases to use jsonrpc.ServerRequest for JSON-RPC request payloads.
  • e2e/compat/compat_test.go
    • Added end-to-end compatibility tests to validate interaction between new and old A2A clients and servers.
    • Included scenarios for an old client communicating with a new server and a new client communicating with an old server.
  • e2e/compat/v0_3/go.mod
    • Added a new Go module file for the v0.3 compatibility test binary, specifying github.com/a2aproject/a2a-go v0.3.6 as a dependency.
  • e2e/compat/v0_3/go.sum
    • Added a new Go sum file for the v0.3 compatibility test binary, listing module checksums.
  • e2e/compat/v0_3/main.go
    • Added a main application for the v0.3 compatibility test binary, implementing both client and server modes for testing against different versions of the A2A SDK.
  • internal/jsonrpc/jsonrpc.go
    • Added IsValidID function for validating JSON-RPC request IDs.
    • Defined new centralized structs: ServerRequest, ServerResponse, ClientRequest, and ClientResponse to standardize JSON-RPC type definitions across the SDK.
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.

Footnotes

  1. 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.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces backward compatibility with v0.3 of the A2A protocol, which is a significant and well-structured feature addition. The changes include a compatibility layer for agent cards and JSON-RPC, along with extensive end-to-end tests to ensure old and new clients/servers can communicate. The refactoring to centralize JSON-RPC types is also a good improvement. I've identified a critical issue with a typo in a security scheme, a high-severity issue where an error is ignored which could lead to data corruption, and a few medium-severity issues related to error handling and placeholders in new files. Overall, this is a solid contribution.

Base automatically changed from yarolegovich/protocol-negotiation to release/spec-v1 February 20, 2026 13:52
@yarolegovich yarolegovich merged commit 98b1078 into release/spec-v1 Feb 20, 2026
4 checks passed
@yarolegovich yarolegovich deleted the yarolegovich/compat-test branch February 20, 2026 15:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants