Omium SDK (TypeScript / JavaScript)

Fault-tolerant operating system for production multi-agent AI — tracing, autonomous recovery, and replay for your agents. The TypeScript counterpart to the Python omium package.

npm install omium

Requires Node.js ≥ 18 (uses the global fetch).

Quick start

import { init, trace } from "omium";

init({ apiKey: process.env.OMIUM_API_KEY });

const answer = await trace("research_agent", async (span) => {
  span.setAttribute("model", "claude");
  span.setTokenCounts(1200, 350);
  return await runAgent(task);
});

Configuration resolves from explicit options → environment → defaults:

| Option | Env var | Default | | ------------- | ---------------- | --------------------- | | apiKey | OMIUM_API_KEY | — | | apiUrl | OMIUM_API_URL | https://api.omium.ai| | project | OMIUM_PROJECT | default | | timeoutMs | OMIUM_TIMEOUT* | 30000 | | autoTrace | OMIUM_TRACING | true |

* OMIUM_TIMEOUT is in seconds (matches the Python SDK); stored as ms.

The recovery moat, from your app

import { RecoveryClient, ReplayClient } from "omium";

const recovery = new RecoveryClient();          // uses init()/env config
await recovery.createCommand(executionId, "retry");
const commands = await recovery.listCommands({ executionId });

const replay = new ReplayClient();
const state = await replay.getState(executionId);          // step timeline + state
const diff = await replay.diff(executionId, 3, 7);          // what changed between steps
const consensus = await replay.getConsensus(executionId);   // the coordinator's verdict

Executions

import { OmiumClient } from "omium";
const client = new OmiumClient();
const exec = await client.createExecution("my-workflow", { inputData: { topic: "x" } });
const status = await client.getExecution(exec.id as string);

OpenTelemetry (optional, dual-export)

Install the OTel peers to mirror every span to your OTLP collector in addition to Omium's native ingest, and to propagate W3C traceparent:

npm install @opentelemetry/api @opentelemetry/sdk-trace-base \
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources

import { initOtel, getTraceparent } from "omium";

await initOtel({ serviceName: "my-agent", endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT });
// Now spans emitted by trace()/OmiumTracer are also exported over OTLP/HTTP.

const traceparent = await getTraceparent(); // propagate across service calls

When the OTel packages aren't installed, all OTel calls are safe no-ops.

API surface

• init / configure / getConfig / isInitialized — configuration + lifecycle
• trace(name, fn) / OmiumTracer / Span — tracing
• RecoveryClient / ReplayClient / OmiumClient — recovery, replay, executions
• initOtel / getTraceparent / injectContext / extractContext / otel.* — OpenTelemetry
• OmiumError, ConfigError, RecoveryError, ReplayError, ExecutionError

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run build       # tsup -> dist (ESM + CJS + d.ts)

License: Proprietary.