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

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 🦕

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.

…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>

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

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.

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

docs/llms.txt

+- **`tasks/list`:** (Request/Response)
+    - Retrieves a list of tasks with optional filtering and pagination.
+    - `params`: `ListTasksParams` (optional: `contextId`, `status`, `limit`, `offset`, `historyLength`).
+    - `result`: `ListTasksResult` (includes `tasks[]`, `total`, `limit`, `offset`).


The description of the tasks/list method's parameters and result uses offset-based pagination (limit, offset), which is inconsistent with the cursor-based pagination (pageSize, pageToken, nextPageToken) used in the main specification and the defined types.

Consider updating the description to reflect the actual implementation to avoid confusion for developers using this summary.

- `params`: `ListTasksParams` (optional: `contextId`, `status`, `pageSize`, `pageToken`, `historyLength`). - `result`: `ListTasksResult` (includes `tasks[]`, `totalSize`, `pageSize`, `nextPageToken`).

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

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 Outdated Show resolved Hide resolved

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

edenreich force-pushed the feature/implement-list-tasks branch from bb07e2f to 3262d7f Compare July 11, 2025 08:56

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

edenreich added 6 commits July 16, 2025 17:52

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

46c2451

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

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

4c7ab21

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

fix: Correct method references in TaskPushNotificationConfig document…

d682b18

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

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

ae49128

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

docs: Update specification to use placeholder for base64-encoded curs…

785925a

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

holtskinner force-pushed the feature/implement-list-tasks branch from 2caed14 to 785925a Compare July 16, 2025 16:52

Formatting

17ce945

holtskinner approved these changes Jul 16, 2025

View reviewed changes

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

holtskinner added 2 commits July 16, 2025 17:57

Fix link

1be5e52

Formatting

667345b

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

edenreich commented Jul 3, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

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!

holtskinner commented Jul 16, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jul 16, 2025

Uh oh!

Uh oh!

gemini-code-assist bot Jul 16, 2025

Uh oh!

Uh oh!

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

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

Are you sure you want to change the base?

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

Conversation

edenreich commented Jul 3, 2025 • edited 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!

gemini-code-assist bot Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gemini-code-assist bot Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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

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

edenreich commented Jul 3, 2025 •

edited

Loading

holtskinner commented Jul 16, 2025 •

edited

Loading