JSON-RPC Format

The platform uses A2A (Agent-to-Agent) JSON-RPC 2.0 as its wire protocol.

Request Format

Every agent request uses the message/send method:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "unique-request-id",
  "params": {
    "message": {
      "parts": [
        {
          "kind": "text",
          "text": "Your question here"
        }
      ]
    }
  }
}

Optional Parameters

Parameter	Type	Description
params.contextId	string	Conversation context ID for multi-turn sessions
params.catalog_context	object	Merchant catalog context (product_count, top categories)

Response Format

Successful responses contain a result with status and artifacts:

{
  "jsonrpc": "2.0",
  "result": {
    "status": "completed",
    "artifacts": [
      {
        "parts": [
          {
            "kind": "text",
            "text": "The agent's analysis response..."
          }
        ]
      }
    ]
  },
  "id": "unique-request-id"
}

Task Lifecycle

Each request transitions through these states:

Status	Description
submitted	Request received and queued
working	Agent is processing (querying data, reasoning)
completed	Analysis finished successfully
failed	An error occurred during processing

Error Responses

Errors use standard JSON-RPC 2.0 error codes:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "The analysis service encountered an error. Please try again."
  },
  "id": "unique-request-id"
}

Code	Meaning
-32700	Parse error -- invalid JSON
-32600	Invalid request -- missing required fields
-32601	Method not found -- unsupported method
-32602	Invalid params -- missing message or parts
-32603	Internal error -- agent processing failure

Streaming

The platform supports streaming responses via Server-Sent Events (SSE). When streaming is enabled, partial results are delivered as the agent works through its tool calls and reasoning steps.

Evidence Citations

Every successful response includes:

• Data Evidence Block -- Lists each tool call with row counts
• Data Freshness Stamp -- The date of the underlying data source

These ensure every number in the response traces back to a specific data query result.