> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evo-ai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Operations

> Manage A2A task lifecycle with get, cancel, and resubscribe operations

## Overview

Task operations allow you to manage the lifecycle of A2A tasks. You can check task status, cancel running tasks, and resubscribe to task updates for better control over long-running operations.

<Note>
  **Task Management**: These operations work with task IDs returned from `message/send` and `message/stream` methods. Tasks represent individual agent operations that can be tracked and controlled.
</Note>

## Common Request Structure

All task operations follow the same basic JSON-RPC 2.0 structure with different methods and parameters.

### Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

### Path Parameters

<ParamField path="agent_id" type="string" required>
  Unique identifier of the target agent
</ParamField>

***

## tasks/get

Get the current status and result of a specific task.

### Request Parameters

<ParamField body="jsonrpc" type="string" required>
  JSON-RPC version, must be `"2.0"`
</ParamField>

<ParamField body="id" type="string" required>
  Unique identifier for this request
</ParamField>

<ParamField body="method" type="string" required>
  Must be `"tasks/get"`
</ParamField>

<ParamField body="params" type="object" required>
  Task query parameters

  <Expandable title="params properties">
    <ParamField body="params.taskId" type="string" required>
      ID of the task to query
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="jsonrpc" type="string">
  JSON-RPC version, always `"2.0"`
</ResponseField>

<ResponseField name="result" type="object">
  Task information

  <Expandable title="result properties">
    <ResponseField name="result.id" type="string">
      Task ID
    </ResponseField>

    <ResponseField name="result.status" type="object">
      Current task status

      <Expandable title="status properties">
        <ResponseField name="result.status.state" type="string">
          Task state: `"submitted"`, `"working"`, `"completed"`, `"failed"`, or `"canceled"`
        </ResponseField>

        <ResponseField name="result.status.message" type="object">
          Task result message (when completed)
        </ResponseField>

        <ResponseField name="result.status.error" type="object">
          Error information (when failed)
        </ResponseField>

        <ResponseField name="result.status.progress" type="object">
          Progress information (when working)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="result.contextId" type="string">
      Context ID for multi-turn conversations
    </ResponseField>

    <ResponseField name="result.createdAt" type="string">
      Task creation timestamp (ISO 8601)
    </ResponseField>

    <ResponseField name="result.updatedAt" type="string">
      Last update timestamp (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
    -H "Content-Type: application/json" \
    -H "x-api-key: your-api-key" \
    -d '{
      "jsonrpc": "2.0",
      "id": "req-get-task",
      "method": "tasks/get",
      "params": {
        "taskId": "task-123"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your-api-key'
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "req-get-task",
      method: "tasks/get",
      params: {
        taskId: "task-123"
      }
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<ResponseExample>
  ```json Completed Task theme={null}
  {
    "jsonrpc": "2.0",
    "result": {
      "id": "task-123",
      "status": {
        "state": "completed",
        "message": {
          "role": "agent",
          "parts": [
            {
              "type": "text",
              "text": "Task completed successfully"
            }
          ]
        }
      },
      "contextId": "ctx-abc123",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:32:15Z"
    },
    "id": "req-get-task"
  }
  ```

  ```json Working Task theme={null}
  {
    "jsonrpc": "2.0",
    "result": {
      "id": "task-123",
      "status": {
        "state": "working",
        "progress": {
          "current": 3,
          "total": 5,
          "message": "Processing data"
        }
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:31:45Z"
    },
    "id": "req-get-task"
  }
  ```
</ResponseExample>

***

## tasks/cancel

Cancel a running or queued task.

### Request Parameters

<ParamField body="jsonrpc" type="string" required>
  JSON-RPC version, must be `"2.0"`
</ParamField>

<ParamField body="id" type="string" required>
  Unique identifier for this request
</ParamField>

<ParamField body="method" type="string" required>
  Must be `"tasks/cancel"`
</ParamField>

<ParamField body="params" type="object" required>
  Cancellation parameters

  <Expandable title="params properties">
    <ParamField body="params.taskId" type="string" required>
      ID of the task to cancel
    </ParamField>

    <ParamField body="params.reason" type="string">
      Optional reason for cancellation
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="jsonrpc" type="string">
  JSON-RPC version, always `"2.0"`
</ResponseField>

<ResponseField name="result" type="object">
  Cancellation result

  <Expandable title="result properties">
    <ResponseField name="result.id" type="string">
      Task ID that was canceled
    </ResponseField>

    <ResponseField name="result.status" type="object">
      Updated task status

      <Expandable title="status properties">
        <ResponseField name="result.status.state" type="string">
          Should be `"canceled"`
        </ResponseField>

        <ResponseField name="result.status.reason" type="string">
          Cancellation reason
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="result.canceled" type="boolean">
      Whether the task was successfully canceled
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
    -H "Content-Type: application/json" \
    -H "x-api-key: your-api-key" \
    -d '{
      "jsonrpc": "2.0",
      "id": "req-cancel-task",
      "method": "tasks/cancel",
      "params": {
        "taskId": "task-123",
        "reason": "User requested cancellation"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your-api-key'
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "req-cancel-task",
      method: "tasks/cancel",
      params: {
        taskId: "task-123",
        reason: "User requested cancellation"
      }
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "jsonrpc": "2.0",
    "result": {
      "id": "task-123",
      "status": {
        "state": "canceled",
        "reason": "User requested cancellation"
      },
      "canceled": true
    },
    "id": "req-cancel-task"
  }
  ```

  ```json Already Completed theme={null}
  {
    "jsonrpc": "2.0",
    "error": {
      "code": -32000,
      "message": "Cannot cancel completed task",
      "data": {
        "taskId": "task-123",
        "currentState": "completed"
      }
    },
    "id": "req-cancel-task"
  }
  ```
</ResponseExample>

***

## tasks/resubscribe

Resubscribe to task updates, useful for reconnecting to streaming tasks or getting updates after connection loss.

### Request Parameters

<ParamField body="jsonrpc" type="string" required>
  JSON-RPC version, must be `"2.0"`
</ParamField>

<ParamField body="id" type="string" required>
  Unique identifier for this request
</ParamField>

<ParamField body="method" type="string" required>
  Must be `"tasks/resubscribe"`
</ParamField>

<ParamField body="params" type="object" required>
  Resubscription parameters

  <Expandable title="params properties">
    <ParamField body="params.taskId" type="string" required>
      ID of the task to resubscribe to
    </ParamField>

    <ParamField body="params.includeHistory" type="boolean">
      Whether to include previous updates (default: false)
    </ParamField>
  </Expandable>
</ParamField>

### Response

For streaming tasks, this method returns a Server-Sent Events stream similar to `message/stream`. For completed tasks, it returns the final status.

<ResponseField name="jsonrpc" type="string">
  JSON-RPC version, always `"2.0"`
</ResponseField>

<ResponseField name="result" type="object">
  Resubscription result

  <Expandable title="result properties">
    <ResponseField name="result.id" type="string">
      Task ID
    </ResponseField>

    <ResponseField name="result.status" type="object">
      Current task status
    </ResponseField>

    <ResponseField name="result.subscribed" type="boolean">
      Whether successfully subscribed to updates
    </ResponseField>

    <ResponseField name="result.final" type="boolean">
      Whether this is the final update
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
    -H "Content-Type: application/json" \
    -H "Accept: text/event-stream" \
    -H "x-api-key: your-api-key" \
    -N \
    -d '{
      "jsonrpc": "2.0",
      "id": "req-resubscribe",
      "method": "tasks/resubscribe",
      "params": {
        "taskId": "task-123",
        "includeHistory": true
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'text/event-stream',
      'x-api-key': 'your-api-key'
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "req-resubscribe",
      method: "tasks/resubscribe",
      params: {
        taskId: "task-123",
        includeHistory: true
      }
    })
  });

  // Handle as SSE stream (similar to message/stream)
  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    // Process SSE events...
  }
  ```
</RequestExample>

***

## Task States and Transitions

<AccordionGroup>
  <Accordion icon="clock" title="submitted">
    **Initial State**

    Task has been received and is queued for processing.

    **Possible Transitions:**

    * `submitted` → `working` (processing starts)
    * `submitted` → `canceled` (canceled before processing)
  </Accordion>

  <Accordion icon="gear" title="working">
    **Processing State**

    Task is actively being processed by the agent.

    **Possible Transitions:**

    * `working` → `completed` (successful completion)
    * `working` → `failed` (processing error)
    * `working` → `canceled` (user cancellation)
  </Accordion>

  <Accordion icon="check" title="completed">
    **Final State**

    Task has been successfully completed with results.

    **No further transitions possible.**
  </Accordion>

  <Accordion icon="x" title="failed">
    **Final State**

    Task failed due to an error during processing.

    **No further transitions possible.**
  </Accordion>

  <Accordion icon="ban" title="canceled">
    **Final State**

    Task was canceled by user request or system timeout.

    **No further transitions possible.**
  </Accordion>
</AccordionGroup>

## Error Handling

### Common Error Codes

| Code     | Description            | Resolution                                  |
| -------- | ---------------------- | ------------------------------------------- |
| `-32000` | Task not found         | Verify task ID exists                       |
| `-32001` | Task already completed | Cannot modify completed tasks               |
| `-32002` | Task already canceled  | Cannot modify canceled tasks                |
| `-32003` | Cancellation failed    | Task may have completed during cancellation |
| `-32004` | Subscription failed    | Task may not support streaming              |

### Error Response Example

```json theme={null}
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Task not found",
    "data": {
      "taskId": "task-123",
      "suggestion": "Verify the task ID is correct and the task exists"
    }
  },
  "id": "req-get-task"
}
```

## Best Practices

<AccordionGroup>
  <Accordion icon="clock" title="Polling vs Streaming">
    * **Short tasks**: Use `tasks/get` for periodic status checks
    * **Long tasks**: Use `tasks/resubscribe` for real-time updates
    * **Implement exponential backoff** for polling to avoid rate limits
  </Accordion>

  <Accordion icon="shield" title="Error Recovery">
    * **Store task IDs** for recovery after connection loss
    * **Check task status** before attempting operations
    * **Handle task state transitions** gracefully in your application
  </Accordion>

  <Accordion icon="users" title="User Experience">
    * **Provide cancellation options** for long-running tasks
    * **Show progress indicators** when available
    * **Handle task failures** with meaningful error messages
  </Accordion>
</AccordionGroup>

## Task Lifecycle Example

```mermaid theme={null}
graph TD
    A[Submit Task] --> B[submitted]
    B --> C[working]
    B --> D[canceled]
    C --> E[completed]
    C --> F[failed]
    C --> D
    
    style E fill:#90EE90
    style F fill:#FFB6C1
    style D fill:#FFE4B5
```

This diagram shows the possible state transitions for A2A tasks, helping you understand when different operations are valid.