Node.js library

The A22A Node.js library provides convenient access to the A22A API from applications written in server-side JavaScript and TypeScript.

RequirementsCopy Anchor Link

Node.js 20.19 or later.

InstallationCopy Anchor Link

npm install @a22a/sdk
# or
pnpm add @a22a/sdk

UsageCopy Anchor Link

The package needs to be configured with your account's API key, which is available on the A22A dashboard.

import { A22A } from "@a22a/sdk";

const a22a = new A22A({ apiKey: "a22a_…" });

const { run_id } = await a22a.runs.invoke({
  project: "acme",
  workflow: "summarise",
  input: { text: "…" }
});

Requests time out after 30 seconds.

Usage with TypeScriptCopy Anchor Link

Types are bundled. Request and response shapes are importable by name.

import type { Manifest, Run, WebhookEvent } from "@a22a/sdk";

Deploying a projectCopy Anchor Link

A project is a set of named workflows. A workflow is a list of steps. A step is a prompt and the model that answers it. Deploy them together as one document; each deploy creates a new version, and runs in progress stay on the version they started with.

await a22a.projects.deploy({
  project: "acme",
  workflows: {
    summarise: {
      steps: [
        {
          id: "extract",
          prompt: "Pull the key facts from {{input.text}}",
          model: "anthropic/claude-haiku-4.5"
        },
        {
          id: "write",
          prompt: "Write a summary from {{extract.output}}",
          model: "anthropic/claude-sonnet-5",
          needs: ["extract"]
        }
      ]
    }
  }
});
// { project: "acme", version: 1, workflows: ["summarise"] }

await a22a.projects.retrieve("acme");
// { id: "…", project: "acme", version: 1, manifest: { … } }

See Workflows for every step field.

Invoking a workflowCopy Anchor Link

const { run_id } = await a22a.runs.invoke({
  project: "acme",
  workflow: "summarise",
  input: { text: "…" }
});

The run is queued on the project's latest version and the call returns at once. input must supply every {{input.*}} field the workflow reads.

Retrieving a runCopy Anchor Link

const run = await a22a.runs.retrieve(run_id);
// { run_id: "4b3e…", status: "completed", steps: [ … ] }

A run is queued, then running, then completed or failed. Each step is pending, running, completed with its output, or failed with its error. One failed step fails the run, and the run carries an error of its own.

Webhook signingCopy Anchor Link

A22A posts run.completed and run.failed to the endpoint set on your dashboard, signed with the endpoint's secret. Verify the signature and parse the event with constructEvent. Pass the raw request body; the signature covers the exact bytes sent.

export async function POST(req: Request) {
  const event = a22a.webhooks.constructEvent({
    body: await req.text(),
    signature: req.headers.get("a22a-signature"),
    secret: "whsec_…"
  });
  // { type: "run.completed", created: "…", data: { run_id, status, steps } }

  if (event.type === "run.completed") await save(event.data);

  return new Response(null, { status: 200 });
}

A missing, malformed, stale or mismatched signature throws InvalidWebhookSignatureError. A body that is not a known event throws InvalidWebhookPayloadError. Respond with a 2xx once you have handled the event; anything else is retried.

Handling errorsCopy Anchor Link

When the library is unable to connect to the API, or the API returns a non-2xx status, a subclass of APIError is thrown. Every class is also reachable as A22A.errors.<Name>.

try {
  await a22a.runs.retrieve(run_id);
} catch (err) {
  if (err instanceof A22A.errors.APIError) {
    console.log(err.status);     // 404
    console.log(err.code);       // "not_found"
    console.log(err.requestId);  // quote this when reporting a problem
  }
  throw err;
}

Any other non-2xx status throws APIError itself. See Errors for every code.