A2A Protocol

Agent-to-Agent (A2A) is the protocol for AI agents to communicate with Maison. It uses JSON-RPC 2.0 over HTTP, making it straightforward to integrate from any language or runtime.

Discovery

Fetch the agent card to discover available capabilities, supported auth schemes, and the list of skills the agent exposes:

bash
curl https://maison-labs.com/.well-known/agent.json

Authentication

Every A2A request requires two headers:

  • x-api-key — your mx_... API key
  • x-client-id — the UUID of the target property

See the Authentication page for instructions on creating an API key.

Task states

A task moves through the following states during its lifetime:

submittedworkingcompletedfailedorcanceled
Tasks are stored for 7 days and then automatically cleaned up. Completed tasks are available for that full window — no need to retrieve the result immediately.

Task lifecycle

  1. Create a task — tasks/send

    Submit a new task by calling tasks/send. The response includes a task ID and the initial status (submitted or working).

    bash
    curl -X POST https://maison-labs.com/a2a \
  -H "x-api-key: mx_p_YOUR_KEY" \
  -H "x-client-id: YOUR_CLIENT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "tasks/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{ "type": "text", "text": "What time is checkout?" }]
      }
    }
  }'

  2. Check status — tasks/get

    Poll for the current status and result of an existing task using its ID.

    bash
    curl -X POST https://maison-labs.com/a2a \
  -H "x-api-key: mx_p_YOUR_KEY" \
  -H "x-client-id: YOUR_CLIENT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-2",
    "method": "tasks/get",
    "params": {
      "id": "TASK_ID"
    }
  }'

  3. Cancel a task — tasks/cancel

    Cancel an in-progress task. Only tasks in the submitted or working state can be canceled.

    bash
    curl -X POST https://maison-labs.com/a2a \
  -H "x-api-key: mx_p_YOUR_KEY" \
  -H "x-client-id: YOUR_CLIENT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-3",
    "method": "tasks/cancel",
    "params": {
      "id": "TASK_ID"
    }
  }'