feat(spec): Add tasks/list method with filtering and pagination to 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>

Author: 4 people

src/a2a/client/base_client.py

@@ -18,6 +18,8 @@
 from a2a.types import (
     AgentCard,
     GetTaskPushNotificationConfigParams,
+    ListTasksParams,
+    ListTasksResult,
     Message,
     MessageSendConfiguration,
     MessageSendParams,
@@ -173,6 +175,15 @@ async def get_task(
             request, context=context, extensions=extensions
         )
 
+    async def list_tasks(
+        self,
+        request: ListTasksParams,
+        *,
+        context: ClientCallContext | None = None,
+    ) -> ListTasksResult:
+        """Retrieves tasks for an agent."""
+        return await self._transport.list_tasks(request, context=context)
+
     async def cancel_task(
         self,
         request: TaskIdParams,

src/a2a/client/client.py

@@ -12,6 +12,8 @@
 from a2a.types import (
     AgentCard,
     GetTaskPushNotificationConfigParams,
+    ListTasksParams,
+    ListTasksResult,
     Message,
     PushNotificationConfig,
     Task,
@@ -137,6 +139,15 @@ async def get_task(
     ) -> Task:
         """Retrieves the current state and history of a specific task."""
 
+    @abstractmethod
+    async def list_tasks(
+        self,
+        request: ListTasksParams,
+        *,
+        context: ClientCallContext | None = None,
+    ) -> ListTasksResult:
+        """Retrieves tasks for an agent."""
+
     @abstractmethod
     async def cancel_task(
         self,

src/a2a/client/transports/base.py

@@ -8,6 +8,8 @@
 from a2a.types import (
     AgentCard,
     GetTaskPushNotificationConfigParams,
+    ListTasksParams,
+    ListTasksResult,
     Message,
     MessageSendParams,
     Task,
@@ -69,6 +71,15 @@ async def get_task(
     ) -> Task:
         """Retrieves the current state and history of a specific task."""
 
+    @abstractmethod
+    async def list_tasks(
+        self,
+        request: ListTasksParams,
+        *,
+        context: ClientCallContext | None = None,
+    ) -> ListTasksResult:
+        """Retrieves tasks for an agent."""
+
     @abstractmethod
     async def cancel_task(
         self,

src/a2a/client/transports/grpc.py

@@ -2,6 +2,8 @@
 
 from collections.abc import AsyncGenerator, Callable
 
+from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
+
 
 try:
     import grpc
@@ -22,6 +24,8 @@
 from a2a.types import (
     AgentCard,
     GetTaskPushNotificationConfigParams,
+    ListTasksParams,
+    ListTasksResult,
     Message,
     MessageSendParams,
     Task,
@@ -169,6 +173,19 @@ async def get_task(
         )
         return proto_utils.FromProto.task(task)
 
+    async def list_tasks(
+        self,
+        request: ListTasksParams,
+        *,
+        context: ClientCallContext | None = None,
+    ) -> ListTasksResult:
+        """Retrieves tasks for an agent."""
+        response = await self.stub.ListTasks(
+            proto_utils.ToProto.list_tasks_request(request)
+        )
+        page_size = request.page_size or DEFAULT_LIST_TASKS_PAGE_SIZE
+        return proto_utils.FromProto.list_tasks_result(response, page_size)
+
     async def cancel_task(
         self,
         request: TaskIdParams,

src/a2a/client/transports/jsonrpc.py

@@ -31,6 +31,10 @@
     GetTaskRequest,
     GetTaskResponse,
     JSONRPCErrorResponse,
+    ListTasksParams,
+    ListTasksRequest,
+    ListTasksResponse,
+    ListTasksResult,
     Message,
     MessageSendParams,
     SendMessageRequest,
@@ -246,6 +250,26 @@ async def get_task(
             raise A2AClientJSONRPCError(response.root)
         return response.root.result
 
+    async def list_tasks(
+        self,
+        request: ListTasksParams,
+        *,
+        context: ClientCallContext | None = None,
+    ) -> ListTasksResult:
+        """Retrieves tasks for an agent."""
+        rpc_request = ListTasksRequest(params=request, id=str(uuid4()))
+        payload, modified_kwargs = await self._apply_interceptors(
+            'tasks/list',
+            rpc_request.model_dump(mode='json', exclude_none=True),
+            self._get_http_args(context),
+            context,
+        )
+        response_data = await self._send_request(payload, modified_kwargs)
+        response = ListTasksResponse.model_validate(response_data)
+        if isinstance(response.root, JSONRPCErrorResponse):
+            raise A2AClientJSONRPCError(response.root)
+        return response.root.result
+
     async def cancel_task(
         self,
         request: TaskIdParams,

src/a2a/client/transports/rest.py

@@ -8,6 +8,7 @@
 
 from google.protobuf.json_format import MessageToDict, Parse, ParseDict
 from httpx_sse import SSEError, aconnect_sse
+from pydantic import BaseModel
 
 from a2a.client.card_resolver import A2ACardResolver
 from a2a.client.errors import (
@@ -22,6 +23,8 @@
 from a2a.types import (
     AgentCard,
     GetTaskPushNotificationConfigParams,
+    ListTasksParams,
+    ListTasksResult,
     Message,
     MessageSendParams,
     Task,
@@ -32,6 +35,7 @@
     TaskStatusUpdateEvent,
 )
 from a2a.utils import proto_utils
+from a2a.utils.constants import DEFAULT_LIST_TASKS_PAGE_SIZE
 from a2a.utils.telemetry import SpanKind, trace_class
 
 
@@ -252,6 +256,28 @@ async def get_task(
         ParseDict(response_data, task)
         return proto_utils.FromProto.task(task)
 
+    async def list_tasks(
+        self,
+        request: ListTasksParams,
+        *,
+        context: ClientCallContext | None = None,
+    ) -> ListTasksResult:
+        """Retrieves tasks for an agent."""
+        _, modified_kwargs = await self._apply_interceptors(
+            request.model_dump(mode='json', exclude_none=True),
+            self._get_http_args(context),
+            context,
+        )
+        response_data = await self._send_get_request(
+            '/v1/tasks',
+            _model_to_query_params(request),
+            modified_kwargs,
+        )
+        response = a2a_pb2.ListTasksResponse()
+        ParseDict(response_data, response)
+        page_size = request.page_size or DEFAULT_LIST_TASKS_PAGE_SIZE
+        return proto_utils.FromProto.list_tasks_result(response, page_size)
+
     async def cancel_task(
         self,
         request: TaskIdParams,
@@ -425,3 +451,21 @@ async def get_card(
     async def close(self) -> None:
         """Closes the httpx client."""
         await self.httpx_client.aclose()
+
+
+def _model_to_query_params(instance: BaseModel) -> dict[str, str]:
+    data = instance.model_dump(mode='json', exclude_none=True)
+    return _json_to_query_params(data)
+
+
+def _json_to_query_params(data: dict[str, Any]) -> dict[str, str]:
+    query_dict = {}
+    for key, value in data.items():
+        if isinstance(value, list):
+            query_dict[key] = ','.join(map(str, value))
+        elif isinstance(value, bool):
+            query_dict[key] = str(value).lower()
+        else:
+            query_dict[key] = str(value)
+
+    return query_dict