Skip to content

feat: use v2 suffix for module ID and provide compat support#270

Merged
yarolegovich merged 10 commits intomainfrom
yarolegovich/api-v2
Mar 9, 2026
Merged

feat: use v2 suffix for module ID and provide compat support#270
yarolegovich merged 10 commits intomainfrom
yarolegovich/api-v2

Conversation

@yarolegovich
Copy link
Copy Markdown
Member

fixes #250

@yarolegovich yarolegovich requested a review from herczyn March 9, 2026 21:15
@gemini-code-assist
Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, 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 implements a major version upgrade for the Go module, transitioning to a /v2 module path. The primary goal is to maintain backward compatibility by introducing a comprehensive a2acompat/a2av0 package. This package contains conversion logic and adapters that enable older clients and servers to communicate with their newer counterparts, ensuring a smooth migration path for users. The changes involve widespread updates to import paths across the codebase and the addition of new test cases to validate the compatibility features.

Highlights

  • Go Module Versioning: The project's Go module path has been updated to include a /v2 suffix, aligning with Go's semantic import versioning best practices for major version bumps.
  • Backward Compatibility Layer: A new a2acompat/a2av0 package has been introduced to provide conversion utilities between the previous (v0) and current (v2) API types, ensuring seamless interaction between old and new components.
  • API Type Conversions: Extensive conversion functions have been added within the compatibility layer to handle various API elements, including messages, tasks, artifacts, and push configurations, facilitating interoperability.
  • Migration Adapters: New adapters are provided for server interceptors, client interceptors, agent executors, and task stores, allowing existing legacy components to be integrated with the updated v2 API.
  • Documentation and Examples: The README.md has been updated to reflect the new go get command and revised example code, while all example projects have been updated to use the new module path.
Changelog
  • README.md
    • Updated go get command to use /v2 module path.
    • Revised example code snippets to reflect API changes (e.g., NextTextPart to NewTextPart, MessageSendParams to SendMessageRequest).
  • a2a/example_test.go
    • Updated import path to v2/a2a.
  • a2aclient/agentcard/resolver.go
    • Updated import paths to v2/....
  • a2aclient/agentcard/resolver_test.go
    • Updated import paths to v2/....
  • a2aclient/auth.go
    • Updated import paths to v2/....
  • a2aclient/auth_test.go
    • Updated import paths to v2/....
  • a2aclient/client.go
    • Updated import paths to v2/....
  • a2aclient/client_test.go
    • Updated import paths to v2/....
  • a2aclient/factory.go
    • Updated import paths to v2/....
  • a2aclient/factory_test.go
    • Updated import paths to v2/....
  • a2aclient/jsonrpc.go
    • Updated import paths to v2/....
  • a2aclient/jsonrpc_test.go
    • Updated import paths to v2/....
  • a2aclient/middleware.go
    • Updated import paths to v2/....
  • a2aclient/rest.go
    • Updated import paths to v2/....
  • a2aclient/rest_test.go
    • Updated import paths to v2/....
  • a2aclient/transport.go
    • Updated import paths to v2/....
  • a2acompat/a2av0/agentcard.go
    • Updated import paths to v2/... and added compatibility logic for agent cards.
  • a2acompat/a2av0/agentcard_test.go
    • Updated import paths to v2/....
  • a2acompat/a2av0/conversions.go
    • Added context and log imports.
    • Introduced a2alegacy alias for the old a2a package.
    • Refactored numerous conversion functions (e.g., toCompatRole to toCompatRole, toCompatTaskState to ToV1TaskState, toCompatEvent to ToV1Event) to handle conversion between v1 and legacy types, including messages, tasks, artifacts, and push configurations.
  • a2acompat/a2av0/conversions_test.go
    • Renamed from a2acompat/a2av0/conversion_test.go.
    • Updated import paths and adjusted test cases to use FromV1Parts and ToV1Parts for data part compatibility testing.
  • a2acompat/a2av0/doc.go
    • Updated import path to v2/a2a.
  • a2acompat/a2av0/jsonrpc_client.go
    • Updated import paths to v2/... and a2alegacy alias.
    • Modified JSON-RPC client methods (SendMessage, SendStreamingMessage, GetTask, CancelTask, SubscribeToTask, GetTaskPushConfig, ListTaskPushConfigs, CreateTaskPushConfig, DeleteTaskPushConfig) to use the new compatibility conversion functions (FromV1SendMessageRequest, ToV1Event, FromV1GetTaskRequest, ToV1Task, etc.).
  • a2acompat/a2av0/jsonrpc_compat_test.go
    • Added new file for JSON-RPC client and server compatibility tests, specifically for header propagation.
  • a2acompat/a2av0/jsonrpc_server.go
    • Updated import paths to v2/... and a2alegacy alias.
    • Modified JSON-RPC server methods (ServeHTTP, eventSeqToSSEDataStream, onGetTask, onCancelTask, onSendMessage, onResubscribeToTask, onSendMessageStream, onGetTaskPushConfig, onListTaskPushConfigs, onSetTaskPushConfig, onDeleteTaskPushConfig, onGetAgentCard) to use the new compatibility conversion functions (ToServiceParams, FromV1Event, ToV1GetTaskRequest, FromV1Task, etc.).
  • a2acompat/a2av0/migration.go
    • Added new file introducing migration adapters for server interceptors, client interceptors, agent executors, and task stores, allowing legacy components to be used with the v2 API.
  • a2acompat/a2av0/types.go
    • Removed file, indicating that the old type definitions are now handled by the compatibility layer.
  • a2aext/activator.go
    • Updated import paths to v2/....
  • a2aext/activator_test.go
    • Updated import paths to v2/....
  • a2aext/propagator.go
    • Updated import paths to v2/....
  • a2aext/propagator_test.go
    • Updated import paths to v2/....
  • a2aext/utils.go
    • Updated import paths to v2/....
  • a2agrpc/v0/client.go
    • Updated import paths to v2/... and a2apb alias.
  • a2agrpc/v0/compat_test.go
    • Updated import paths to v2/....
  • a2agrpc/v0/handler.go
    • Updated import paths to v2/... and a2apb alias.
  • a2agrpc/v0/handler_test.go
    • Updated import paths to v2/... and a2apb alias.
  • a2agrpc/v1/client.go
    • Updated import paths to v2/....
  • a2agrpc/v1/handler.go
    • Updated import paths to v2/....
  • a2agrpc/v1/handler_test.go
    • Updated import paths to v2/....
  • a2apb/v0/a2a_grpc.pb.go
    • Removed file.
  • a2apb/v0/doc.go
    • Removed file.
  • a2apb/v0/pbconv/from_proto.go
    • Updated import paths to v2/... and a2apb alias.
  • a2apb/v0/pbconv/from_proto_test.go
    • Updated import paths to v2/... and a2apb alias.
  • a2apb/v0/pbconv/id_codec.go
    • Updated import paths to v2/....
  • a2apb/v0/pbconv/id_codec_test.go
    • Updated import paths to v2/....
  • a2apb/v0/pbconv/to_proto.go
    • Updated import paths to v2/... and a2apb alias.
  • a2apb/v0/pbconv/to_proto_test.go
    • Updated import paths to v2/... and a2apb alias.
  • a2apb/v1/pbconv/from_proto.go
    • Updated import paths to v2/....
  • a2apb/v1/pbconv/from_proto_test.go
    • Updated import paths to v2/....
  • a2apb/v1/pbconv/to_proto.go
    • Updated import paths to v2/....
  • a2apb/v1/pbconv/to_proto_test.go
    • Updated import paths to v2/....
  • a2asrv/agentcard.go
    • Updated import paths to v2/....
  • a2asrv/agentcard_test.go
    • Updated import paths to v2/....
  • a2asrv/agentexec.go
    • Updated import paths to v2/....
  • a2asrv/eventqueue/manager.go
    • Updated import paths to v2/....
  • a2asrv/eventqueue/manager_in_memory_impl.go
    • Updated import paths to v2/....
  • a2asrv/eventqueue/manager_in_memory_impl_test.go
    • Updated import paths to v2/....
  • a2asrv/eventqueue/queue.go
    • Updated import paths to v2/....
  • a2asrv/eventqueue/queue_in_memory_impl_test.go
    • Updated import paths to v2/....
  • a2asrv/exectx.go
    • Updated import paths to v2/....
  • a2asrv/extensions.go
    • Updated import paths to v2/....
  • a2asrv/handler.go
    • Updated import paths to v2/....
    • Updated comment for WithLogger to reflect the new module path.
  • a2asrv/handler_test.go
    • Updated import paths to v2/....
  • a2asrv/intercepted_handler.go
    • Updated import paths to v2/....
  • a2asrv/intercepted_handler_test.go
    • Updated import paths to v2/....
  • a2asrv/jsonrpc.go
    • Updated import paths to v2/....
  • a2asrv/jsonrpc_test.go
    • Updated import paths to v2/....
  • a2asrv/middleware.go
    • Updated import paths to v2/....
  • a2asrv/push/api.go
    • Updated import paths to v2/....
  • a2asrv/push/doc.go
    • Updated comment to reflect the new module path.
  • a2asrv/push/sender.go
    • Updated import paths to v2/....
  • a2asrv/push/sender_test.go
    • Updated import paths to v2/....
  • a2asrv/push/store.go
    • Updated import paths to v2/....
  • a2asrv/push/store_test.go
    • Updated import paths to v2/....
  • a2asrv/rest.go
    • Updated import paths to v2/....
  • a2asrv/rest_test.go
    • Updated import paths to v2/....
  • a2asrv/taskstore/api.go
    • Updated import paths to v2/....
  • a2asrv/taskstore/inmemory.go
    • Updated import paths to v2/....
  • a2asrv/taskstore/store_test.go
    • Updated import paths to v2/....
  • a2asrv/taskstore/validator.go
    • Updated import paths to v2/....
  • a2asrv/taskstore/validator_test.go
    • Updated import paths to v2/....
  • a2asrv/workqueue/pullqueue.go
    • Updated import paths to v2/....
  • a2asrv/workqueue/pushqueue.go
    • Updated import paths to v2/....
  • a2asrv/workqueue/queue.go
    • Updated import paths to v2/....
  • e2e/compat/compat_test.go
    • Added new file for end-to-end compatibility tests between old clients/new servers and new clients/old servers.
  • e2e/compat/migration_test.go
    • Added new file for migration tests, including interceptor modifications.
  • e2e/extensions_durations_test.go
    • Updated import paths to v2/....
  • e2e/jsonrpc_test.go
    • Updated import paths to v2/....
  • e2e/tck/sut.go
    • Updated import paths to v2/....
  • e2e/tck/sut_agent_executor.go
    • Updated import paths to v2/....
  • examples/clustermode/client/main.go
    • Updated import paths to v2/....
  • examples/clustermode/server/agent.go
    • Updated import paths to v2/....
  • examples/clustermode/server/dbutil.go
    • Updated import paths to v2/....
  • examples/clustermode/server/eventqueue.go
    • Updated import paths to v2/....
  • examples/clustermode/server/main.go
    • Updated import paths to v2/....
  • examples/clustermode/server/taskstore.go
    • Updated import paths to v2/....
  • examples/clustermode/server/workqueue.go
    • Updated import paths to v2/....
  • examples/helloworld/client/main.go
    • Updated import paths to v2/....
  • examples/helloworld/server/grpc/main.go
    • Updated import paths to v2/....
  • examples/helloworld/server/jsonrpc/main.go
    • Updated import paths to v2/....
  • examples/helloworld/server/rest/main.go
    • Updated import paths to v2/....
    • Updated comment about REST handler path to /v2/....
  • go.mod
    • Updated module path to github.com/a2aproject/a2a-go/v2.
    • Added require github.com/a2aproject/a2a-go v0.3.7 for backward compatibility.
  • go.sum
    • Updated dependencies to reflect the new module path and added v0.3.7 for the old module.
  • internal/eventpipe/local.go
    • Updated import paths to v2/....
  • internal/eventpipe/local_test.go
    • Updated import paths to v2/....
  • internal/grpcutil/errors.go
    • Updated import paths to v2/....
  • internal/grpcutil/errors_test.go
    • Updated import paths to v2/....
  • internal/jsonrpc/jsonrpc.go
    • Updated import paths to v2/....
  • internal/jsonrpc/jsonrpc_test.go
    • Updated import paths to v2/....
  • internal/pathtemplate/pathtemplate_test.go
    • Updated a test path to include /v2.
  • internal/rest/rest.go
    • Updated import paths to v2/....
  • internal/rest/rest_test.go
    • Updated import paths to v2/....
  • internal/taskexec/api.go
    • Updated import paths to v2/....
  • internal/taskexec/distributed_manager.go
    • Updated import paths to v2/....
  • internal/taskexec/distributed_manager_test.go
    • Updated import paths to v2/....
  • internal/taskexec/doc.go
    • Updated the link to the sequence diagram to reflect the new module path.
  • internal/taskexec/execution_handler.go
    • Updated import paths to v2/....
  • internal/taskexec/execution_handler_test.go
    • Updated import paths to v2/....
  • internal/taskexec/limiter.go
    • Updated import paths to v2/....
  • internal/taskexec/limiter_test.go
    • Updated import paths to v2/....
  • internal/taskexec/local_manager.go
    • Updated import paths to v2/....
  • internal/taskexec/manager_test.go
    • Updated import paths to v2/....
  • internal/taskexec/promise.go
    • Updated import paths to v2/....
  • internal/taskexec/subscription.go
    • Updated import paths to v2/....
  • internal/taskexec/subscription_test.go
    • Updated import paths to v2/....
  • internal/taskexec/work_queue_handler.go
    • Updated import paths to v2/....
  • internal/taskexec/work_queue_handler_test.go
    • Updated import paths to v2/....
  • internal/taskupdate/final.go
    • Updated import paths to v2/....
  • internal/taskupdate/manager.go
    • Updated import paths to v2/....
  • internal/taskupdate/manager_test.go
    • Updated import paths to v2/....
  • internal/testutil/push_config_store.go
    • Updated import paths to v2/....
  • internal/testutil/push_sender.go
    • Updated import paths to v2/....
  • internal/testutil/queue.go
    • Updated import paths to v2/....
  • internal/testutil/queue_manager.go
    • Updated import paths to v2/....
  • internal/testutil/task_store.go
    • Updated import paths to v2/....
  • internal/testutil/testexecutor/executor.go
    • Updated import paths to v2/....
  • internal/testutil/workqueue.go
    • Updated import paths to v2/....
Activity
  • The pull request was created by yarolegovich.
  • It addresses issue [Bug]: Importing module following instructions doesn't work #250, indicating a specific problem or feature request is being resolved.
  • The changes involve a significant refactoring effort to introduce Go module v2 versioning and a compatibility layer.
  • New end-to-end and migration tests were added to ensure the compatibility features work as expected.
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.

@yarolegovich yarolegovich merged commit dd1b6ba into main Mar 9, 2026
4 checks passed
@yarolegovich yarolegovich deleted the yarolegovich/api-v2 branch March 9, 2026 21:38
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 a v2 of the module, updating the module path and providing a compatibility layer for v0.3 clients and servers. The changes are extensive, touching most of the codebase to update import paths and introduce conversion logic between new and legacy types. The addition of a migration layer with adapters for legacy components is a solid approach. Overall, the changes are well-structured. I've identified a critical bug in the JSON-RPC compatibility server that would cause incorrect responses, and a high-severity correctness issue in the task store adapter's error handling. Addressing these will be important for the stability of the compatibility layer.

Note: Security Review did not run due to the size of the PR.

Comment on lines +212 to +218
version, err := s.TaskStore.Save(ctx, legacyTask, legacyEvent, legacya2a.TaskVersion(update.PrevVersion))
if err != nil {
if errors.Is(err, legacya2a.ErrConcurrentTaskModification) {
return taskstore.TaskVersionMissing, taskstore.ErrConcurrentModification
}
}
return taskstore.TaskVersion(version), err
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

high

When s.TaskStore.Save returns an error other than ErrConcurrentTaskModification, the function currently returns both the (potentially invalid) version and the error. It's better practice to return the zero value for TaskVersion (taskstore.TaskVersionMissing) whenever an error occurs to avoid ambiguity for the caller.

    version, err := s.TaskStore.Save(ctx, legacyTask, legacyEvent, legacya2a.TaskVersion(update.PrevVersion))
	if err != nil {
		if errors.Is(err, legacya2a.ErrConcurrentTaskModification) {
			return taskstore.TaskVersionMissing, taskstore.ErrConcurrentModification
		}
		return taskstore.TaskVersionMissing, err
	}
	return taskstore.TaskVersion(version), nil
References
  1. Implement optimistic concurrency control in Save operations by comparing the provided previous version with the currently stored version. If they don't match (and the previous version is not TaskVersionMissing), return an error to prevent race conditions. This comment ensures consistent error handling for version returns, aligning with robust version management.

yarolegovich pushed a commit that referenced this pull request Mar 17, 2026
🤖 I have created a release *beep* *boop*
---


##
[1.0.0](v1.0.0-alpha.3...v1.0.0)
(2026-03-17)


### Features

* implement the new rest error handling
([#282](#282))
([a3bda30](a3bda30))
* use v2 suffix for module ID and provide compat support
([#270](#270))
([dd1b6ba](dd1b6ba)),
closes [#250](#250)


### Bug Fixes

* a2asrv jsonrpc Content-Type
([#265](#265))
([2568a46](2568a46))
* bugs before going from alpha
([#279](#279))
([b1f055c](b1f055c))
* GetTaskRequest nil pointer assignment check
([#258](#258))
([440bb79](440bb79))
* inject headers into service params
([#277](#277))
([d33f3bd](d33f3bd)),
closes [#275](#275)
* propagate cancelation signal using task store
([#272](#272))
([5e1d462](5e1d462)),
closes [#245](#245)
* regenerate spec and fix returnImmediately
([#284](#284))
([2eee0b9](2eee0b9))
* task modified after save
([#266](#266))
([c15febe](c15febe))
* taskupdater result mutable
([#274](#274))
([6038d92](6038d92))
* update pushsender
([#256](#256))
([5f7a594](5f7a594))
* use enum values as in the spec
([#261](#261))
([eb98981](eb98981)),
closes [#251](#251)


### Documentation

* **a2asrv:** add Example_* test functions for pkg.go.dev documentation
([#262](#262))
([7888e37](7888e37))
* add example tests a2a
([#240](#240))
([4fe08a9](4fe08a9))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).
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.

[Bug]: Importing module following instructions doesn't work

2 participants