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

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.

Common Request Structure

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

Headers

Content-Type

string

required

Must be application/json

x-api-key

string

required

Your API key for authentication

Path Parameters

agent_id

string

required

Unique identifier of the target agent

tasks/get

Get the current status and result of a specific task.

Request Parameters

jsonrpc

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

method

string

required

Must be "tasks/get"

params

object

required

Task query parameters

Show params properties

params.taskId

string

required

ID of the task to query

Response

jsonrpc

string

JSON-RPC version, always "2.0"

result

object

Task information

Show result properties

result.id

string

Task ID

result.status

object

Current task status

Show status properties

result.status.state

string

Task state: "submitted", "working", "completed", "failed", or "canceled"

result.status.message

object

Task result message (when completed)

result.status.error

object

Error information (when failed)

result.status.progress

object

Progress information (when working)

result.contextId

string

Context ID for multi-turn conversations

result.createdAt

string

Task creation timestamp (ISO 8601)

result.updatedAt

string

Last update timestamp (ISO 8601)

Example

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"
    }
  }'

{
  "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"
}

tasks/cancel

Cancel a running or queued task.

Request Parameters

jsonrpc

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

method

string

required

Must be "tasks/cancel"

params

object

required

Cancellation parameters

Show params properties

params.taskId

string

required

ID of the task to cancel

params.reason

string

Optional reason for cancellation

Response

jsonrpc

string

JSON-RPC version, always "2.0"

result

object

Cancellation result

Show result properties

result.id

string

Task ID that was canceled

result.status

object

Updated task status

Show status properties

result.status.state

string

Should be "canceled"

result.status.reason

string

Cancellation reason

result.canceled

boolean

Whether the task was successfully canceled

Example

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"
    }
  }'

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-123",
    "status": {
      "state": "canceled",
      "reason": "User requested cancellation"
    },
    "canceled": true
  },
  "id": "req-cancel-task"
}

tasks/resubscribe

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

Request Parameters

jsonrpc

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

method

string

required

Must be "tasks/resubscribe"

params

object

required

Resubscription parameters

Show params properties

params.taskId

string

required

ID of the task to resubscribe to

params.includeHistory

boolean

Whether to include previous updates (default: false)

Response

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

jsonrpc

string

JSON-RPC version, always "2.0"

result

object

Resubscription result

Show result properties

result.id

string

Task ID

result.status

object

Current task status

result.subscribed

boolean

Whether successfully subscribed to updates

result.final

boolean

Whether this is the final update

Example

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
    }
  }'

Task States and Transitions

submitted

Initial StateTask has been received and is queued for processing.Possible Transitions:

submitted → working (processing starts)
submitted → canceled (canceled before processing)

working

Processing StateTask is actively being processed by the agent.Possible Transitions:

working → completed (successful completion)
working → failed (processing error)
working → canceled (user cancellation)

completed

Final StateTask has been successfully completed with results.No further transitions possible.

failed

Final StateTask failed due to an error during processing.No further transitions possible.

canceled

Final StateTask was canceled by user request or system timeout.No further transitions possible.

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

{
  "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

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

Error Recovery

Store task IDs for recovery after connection loss
Check task status before attempting operations
Handle task state transitions gracefully in your application

User Experience

Provide cancellation options for long-running tasks
Show progress indicators when available
Handle task failures with meaningful error messages

Task Lifecycle Example

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

API Documentation

A2A Protocol Endpoints

Task Operations

Overview

Common Request Structure

Headers

Path Parameters

tasks/get

Request Parameters

Response

Example

tasks/cancel

Request Parameters

Response

Example

tasks/resubscribe

Request Parameters

Response

Example

Task States and Transitions

Error Handling

Common Error Codes

Error Response Example

Best Practices

Task Lifecycle Example

API Documentation

A2A Protocol Endpoints

​Overview

​Common Request Structure

​Headers

​Path Parameters

​tasks/get

​Request Parameters

​Response

​Example

​tasks/cancel

​Request Parameters

​Response

​Example

​tasks/resubscribe

​Request Parameters

​Response

​Example

​Task States and Transitions

​Error Handling

​Common Error Codes

​Error Response Example

​Best Practices

​Task Lifecycle Example

Overview

Common Request Structure

Headers

Path Parameters

tasks/get

Request Parameters

Response

Example

tasks/cancel

Request Parameters

Response

Example

tasks/resubscribe

Request Parameters

Response

Example

Task States and Transitions

Error Handling

Common Error Codes

Error Response Example

Best Practices

Task Lifecycle Example