Skip to content
Get started

SDK (TypeScript)

SDK (preview). packages/sdk (@agentflowbind/sdk) is being built alongside this docs site (docs/specs/phase-2.md §2.4) and hasn't shipped yet. Every code sample below shows the intended API surface so you can plan an integration around it — until it ships, use the plain HTTP calls shown throughout the rest of these guides.

#Install and construct a client (preview)

bash
npm install @agentflowbind/sdk
typescript
// SDK (preview)
import { AgentFlowBind } from "@agentflowbind/sdk";

const client = new AgentFlowBind({
  apiKey: process.env.AFB_API_KEY!,
  baseUrl: "https://api.agentflowbind.com", // optional — this is the default
});

ESM, fully typed, zero runtime dependencies — it wraps the same fetch-based calls shown elsewhere in these guides, plus automatic retries on 429/5xx (honouring Retry-After) and a typed AgentFlowBindError with code/status/details matching the error envelope.

#Agents and files (preview)

typescript
// SDK (preview)
const agents = await client.agents.list();
const agent = await client.agents.create({ presetId: "document/supplier-invoice", name: "AP extractor" });
const file = await client.files.upload(fileBytes, { filename: "invoice.pdf", mime: "application/pdf" });

#Runs (preview)

typescript
// SDK (preview)
const run = await client.runs.create({ agentId: agent.id, input: { fileIds: [file.id] } });

// Polls GET /v1/runs/:id (or uses SSE, when available) until a terminal status
const finished = await client.runs.wait(run.id, {
  pollMs: 2000,
  timeoutMs: 5 * 60_000,
  onEvent: (event) => console.log(event.type, event.data),
});

const output = await client.runs.output(finished.id);
typescript
// SDK (preview) — human-in-the-loop
await client.runs.input(run.id, { answer: "EUR" });
await client.runs.approve(run.id, { approved: true });
await client.runs.review(run.id, { accept: false, correctedOutput: { total: 1249.5 } });
await client.runs.feedback(run.id, { rating: 4, correctedOutput: { total: 1249.5 } });
await client.runs.cancel(run.id);

for await (const page of client.runs.list({ status: "succeeded" })) {
  console.log(page.runs.length);
}

#Webhooks and usage (preview)

typescript
// SDK (preview)
await client.webhooks.create({ url: "https://example.com/hooks/afb", events: ["run.succeeded"], secret: "whsec_..." });
await client.webhooks.list();
await client.webhooks.delete(webhookId);

const usage = await client.usage.get({ from: "2026-03-01", to: "2026-03-31" });
typescript
// SDK (preview) — same check documented in Webhooks, exposed as a helper
import { verifyWebhookSignature } from "@agentflowbind/sdk";

const ok = verifyWebhookSignature(process.env.AFB_WEBHOOK_SECRET!, header, rawBody);

#Error handling (preview)

typescript
// SDK (preview)
import { AgentFlowBindError } from "@agentflowbind/sdk";

try {
  await client.runs.create({ agentId, input: { fileIds: [file.id] } });
} catch (err) {
  if (err instanceof AgentFlowBindError && err.code === "billing.insufficient_credits") {
    console.error(`Need ${err.details?.required}, have ${err.details?.available}`);
  }
  throw err;
}

Once published, packages/sdk's own README will supersede this page as the canonical reference — this guide will drop the "(preview)" marker at that point.