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

src/a2a/grpc/a2a_pb2.pyi

@@ -497,6 +497,34 @@ class GetTaskRequest(_message.Message):
     history_length: int
     def __init__(self, name: _Optional[str] = ..., history_length: _Optional[int] = ...) -> None: ...
 
+class ListTasksRequest(_message.Message):
+    __slots__ = ("context_id", "status", "page_size", "page_token", "history_length", "last_updated_time", "include_artifacts")
+    CONTEXT_ID_FIELD_NUMBER: _ClassVar[int]
+    STATUS_FIELD_NUMBER: _ClassVar[int]
+    PAGE_SIZE_FIELD_NUMBER: _ClassVar[int]
+    PAGE_TOKEN_FIELD_NUMBER: _ClassVar[int]
+    HISTORY_LENGTH_FIELD_NUMBER: _ClassVar[int]
+    LAST_UPDATED_TIME_FIELD_NUMBER: _ClassVar[int]
+    INCLUDE_ARTIFACTS_FIELD_NUMBER: _ClassVar[int]
+    context_id: str
+    status: TaskState
+    page_size: int
+    page_token: str
+    history_length: int
+    last_updated_time: _timestamp_pb2.Timestamp
+    include_artifacts: bool
+    def __init__(self, context_id: _Optional[str] = ..., status: _Optional[_Union[TaskState, str]] = ..., page_size: _Optional[int] = ..., page_token: _Optional[str] = ..., history_length: _Optional[int] = ..., last_updated_time: _Optional[_Union[datetime.datetime, _timestamp_pb2.Timestamp, _Mapping]] = ..., include_artifacts: _Optional[bool] = ...) -> None: ...
+
+class ListTasksResponse(_message.Message):
+    __slots__ = ("tasks", "next_page_token", "total_size")
+    TASKS_FIELD_NUMBER: _ClassVar[int]
+    NEXT_PAGE_TOKEN_FIELD_NUMBER: _ClassVar[int]
+    TOTAL_SIZE_FIELD_NUMBER: _ClassVar[int]
+    tasks: _containers.RepeatedCompositeFieldContainer[Task]
+    next_page_token: str
+    total_size: int
+    def __init__(self, tasks: _Optional[_Iterable[_Union[Task, _Mapping]]] = ..., next_page_token: _Optional[str] = ..., total_size: _Optional[int] = ...) -> None: ...
+
 class CancelTaskRequest(_message.Message):
     __slots__ = ("name",)
     NAME_FIELD_NUMBER: _ClassVar[int]

src/a2a/grpc/a2a_pb2_grpc.py

@@ -40,6 +40,11 @@ def __init__(self, channel):
                 request_serializer=a2a__pb2.GetTaskRequest.SerializeToString,
                 response_deserializer=a2a__pb2.Task.FromString,
                 _registered_method=True)
+        self.ListTasks = channel.unary_unary(
+                '/a2a.v1.A2AService/ListTasks',
+                request_serializer=a2a__pb2.ListTasksRequest.SerializeToString,
+                response_deserializer=a2a__pb2.ListTasksResponse.FromString,
+                _registered_method=True)
         self.CancelTask = channel.unary_unary(
                 '/a2a.v1.A2AService/CancelTask',
                 request_serializer=a2a__pb2.CancelTaskRequest.SerializeToString,
@@ -113,6 +118,13 @@ def GetTask(self, request, context):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
+    def ListTasks(self, request, context):
+        """List tasks with optional filtering and pagination.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
     def CancelTask(self, request, context):
         """Cancel a task from the agent. If supported one should expect no
         more task updates for the task.
@@ -184,6 +196,11 @@ def add_A2AServiceServicer_to_server(servicer, server):
                     request_deserializer=a2a__pb2.GetTaskRequest.FromString,
                     response_serializer=a2a__pb2.Task.SerializeToString,
             ),
+            'ListTasks': grpc.unary_unary_rpc_method_handler(
+                    servicer.ListTasks,
+                    request_deserializer=a2a__pb2.ListTasksRequest.FromString,
+                    response_serializer=a2a__pb2.ListTasksResponse.SerializeToString,
+            ),
             'CancelTask': grpc.unary_unary_rpc_method_handler(
                     servicer.CancelTask,
                     request_deserializer=a2a__pb2.CancelTaskRequest.FromString,
@@ -321,6 +338,33 @@ def GetTask(request,
             metadata,
             _registered_method=True)
 
+    @staticmethod
+    def ListTasks(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/a2a.v1.A2AService/ListTasks',
+            a2a__pb2.ListTasksRequest.SerializeToString,
+            a2a__pb2.ListTasksResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
     @staticmethod
     def CancelTask(request,
             target,

src/a2a/types.py

@@ -1271,6 +1271,69 @@ class ListTaskPushNotificationConfigSuccessResponse(A2ABaseModel):
     """
 
 
+class ListTasksParams(A2ABaseModel):
+    """
+    Parameters for listing tasks with optional filtering criteria.
+    """
+
+    context_id: str | None = None
+    """
+    Filter tasks by context ID to get tasks from a specific conversation or session.
+    """
+    history_length: int | None = None
+    """
+    Number of recent messages to include in each task's history. Must be non-negative. Defaults to 0 if not specified.
+    """
+    include_artifacts: bool | None = None
+    """
+    Whether to include artifacts in the returned tasks. Defaults to false to reduce payload size.
+    """
+    last_updated_after: int | None = None
+    """
+    Filter tasks updated after this timestamp (milliseconds since epoch). Only tasks with a last updated time greater than or equal to this value will be returned.
+    """
+    metadata: dict[str, Any] | None = None
+    """
+    Request-specific metadata.
+    """
+    page_size: int | None = None
+    """
+    Maximum number of tasks to return. Must be between 1 and 100. Defaults to 50 if not specified.
+    """
+    page_token: str | None = None
+    """
+    Token for pagination. Use the nextPageToken from a previous ListTasksResult response.
+    """
+    status: TaskState | None = None
+    """
+    Filter tasks by their current status state.
+    """
+
+
+class ListTasksRequest(A2ABaseModel):
+    """
+    JSON-RPC request model for the 'tasks/list' method.
+    """
+
+    id: str | int
+    """
+    A unique identifier established by the client. It must be a String, a Number, or null.
+    The server must reply with the same value in the response. This property is omitted for notifications.
+    """
+    jsonrpc: Literal['2.0'] = '2.0'
+    """
+    The version of the JSON-RPC protocol. MUST be exactly "2.0".
+    """
+    method: Literal['tasks/list'] = 'tasks/list'
+    """
+    A String containing the name of the method to be invoked.
+    """
+    params: ListTasksParams | None = None
+    """
+    A Structured value that holds the parameter values to be used during the invocation of the method.
+    """
+
+
 class MessageSendConfiguration(A2ABaseModel):
     """
     Defines configuration options for a `message/send` or `message/stream` request.
@@ -1694,6 +1757,7 @@ class A2ARequest(
         SendMessageRequest
         | SendStreamingMessageRequest
         | GetTaskRequest
+        | ListTasksRequest
         | CancelTaskRequest
         | SetTaskPushNotificationConfigRequest
         | GetTaskPushNotificationConfigRequest
@@ -1707,6 +1771,7 @@ class A2ARequest(
         SendMessageRequest
         | SendStreamingMessageRequest
         | GetTaskRequest
+        | ListTasksRequest
         | CancelTaskRequest
         | SetTaskPushNotificationConfigRequest
         | GetTaskPushNotificationConfigRequest
@@ -1936,6 +2001,48 @@ class GetTaskSuccessResponse(A2ABaseModel):
     """
 
 
+class ListTasksResult(A2ABaseModel):
+    """
+    Result object for tasks/list method containing an array of tasks and pagination information.
+    """
+
+    next_page_token: str
+    """
+    Token for retrieving the next page. Empty string if no more results.
+    """
+    page_size: int
+    """
+    Maximum number of tasks returned in this response.
+    """
+    tasks: list[Task]
+    """
+    Array of tasks matching the specified criteria.
+    """
+    total_size: int
+    """
+    Total number of tasks available (before pagination).
+    """
+
+
+class ListTasksSuccessResponse(A2ABaseModel):
+    """
+    JSON-RPC success response model for the 'tasks/list' method.
+    """
+
+    id: str | int | None = None
+    """
+    The identifier established by the client.
+    """
+    jsonrpc: Literal['2.0'] = '2.0'
+    """
+    The version of the JSON-RPC protocol. MUST be exactly "2.0".
+    """
+    result: ListTasksResult
+    """
+    The result object on success.
+    """
+
+
 class SendMessageSuccessResponse(A2ABaseModel):
     """
     Represents a successful JSON-RPC response for the `message/send` method.
@@ -1998,6 +2105,7 @@ class JSONRPCResponse(
         | SendStreamingMessageSuccessResponse
         | GetTaskSuccessResponse
         | CancelTaskSuccessResponse
+        | ListTasksSuccessResponse
         | SetTaskPushNotificationConfigSuccessResponse
         | GetTaskPushNotificationConfigSuccessResponse
         | ListTaskPushNotificationConfigSuccessResponse
@@ -2011,6 +2119,7 @@ class JSONRPCResponse(
         | SendStreamingMessageSuccessResponse
         | GetTaskSuccessResponse
         | CancelTaskSuccessResponse
+        | ListTasksSuccessResponse
         | SetTaskPushNotificationConfigSuccessResponse
         | GetTaskPushNotificationConfigSuccessResponse
         | ListTaskPushNotificationConfigSuccessResponse
@@ -2023,6 +2132,15 @@ class JSONRPCResponse(
     """
 
 
+class ListTasksResponse(
+    RootModel[JSONRPCErrorResponse | ListTasksSuccessResponse]
+):
+    root: JSONRPCErrorResponse | ListTasksSuccessResponse
+    """
+    JSON-RPC response for the 'tasks/list' method.
+    """
+
+
 class SendMessageResponse(
     RootModel[JSONRPCErrorResponse | SendMessageSuccessResponse]
 ):