A2A, with an actual contract.

Discover and authenticate

Public discovery path: /.well-known/agent-card.json. RPC endpoint: POST /a2a. The card advertises JSONRPC / 1.0 and bearer authentication. Send A2A-Version: 1.0 and Authorization: Bearer YOUR_ISSUED_KEY. Absent version means 0.3 under the specification, which this service rejects; no compatibility layer is enabled. The card is unsigned; use HTTPS and a trusted origin in production.

{
  "jsonrpc": "2.0",
  "id": "example-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "unique-message-0001",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "command": "recommend",
            "requirements": {
              "sites": 2,
              "storage_gb": 20,
              "managed": false
            }
          },
          "mediaType": "application/json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": [
        "application/json"
      ],
      "historyLength": 0
    }
  }
}

This is the A2A 1.0 protobuf JSON shape, not the older kind: data shape. Use one data part per message. Text, files, URLs, arbitrary metadata, tenant overrides, extensions and unknown command fields are rejected rather than interpreted as authority. Returned status text explains the protocol result; the output artifact is structured JSON.

Methods and capability boundaries

Each message creates a new terminal task. For the next step, send a new message with the returned owned contextId, and quote ID where relevant. Do not reopen a completed task via taskId. Task completion means a response was prepared, never that a review was approved, money was paid or service provisioned.

Command payloads

[
  {
    "command": "discover",
    "product_id": "hosting-298"
  },
  {
    "command": "recommend",
    "requirements": {
      "sites": 2,
      "storage_gb": 20
    }
  },
  {
    "command": "quote",
    "quote": {
      "currency": "PKR",
      "lines": [
        {
          "product_id": "hosting-298",
          "offer_id": "two-plus-one",
          "quantity": 1
        }
      ]
    }
  },
  {
    "command": "counteroffer",
    "quote_id": "OWN_QUOTE_ID",
    "counteroffer": {
      "requested_discount_bps": 0,
      "alternative_offer_id": "annual"
    }
  },
  {
    "command": "quote_status",
    "quote_id": "OWN_QUOTE_ID"
  },
  {
    "command": "handoff",
    "quote_id": "OWN_QUOTE_ID",
    "acceptance": {
      "revision": 1,
      "acknowledge_live_check": true
    }
  }
]

Counteroffers cannot authorize extra discounts. A 0-basis-point request can choose a published alternative; positive exceptions route to review without changing totals. Hosting handoff stays blocked. A domain registration may return a generic live-check link, which does not bind quote/price/currency/term/promotion in the billing portal.

Errors, retries and expiry

Reuse the identical messageId and message/configuration for a retry. The JSON-RPC request ID only correlates responses; it is not an idempotency key. A changed payload under an existing message ID is rejected. Task + commerce mutation + engine idempotency are committed together. REST and A2A share the engine; use one interface's idempotency identity for a retry rather than inventing a new cross-protocol request.

HTTP 401/403 handles missing keys/roles; 429 returns Retry-After; 413 bounds body size. Protocol errors use the pinned SDK mapping: -32700 parse, -32600 invalid envelope, -32601 unknown method, -32602 malformed parameters, -32001 missing/private/expired task, -32002 noncancelable, -32003 push unsupported, -32004 unsupported operation, -32005 content type, -32007 extended card absent, -32009 unsupported version.

Quotes and task responses expire after 24 hours. Historical task snapshots are not reusable acceptance: changed/expired quote artifacts are redacted with a refresh instruction. Use quote_status for current engine state. Catalog/price changes require a new quote and renewed acceptance. Business outcomes such as checkout_disabled or quote_expired can be returned inside a completed response-preparation task.

Pinned official specification ↗ · Official SDK releases ↗ · Executable supported wire profile

What an agent conversation means here

An external assistant chooses to call this endpoint; a web crawler visiting the site does not automatically start a conversation. The six advertised skills accept validated application/json data parts. Ordinary free-text questions, agent-supplied URLs and instructions to override policy are rejected. A language model is not required or configured inside this service.

Your purchasing client maps customer requirements to structured commands and explains the returned facts to its user. Recommendations include match_status, explanation and next_step. A no-match result asks the client to revise filters or seek human assessment; it never invents a plan, capacity or price.

Protocol completion means a response was prepared. Quote and review states remain separate; every quote requires manual review and checkout stays disabled. These are implemented interactions, not a claim of automatic connection to every AI platform.