# Agent tasks.  Streaming trace.

The A2A protocol lets agents communicate via JSON-RPC 2.0 task requests. Tasks stream live updates via SSE. Payment-required events are first-class — handled via the x402 extension, not as errors.

[A2A reference](/content/docs/a2a/index.html) [View live tasks](/content/dashboard/tasks/index.html)

## Task lifecycle

### Five states

`pending` Task received. Not yet assigned to a worker.

`processing` Agent is executing. SSE stream is open.

`completed` Artifacts available. Final state.

`failed` Execution error. Includes error message and requestId.

`cancelled` Cancelled by caller before completion.

## JSON-RPC 2.0

### Methods

`tasks/send`

Submit a new task. Returns task object with initial state.

`tasks/get`

Retrieve task by ID. Includes artifacts if completed.

`tasks/cancel`

Cancel an in-progress task. Idempotent.

`tasks/sendSubscribe`

Submit and subscribe. Opens SSE stream for live updates.

All methods POST to `POST /api/a2a` with JSON-RPC 2.0 envelope.

## Send a task

```
curl -X POST https://p402.io/api/a2a \
  -H "Authorization: Bearer $P402_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n    "jsonrpc": "2.0",\n    "method": "tasks/send",\n    "id": "1",\n    "params": {\n      "message": {\n        "role": "user",\n        "parts": [{\
          "type": "text",\
          "text": "Analyze this dataset"\
        }]\n      },\n      "metadata": {\n        "budget_usd": 0.50\n      }\n    }\n  }'
```

### Response:
```
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "id": "task_01HX...",
    "status": { "state": "pending" }
  }
}
```

## Paid workflows

### Payment-required tasks

When an agent requires payment, it emits a `payment-required` message — not an HTTP error. The orchestrator handles the x402 extension inline.

Agent sends  
`{ type: 'payment-required', data: X402PaymentRequired }`

Client sends  
`{ type: 'payment-submitted', data: X402PaymentSubmitted }`

Agent sends  
`{ type: 'payment-completed', data: X402PaymentCompleted }`

Payment events appear as structured cards in the Tasks dashboard. Billing cap errors are returned as JSON-RPC `-32000` block errors — the orchestrator does not crash.

## SSE stream subscription

```
# Subscribe to task updates:
curl -N https://p402.io/api/a2a/stream?taskId=task_01HX... \
  -H "Authorization: Bearer $P402_API_KEY"

# Stream events:
data: {"type":"status","state":"processing"}
data: {"type":"payment-required","amount":"500000"}
data: {"type":"payment-completed","txHash":"0x..."}
data: {"type":"status","state":"completed"}
data: {"type":"artifact","text":"Analysis complete..."}
```

## Decision trace

### See every routing decision

The trace viewer streams every routing decision in real time — provider selected, cost saved, mandate checked, policy enforced, settlement attempted. Useful for debugging and auditing agentic workflows.