AbsoluteJS

A2A

@absolutejs/a2av0.3.6betaAI

Production A2A Protocol 1.0 client and server with streaming, durable tasks, push configuration, and Agency enforcement.

#Installation

BASH
bun add @absolutejs/a2a

#Capabilities

Overview

An A2A Protocol 1.0 JSON-RPC client and server for AbsoluteJS. It implements Agent Card discovery, messages, streaming, task subscriptions, filtered and paginated task listing, push notification configuration, authenticated extended cards, explicit version and extension negotiation, and AbsoluteJS Agency enforcement.

Agency is a required host peer (>=0.7.1 <0.8.0), not a bundled dependency. The host therefore owns one action ledger and one contract version across A2A and every other agent transport. This package tests against exactly 0.7.1; support for a new Agency minor requires an explicit compatibility release.

Protocol reference:

Show 1 more

The protocol version is intentionally pinned. A2A 1.0 changed its JSON-RPC method names and Agent Card shape from 0.3; this package does not silently downgrade and lose security or behavior.

Security boundaries

Discovery and RPC clients require HTTPS outside localhost, reject credentials in URLs and redirects, enforce timeouts and response-size limits, and validate response media types. Servers authenticate before parsing bodies, cap request sizes, bind every task and push configuration to the authenticated caller, and refuse to advertise optional capabilities that are not configured.

Optional protocol capabilities

The same handler supports the A2A 1.0 optional methods when their advertised capabilities are configured:

For production push configuration storage, implement A2aPushNotificationConfigStore with the same authorization-key isolation as the included memory store. Webhook delivery should independently resolve DNS, block private and link-local destinations, avoid redirects, authenticate each request, and retry idempotently.

Agency approval flow

When policy requires approval, the server returns an A2A extension error with the Agency actionId. After approval, resend the same request with that ID at metadata[ABSOLUTE_AGENCY_EXTENSION].actionId; Agency re-evaluates policy, issues a single-use lease, and records the execution receipt.

Task isolation

Task ownership is always keyed by the authorization result. A caller cannot probe, list, cancel, or overwrite another caller's task, and PostgreSQL updates protect terminal task states atomically.

Operator posture

Hosts that operate multi-agent fleets can attach trusted labels in the authorization result and use the separate operator view. Labels are never read from A2A request data. Operator results omit task artifacts and history unless explicitly requested, so a status console does not accidentally retrieve task payloads.

Outcomes

What you can build

Standards-based agent transport

Expose authenticated JSON-RPC messaging, streaming, task subscriptions, pagination, push configuration, and extended Agent Cards through the A2A 1.0 protocol.

Governed remote actions

Connect Agency approval decisions and single-use execution leases to remote agent actions without creating a second action ledger.

Hardening checklist

Production guidance

Persist and isolate every callerUse durable authorization-fenced task and push-configuration stores. Independently harden webhook delivery against private-network resolution, redirects, unauthenticated requests, and non-idempotent retries.

Follow in order

Troubleshooting path

1
Protocol or discovery failures
Confirm the advertised protocol version and optional capabilities match the configured handlers. Then inspect authentication, authorization-key task ownership, media type, response size, and timeout failures.

#Security boundaries

Partial snippet

Discovery and RPC clients require HTTPS outside localhost, reject credentials in URLs and redirects, enforce timeouts and response-size limits, and validate response media types. Servers authenticate before parsing bodies, cap request sizes, bind every task and push configuration to the authenticated caller, and refuse to advertise optional capabilities that are not configured.

TS
import { createA2aHandler, createPostgresA2aTaskStore } from "@absolutejs/a2a";

const a2a = createA2aHandler({
  path: "/a2a",
  agentCard: {
    name: "Support Agent",
    description: "Resolves customer support cases.",
    version: "1.0.0",
    supportedInterfaces: [
      {
        protocolBinding: "JSONRPC",
        protocolVersion: "1.0",
        url: "https://example.com/a2a",
      },
    ],
    capabilities: {},
    defaultInputModes: ["text/plain"],
    defaultOutputModes: ["text/plain"],
    skills: [],
  },
  authorize: verifyA2aBearer,
  taskStore: createPostgresA2aTaskStore({ client }),
  agency: { agency },
  sendMessage: async ({ message }) => ({
    task: await startSupportTask(message),
  }),
});

#Optional protocol capabilities

Partial snippet

The same handler supports the A2A 1.0 optional methods when their advertised capabilities are configured:

TS
import { createMemoryA2aPushNotificationConfigStore } from "@absolutejs/a2a";

const a2a = createA2aHandler({
  // ...the required configuration above
  pushNotifications: {
    store: createMemoryA2aPushNotificationConfigStore(),
  },
  extendedAgentCard: authenticatedCard,
  sendStreamingMessage: async function* (request, context) {
    yield* runAgentStream(request, context);
  },
  subscribeToTask: async function* (task, context) {
    yield* subscribeToAgentTask(task, context);
  },
});

#Operator posture

Partial snippet

Hosts that operate multi-agent fleets can attach trusted labels in the authorization result and use the separate operator view. Labels are never read from A2A request data. Operator results omit task artifacts and history unless explicitly requested, so a status console does not accidentally retrieve task payloads.

TS
const taskStore = createPostgresA2aTaskStore({ client });

const authorized = {
  actor,
  authorizationKey,
  caller,
  ok: true as const,
  taskLabels: { clientId: actor.agentId, tenantId: tenant.id },
};

const posture = await taskStore.listForOperator({
  labels: { tenantId: tenant.id },
  pageSize: 25,
});

#Public entry points

Supported entry points declared by this project’s package manifest. Internal dist paths are not part of the package contract.

Public package entry point declared in package.json.

@absolutejs/a2a@absolutejs/a2a/manifest@absolutejs/a2a/manifest.json

#Package commands

Scripts declared by this project’s package manifest.

bun run buildrm -rf dist && bun build src/index.ts src/manifest.ts --outdir dist --target=bun --external @absolutejs/agency --external '@absolutejs/agency/*' --external @sinclair/typebox --external drizzle-orm --external 'drizzle-orm/*' && tsc -p tsconfig.build.json && absolute-manifest emit
bun run check:packagebun run format && bun run typecheck && bun run test && bun run build
bun run formatprettier --write "./**/*.{ts,json,md}"
bun run testbun test
bun run typechecktsc --noEmit

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

47 symbols
A2aClientErrorexportPermalink
TS
A2aClientError
Exported from @absolutejs/a2a