@blackbox-ai/sdk

TypeScript/JavaScript SDK for BLACKBOX — the flight recorder for AI agents.

Install

npm install @blackbox-ai/sdk
# or
pnpm add @blackbox-ai/sdk

Quickstart

import { BlackboxClient } from "@blackbox-ai/sdk";

const bb = new BlackboxClient({
  apiUrl: "https://your-blackbox.railway.app",
  apiKey: process.env.BLACKBOX_AGENT_KEY,
});

const run = bb.run("invoice-review-4821");

await run.genesis({
  system_prompt: "You are a helpful assistant.",
  model_snapshot: "gpt-4o",
  tools: ["web_search"],
});

await run.reasoning("Analysing the user request...");
await run.toolCall("web_search", { query: "latest AAPL price" });
await run.seal();

Every event is hashed and chained. Replay, diff, and audit any run in the BLACKBOX UI.

Environment variables

BLACKBOX_API_URL=https://your-blackbox.railway.app
BLACKBOX_AGENT_KEY=bb_agent_...

API

BlackboxClient

const bb = new BlackboxClient({ apiUrl?, apiKey? });

bb.run(runId)            // → BlackboxRun helper
bb.record(event)         // → EventOut
bb.getRun(runId)         // → RunOut (with chain_valid)
bb.listRuns()            // → RunSummary[]
bb.verify(runId, input)  // → VerifyOut
bb.getAuditCertificate(runId) // → AuditCertificate (no auth)
bb.streamEvents({ onEvent }) // → EventSource (SSE)

BlackboxRun

const run = bb.run("my-run-id");

await run.genesis({ system_prompt, model_snapshot, tools })
await run.reasoning("title", payload?, { model?, tokens_in?, tokens_out?, cost_usd?, latency_ms? })
await run.toolCall("tool_name", payload?, { latency_ms? })
await run.retrieval("title", payload?)
await run.fault("title", payload?)
await run.verify({ output_text, cost_usd?, latency_ms? })
await run.seal()

OpenTelemetry alternative

BLACKBOX also accepts standard OTLP traces — no SDK needed:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://your-blackbox.railway.app/v1/otel/traces

License

MIT