feat(spec): Add `tasks/list` method with filtering and pagination to the specification by a2a-bot · Pull Request #511 · a2aproject/a2a-python

a2a-bot · 2025-10-16T19:47:53Z

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 · 2025-10-16T19:48:12Z

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.

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.

src/a2a/types.py

…1fc28afe9429c91cbc

lkawka · 2025-11-05T19:25:45Z

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

src/a2a/server/request_handlers/default_request_handler.py

src/a2a/server/tasks/database_task_store.py

src/a2a/types.py

src/a2a/server/request_handlers/default_request_handler.py

src/a2a/server/tasks/inmemory_task_store.py

src/a2a/server/request_handlers/rest_handler.py

src/a2a/server/tasks/task_store.py

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>

src/a2a/server/tasks/database_task_store.py

holtskinner · 2025-11-07T15:22:54Z

/gemini review

src/a2a/server/tasks/inmemory_task_store.py

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.

tests/server/request_handlers/test_jsonrpc_handler.py

src/a2a/server/tasks/database_task_store.py

src/a2a/server/tasks/inmemory_task_store.py

src/a2a/types.py

src/a2a/server/tasks/inmemory_task_store.py

src/a2a/server/request_handlers/default_request_handler.py

src/a2a/server/tasks/database_task_store.py

tests/server/tasks/test_database_task_store.py

…4991fc28afe9429c91cbc

# Description Do not use `NULLS LAST` which is not available in MySQL, coalesce nulls to empty strings which will appear last in descending ordering (there are tests for this behavior already, however CI wasn't enabled for this branch). Currently `NULLS LAST` fails MySQL tests: ``` (1064, "You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'NULLS LAST, tasks.id DESC \n LIMIT 51' at line 3") ``` ([actions run](https://github.com/a2aproject/a2a-python/actions/runs/21520017047/job/62008309612?pr=651)) Enable tests run against `1.0-dev` to prevent it in the future. Re #511 Fixes #652 --- Mark as "refactor" for release please as it's a fix for a non-released feature, hence shouldn't get into a changelog. BEGIN_COMMIT_OVERRIDE refactor: use MySQL compatible syntax in list tasks END_COMMIT_OVERRIDE

…the specification (#511) 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 🦕 --------- Co-authored-by: lkawka <lkawka@google.com> Co-authored-by: lkawka <luk.kawka@gmail.com> Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>

# Description Do not use `NULLS LAST` which is not available in MySQL, coalesce nulls to empty strings which will appear last in descending ordering (there are tests for this behavior already, however CI wasn't enabled for this branch). Currently `NULLS LAST` fails MySQL tests: ``` (1064, "You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'NULLS LAST, tasks.id DESC \n LIMIT 51' at line 3") ``` ([actions run](https://github.com/a2aproject/a2a-python/actions/runs/21520017047/job/62008309612?pr=651)) Enable tests run against `1.0-dev` to prevent it in the future. Re #511 Fixes #652 --- Mark as "refactor" for release please as it's a fix for a non-released feature, hence shouldn't get into a changelog. BEGIN_COMMIT_OVERRIDE refactor: use MySQL compatible syntax in list tasks END_COMMIT_OVERRIDE

🤖 I have created a release *beep* *boop* --- ### ⚠ BREAKING CHANGES * **spec**: upgrade SDK to A2A 1.0 spec and use proto-based types ([#572](#572), [#665](#665), [#804](#804), [#765](#765)) * **client:** introduce ServiceParameters for extensions and include it in ClientCallContext ([#784](#784)) * **client:** rename "callback" -> "push_notification_config" ([#749](#749)) * **client:** transport agnostic interceptors ([#796](#796)) ([a910cbc](a910cbc)) * add `protocol_version` column to Task and PushNotificationConfig models and create a migration ([#789](#789)) ([2e2d431](2e2d431)) * **server:** implement `Resource Scoping` for tasks and push notifications ([#709](#709)) ([f0d4669](f0d4669)) ### Features * add GetExtendedAgentCardRequest as input parameter to GetExtendedAgentCard method ([#767](#767)) ([13a092f](13a092f)) * add validation for the JSON-RPC version ([#808](#808)) ([6eb7e41](6eb7e41)) * **client:** expose close() and async context manager support on abstract Client ([#719](#719)) ([e25ba7b](e25ba7b)) * **compat:** AgentCard backward compatibility helpers and tests ([#760](#760)) ([81f3494](81f3494)) * **compat:** GRPC client compatible with 0.3 server ([#779](#779)) ([0ebca93](0ebca93)) * **compat:** GRPC server compatible with 0.3 client ([#772](#772)) ([80d827a](80d827a)) * **compat:** legacy v0.3 protocol models, conversion logic and utilities ([#754](#754)) ([26835ad](26835ad)) * **compat:** REST and JSONRPC clients compatible with 0.3 servers ([#798](#798)) ([08794f7](08794f7)) * **compat:** REST and JSONRPC servers compatible with 0.3 clients ([#795](#795)) ([9856054](9856054)) * **compat:** set a2a-version header to 1.0.0 ([#764](#764)) ([4cb68aa](4cb68aa)) * **compat:** unify v0.3 REST url prefix and expand cross-version tests ([#820](#820)) ([0925f0a](0925f0a)) * database forward compatibility: make `owner` field optional ([#812](#812)) ([cc29d1f](cc29d1f)) * handle tenant in Client ([#758](#758)) ([5b354e4](5b354e4)) * implement missing push notifications related methods ([#711](#711)) ([041f0f5](041f0f5)) * implement rich gRPC error details per A2A v1.0 spec ([#790](#790)) ([245eca3](245eca3)) * **rest:** add tenant support to rest ([#773](#773)) ([4771b5a](4771b5a)) * send task as a first subscribe event ([#716](#716)) ([e71ac62](e71ac62)) * **server, grpc:** Implement tenant context propagation for gRPC requests. ([#781](#781)) ([164f919](164f919)) * **server, json-rpc:** Implement tenant context propagation for JSON-RPC requests. ([#778](#778)) ([72a330d](72a330d)) * **server:** add v0.3 legacy compatibility for database models ([#783](#783)) ([08c491e](08c491e)) * **spec:** add `tasks/list` method with filtering and pagination to the specification ([#511](#511)) ([d5818e5](d5818e5)) * use StreamResponse as push notifications payload ([#724](#724)) ([a149a09](a149a09)) * **rest:** update REST error handling to use `google.rpc.Status` ([#838](#838)) ([ea7d3ad](ea7d3ad)) ### Bug Fixes * add history length and page size validations ([#726](#726)) ([e67934b](e67934b)) * allign error codes with the latest spec ([#826](#826)) ([709b1ff](709b1ff)) * **client:** align send_message signature with BaseClient ([#740](#740)) ([57cb529](57cb529)) * get_agent_card trailing slash when agent_card_path="" ([#799](#799)) ([#800](#800)) ([a55c97e](a55c97e)) * handle parsing error in REST ([#806](#806)) ([bbd09f2](bbd09f2)) * Improve error handling for Timeout exceptions on REST and JSON-RPC clients ([#690](#690)) ([2acd838](2acd838)) * Improve streaming errors handling ([#576](#576)) ([7ea7475](7ea7475)) * properly handle unset and zero history length ([#717](#717)) ([72a1007](72a1007)) * return entire history when history_length=0 ([#537](#537)) ([acdc0de](acdc0de)) * return mandatory fields from list_tasks ([#710](#710)) ([6132053](6132053)) * taskslist error on invalid page token and response serialization ([#814](#814)) ([a102d31](a102d31)) * use correct REST path for Get Extended Agent Card operation ([#769](#769)) ([ced3f99](ced3f99)) * Use POST method for REST endpoint /tasks/{id}:subscribe ([#843](#843)) ([a0827d0](a0827d0)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: Ivan Shymko <ishymko@google.com>

Update to specification from 0a9f629e801d4ae89f94991fc28afe9429c91cbc

4255e39

a2a-bot requested a review from a team as a code owner October 16, 2025 19:47

a2a-bot added automated dependencies labels Oct 16, 2025

gemini-code-assist bot reviewed Oct 16, 2025

View reviewed changes

src/a2a/types.py Show resolved Hide resolved

src/a2a/types.py Show resolved Hide resolved

src/a2a/types.py Show resolved Hide resolved

holtskinner changed the title ~~Update to specification from 0a9f629e801d4ae89f94991fc28afe9429c91cbc~~ feat(spec): Add tasks/list method with filtering and pagination to the specification Oct 17, 2025

lkawka self-assigned this Oct 20, 2025

Add empty list_tasks methods

e5853a6

lkawka force-pushed the auto-update-a2a-types-0a9f629e801d4ae89f94991fc28afe9429c91cbc branch from 39b57dc to e5853a6 Compare October 21, 2025 07:37

Add client support for task/list method

643a2e0

holtskinner changed the title ~~feat(spec): Add tasks/list method with filtering and pagination to the specification~~ feat(spec): Add tasks/list method with filtering and pagination to the specification Oct 23, 2025

lkawka added 3 commits November 4, 2025 18:36

Add server support

c1d3392

linter fix

a57f24a

Merge branch 'main' into auto-update-a2a-types-0a9f629e801d4ae89f9499…

f7461fc

…1fc28afe9429c91cbc

lkawka changed the base branch from main to 1.0-dev November 4, 2025 18:50

gemini-code-assist bot reviewed Nov 5, 2025

View reviewed changes

lkawka added 2 commits November 5, 2025 20:17

remove dead code

32cc97c

Move payload reduction to default_request_handler

eccaa80

holtskinner requested changes Nov 6, 2025

View reviewed changes

src/a2a/server/request_handlers/rest_handler.py Show resolved Hide resolved

src/a2a/server/request_handlers/rest_handler.py Outdated Show resolved Hide resolved

src/a2a/server/tasks/task_store.py Outdated Show resolved Hide resolved

lkawka and others added 4 commits November 7, 2025 00:01

Add integration tests

ec96994

format

7b52ed2

Apply suggestion from @holtskinner

d79a229

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>

change next_page_token default val

d638093

lkawka requested a review from herczyn November 7, 2025 00:11

holtskinner reviewed Nov 7, 2025

View reviewed changes

src/a2a/server/tasks/database_task_store.py Outdated Show resolved Hide resolved

holtskinner approved these changes Nov 7, 2025

View reviewed changes

holtskinner reviewed Nov 7, 2025

View reviewed changes

src/a2a/server/tasks/inmemory_task_store.py Outdated Show resolved Hide resolved

gemini-code-assist bot reviewed Nov 7, 2025

View reviewed changes

tests/server/request_handlers/test_jsonrpc_handler.py Show resolved Hide resolved

src/a2a/server/tasks/database_task_store.py Outdated Show resolved Hide resolved

src/a2a/server/tasks/inmemory_task_store.py Outdated Show resolved Hide resolved

src/a2a/types.py Show resolved Hide resolved

lkawka added 2 commits November 7, 2025 21:03

change empty next_page_token value to None

50eba6a

rm random param

1d712e8

lkawka removed the request for review from herczyn November 7, 2025 21:08

guglielmo-san reviewed Nov 12, 2025

View reviewed changes

src/a2a/server/tasks/inmemory_task_store.py Outdated Show resolved Hide resolved

lkawka requested a review from yarolegovich November 12, 2025 20:11

yarolegovich reviewed Nov 13, 2025

View reviewed changes

lkawka added 2 commits November 13, 2025 18:09

Change last token to '' and add more list_tasks tests

51ee2c7

Merge branch '1.0-dev' into auto-update-a2a-types-0a9f629e801d4ae89f9…

10b638a

…4991fc28afe9429c91cbc

lkawka requested a review from yarolegovich November 13, 2025 18:15

lkawka added 4 commits November 21, 2025 10:17

Cursor-based pagination and update time handling

20526d7

Merge branch '1.0-dev' into auto-update-a2a-types-0a9f629e801d4ae89f9…

f145fc9

…4991fc28afe9429c91cbc

fix

a12429c

tighten where statement

f2101f4

yarolegovich approved these changes Nov 24, 2025

View reviewed changes

lkawka merged commit d5818e5 into 1.0-dev Nov 24, 2025
3 checks passed

lkawka deleted the auto-update-a2a-types-0a9f629e801d4ae89f94991fc28afe9429c91cbc branch November 24, 2025 16:23

This was referenced Jan 30, 2026

fix: use MySQL compatible syntax in list tasks #651

Merged

[Bug]: Tests are failing on 1.0-dev #652

Closed

This was referenced Mar 12, 2026

chore(1.0-dev): release 1.0.0-alpha.0 #818

Closed

chore(1.0-dev): release 1.0.0-alpha.0 #825

Closed

chore(1.0-dev): release 1.0.0-alpha.0 #828

Merged

a2a-bot mentioned this pull request Mar 17, 2026

chore(1.0-dev): release 1.0.0-alpha.0 #852

Closed

Conversation

a2a-bot commented Oct 16, 2025 • edited by lkawka Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Oct 16, 2025

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!

Uh oh!

Uh oh!

lkawka commented Nov 5, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

holtskinner commented Nov 7, 2025

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

a2a-bot commented Oct 16, 2025 •

edited by lkawka

Loading