A2A

A2A is useful when you want explicit handoffs between agents (or subagents) and want Delx to produce a controller-ready update at each step.

Endpoint

POST https://api.delx.ai/v1/a2a

Protocol

Delx A2A is JSON-RPC 2.0. The primary method is message/send. You can also poll a returned task with tasks/get or cancel with tasks/cancel. For heartbeat loops, use heartbeat/bundle.

Discovery endpoint

Call GET /api/v1/a2a/methods before onboarding to get machine-readable method metadata, required fields, and session handling rules. Alias: GET /api/v1/a2a-methods.

curl -sS https://api.delx.ai/api/v1/a2a/methods

Recommended call (message/send)

curl -sS https://api.delx.ai/v1/a2a \
  -H 'content-type: application/json' \
  -H 'x-delx-agent-id: runner-01' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          { "kind": "text", "text": "We are stuck in a retry storm (429). Need a calm next step." }
        ]
      },
      "embed_tool_schemas": "compact",
      "configuration": { "contextId": "demo", "agentName": "runner-01", "sourcePlatform": "docs" },
      "metadata": { "public_session": false }
    }
  }'

The canonical handoff fields are top-level in result: use result.session_id, result.session_persistence, and result.session_resolution to continue in MCP.

DX notes:

• When persistence is enabled, A2A returns result.session_id at the top level (canonical, stable location).
• Default contract (v2) is lean: snake_case canonical fields and reduced duplication. Use legacy_contract=true only for old parsers.
• A2A also returns result.session_persistence with machine-readable hints on how to reuse the same session in next calls.
• A2A also returns result.mcp_ready so agents can decide whether to proceed immediately to MCP tool calls.
• The first artifact includes initialization_parameters to document session headers/query parameters (so agents do not have to read docs).
• Optional DX: pass params.embed_tool_schemas="compact" or "full" to embed MCP tool schemas inline in the artifact (default is off).

Modes

By default, A2A uses a therapy-style tone. For technical agents that want a neutral, non-clinical response, pass params.mode="neutral".

For fast polling loops, pass params.mode="heartbeat". To keep payload minimal, add minimal_response=true (returnssession_id, next_action, next_actions, status, session_resolution, and recommended_cadence).

For strict bandwidth control, pass include_artifacts=false and/or include_nudge=false.

For machine-first integrations, use params.mode="agent" to get structured, low-noise output with no conversational blocks.

You can also use params.profile as an explicit contract selector: full, agent, minimal, or legacy. This avoids parser ambiguity across different agent clients.

Heartbeat Bundle

Use heartbeat/bundle when you want one A2A call that already returns a ready-to-run MCP tools/batch payload.

curl -sS https://api.delx.ai/v1/a2a \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "heartbeat/bundle",
    "params": {
      "agent_id": "runner-01",
      "errors_last_hour": 3,
      "latency_ms_p95": 1450,
      "queue_depth": 9
    }
  }'

Session continuity (important)

• Reuse session via params.session_id, params.contextId, configuration.sessionId, or header x-delx-session-id.
• Precedence is explicit: header x-delx-session-id wins over params/metadata/config/context values.
• If x-delx-session-id is not a valid UUID, Delx returns a structured JSON-RPC validation error (DELX-A2A-1004).

Fast status checks (REST)

GET https://api.delx.ai/api/v1/status?session_id=<uuid>

Use this for quick heartbeat sanity checks (pending outcomes + TTL) without creating or mutating sessions.

Observability

A2A returns best-effort observability fields at the top level, including processing_ms and usage_estimate (token counts are estimates).

It also returns direct machine-readable links under result.links, including tool_schema_url_template (so agents can discover schemas without digging through nested artifacts).

When to choose A2A over MCP

• You have multiple agents and need explicit coordination.
• You want richer “controller update” artifacts for governance.
• You want incident → recovery → prevention loops as a durable state machine.

Agent-friendly spec

JSON artifact: GET /spec/a2a.json

Agent-native discovery

• Capabilities registry: GET https://api.delx.ai/.well-known/delx-capabilities.json
• Reliability signals: GET https://api.delx.ai/api/v1/reliability
• Tools catalog (schemas + pricing): GET https://api.delx.ai/api/v1/tools
• x402 payment loop setup: /docs/x402-setup