What Is A2A and How Do You Implement It in 2026?

#!/usr/bin/env bash
set -euo pipefail
AGENT="https://agent.example.com"

# 1. Discovery. Read the card, then take the HTTP+JSON base URL from it.
CARD=$(curl -fsS "$AGENT/.well-known/agent-card.json")
BASE=$(echo "$CARD" | jq -r '[.supportedInterfaces[]
        | select(.protocolBinding == "HTTP+JSON") | .url][0]')

# 2. Delegate. returnImmediately stops the call blocking until the task ends.
TASK=$(curl -fsS -X POST "$BASE/message:send" \
  -H 'Content-Type: application/a2a+json' \
  -H 'A2A-Version: 1.0' \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{
        "message": {
          "messageId": "'"$(uuidgen)"'",
          "role": "ROLE_USER",
          "parts": [{ "text": "Summarise our Q3 returns policy changes." }]
        },
        "configuration": {
          "acceptedOutputModes": ["text/plain"],
          "returnImmediately": true
        }
      }' | jq -r '.task.id')

# 3. Poll GetTask until the task stops moving. Results arrive as artifacts.
while true; do
  STATE_JSON=$(curl -fsS "$BASE/tasks/$TASK" \
    -H 'A2A-Version: 1.0' -H "Authorization: Bearer $AGENT_TOKEN")
  case "$(echo "$STATE_JSON" | jq -r '.status.state')" in
    TASK_STATE_COMPLETED)
      echo "$STATE_JSON" | jq -r '.artifacts[].parts[].text'; break ;;
    TASK_STATE_FAILED|TASK_STATE_CANCELED|TASK_STATE_REJECTED)
      echo "ended without a result"; exit 1 ;;
    TASK_STATE_INPUT_REQUIRED|TASK_STATE_AUTH_REQUIRED)
      echo "agent is waiting on you"; exit 1 ;;
    *) sleep 2 ;;
  esac
done

// npm install @a2a-js/sdk express
import express from 'express';
import { A2A_PROTOCOL_VERSION, AGENT_CARD_PATH, AgentCard } from '@a2a-js/sdk';
import { DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder }
  from '@a2a-js/sdk/server/express';
import { ReturnsPolicyExecutor } from './executor.js';

const card: AgentCard = {
  name: 'Returns Policy Agent',
  description: 'Answers questions about our returns, refunds and exchanges.',
  supportedInterfaces: [
    { url: 'https://agent.example.com/a2a/jsonrpc', protocolBinding: 'JSONRPC',
      tenant: '', protocolVersion: A2A_PROTOCOL_VERSION },
    { url: 'https://agent.example.com/a2a/rest', protocolBinding: 'HTTP+JSON',
      tenant: '', protocolVersion: A2A_PROTOCOL_VERSION },
  ],
  provider: { organization: 'Example Retail', url: 'https://www.example.com' },
  version: '1.4.0',
  capabilities: { streaming: true, pushNotifications: true,
                  extensions: [], extendedAgentCard: false },
  securitySchemes: {}, securityRequirements: [], signatures: [],
  defaultInputModes: ['text/plain'], defaultOutputModes: ['text/plain'],
  skills: [{
    id: 'returns_policy',
    name: 'Returns policy lookup',
    description: 'Explains return windows, refund timings and exclusions.',
    tags: ['returns', 'refunds', 'policy'],
    examples: ['How long do I have to return a jacket bought on sale?'],
    inputModes: ['text/plain'], outputModes: ['text/plain'],
    securityRequirements: [],
  }],
};

const handler = new DefaultRequestHandler(
  card, new InMemoryTaskStore(), new ReturnsPolicyExecutor());
const app = express();
app.use(`/${AGENT_CARD_PATH}`, agentCardHandler({ agentCardProvider: handler }));
app.use('/a2a/jsonrpc', jsonRpcHandler(
  { requestHandler: handler, userBuilder: UserBuilder.noAuthentication }));
app.use('/a2a/rest', restHandler(
  { requestHandler: handler, userBuilder: UserBuilder.noAuthentication }));
app.listen(41241);

import express from 'express';
const AGENT = 'https://agent.example.com/a2a/rest';
const WEBHOOK = 'https://ops.example.com/a2a/task-updates';
const TOKEN = process.env.A2A_WEBHOOK_TOKEN;
const HEADERS = { 'Content-Type': 'application/a2a+json', 'A2A-Version': '1.0' };
const ours = new Set();

// 1. Delegate, naming the webhook. The task id comes back straight away.
export async function delegate(text) {
  const res = await fetch(`${AGENT}/message:send`, {
    method: 'POST', headers: HEADERS,
    body: JSON.stringify({
      message: { messageId: crypto.randomUUID(), role: 'ROLE_USER', parts: [{ text }] },
      configuration: {
        returnImmediately: true,
        taskPushNotificationConfig: { url: WEBHOOK, token: TOKEN },
      },
    }),
  });
  const { task } = await res.json();
  ours.add(task.id);
}
// 2. Receive. The body carries exactly one of task, message,
//    statusUpdate or artifactUpdate at the top level.
const app = express();
app.use(express.json({ type: ['application/json', 'application/a2a+json'] }));
app.post('/a2a/task-updates', async (req, res) => {
  if (req.get('X-A2A-Notification-Token') !== TOKEN) return res.sendStatus(401);
  const event = req.body.statusUpdate ?? req.body.artifactUpdate ?? req.body.task;
  const taskId = event?.taskId ?? event?.id;
  if (!ours.has(taskId)) return res.sendStatus(202);
  res.sendStatus(200); // ack first: delivery is at least once, so expect repeats
  if (req.body.statusUpdate?.status?.state === 'TASK_STATE_COMPLETED') {
    const r = await fetch(`${AGENT}/tasks/${taskId}`, { headers: HEADERS });
    const task = await r.json();
    console.log(task.artifacts.flatMap((a) => a.parts)
      .map((p) => p.text).filter(Boolean).join('\n'));
    ours.delete(taskId);
  }
});
app.listen(8080);