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.

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"

id · 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

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

Completed Task

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

id · 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

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

Success

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

id · 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

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 State

Task has been received and is queued for processing.

Possible Transitions:

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

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)

completed

Final State

Task has been successfully completed with results.

No further transitions possible.

failed

Final State

Task failed due to an error during processing.

No further transitions possible.

canceled

Final State

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