A2A Protocol

Endpoint

https://maison-labs.com/a2a

Authenticate every request with x-api-key: mx_p_YOUR_KEY. See the Authentication page for how to create an API key.

Task states

A task moves through the following states during its lifetime:

Error codes

Tool failures become JSON-RPC errors. The data field carries the HTTP status the REST transport would have returned, plus the standard error body:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "error": {
    "code": -32005,
    "message": "forbidden: Missing grant clients WRITE (global)",
    "data": {
      "status": 403,
      "error": "Forbidden",
      "code": "forbidden",
      "details": { "missing": [{ "feature": "clients", "level": "WRITE", "scope": "global" }] }
    }
  }
}

Task lifecycle

1. 1

   Discover — agent card

   Fetch the agent card to discover capabilities, supported auth schemes, and the full skill catalogue. The agent card is public (no key required):

   bash

   Copy

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

   Also available at /.well-known/agent-card.json. Skills on the agent card mirror the full OpenAPI tool catalogue.

2. 2

   Invoke a tool — tasks/send with a data part

   To run a specific tool, send tasks/send with a data part containing { tool, input }. The tool runs synchronously; the completed task carries the output as a data artifact:

   bash

   Copy

   curl -X POST https://maison-labs.com/a2a \
     -H "x-api-key: mx_p_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": "req-1",
       "method": "tasks/send",
       "params": {
         "message": {
           "role": "user",
           "parts": [
             {
               "type": "data",
               "data": {
                 "tool": "create_client",
                 "input": { "name": "Grand Hotel", "domain": "grand-hotel.com" }
               }
             }
           ]
         }
       }
     }'

3. 3

   Send a text message — tasks/send with a text part

   A text-only message (no data part) is answered by the send_message tool for the client identified by metadata.clientId or the x-client-id header:

   bash

   Copy

   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/send",
       "params": {
         "message": {
           "role": "user",
           "parts": [{ "type": "text", "text": "What time is checkout?" }]
         },
         "metadata": { "clientId": "YOUR_CLIENT_UUID" }
       }
     }'

4. 4

   Check status — tasks/get

   Read a task back by its ID. Only the user who created the task can retrieve it. Tasks are stored for 7 days.

   bash

   Copy

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

5. 5

   Cancel — tasks/cancel

   tasks/cancel always returns TaskNotCancelable because tasks never stay in flight — they complete synchronously within tasks/send.

   bash

   Copy

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

Skill catalogue

The following skills are available on the A2A endpoint. Each skill corresponds to a tool with the same name on the REST and MCP interfaces. The catalogue is rendered live from https://maison-labs.com/api/v1/openapi.json.

Loading catalogue…