Task Operations

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

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

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

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

POST

api

a2a

{agent_id}

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

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

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

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

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

string

required

Must be application/json

string

required

Your API key for authentication

Path Parameters

string

required

Unique identifier of the target agent

tasks/get

Get the current status and result of a specific task.

Request Parameters

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

string

required

Must be "tasks/get"

object

required

Task query parameters

Show params properties

string

required

ID of the task to query

Response

string

JSON-RPC version, always "2.0"

object

Task information

Show result properties

string

Task ID

object

Current task status

Show status properties

string

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

object

Task result message (when completed)

object

Error information (when failed)

object

Progress information (when working)

string

Context ID for multi-turn conversations

string

Task creation timestamp (ISO 8601)

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

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

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

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

tasks/cancel

Cancel a running or queued task.

Request Parameters

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

string

required

Must be "tasks/cancel"

object

required

Cancellation parameters

Show params properties

string

required

ID of the task to cancel

string

Optional reason for cancellation

Response

string

JSON-RPC version, always "2.0"

object

Cancellation result

Show result properties

string

Task ID that was canceled

object

Updated task status

Show status properties

string

Should be "canceled"

string

Cancellation reason

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

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

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

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Cannot cancel completed task",
    "data": {
      "taskId": "task-123",
      "currentState": "completed"
    }
  },
  "id": "req-cancel-task"
}

tasks/resubscribe

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

Request Parameters

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request

string

required

Must be "tasks/resubscribe"

object

required

Resubscription parameters

Show params properties

string

required

ID of the task to resubscribe to

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.

string

JSON-RPC version, always "2.0"

object

Resubscription result

Show result properties

string

Task ID

object

Current task status

boolean

Whether successfully subscribed to updates

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

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

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

​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