refactor!: Update to Protocol v1.0.0-rc and fix all tests #665

muscariello · 2026-02-02T15:52:22Z

Description

Updates the SDK to support the A2A Protocol v1.0.0-rc specifications.

Changes

Protocol Update: Updated core types, definitions, Client, and Server implementations to match Protocol v1.0.0-rc.
Bug Fixes:
- Fixed RestTransport URL construction.
- Resolved pyright, ruff, and mypy linting errors across the codebase.
- Fixed import resolution issues for optional dependencies (grpc, sqlalchemy, opentelemetry).
Tests:
- Fixed all failing unit and integration tests.
- Added support for running PostgreSQL and MySQL integration tests (verified locally).
Cleanup: Removed redundant pyrightconfig.json.

Testing

All unit and integration tests are passing.
Database integration tests verified locally with Docker containers (docker-compose file was used for verification but is not included in the repo).

gemini-code-assist · 2026-02-02T15:58:13Z

Summary of Changes

Hello @muscariello, 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 significant refactoring of the Python SDK to align with Protocol V1 specifications. The core change involves migrating from Pydantic-based data models to native Protobuf message objects for all A2A types, which improves performance and consistency. This transition necessitated updates to field names, data structures like PushNotificationConfig, and the underlying serialization/deserialization logic across both client and server components. Additionally, the PR streamlines the code generation process and removes outdated legacy client implementations, ensuring the SDK is modern and fully compliant with the latest protocol standards.

Highlights

Protocol V1 Alignment: The Python SDK has been updated to fully comply with Protocol V1 specifications, ensuring compatibility with the latest protocol standards.
Pydantic to Protobuf Transition: A major refactor has been implemented to transition from Pydantic-based data models to direct usage of Protobuf message objects for A2A types. This impacts client and server serialization, deserialization, and data handling.
Field Renaming: Key fields across various structures have been renamed for clarity and consistency, specifically changing 'name' fields to 'id' and 'task_id'.
Updated PushNotificationConfig: The internal structure and handling of the PushNotificationConfig used in requests have been updated to reflect the new protocol specifications.
Code Generation Streamlining: The code generation process has been improved, with buf.gen.yaml now directing Python type generation to src/a2a/types and including OpenAPI v2 spec generation. A new gen_proto.sh script manages these tasks.
Legacy Client Removal: Deprecated client components, specifically a2a.client.legacy.A2AClient and a2a.client.legacy_grpc.A2AGrpcClient, have been removed to streamline the codebase.
Database Model Updates: SQLAlchemy custom types (PydanticType, PydanticListType) have been enhanced to seamlessly handle both Pydantic models and Protobuf messages for robust data persistence.

Ignored Files

Ignored by pattern: .github/workflows/** (3)
- .github/workflows/linter.yaml
- .github/workflows/unit-tests.yml
- .github/workflows/update-a2a-types.yml

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 is a substantial and well-executed pull request that refactors the Python SDK to align with Protocol V1. The changes are extensive, touching nearly every part of the codebase, and appear to be implemented correctly and consistently with the goals outlined in the description.

Key improvements include:

A shift from Pydantic models to using Protobuf-generated classes directly, which simplifies the code by removing the proto_utils conversion layer.
A new, clearer exception hierarchy defined in a2a.utils.errors.
The introduction of a robust signing and verification mechanism for Agent Cards.
Renaming of fields and methods (e.g., resubscribe to subscribe, get_card to get_extended_agent_card) for better clarity and consistency with the protocol.
Comprehensive updates to tests to cover the new protocol version and features.

The overall quality of the refactoring is high. I have only one minor stylistic suggestion.

src/a2a/client/client_factory.py

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Tehsmash · 2026-02-03T09:58:15Z

src/a2a/server/request_handlers/default_request_handler.py

        params: SubscribeToTaskRequest,
        context: ServerCallContext | None = None,
-    ) -> AsyncGenerator[StreamResponse]:
+    ) -> AsyncGenerator[Event, None]:


I'm not sure we want to revert this change

The revert to AsyncGenerator[Event, None] is intentional here. The DefaultRequestHandler now operates on domain objects (Event), keeping it decoupled from the wire format. The transformation to StreamResponse (the Protobuf message) is handled up the stack in grpc_handler.py (and similarly for REST), which wraps the events before sending them to the client.

src/a2a/server/request_handlers/default_request_handler.py

src/a2a/server/request_handlers/rest_handler.py

src/a2a/server/models.py

Tehsmash · 2026-02-03T10:54:45Z

src/a2a/utils/parts.py

-    return [
-        MessageToDict(part.data.data) for part in parts if part.HasField('data')
-    ]
+    return [MessageToDict(part.data) for part in parts if part.HasField('data')]


part.data is of type protobuf.Value which can contain any JSON compatible type, dict, string, array etc
So the return type list[dict[str, Any]] isn't correct, and also I don't think we want to use MessageToDict because part.data isn't a message type.

Honestly I think with the changes to Part, both get_data_parts and get_file_parts functions probably need refactoring out of the code because they don't mean what they used to mean.

Agreed that these helper functions have drifted from their original specific intent now that Part is more generic. For this PR, I've updated the type hints to list[Any] to match the current schema. I'd prefer to handle the larger refactoring/deprecation of these helpers in a separate follow-up PR to keep this migration focused on the protocol update.

tests/client/transports/test_grpc_client.py

tests/integration/test_client_server_integration.py

pyproject.toml

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

…ests Signed-off-by: Luca Muscariello <muscariello@ieee.org>

ishymko

Thank you for this @muscariello and thank you @Tehsmash for your reviews!

Re #559 (comment): is it the last step required before merging 1.0-a2a_proto_refactor it with 1.0-dev?

src/a2a/client/transports/rest.py

src/a2a/server/request_handlers/default_request_handler.py

tests/e2e/push_notifications/test_default_push_notification_support.py

- Remove redundant ID extraction helpers in server handlers - Fix get_data_parts return type annotation - Remove unnecessary cast in models.py - Update pyrightconfig.json excludes - Update tests to use full resource text for IDs Signed-off-by: Luca Muscariello <muscariello@ieee.org>

- Switch pyright config to use 'exclude' instead of 'ignore' for types. - Update REST transport to explicitly construct resource URLs, accommodating bare ID inputs. - Update tests to use bare IDs instead of resource names, aligning with 'Short ID' convention. - Ensure parts.py uses correct typing. Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Configuration is already present in pyproject.toml. Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

Remove local type ignores for optional dependencies Signed-off-by: Luca Muscariello <muscariello@ieee.org>

muscariello · 2026-02-07T16:50:23Z

I am refactoring a2a-samples/samples/python wrt this PR. I will share based on the outcome on Monday.

muscariello · 2026-02-08T09:24:06Z

https://github.com/a2aproject/a2a-samples/compare/main...muscariello:a2a-samples:refactor/sdk-v1-rc?diff=split&w

This is how I had to update the python samples to work with this PR.

@holtskinner @herczyn @Tehsmash anybody could have a look ?

ishymko · 2026-02-09T11:30:09Z

Hey @muscariello, looked through the diff and I see final field is still used in TaskStatusUpdateEvent in samples/python/agents/travel_planner_agent/agent_executor.py in the diff, but it was removed in 1.0 (a2aproject/A2A#1308). It happened quite recently, seems like current types should be regenerated.

muscariello · 2026-02-09T21:49:00Z

Hey @ishymko
I run another pass on the sample app. Should be ok.
I am not sure if the spacc v1-rc has got new changes but I will check again tomorrow.

muscariello requested review from a team and a2a-bot as code owners February 2, 2026 15:52

muscariello changed the base branch from main to 1.0-a2a_proto_refactor February 2, 2026 15:53

muscariello marked this pull request as draft February 2, 2026 15:57

muscariello force-pushed the spec-update-rc1 branch from 5584d97 to 70316d9 Compare February 2, 2026 16:00

gemini-code-assist bot reviewed Feb 2, 2026

View reviewed changes

src/a2a/client/client_factory.py Outdated Show resolved Hide resolved

muscariello force-pushed the spec-update-rc1 branch 2 times, most recently from 7d64a4a to d1b8162 Compare February 2, 2026 21:25

refactor: Update to Protocol V1 and fix all tests

898119c

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

muscariello force-pushed the spec-update-rc1 branch from d1b8162 to 898119c Compare February 2, 2026 21:27

muscariello marked this pull request as ready for review February 2, 2026 21:36

muscariello changed the title ~~refactor: Update to Protocol V1 and fix all tests~~ refactor!: Update to Protocol V1 and fix all tests Feb 2, 2026

muscariello changed the title ~~refactor!: Update to Protocol V1 and fix all tests~~ refactor!: Update to Protocol v1.0.0-rc and fix all tests Feb 2, 2026

Tehsmash suggested changes Feb 3, 2026

View reviewed changes

holtskinner reviewed Feb 3, 2026

View reviewed changes

pyproject.toml Outdated Show resolved Hide resolved

muscariello added 3 commits February 4, 2026 13:31

fix(review): Address feedback from PR a2aproject#665

6d04127

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

fix(tests): resolve failing tests after review feedback

38d266a

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

fix(client): update rest transport URL construction and integration t…

c181de7

…ests Signed-off-by: Luca Muscariello <muscariello@ieee.org>

ishymko reviewed Feb 5, 2026

View reviewed changes

muscariello added 9 commits February 6, 2026 17:18

chore: remove redundant pyrightconfig.json

119d0bd

Configuration is already present in pyproject.toml. Signed-off-by: Luca Muscariello <muscariello@ieee.org>

fix: fix linting, tests and add docker-compose

54f9639

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

fix: resolve pyright linting errors in tests

ac09e07

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

chore: remove docker-compose.yaml from git

e81c368

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

fix: ignore missing imports for optional dependencies in pyright

d1a4852

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

fix: ignore missing imports for all optional packages in pyright

1647415

Signed-off-by: Luca Muscariello <muscariello@ieee.org>

ci: install all extras in linter workflow to fix type checking

6640dcd

Remove local type ignores for optional dependencies Signed-off-by: Luca Muscariello <muscariello@ieee.org>

refactor!: Update to Protocol v1.0.0-rc and fix all tests #665

Are you sure you want to change the base?

refactor!: Update to Protocol v1.0.0-rc and fix all tests #665

Conversation

muscariello commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Testing

Uh oh!

gemini-code-assist bot commented Feb 2, 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!

Tehsmash Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

muscariello Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Tehsmash Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

muscariello Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ishymko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

muscariello commented Feb 7, 2026

Uh oh!

muscariello commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ishymko commented Feb 9, 2026

Uh oh!

muscariello commented Feb 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

muscariello commented Feb 2, 2026 •

edited

Loading

muscariello commented Feb 8, 2026 •

edited

Loading