A2A client

npm install @nylorun/agents

import { createA2aClient } from "@nylorun/agents/a2a";

const a2a = createA2aClient({
  url: `${process.env.NYLORUN_RUNTIME_URL}/v1/a2a/agents/support`,
  key: process.env.NYLORUN_SERVER_KEY!,
  subject: "a2a:billing",
});

const task = await a2a.send({
  messageId: "refund:demo-123",
  contextId: "ticket-4821",
  parts: [{ text: "Refund order demo-123." }],
  returnImmediately: true,
  push: { url: "https://app.example.com/a2a/push", token: pushToken },
});

createA2aClient() speaks A2A 1.0 JSON-RPC to one agent: an Agent on the Runtime, an endpoint createA2aHandler() serves, or any other A2A 1.0 agent. It sends A2A-Version: 1.0 and activates all five profile v2 extensions with A2A-Extensions. It is in @nylorun/agents 0.31.0-beta or later, from @nylorun/agents/a2a and from @nylorun/agents. Run it on your server: it carries an application key.

Create a clientCopy Anchor Link

Keep the subject stable for one caller: it owns the contexts, and another subject's task answers as not found.

Send a taskCopy Anchor Link

const task = await a2a.send({
  messageId: "refund:demo-123",
  contextId: "ticket-4821",
  parts: [{ text: "Refund order demo-123." }],
  returnImmediately: true,
  push: { url: "https://app.example.com/a2a/push", token: pushToken },
  traceparent,
});

send() resolves to the A2A Task. Without returnImmediately, it waits until the task ends or pauses, up to the Runtime limit a2aWaitMs (5 minutes by default), then answers with the task still TASK_STATE_WORKING. For long work, pass returnImmediately and a push config.

A message to a context whose task is still running is queued: send() answers with the task that will take it, TASK_STATE_SUBMITTED, under the queued message's id until a turn takes it. With delivery: "reject", the client throws A2aError with reason CONTEXT_BUSY instead.

Read, list, and cancelCopy Anchor Link

const current = await a2a.get(task.id, { historyLength: 10 });

const page = await a2a.list({
  contextId: "ticket-4821",
  status: "TASK_STATE_WORKING",
  statusTimestampAfter: "2026-11-02T09:00:00Z",
  pageSize: 50,
});

for await (const each of a2a.listAll({ contextId: "ticket-4821" })) console.log(each.id, each.status.state);

await a2a.cancel(task.id);

const card = await a2a.card();

Each is one JSON-RPC request to POST /v1/a2a/agents/{agentId}, and the card is GET /v1/a2a/agents/{agentId}/card. A queued message that no turn has taken yet is not a task ListTasks lists, and it cannot be cancelled until it starts: CancelTask answers TaskNotCancelableError. A task that already ended answers the same.

Answer an interactionCopy Anchor Link

An approval, a question, or a connection request pauses the task under interactions/v1. Answer on the same task:

import { readInteraction } from "@nylorun/agents/a2a";

const open = readInteraction(task);
if (open?.kind === "approval") {
  await a2a.answer({
    taskId: task.id,
    contextId: task.contextId,
    interactionId: open.interactionId,
    approved: true,
    messageId: `answer:${open.interactionId}`,
  });
}

answer() takes exactly one of approved, for an approval, and value, for a question or a connection ({ connected: true }). The messageId makes the answer safe to retry.

Read the extensionsCopy Anchor Link

Each reader takes whatever you hold: a push's StreamResponse, a task, a status update, a status, a message, or an artifact. It looks in that object's own metadata, then its status message's, and returns undefined when the data is missing or not the profile's shape. A core A2A agent's tasks read as plain A2A.

Verify pushesCopy Anchor Link

import { readFiles, readProgress, readTelemetry, verifyA2aPush } from "@nylorun/agents/a2a";

export async function POST(request: Request) {
  const update = await verifyA2aPush({
    secret: process.env.A2A_PUSH_SECRET!,
    headers: request.headers,
    body: await request.text(),
    token: pushToken,
  });

  const steps = readProgress(update)?.steps;
  const totals = readTelemetry(update)?.totals;
  for (const { file } of readFiles(update)) await saveFile(file.path, file.version, file.sha256);
  await saveStatus(update, { steps, totals });
  return new Response(null, { status: 204 });
}

verifyA2aPush() resolves to the parsed delivery, or throws A2aPushVerificationError with a reason. Signing, retries, and ordering are on Push notifications.

The change feedCopy Anchor Link

import { listTurnChanges } from "@nylorun/agents/a2a";

let cursor = await loadCursor(); // undefined the first time
let hasMore = true;
while (hasMore) {
  const page = await listTurnChanges({
    baseUrl: process.env.NYLORUN_RUNTIME_URL!,
    key: process.env.NYLORUN_SERVER_KEY!,
    changedAfter: cursor,
    limit: 100,
  });
  for (const turn of page.turns) if (turn.a2a) await reconcile(turn);
  cursor = page.cursor;
  hasMore = page.hasMore;
  await saveCursor(cursor);
}

Pushes can be lost: a receiver down for more than a day, or one that refused them. The change feed is the backstop. listTurnChanges() calls GET /v1/turns?changedAfter=<cursor> and returns the turns that changed after the cursor, in the order they changed. A turn appears again each time it changes. Store cursor and pass it as changedAfter next time; it comes back even when turns is empty. Without changedAfter, the feed starts from the beginning. One call covers every task, so a receiver can run it on a timer and when it starts, then read any task it is unsure of with a2a.get().

It needs the Host feature turns. Each turn:

ErrorsCopy Anchor Link

A JSON-RPC error from the agent throws A2aError:

An HTTP refusal, such as 401, 404 for an unknown Agent, or 429, throws the SDK's RuntimeError; see Errors in the Agents SDK reference.