feat(spec): Add `tasks/list` method with filtering and pagination to the specification by edenreich · Pull Request #831 · a2aproject/A2A

edenreich · 2025-07-03T17:15:50Z

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

Follow the CONTRIBUTING Guide.
Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
Ensure the tests and linter pass (Run nox -s format from the repository root to format)
Appropriate docs were updated (if necessary)
Fix existing linting errors (I guess they were already on the main upstream)

Fixes #761 🦕

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

Release-As: 1.0.0
END_COMMIT_OVERRIDE

gemini-code-assist

Summary of Changes

Hello @edenreich, 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 new tasks/list method to the A2A protocol specification. This addition significantly enhances the protocol's task management capabilities by allowing clients to retrieve a paginated and filterable list of tasks, enabling more efficient discovery and oversight of ongoing or completed operations.

Highlights

New tasks/list Method: A new tasks/list method has been added to the A2A protocol, enabling clients to query and retrieve a list of tasks.
Filtering and Pagination Capabilities: The tasks/list method supports filtering by contextId and status, as well as pagination using limit and offset parameters, providing flexible task discovery and management.
Comprehensive Specification Updates: The new method is fully documented across the specification, including its detailed parameters (ListTasksParams) and result (ListTasksResult) objects, along with usage examples.
Protocol Definition Updates: Corresponding updates have been made to the gRPC (a2a.proto), JSON Schema (a2a.json), and TypeScript (types.ts) definitions to incorporate the new method and its associated types.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 is currently in preview and 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 to provide feedback.

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 adds the tasks/list method to the A2A specification, enabling clients to retrieve a paginated and filterable list of tasks. The changes are consistently applied across the markdown documentation, gRPC proto definitions, JSON schema, and TypeScript types. My review focuses on the design of the new endpoint, particularly the pagination strategy and the clarity of the gRPC request parameters. I've identified a couple of areas for improvement regarding consistency and potential ambiguity to ensure the specification is robust and clear for implementers.

docs/specification.md

.gitattributes

edenreich · 2025-07-08T20:40:29Z

Not sure about this linting error of 404.html file, I didn't even touched this file. I guess it will be fixed on the main upstream.

holtskinner · 2025-07-16T16:54:36Z

I did a rebase to pull in the updates from main so the lint errors don't mess with your PR.

@kthota-g and @pstephengoogle Can you please review/approve this change to the spec?

holtskinner · 2025-07-16T16:59:05Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces the tasks/list method to the A2A specification, enabling clients to fetch tasks with filtering and pagination. The changes are comprehensive, updating the main specification document, gRPC proto, JSON schema, and TypeScript types. The implementation of cursor-based pagination is well-documented. I've identified some inconsistencies in the documentation examples and missing information that could cause confusion for implementers. My review includes suggestions to align the documentation and improve clarity. Overall, this is a valuable addition to the protocol.

docs/llms.txt

docs/specification.md

gemini-code-assist · 2025-07-16T17:00:01Z

docs/specification.md

 </div>

-#### 7.4.1. `TaskIdParams` Object (for `tasks/cancel` and `tasks/pushNotificationConfig/get`)
+- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`TaskNotFoundError`](#82-a2a-specific-errors), [`TaskNotCancelableError`](#82-a2a-specific-errors)).


Consider adding TaskNotFoundError and TaskNotCancelableError to the list of possible errors for this endpoint.

Suggested change

- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`TaskNotFoundError`](#82-a2a-specific-errors), [`TaskNotCancelableError`](#82-a2a-specific-errors)).

- **Response `error` type (on failure)**: [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`TaskNotFoundError`](#82-a2a-specific-errors), [`TaskNotCancelableError`](#82-a2a-specific-errors)).

ReubenBond · 2025-07-31T15:47:17Z

If I send a tasks/list command to a public-facing compliant A2A server without specifying a contextId, will I receive everyone's tasks? I believe the answer should be no, but the spec appears to not constrain the scope of the query when a contextId is not specified. We could add some text to say the implementation can decide the implicit scope when no contextId is specified. The implementation can implicitly scope a query to a user/tenant/etc. Alternatively, the scope could be an explicit parameter.

docs/specification.md

…ecification Signed-off-by: Eden Reich <eden.reich@gmail.com>

wap definitions for 'CancelTaskRequest' and 'ListTasksRequest' in JSON schema; add detailed structure for 'ListTasks' methods. And mark the file as generated so it's easier to understand that this file is generated and it doesn't expand on the pull request. Signed-off-by: Eden Reich <eden.reich@gmail.com>

Signed-off-by: Eden Reich <eden.reich@gmail.com>

…ation Signed-off-by: Eden Reich <eden.reich@gmail.com>

…ation approach Signed-off-by: Eden Reich <eden.reich@gmail.com>

edenreich · 2025-09-15T13:14:43Z

IMHO MUST-FIX (tasks/list):

Add inline unit note for lastUpdatedAfter (ms epoch) in param bullets.

Define includeArtifacts=false semantics: artifacts field MUST be omitted (not empty array).

Add explicit InvalidParamsError cases table: pageSize out of bounds (1–100), malformed/expired pageToken, historyLength < 0, invalid status value, invalid lastUpdatedAfter (and optionally future timestamp).

Make ordering normative: MUST return tasks sorted by descending last update time.

Propagate pageSize (1–100, default 50) and historyLength (>=0, default 0) bounds/defaults across spec text, proto comments, JSON Schema, TS JSDoc.

Decide & document final-page nextPageToken behavior (omit vs empty) and keep consistent.

Clarify totalSize semantics (exact vs approximate vs optional) and align across layers.

@muscariello Thanks for reviewing, I have addressed those too. Good catch with the inconsistency between proto file and spec - those should be now in sync. I'll add a changelog - would highly recommend that this project uses semantic-release, it would make things much easier!

Signed-off-by: Eden Reich <eden.reich@gmail.com>

…ksResult, ListTasksRequest, ListTasksSuccessResponse, and ListTasksResponse Signed-off-by: Eden Reich <eden.reich@gmail.com>

git-vote · 2025-09-15T19:53:19Z

Vote status

So far 37.50% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
3	0	0	5

Binding votes (3)

User	Vote	Timestamp
darrelmiller	In favor	2025-09-13 13:34:47.0 +00:00:00
lerhaupt	In favor	2025-09-14 20:21:00.0 +00:00:00
muscariello	In favor	2025-09-15 11:16:31.0 +00:00:00
@geneknit	Pending
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

Non-binding votes (2)

User	Vote	Timestamp
matoushavlena	In favor	2025-09-15 8:29:35.0 +00:00:00
pilartomas	In favor	2025-09-15 10:53:23.0 +00:00:00

git-vote · 2025-09-16T16:11:24Z

Votes can only be checked once a day.

mrbobbytables · 2025-09-16T18:44:07Z

/check-vote

git-vote · 2025-09-16T18:44:10Z

Votes can only be checked once a day.

git-vote · 2025-09-16T19:53:35Z

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
darrelmiller	In favor	2025-09-13 13:34:47.0 +00:00:00
geneknit	In favor	2025-09-16 15:47:35.0 +00:00:00
lerhaupt	In favor	2025-09-14 20:21:00.0 +00:00:00
muscariello	In favor	2025-09-15 11:16:31.0 +00:00:00
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

Non-binding votes (2)

User	Vote	Timestamp
matoushavlena	In favor	2025-09-15 8:29:35.0 +00:00:00
pilartomas	In favor	2025-09-15 10:53:23.0 +00:00:00

git-vote · 2025-09-17T20:23:19Z

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
darrelmiller	In favor	2025-09-13 13:34:47.0 +00:00:00
geneknit	In favor	2025-09-16 15:47:35.0 +00:00:00
lerhaupt	In favor	2025-09-14 20:21:00.0 +00:00:00
muscariello	In favor	2025-09-15 11:16:31.0 +00:00:00
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

Non-binding votes (2)

User	Vote	Timestamp
matoushavlena	In favor	2025-09-15 8:29:35.0 +00:00:00
pilartomas	In favor	2025-09-15 10:53:23.0 +00:00:00

git-vote · 2025-09-18T20:23:36Z

Vote status

So far 50.00% of the users with binding vote are in favor and 0.00% are against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
4	0	0	4

Binding votes (4)

User	Vote	Timestamp
darrelmiller	In favor	2025-09-13 13:34:47.0 +00:00:00
geneknit	In favor	2025-09-16 15:47:35.0 +00:00:00
lerhaupt	In favor	2025-09-14 20:21:00.0 +00:00:00
muscariello	In favor	2025-09-15 11:16:31.0 +00:00:00
@hughesthe1st	Pending
@ToddSegal	Pending
@000-000-000-000-000	Pending
@SivaNSAP	Pending

Non-binding votes (2)

User	Vote	Timestamp
matoushavlena	In favor	2025-09-15 8:29:35.0 +00:00:00
pilartomas	In favor	2025-09-15 10:53:23.0 +00:00:00

ToddSegal · 2025-09-18T21:53:04Z

I'm in favor of the change but need to figure out how we avoid merging this as part of 0.3. This needs to be part of 0.4 and we need the links for 'latest' to point to 0.3 without this change.

amye · 2025-09-18T21:56:14Z

I'm in favor of the change but need to figure out how we avoid merging this as part of 0.3. This needs to be part of 0.4 and we need the links for 'latest' to point to 0.3 without this change.

So what'll happen is: the vote will close as 'pass', we mark it as 'approved for .4' and we merge it at that time. We can document this process as part of the release.

git-vote · 2025-09-19T08:25:07Z

Vote closed

The vote passed! 🎉

75.00% of the users with binding vote were in favor and 0.00% were against (passing threshold: 51%).

Summary

In favor	Against	Abstain	Not voted
6	0	0	2

Binding votes (6)

User	Vote	Timestamp
@SivaNSAP	In favor	2025-09-18 21:09:40.0 +00:00:00
@ToddSegal	In favor	2025-09-19 0:34:18.0 +00:00:00
@darrelmiller	In favor	2025-09-13 13:34:47.0 +00:00:00
@geneknit	In favor	2025-09-16 15:47:35.0 +00:00:00
@lerhaupt	In favor	2025-09-14 20:21:00.0 +00:00:00
@muscariello	In favor	2025-09-15 11:16:31.0 +00:00:00

Non-binding votes (2)

User	Vote	Timestamp
@matoushavlena	In favor	2025-09-15 8:29:35.0 +00:00:00
@pilartomas	In favor	2025-09-15 10:53:23.0 +00:00:00

…the specification (a2aproject#831) # Description Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly: - [x] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/A2A/blob/main/CONTRIBUTING.md). - [x] Make your Pull Request title in the <https://www.conventionalcommits.org/> specification. - [x] Ensure the tests and linter pass (Run `nox -s format` from the repository root to format) - [x] Appropriate docs were updated (if necessary) - [x] Fix existing linting errors (I guess they were already on the main upstream) Fixes a2aproject#761 🦕 --------- Signed-off-by: Eden Reich <eden.reich@gmail.com> Co-authored-by: Holt Skinner <holtskinner@google.com> Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com> Co-authored-by: Darrel <darrmi@microsoft.com> Co-authored-by: Amye Scavarda Perrin <amye@amye.org>

edenreich requested a review from a team as a code owner July 3, 2025 17:15

gemini-code-assist bot reviewed Jul 3, 2025

View reviewed changes

edenreich changed the title ~~docs: Add 'tasks/list' method with filtering and pagination to the specification~~ feat: Add 'tasks/list' method with filtering and pagination to the specification Jul 3, 2025

edenreich changed the title ~~feat: Add 'tasks/list' method with filtering and pagination to the specification~~ feat(spec): Add 'tasks/list' method with filtering and pagination to the specification Jul 3, 2025

gemini-code-assist bot reviewed Jul 3, 2025

View reviewed changes

docs/specification.md Outdated Show resolved Hide resolved

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 Jul 4, 2025

holtskinner assigned kthota-g and pstephengoogle Jul 7, 2025

holtskinner requested changes Jul 7, 2025

View reviewed changes

docs/specification.md Outdated Show resolved Hide resolved

docs/specification.md Show resolved Hide resolved

holtskinner reviewed Jul 7, 2025

View reviewed changes

.gitattributes Show resolved Hide resolved

holtskinner force-pushed the main branch from f6095b5 to 3e8f8a5 Compare July 8, 2025 15:36

edenreich requested a review from holtskinner July 11, 2025 08:57

holtskinner approved these changes Jul 16, 2025

View reviewed changes

a2aproject deleted a comment from gemini-code-assist bot Jul 16, 2025

gemini-code-assist bot reviewed Jul 16, 2025

View reviewed changes

holtskinner requested a review from a team as a code owner July 23, 2025 14:20

holtskinner unassigned kthota-g and pstephengoogle Jul 31, 2025

holtskinner requested a review from a team July 31, 2025 16:20

holtskinner added the TSC Review To be reviewed by the Technical Steering Committee label Jul 31, 2025

mikekistler reviewed Aug 13, 2025

View reviewed changes

docs/specification.md Outdated Show resolved Hide resolved

edenreich added 5 commits August 13, 2025 15:19

docs: Add 'tasks/list' method with filtering and pagination to API sp…

ed5d7ab

…ecification Signed-off-by: Eden Reich <eden.reich@gmail.com>

fix(linting): Reduce the length of the comments in the proto file

5373234

Signed-off-by: Eden Reich <eden.reich@gmail.com>

fix: Correct method references in TaskPushNotificationConfig document…

e42d7b2

…ation Signed-off-by: Eden Reich <eden.reich@gmail.com>

refactor: Use next page token and page size for a more scalable pagin…

0dc306c

…ation approach Signed-off-by: Eden Reich <eden.reich@gmail.com>

edenreich added 2 commits September 15, 2025 15:18

docs(changelog): Add entry for v0.4.0 with tasks/list feature

4b3df0d

Signed-off-by: Eden Reich <eden.reich@gmail.com>

docs(types): Add @ since 0.4.0 annotation to ListTasksParams, ListTas…

d33d873

…ksResult, ListTasksRequest, ListTasksSuccessResponse, and ListTasksResponse Signed-off-by: Eden Reich <eden.reich@gmail.com>

a2aproject deleted a comment from git-vote bot Sep 15, 2025

git-vote bot added gitvote/closed gitvote/passed and removed gitvote/open labels Sep 19, 2025

darrelmiller added this to the 0.4.0 milestone Sep 24, 2025

yarolegovich mentioned this pull request Oct 2, 2025

[Task] Implement tasks/list RPC a2aproject/a2a-go#58

Closed

darrelmiller removed this from the 0.4.0 milestone Oct 13, 2025

darrelmiller and others added 2 commits October 16, 2025 08:02

Merge branch 'main' into feature/implement-list-tasks

4e1b243

Merge branch 'main' into feature/implement-list-tasks

816ec73

amye merged commit 0a9f629 into a2aproject:main Oct 16, 2025
8 checks passed

a2a-bot mentioned this pull request Oct 16, 2025

chore(main): release 0.4.0 #974

Closed

This was referenced Oct 20, 2025

[Feat]: Implement new task/list method #1162

Closed

[Task]: Implement tasks/list method a2aproject/a2a-python#515

Closed

lkawka mentioned this pull request Nov 17, 2025

feat(spec): Add last update time to Task #1206

Closed

a2a-bot mentioned this pull request Nov 21, 2025

chore(main): release 1.0.0 #1221

Merged

birdayz mentioned this pull request Feb 14, 2026

feat: implement tasks/list RPC a2aproject/a2a-go#210

Merged

	- Response `error` type (on failure): [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`TaskNotFoundError`](#82-a2a-specific-errors), [`TaskNotCancelableError`](#82-a2a-specific-errors)).
	- Response `error` type (on failure): [`JSONRPCError`](#612-jsonrpcerror-object) (e.g., [`TaskNotFoundError`](#82-a2a-specific-errors), [`TaskNotCancelableError`](#82-a2a-specific-errors)).

Conversation

edenreich commented Jul 3, 2025 • edited by holtskinner Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

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!

Uh oh!

edenreich commented Jul 8, 2025

Uh oh!

holtskinner commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

holtskinner commented Jul 16, 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!

gemini-code-assist bot Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

ReubenBond commented Jul 31, 2025

Uh oh!

Uh oh!

edenreich commented Sep 15, 2025

Uh oh!

git-vote bot commented Sep 15, 2025

Vote status

Summary

Binding votes (3)

Non-binding votes (2)

Uh oh!

git-vote bot commented Sep 16, 2025

Uh oh!

mrbobbytables commented Sep 16, 2025

Uh oh!

git-vote bot commented Sep 16, 2025

Uh oh!

git-vote bot commented Sep 16, 2025

Vote status

Summary

Binding votes (4)

Non-binding votes (2)

Uh oh!

git-vote bot commented Sep 17, 2025

Vote status

Summary

Binding votes (4)

Non-binding votes (2)

Uh oh!

git-vote bot commented Sep 18, 2025

Vote status

Summary

Binding votes (4)

Non-binding votes (2)

Uh oh!

ToddSegal commented Sep 18, 2025

Uh oh!

amye commented Sep 18, 2025

Uh oh!

git-vote bot commented Sep 19, 2025

Vote closed

Summary

Binding votes (6)

Non-binding votes (2)

Uh oh!

edenreich commented Jul 3, 2025 •

edited by holtskinner

Loading

holtskinner commented Jul 16, 2025 •

edited

Loading