fix(grpc): missing field in gRPC spec - state_transition_history

[a2a-bot]

Commit: a2aproject/A2A@a2de798

[gemini-code-assist]

Summary of Changes

Hello @a2a-bot, 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 significantly enhances the A2A API's task management by introducing a new ListTasks RPC method. This method provides flexible querying capabilities, allowing users to filter and paginate task results based on various criteria. Alongside this major addition, existing data structures have been refined, including a field rename in the Message type and the addition of a new capability flag in AgentCapabilities. These changes ensure the API remains robust and provides comprehensive task interaction options.

Highlights

• New ListTasks RPC Method: A new gRPC method, ListTasks, has been introduced to the A2AService, enabling clients to retrieve a list of tasks.
• Enhanced Task Listing Capabilities: The new ListTasks method supports filtering tasks by context_id, status, and last_updated_after, along with pagination options like page_size and page_token.
• Configurable Task Details: Clients can now specify history_length to control the number of recent messages included and include_artifacts to determine if artifacts should be part of the returned task objects.
• Message Structure Refinement: The Message protobuf definition has been updated, renaming the content field to parts and introducing a new reference_task_ids field for better task relationship tracking.
• Agent Capabilities Update: The AgentCapabilities message now includes a state_transition_history field, indicating whether an agent supports tracking task state transitions.
• Generated Code Regeneration: All Python protobuf and gRPC generated files (a2a_pb2.py, a2a_pb2.pyi, a2a_pb2_grpc.py) have been regenerated to incorporate these schema changes, including updates to __slots__ for various message classes in type stubs.
• JSON-RPC Model Alignment: Corresponding Pydantic models in src/a2a/types.py have been added or modified to align with the new ListTasks functionality and other protobuf schema updates.

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

[gemini-code-assist]

Code Review

This pull request updates the A2A specification, which involves regenerating several key files including Protobuf definitions, gRPC stubs, and Pydantic type models. The main changes include the addition of a ListTasks method, updates to the Message and AgentCapabilities structures, and improvements to the generated type stubs. My review focuses on the newly added Pydantic models, where I've suggested adding validation constraints to align with the documentation, which would improve data integrity. I've also noted a positive change in the Protobuf stubs regarding the use of __slots__, which enhances type safety.

[gemini-code-assist]

The docstring for history_length states it must be non-negative. This can be enforced at the type level using Pydantic's Field for better data integrity. Since this is a generated file, this change should be reflected in the source JSON schema.

Suggested change

	history_length: int | None = None
	history_length: int | None = Field(default=None, ge=0)

[gemini-code-assist]

The docstring for page_size mentions that the value must be between 1 and 100. It would be beneficial to enforce this constraint directly in the Pydantic model using Field. This would provide automatic validation and clearer error messages for developers using this type. Since this file is auto-generated, this change should ideally be made in the source JSON schema that datamodel-codegen uses.

Suggested change

	page_size: int | None = None
	page_size: int | None = Field(default=None, ge=1, le=100)

[gemini-code-assist]

Changing __slots__ to an empty tuple is a good improvement for these generated Protobuf message stubs. It correctly signals that these classes do not have a __dict__ and prevents accidental assignment of attributes that are not part of the Protobuf definition, which is a common source of runtime errors. This change makes the type hints more robust.

[coyotwill]

Beware: This may be an annoying breaking change.

Over-the-wire this it's still the same proto field number, so the recipient won't be impacted.

But people updating the python a2a package will need to change their code from the_message.content[0] to the_message.parts[0] if they are constructing the gRPC message manually.

Also, the helpers will break. For instance: proto_utils.FromProto.message() is still referencing message.content which does not exist anymore. (at least I see it's not updated in this commit)