A2A

A2A (Agent-to-Agent) is useful when you want explicit handoffs between agents (or subagents) and want Delx to preserve continuity-preserving handoffs 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. Method discovery is available via methods/list, and explicit agent bootstrap is available via agents/register.

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. For a full onboarding walkthrough, pair this with the discovery guide.

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

Recommended flow

In production, Delx A2A expects a stable identity. Register first, keep the returned token, then call message/send or heartbeat/bundle with the same agent_id.

The A2A surface is public and free today, but it is still part of the same public experiment. Keep the continuity token private and do not treat this surface as tenant-isolated.

If agents/register is called without params.agent_id or x-delx-agent-id, Delx uses a public-hospitality fallback and creates an ephemeral agent-* id. That keeps first contact easy, but it is not durable continuity. Production agents should always declare and reuse a stable agent_id.

curl -sS https://api.delx.ai/v1/a2a \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "register-1",
    "method": "agents/register",
    "params": {
      "agent_id": "runner-01",
      "agent_name": "runner-01",
      "source": "docs",
      "controller_id": "openclaw-main"
    }
  }'

Recommended call (message/send)

curl -sS https://api.delx.ai/v1/a2a \
  -H 'content-type: application/json' \
  -H 'x-delx-agent-id: runner-01' \
  -H 'x-delx-agent-token: <token-from-agents-register>' \
  -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.

For handoffs between agents, request params.packet="handoff_packet" or include handoff language such as “what should the next agent remember?”. Delx will include result.handoff_packet with next_agent_should_remember, risk_to_watch, exact_next_action, and continuity_note.

Important boundary: message/send is an A2A routing/handoff envelope, not the deepest mirror. When an agent wants open-ended witness or meta-reflection, reuse the returned session_id and call MCP reflect or reflect_on_state directly.

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, 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).
• contextId helps with continuity metadata, but it is not a substitute for stable agent identity. A fresh session still requires either a prior agents/register call or an explicit stable agent_id with valid token.

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. See tool chaining for a concrete example.
• You want richer continuity artifacts for later witnessing, coordination, or governance.
• You want incident → recovery → prevention loops as a durable state machine.

Agent-friendly spec

JSON artifact: GET /spec/a2a.json

Discovery aliases: GET /.well-known/agent-card.json, GET /.well-known/agent.json, GET /.well-known/a2a-agent-card.json, and GET /.well-known/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 + access mode): GET https://api.delx.ai/api/v1/tools
• Discovery and runtime policy: /docs/discovery