Skip to main content

JSON-RPC 2.0 binding

Same AAP payload feeding two transports: JSON-RPC 2.0 on the left, HTTP+JSON on the right

A2A defines a JSON-RPC 2.0 binding in Section 9 of its specification. AAP rides on top of it without modification: every skill is invoked via the SendMessage JSON-RPC method, with the AAP request packaged as a typed DataPart inside params.message.parts[].

What changed in A2A v1.0

A2A v1.0 reshaped the JSON-RPC wire format. AAP examples on this page reflect the new shape; see A2A spec §A.2.1 — Breaking Change: Kind Discriminator Removed for the source of truth.

AspectLegacy (v0.3.x)Current (v1.0)
Method namemessage/sendSendMessage
Role"user" / "agent""ROLE_USER" / "ROLE_AGENT"
Part discriminatorper-part kind: "data" fieldmember-name discriminator (no kind)
messageIdoptionalrequired on every Message
mediaType on DataPartabsentapplication/vnd.autoagent.<skill>-request+json

Endpoint and method​

A dealer agent advertises one or more JSON-RPC endpoints under supported_interfaces[] of its agent card. Each entry has protocol_binding: "JSONRPC" and a url.

POST {jsonrpc-url}
Content-Type: application/json

If the agent declares auth_type: "bearer", every request MUST also send:

Authorization: Bearer <token>

All AAP skills use a single JSON-RPC method:

"method": "SendMessage"

The id field is the standard JSON-RPC request id; AAP does not constrain it. The params.message is an A2A Message whose first parts[] entry is the typed AAP DataPart. A buyer agent MUST also include params.configuration.acceptedOutputModes listing the AAP response media type it expects.

Generic envelope​

Every AAP request looks like this on the wire:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9F4M7C0X3K5RN8B3WJTW2P",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "<scope>.<thing>.request",
            "...": "skill-specific fields"
          },
          "mediaType": "application/vnd.autoagent.<skill>-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.<skill>-response+json"]
    }
  }
}

The response wraps an A2A Message in result.message:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "message": {
      "messageId": "01HZ9F4N1JZ7QS8VKR2A3B4C5D",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "<scope>.<thing>.response",
            "data": { "...": "skill-specific response data" }
          },
          "mediaType": "application/vnd.autoagent.<skill>-response+json"
        }
      ]
    }
  }
}

The messageId on the response is generated by the dealer agent; it MUST differ from the messageId the buyer agent sent on the request.

The remainder of this page shows the full envelope for each of the seven skills.

dealer.information​

Request​

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9G5N8D1Y4M6SP9C4XKVW3Q",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "dealer.information.request"
          },
          "mediaType": "application/vnd.autoagent.dealer-information-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.dealer-information-response+json"]
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "message": {
      "messageId": "01HZ9G5P2KA8RT9WMS3B4C5D6E",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "dealer.information.response",
            "data": {
              "dealer_id": "dealer_demo_toyota",
              "legal_name": "Demo Toyota of San Francisco, LLC",
              "trade_name": "Demo Toyota",
              "brands": ["Toyota"],
              "address": {
                "line1": "100 Market St",
                "city": "San Francisco",
                "region_code": "CA",
                "postal_code": "94105",
                "country_code": "US"
              }
            }
          },
          "mediaType": "application/vnd.autoagent.dealer-information-response+json"
        }
      ]
    }
  }
}

inventory.facets​

Request​

{
  "jsonrpc": "2.0",
  "id": "req-2",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9H6P9E2Z5N7TQ0D5YMWX4R",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "inventory.facets.request",
            "filters": { "condition": ["used"] }
          },
          "mediaType": "application/vnd.autoagent.inventory-facets-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.inventory-facets-response+json"]
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": "req-2",
  "result": {
    "message": {
      "messageId": "01HZ9H6Q3KB9SV0XNT4C5D6E7F",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "inventory.facets.response",
            "data": {
              "makes": [{ "value": "Honda", "count": 12 }, { "value": "Toyota", "count": 27 }],
              "conditions": [{ "value": "used", "count": 39 }],
              "year_range": { "min": 2015, "max": 2024 },
              "price_range": { "min": 9990, "max": 38990 }
            }
          },
          "mediaType": "application/vnd.autoagent.inventory-facets-response+json"
        }
      ]
    }
  }
}

inventory.search​

Request​

{
  "jsonrpc": "2.0",
  "id": "req-3",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9F4M7C0X3K5RN8B3WJTW2P",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "inventory.search.request",
            "filters": {
              "make": ["Honda"],
              "condition": ["used", "certified"],
              "year_min": 2020,
              "price_max": 30000
            },
            "pagination": { "skip": 0, "limit": 20 },
            "sort": { "field": "price", "order": "asc" },
            "privacy": { "anonymous": true }
          },
          "mediaType": "application/vnd.autoagent.inventory-search-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.inventory-search-response+json"]
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": "req-3",
  "result": {
    "message": {
      "messageId": "01HZ9F4N1JZ7QS8VKR2A3B4C5D",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "inventory.search.response",
            "data": {
              "total": 1,
              "skip": 0,
              "limit": 20,
              "vehicles": [
                {
                  "dealer_id": "dealer_demo_toyota",
                  "vin": "1HGCY2F57RA000001",
                  "stock": "T12345",
                  "year": 2022,
                  "make": "Honda",
                  "model": "Civic",
                  "trim": "EX",
                  "condition": "certified",
                  "list_price": { "amount": 24990, "currency": "USD" },
                  "price": { "amount": 26780, "currency": "USD" },
                  "status": "In Stock",
                  "last_verified_at": "2026-04-30T10:15:00Z"
                }
              ]
            }
          },
          "mediaType": "application/vnd.autoagent.inventory-search-response+json"
        }
      ]
    }
  }
}

inventory.vehicle​

Request​

{
  "jsonrpc": "2.0",
  "id": "req-4",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9J7Q0F3A6P8VR1E6ZNXY5S",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "inventory.vehicle.request",
            "vin": "1HGCY2F57RA000001",
            "zip_code": "94105"
          },
          "mediaType": "application/vnd.autoagent.vehicle-detail-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.vehicle-detail-response+json"]
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": "req-4",
  "result": {
    "message": {
      "messageId": "01HZ9J7R4MC0TW1YPV5D6E7F8G",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "inventory.vehicle.response",
            "data": {
              "dealer_id": "dealer_demo_toyota",
              "vin": "1HGCY2F57RA000001",
              "stock": "T12345",
              "year": 2022,
              "make": "Honda",
              "model": "Civic",
              "trim": "EX",
              "condition": "certified",
              "msrp":          { "amount": 26500, "currency": "USD" },
              "list_price":    { "amount": 24990, "currency": "USD" },
              "offered_price": { "amount": 26615, "currency": "USD" },
              "price":         { "amount": 26780, "currency": "USD" },
              "zip_code": "94105",
              "status": "In Stock",
              "vdp_url": "https://demo-toyota.example.com/inventory/T12345",
              "last_verified_at": "2026-04-30T10:15:00Z"
            }
          },
          "mediaType": "application/vnd.autoagent.vehicle-detail-response+json"
        }
      ]
    }
  }
}

lead.general​

Request​

{
  "jsonrpc": "2.0",
  "id": "req-5",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9K8R1G4B7Q9WS2F7APYZ6T",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "lead.general.request",
            "lead_intent": "financing_question",
            "message": "I'd like to know if you offer 0% APR financing on certified used Civics.",
            "customer": {
              "first_name": "Anna",
              "last_name": "Lee",
              "email": "anna@example.com",
              "phone": "+14155550123",
              "preferred_contact": "email"
            },
            "consent": {
              "granted_at": "2026-04-30T10:14:00Z",
              "allowed_channels": ["email"],
              "consent_text": "I agree to share my name and email with Demo Toyota to receive a financing answer.",
              "source_agent": "chatgpt-shopping",
              "scope": ["general_inquiry"]
            },
            "source_agent": "chatgpt-shopping",
            "submitted_at": "2026-04-30T10:14:30Z"
          },
          "mediaType": "application/vnd.autoagent.general-lead-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.lead-response+json"]
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": "req-5",
  "result": {
    "message": {
      "messageId": "01HZ9K8S5ND1VX2ZQW6E7F8G9H",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "lead.general.response",
            "data": {
              "lead_id": "lead_2026_04_30_anna_001",
              "status": "received",
              "dealer": {
                "name": "Demo Toyota",
                "phone": "+14155550100"
              }
            },
            "message": "A finance manager will email Anna within one business day."
          },
          "mediaType": "application/vnd.autoagent.lead-response+json"
        }
      ]
    }
  }
}

lead.vehicle​

Request​

{
  "jsonrpc": "2.0",
  "id": "req-6",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9M9S2H5C8R0XT3G8BQZA7V",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "lead.vehicle.request",
            "vehicles": [
              { "vin": "1HGCY2F57RA000001" }
            ],
            "intent": "buy",
            "finance_type": "finance",
            "timeline": "1_3_months",
            "message": "Interested in this Civic; is it still available?",
            "customer": {
              "first_name": "Anna",
              "last_name": "Lee",
              "email": "anna@example.com",
              "phone": "+14155550123",
              "preferred_contact": "email"
            },
            "consent": {
              "granted_at": "2026-04-30T10:15:00Z",
              "allowed_channels": ["email", "phone"],
              "consent_text": "I agree to share my contact info with Demo Toyota about this 2022 Honda Civic.",
              "source_agent": "chatgpt-shopping",
              "scope": ["vehicle_inquiry"]
            },
            "source_agent": "chatgpt-shopping",
            "submitted_at": "2026-04-30T10:15:10Z"
          },
          "mediaType": "application/vnd.autoagent.vehicle-lead-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.lead-response+json"]
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": "req-6",
  "result": {
    "message": {
      "messageId": "01HZ9M9T6PE2WY3ARX7F8G9H0J",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "lead.vehicle.response",
            "data": {
              "lead_id": "lead_2026_04_30_anna_002",
              "status": "received",
              "dealer": {
                "name": "Demo Toyota",
                "phone": "+14155550100"
              }
            }
          },
          "mediaType": "application/vnd.autoagent.lead-response+json"
        }
      ]
    }
  }
}

lead.appointment​

Request​

{
  "jsonrpc": "2.0",
  "id": "req-7",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "01HZ9N0T3J6D9S1YV4H9CRABCDV",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "lead.appointment.request",
            "appointment_type": "test_drive",
            "vehicles": [
              { "vin": "1HGCY2F57RA000001" }
            ],
            "requested_windows": [
              { "start": "2026-05-02T17:00:00Z", "end": "2026-05-02T18:00:00Z" },
              { "start": "2026-05-03T16:00:00Z", "end": "2026-05-03T17:00:00Z" }
            ],
            "timezone": "America/Los_Angeles",
            "duration_minutes": 60,
            "customer": {
              "first_name": "Anna",
              "last_name": "Lee",
              "email": "anna@example.com",
              "phone": "+14155550123",
              "preferred_contact": "phone"
            },
            "consent": {
              "granted_at": "2026-04-30T10:16:00Z",
              "allowed_channels": ["phone", "email"],
              "consent_text": "I agree to share my contact info with Demo Toyota to schedule a test drive.",
              "source_agent": "chatgpt-shopping",
              "scope": ["appointment"]
            },
            "source_agent": "chatgpt-shopping",
            "submitted_at": "2026-04-30T10:16:05Z"
          },
          "mediaType": "application/vnd.autoagent.appointment-lead-request+json"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": ["application/vnd.autoagent.appointment-lead-response+json"]
    }
  }
}

Response​

{
  "jsonrpc": "2.0",
  "id": "req-7",
  "result": {
    "message": {
      "messageId": "01HZ9N0V7QF3XZ4BSY8G9H0J1K",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "data": {
            "type": "lead.appointment.response",
            "data": {
              "appointment_id": "appt_2026_04_30_anna_001",
              "status": "confirmed",
              "confirmed_window": {
                "start": "2026-05-02T17:00:00Z",
                "end": "2026-05-02T18:00:00Z"
              },
              "dealer": {
                "name": "Demo Toyota",
                "phone": "+14155550100"
              }
            },
            "message": "Confirmed for Saturday at 10am Pacific. Please bring a valid driver's license."
          },
          "mediaType": "application/vnd.autoagent.appointment-lead-response+json"
        }
      ]
    }
  }
}

Error mapping (A2A Section 9.5)​

When a skill cannot be fulfilled, the dealer agent MUST return a JSON-RPC error envelope. AAP defines a typed error payload (aap.error) carried in error.data. The mapping uses the standard JSON-RPC code for transport errors and AAP's own code for business errors.

{
  "jsonrpc": "2.0",
  "id": "req-3",
  "error": {
    "code": -32602,
    "message": "Invalid params: filters.year_min must be an integer",
    "data": {
      "type": "aap.error",
      "error_id": "err_01HZ9EXAMPLE",
      "code": "SCHEMA_VALIDATION_FAILED",
      "message": "filters.year_min must be an integer",
      "retryable": false,
      "details": {
        "instancePath": "/filters/year_min",
        "received": "twenty-twenty"
      },
      "created_at": "2026-04-30T10:15:30Z"
    }
  }
}

Recommended JSON-RPC code mapping:

AAP codeJSON-RPC codeNotes
SCHEMA_VALIDATION_FAILED-32602JSON-RPC "Invalid params".
MISSING_REQUIRED_FIELD-32602"Invalid params".
UNSUPPORTED_SKILL-32601JSON-RPC "Method not found" — the dealer does not implement this skill (rare for AAP-compliant agents but allowed for forward compat).
VEHICLE_NOT_FOUND-32000Application error.
VEHICLE_UNAVAILABLE-32000Application error.
CONTACT_CONSENT_REQUIRED-32000Application error.
INVALID_CONSENT-32000Application error.
APPOINTMENT_TIME_UNAVAILABLE-32000Application error.
AUTH_REQUIRED-32001Reserved server-error range; AAP-specific.
RATE_LIMITED-32002Reserved server-error range; AAP-specific.
INTERNAL_ERROR-32603JSON-RPC "Internal error".

See Errors for the full vocabulary and per-code semantics.