SDKS

TypeScript SDK.

@actae/sdk — a feature-parity port of the Python SDK for Node 20+, with bigint-safe JSON, lazy adapter imports, and live streaming.

Install

$ npm install @actae/sdk

Node 20+, ESM-only, single runtime dependency ws. newClientFromEnv() reads ACTAE_URL, ACTAE_WS_URL, ACTAE_API_KEY.

60-second start

typescript
import { ActaeClient } from "@actae/sdk";

const client = new ActaeClient({ apiKey: "sk-…", endpoint: "http://localhost:8002"});
const ev = await client.record("my-channel", "agent.step", { input: "hello"}, { actor: "agent"});
const events = await client.replay("my-channel", { limit: 100});

API surface

The SDK mirrors the Python ActaeClient 1:1 — every HTTP method is available directly and through namespaced facades (client.events.record(...) === client.record(...)).

AreaClient methodsFacade
Eventsrecord, replay, query, transitionclient.events
StatesaveState, latestState, listStates, getState, deleteStateclient.state
Channels/forksfork, getForkReceipt, resolveStep, diffStates, decisionTrail, compareChannels, promoteChannel, …client.channels
Tool executionsclaimExecution, completeExecution, failExecution, heartbeatExecution, cancelExecutionclient.executions
Consumer groupscreateGroup, joinGroup, claimWork, ackWork, heartbeat, groupOffsetsclient.groups
Wake-upsscheduleWakeup, listWakeups, getWakeup, cancelWakeupclient.wakeups
WebSocketconnect, subscribe, subscribeAndWait, publish, streamclient.ws

Errors

All errors extend ActaeError: AuthError (401), LockError (402), ConnectionError (transport), RateLimitError (429, with retryAfterSeconds), SnapshotBoundaryError/VersionConflictError/IdempotencyConflictError (409s), SessionError/SessionCompletedError/NoRestorableCheckpointError, ServerError (5xx). Branch with instanceof.

WebSocket realtime

typescript
await client.connect();
client.onMessage((topic, event) => console.log(topic, event));
await client.subscribe("my-channel", 0);  // cursor 0 = replay from start
const ev = await client.publish("my-channel", { note: "hi"});
client.disconnect();
  • publish returns the persisted event from the server ack; a stable operationId makes retries idempotent.
  • stream(topic, cursor?) is an async iterator of live events, ending on disconnect.
  • The server does not echo publishes back — set echoSelf: true for single-client demos.
  • Auto-reconnect (0.5s → 30s backoff) resubscribes all topics; disconnect() disables it permanently.

int64 / bigint fidelity

Integers beyond Number.MAX_SAFE_INTEGER arrive as bigint — never silently rounded. The serializer emits bigint as raw JSON number tokens, so received payloads round-trip. Accessors asInt64, asBigInt, asFloat, asString, asMap, asList mirror the Go SDK.

AgentSession, StateManager, and adapters

AgentSession covers step/fork/resume with deterministic operation keys, boundaryMode (exact/approximate/lineage_only), and boundary provenance on the session (forkReceipt, sourceStateSha256, reproducibility). StateManager is the framework-agnostic versioned-state helper.

Adapters live behind subpath exports with lazy framework imports: @actae/sdk/adapters/langgraph (ActaeCheckpointSaver), /langchain, /claude, /openai (installActaeTracing), /codex (CodexOTLPReceiver), /copilot. No CrewAI adapter — CrewAI has no TypeScript port.