feat(spec): Add tasks/list method with filtering and pagination to the specification

[a2a-bot]

Commit: a2aproject/A2A@0a9f629

This PR introduces support for the new tasks/list method, including:

• Automatically generated type definitions from the specification.
• Complete client-side and server-side implementations.

Fixes #515 🦕

[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 by introducing a new ListTasks method. This method provides a robust way to query and manage tasks, offering capabilities such as filtering by context ID and task status, specifying history length, filtering by last updated time, and controlling the inclusion of artifacts. It also supports pagination, making it suitable for handling large numbers of tasks efficiently. The changes span across the gRPC definitions and the Python type definitions, ensuring full integration and usability of this new feature.

Highlights

• New ListTasks API Method: Introduced a new RPC method ListTasks to allow clients to retrieve a paginated and filterable list of tasks.
• Expanded Task Management Capabilities: Added comprehensive request and response models for ListTasks, including parameters for filtering by context_id, status, history_length, last_updated_time, and options for pagination (page_size, page_token) and artifact inclusion.
• Protocol Buffer Updates: Updated the Python generated protobuf files (a2a_pb2.py, a2a_pb2.pyi, a2a_pb2_grpc.py) to reflect the new ListTasks method and its associated message types, ensuring gRPC compatibility.
• JSON-RPC Type Definitions: Integrated the new ListTasks functionality into the a2a/types.py file with new Pydantic models for JSON-RPC requests and responses, enhancing the Python client's ability to interact with this new API.

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 and the corresponding generated Python files to introduce the ListTasks functionality. The changes correctly add the necessary protobuf messages, gRPC service definitions, and Pydantic models for the JSON-RPC transport. It appears the implementation of these new endpoints in the server handlers and client transports is planned for future work.

My review focuses on the manually edited src/a2a/types.py file. I've suggested adding Pydantic validators to the ListTasksParams model to enforce constraints mentioned in the docstrings, which will improve data integrity. I also pointed out a small inconsistency in a docstring for better clarity. Overall, the changes are well-structured and align with the existing design.

[lkawka]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the tasks/list method, providing filtering and pagination capabilities for tasks. The changes are extensive, touching the client, server, transports, data stores, and tests. The implementation is solid, but I have a few suggestions to improve consistency, validation, and code clarity. Specifically, I recommend centralizing the payload reduction logic, adding a validator for request parameters, and removing some dead code. Overall, a great addition to the A2A specification.

[holtskinner]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the tasks/list method across the entire stack, from the specification and type definitions to client and server implementations for all transports (gRPC, JSON-RPC, REST), and includes comprehensive tests. The changes are well-structured and thorough. I've found a few minor issues, mostly related to robustness, documentation, and a small bug in a test case. Overall, this is a solid contribution.

[yarolegovich]

instead of limit-offset it's better to return task id of the last selected task as a page token and use it in where(task.id < pageToken).
looking at TaskMixin:

id: Mapped[str] = mapped_column(String(36), primary_key=True, index=True)

I think we should coordinate the migration to uuid v7 for id generation so that primary index inserts are mostly append only and not random

[lkawka]

Firstly, v7 uuids are out of scope for this PR.

Secondly, I don't agree that we should use ids or timestamps as offsets for the following reasons:

1. Users can provide custom ID generators, making not to have any specific order.
2. I image that we can add other sorting options in the future and this approach is more future-proof.

[yarolegovich]

v7 uuids are out of scope for this PR.

Agree.

Users can provide custom ID generators, making not to have any specific order.

ID is already a primary key in your TaskModel which means tasks are stored sorted by it, regardless of whether it's random, increasing or monotonic.

I image that we can add other sorting options in the future and this approach is more future-proof.

Sorting option should have secondary indices, selector column value should be used as a cursor.

Btw, in the current spec version:

Ordering: Implementations MUST return tasks sorted by their last update time in descending order (most recently updated tasks first). This ensures consistent pagination and allows clients to efficiently monitor recent task activity.

So ID ordering is not really spec compliant, a last_update timestamp should be added to TaskModel (ideally with a creation timestamp).

There's also a section about offset-based pagination:

Pagination Strategy: This method uses cursor-based pagination (via pageToken/nextPageToken) rather than offset-based pagination for better performance and consistency, especially with large datasets. Cursor-based pagination avoids the "deep pagination problem" where skipping large numbers of records becomes inefficient for databases.

[lkawka]

Oh, I somehow missed the part about the cursor-based pagination. Will change the implementation.

[yarolegovich]

task model needs to be updated to have user credentials in it with a db index for faster queries. otherwise anyone can query all the tasks on the server. can be done in a separate index.

[lkawka]

I feel like this is not something we cannot do properly at this time. There is a number of different auth schemes and resource ownership models that the server maintainers can decide to follow. This is also a broader topic then just the task/list method.

For now, all resources are accessible to all-users/all-authenticated-users.

We do have a plan on adding support for common auth schemes in the SDK and this is when this could potentially be addressed.

[yarolegovich]

There is ServerCallContext with User in it, it's even passed to DatabaseTaskStore, just unused. User.username should be an indexed field in TaskModel to filter on.

[lkawka]

But this is making an assumption that tasks are user-scoped. Correct me if I'm wrong but I think that doesn't always has to be the case. For instance, they could be tenant scoped. I don't see other parts of the SDK user-scoping tasks and we should be consistent.

[yarolegovich]

There's another note in the specification 🙂

Security Note: Implementations MUST ensure appropriate scope limitation based on the authenticated user's permissions. Servers SHOULD NOT return tasks from other users or unauthorized contexts. Even when contextId is not specified in the request, the implementation MUST still scope results to the caller's authorization and tenancy boundaries. The implementation MAY choose to limit results to tasks created by the current authenticated user, tasks within a default user context, or return an authorization error if the scope cannot be safely determined.

[yarolegovich]

I agree it's bigger issue of persistent task store implementation, we can address this separately.