@gnldev/a2a weekly downloads statistics

@gnldev/a2a

Agent-to-agent, both ways. Serve your GNL agents to any Agent2Agent (A2A) client with createA2AServer (@gnldev/a2a/server), and call a remote agent — another GNL server or any A2A agent — as an AI SDK tool with createA2ATool.

Serve agents over A2A

import { createA2AServer } from '@gnldev/a2a/server';
import { InMemoryJournal } from '@gnldev/durable';

const a2a = createA2AServer(
  { journal: new InMemoryJournal(), agents: { researcher: { model, description: 'Finds sources' } } },
  { identify: (req) => auth.authenticate(req), authorize: (p, req, ctx) => auth.authorize(p, req, ctx) },
);
// a2a is a fetch handler: (request) => Promise<Response>. Mount it with your host, e.g. Hono's app.mount('/a2a', a2a).

What a client sees (A2A JSON-RPC binding; the card says protocolVersion: '0.3.0'):

Request	Answer
GET /agents/<name>/.well-known/agent.json (or agent-card.json)	the Agent Card: name, description, url, one skill, capabilities.streaming: false
POST /agents/<name> message/send	a Task — completed with the answer as an artifact, or input-required
POST /agents/<name> tasks/get { id }	the task, read from the journal (no model call)
POST /agents/<name> tasks/cancel { id }	the task, canceled

A task is a GNL run, so the engine's guarantees carry over:

• The message id names the work. For a user it is a workKey (unique within that user); for an anonymous caller the run id is a2a:<messageId>. A client that re-sends a message after a lost reply gets the same task back, replayed from the journal — the model and the tools do not run again.
• input-required is a run suspended for approval. The status message carries the interrupts in a data part ({ interrupts: [{ toolCallId, toolName, args, reason }] }). Reply on the task (message.taskId) with a data part { approvals: { <toolCallId>: true | false } }; the run continues as its recorded owner, from its frozen input.
• tasks/cancel is cancelAgentRun: terminal, and a generation running in this process is aborted. A completed or failed task answers -32002.
• A task is its owner's. Identity goes through @gnldev/auth's doorGate (the same as the AG-UI, chat and MCP doors); ownership through @gnldev/durable's runOwnerOf + decideRunAccess. Another user's or another organization's task answers -32001 Task not found, the same as an id that does not exist.

Errors are JSON-RPC errors: -32700 parse error, -32600 invalid request (and an unknown agent, with HTTP 404 and data.code: 'agent_not_found'), -32601 method not found, -32602 invalid params, -32001 task not found, -32002 task not cancelable, -32004 unsupported operation (message/stream, push notifications), -32040 the door refused the caller (data.status is the HTTP status: 400, 401, 403).

Options

• identify — who is calling (@gnldev/auth Identify, the function you hand every door). An application credential names the end user it acts for in params.metadata.resourceId; naming nobody is refused. Without identify every caller is anonymous: an anonymous task is reachable by every anonymous caller who knows its id, and the host rule below applies.
• authorize — the provider's authorize, asked for agents:run (message/send), runs:read (tasks/get, and catalog:read for the card) and run:cancel (tasks/cancel).
• onDecision — each request's outcome, to your provider's hook (auth.onDecision).
• allowedHosts / allowCrossSite — the open-surface rules for a request with no identity, with the same meaning as on createRestApi.
• baseUrl — the public URL the handler is mounted at; the card's url is <baseUrl>/agents/<name>. Default: read from the card request, which is right unless your host strips a mount prefix.
• agentVersion — the version the card advertises (default '1.0.0').

Its protections, printed when it is built. createA2AServer prints a short block — whether callers are named (identify), which hosts an anonymous caller may use (allowedHosts), whether other sites may call it (allowCrossSite) — as createRestApi prints its own matrix — to standard error, never standard output; protectionsBanner: false silences it. An option given in the config (first argument) instead of the options is refused by name, not ignored.

Not here: message/stream and tasks/resubscribe (SSE), push notifications, tasks/get's historyLength, file parts. The REST API's own gates — the budget gate, the agent approval registry and the paid resource gate — belong to createRestApi, as they do for the AG-UI and chat doors.

Call a remote agent

createA2ATool calls a remote agent on a @gnldev/server REST endpoint (protocol: 'gnl', the default) or any A2A agent (protocol: 'a2a') as an AI SDK tool. Deduped across the network when the remote is GNL: runId is deterministic — a2a:${idempotencyKey ?? toolCallId} → a GNL remote's runDurable replays the same runId, so a second POST has no side effect (a standard A2A remote decides for itself what a repeated messageId does) (at-most-once for the remote effect).…