Skip to main content
Get started
DocumentationA2A overview
A2A

A2A overview

Let external agents talk to Aly stores as task partners, not just scrape pages or guess at APIs.

Agent-to-Agent JSON-RPC and HTTP+JSON tasks, host-aware agent cards, streaming, push configs, and workspace bearer auth.

Agent2Agent (A2A) Protocol

Overview

A2A lets one AI agent talk to another AI agent as a task partner. Instead of scraping pages or guessing private APIs, an outside agent can discover what a store agent can do, send a message, and receive a structured task result.

Official standard

Read the official What is A2A? guide and A2A v1.0 specification. A2A was launched by Google with a broad partner ecosystem and is now a Linux Foundation-hosted open standard guided by a technical steering committee.

Aly support

Aly exposes A2A-compatible JSON-RPC plus HTTP+JSON aliases for published stores. Agents can search catalogs, inspect store details, manage carts, start checkout, check order status by confirmation token, or hand off x402 purchases.

Get started

Start with the host-aware agent card, then call SendMessage on /api/a2a. Use a workspace OAuth token or API key for cart, checkout, and task management routes.

At a glance

JSON-RPCPOST /api/a2a
HTTP+JSON aliasesPOST /api/a2a/message:send, POST /api/a2a/message:stream, and task routes under /api/a2a/tasks
StreamingPOST /api/a2a/streaming or JSON-RPC SendStreamingMessage returns Server-Sent Events.
DiscoveryGET /.well-known/agent-card.json is host-aware and returns platform or store-scoped skills.
AuthPublic SendMessage skills can run without a bearer. Cart and checkout skills require a workspace-scoped OAuth token or API key with write:orders. Task read/list/cancel/subscribe/push routes require a workspace-scoped OAuth token or API key.
PersistenceTasks live in Convex. contextId groups related tasks; the current SendMessage path creates a new task per call.
VersionAly emits A2A-Version: 1.0 on A2A responses. Clients should send A2A-Version: 1.0; the current routes are tolerant and do not reject a missing or different request version header.
JSON shapePublic responses use ProtoJSON camelCase such as messageId, contextId, taskId, and mediaType. Snake_case input is accepted for compatibility.
Aly's current A2A coverage
Aly tracks the current Agent2Agent protocol specification for the public JSON shape, task states, method names, and HTTP+JSON aliases. The live implementation does not yet implementGetExtendedAgentCard, strict request version negotiation,historyLength trimming, task status filters,statusTimestampAfter, or includeArtifacts.

JSON-RPC methods

MethodPurpose
SendMessage / message/sendCreate a task from a buyer or agent message, dispatch it to a skill, and return { task }.
SendStreamingMessage / message/streamCreate a task and stream statusUpdate / artifactUpdate events.
GetTask / tasks/getFetch a task by taskId. Requires workspace bearer auth.
CancelTask / tasks/cancelMove a non-terminal task to TASK_STATE_CANCELED. Requires workspace bearer auth.
ListTasks / tasks/listPaginated list for the authenticated workspace, optionally filtered by contextId.
SubscribeToTask / tasks/resubscribeOpen an SSE stream for updates to an existing non-terminal task.
*TaskPushNotificationConfigCreate, get, list, and delete webhook-style push configs for a task.

Minimum-viable call

bash
curl -X POST https://aly.store/api/a2a \  -H "Content-Type: application/json" \  -H "A2A-Version: 1.0" \  -d '{    "jsonrpc": "2.0",    "id": "req_1",    "method": "SendMessage",    "params": {      "message": {        "messageId": "msg_1",        "contextId": "ctx_4f...11",        "role": "ROLE_USER",        "parts": [{ "text": "Search for linen totes on store acme." }]      }    }  }'

The response is a JSON-RPC result. For SendMessage, Aly wraps the task as result.task; for GetTask, the task is returned directly.

Task shape

json
{  "jsonrpc": "2.0",  "id": "req_1",  "result": {    "task": {      "id": "task_8e3...77c",      "contextId": "ctx_4f...11",      "status": {        "state": "TASK_STATE_COMPLETED",        "timestamp": "2026-05-25T14:32:10.000Z",        "message": {          "messageId": "task_8e3...77c-h1",          "role": "ROLE_AGENT",          "parts": [{ "text": "Found 2 product(s) on Acme." }]        }      },      "artifacts": [        {          "artifactId": "search_results",          "name": "search_results",          "parts": [            {              "mediaType": "application/json",              "data": {                "store": { "slug": "acme", "title": "Acme" },                "products": [{ "id": "products_abc", "name": "Linen Tote" }],                "total": 1              }            }          ]        }      ],      "history": [        {          "messageId": "task_8e3...77c-h0",          "role": "ROLE_USER",          "parts": [{ "text": "Search for linen totes on store acme." }]        }      ],      "metadata": {}    }  }}

Status values

  • TASK_STATE_SUBMITTED — accepted into the task store. Aly maps internal pending/accepted states to this public value.
  • TASK_STATE_WORKING — the task is actively running. Aly maps internal running state to this public value.
  • TASK_STATE_INPUT_REQUIRED — the task produced an artifact but needs the buyer or caller to take the next step, such as completing checkout or starting an x402 payment.
  • TASK_STATE_COMPLETED — task ended successfully.
  • TASK_STATE_FAILED — the skill failed irrecoverably.
  • TASK_STATE_CANCELED — caller canceled a non-terminal task.
  • TASK_STATE_REJECTED or TASK_STATE_AUTH_REQUIRED — reserved terminal/interrupted states supported by the task store.

Streaming variant

POST /api/a2a/streaming expects a JSON body shaped like { "params": { "message": ... } } and emits SSEdata: frames containing statusUpdate andartifactUpdate payloads. Calling SendStreamingMessage through /api/a2areturns the same stream with each event wrapped in a JSON-RPC result.

How A2A fits with MCP

A2A and MCP solve different layers of agent work. MCP connects an agent to tools and data inside a system; A2A lets agents communicate and delegate across systems. Aly supports both: MCP for operating a workspace, A2A for external agents working with a store agent.

A2A and MCP relationship diagram from the official A2A documentation

Discovery

The agent card describes supported interfaces, capabilities, security schemes, default input/output modes, and the skill catalog. It is host-aware: aly.store returns the platform card, while <slug>.aly.store or a verified custom domain returns a store-scoped card. See Agent card.

Rate limits
The JSON-RPC and streaming routes use a process-local 60 request/minute IP bucket and return 429 with Retry-Afterwhen exhausted. Treat this as best-effort throttling rather than a globally durable quota.

Next steps

Updated

Was this page helpful?