A2A Protocol

Overview

The A2A (Agent-to-Agent) protocol enables standardized agent discovery and inter-agent communication. aixyz implements A2A protocol version 0.3.0 with an agent card for discovery and a JSON-RPC endpoint for task execution.

Endpoints

Endpoint	Method	Description
`/.well-known/agent-card.json`	GET	Agent discovery card with metadata, skills, and capabilities
`/agent`	POST	JSON-RPC task handler, x402-gated if `accepts` is defined

Agent Card

The agent card is automatically generated from your aixyz.config.ts. Other agents fetch this card to discover your agent’s capabilities.

curl http://localhost:3000/.well-known/agent-card.json

Example response:

{
  "name": "Weather Agent",
  "description": "Get current weather for any location worldwide.",
  "protocolVersion": "0.3.0",
  "version": "0.1.0",
  "url": "https://my-agent.vercel.app/agent",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "get-weather",
      "name": "Get Weather",
      "description": "Get current weather conditions for any city",
      "tags": ["weather"],
      "examples": ["What's the weather in Tokyo?"]
    }
  ]
}

JSON-RPC Endpoint

The /agent endpoint accepts JSON-RPC 2.0 requests. The primary method is tasks/send:

curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/send",
    "id": "1",
    "params": {
      "id": "task-1",
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "What is the weather in NYC?"}]
      }
    }
  }'

Capabilities

The agent card’s capabilities field is configured via the capabilities export from your agent file. If omitted, defaults to { streaming: true, pushNotifications: false }.

app/agent.ts

import type { Capabilities } from "aixyz/app/plugins/a2a";

export const capabilities: Capabilities = {
  streaming: false,
  pushNotifications: false,
};

When streaming is false, the executor uses agent.generate() instead of agent.stream(), returning a single artifact with the full response. See agent.ts — Capabilities for the full reference.

Using the A2A Plugin

The A2APlugin wires up both endpoints on your server:

import { A2APlugin } from "aixyz/app/plugins/a2a";

// agentExports is `import * as agent from "./agent"`
// reads `default` (the ToolLoopAgent), `accepts` (payment config), and `capabilities`
await server.withPlugin(new A2APlugin([{ exports: agent }]));

This registers:

A GET handler at /.well-known/agent-card.json serving the agent card
A POST handler at /agent routing JSON-RPC requests to ToolLoopAgentExecutor

Sub-Agent Routing

Pass multiple entries with a name to mount sub-agents under their own paths:

app/server.ts

import * as research from "./agents/research";
import * as implement from "./agents/implement";

await server.withPlugin(
  new A2APlugin([
    { exports: agent }, // → /agent
    { name: "research", exports: research }, // → /research/agent
    { name: "implement", exports: implement }, // → /implement/agent
  ]),
);

Each sub-agent gets its own agent card at /{name}/.well-known/agent-card.json and its own JSON-RPC endpoint at /{name}/agent. When using app/agents/, the build pipeline generates these calls automatically.

Payment Integration

When an agent exports an accepts configuration with scheme: "exact", the /agent endpoint is gated behind x402 payment. Clients must include a valid X-Payment header. Agents without accepts are served without payment requirements.

x402 Payments

How payment gating works on A2A endpoints.

MCP Protocol

Expose tools via MCP alongside A2A.

Getting Started

CLI

Config

File-system layout

Functions

Protocols

A2A Protocol

Overview

Endpoints

Agent Card

JSON-RPC Endpoint

Capabilities

Using the A2A Plugin

Sub-Agent Routing

Payment Integration

x402 Payments

MCP Protocol

​Overview

​Endpoints

​Agent Card

​JSON-RPC Endpoint

​Capabilities

​Using the A2A Plugin

​Sub-Agent Routing

​Payment Integration

x402 Payments

MCP Protocol

Overview

Endpoints

Agent Card

JSON-RPC Endpoint

Capabilities

Using the A2A Plugin

Sub-Agent Routing

Payment Integration