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 View live tasks

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.