Skip to content
Execlave
Back to Docs

SDK Reference

Complete API reference for the Execlave SDKs.

Installation

npm install @execlave/sdk

Zero runtime dependencies. Supports Node.js 18+ and modern bundlers for browser-side usage. TypeScript types included.

Initialization

import { Execlave } from '@execlave/sdk';

const ag = new Execlave({
  apiKey: process.env.EXECLAVE_API_KEY!,      // required
  baseUrl: 'http://localhost:4000',              // default
  environment: 'production',                      // default
  asyncMode: true,                                // default: buffer traces
  batchSize: 100,                                 // max traces per flush
  flushIntervalMs: 10_000,                        // 10s flush interval
  debug: false,                                   // verbose logging
  enableControlChannel: true,                     // kill-switch polling
  pollIntervalMs: 15_000,                         // poll interval
  enableInjectionScan: true,                      // prompt injection detection
  enforcementOnOutage: 'fail_open',               // fail_open | fail_closed
  policyCacheTtlMs: 60_000,                       // policy decision cache TTL
});
Important

Create a single Execlave instance and share it across your app. The SDK manages connection pooling, batching, and background flushing internally.

Methods

registerAgent

ag.registerAgent(config: AgentConfig): Promise<Agent>

Register a new agent or update an existing one. Idempotent — safe to call on every app startup.

Parameters

agentId(string)Unique identifier for the agent
name(string)Display name
type(string)chatbot | copilot | autonomous | workflow | data_processing
platform(string)custom | openai | anthropic | langchain
description?(string)Agent description
model?(string)Default model identifier
tags?(string[])Tags for filtering

Returns

Promise<Agent>
await ag.registerAgent({
  agentId: 'support-bot',
  name: 'Customer Support Bot',
  type: 'chatbot',
  platform: 'openai',
  tags: ['support', 'tier-1'],
});

startTrace

ag.startTrace(opts: TraceOptions): Trace

Start a new trace to record an LLM interaction. Returns a chainable Trace object.

Parameters

agentId(string)Agent performing the trace
sessionId?(string)Group traces into conversations
parentTraceId?(string)Link to a parent trace for nested calls

Returns

Trace
const trace = ag.startTrace({ agentId: 'support-bot' });
trace
  .setInput('How do I reset my password?')
  .setOutput('Go to Settings > Security...')
  .setModel('gpt-4')
  .setTokens(150, 320)
  .setCost(0.0045)
  .finish();

// Or finish with error:
trace.finish('error', 'LLM call timed out');

wrap

ag.wrap<T>(fn: (input: string) => Promise<T>, opts): (input: string) => Promise<T>

Wrap a function with automatic tracing. Input/output are captured, and the trace is finished on return or error.

Parameters

fn(Function)Async function to wrap
opts.agentId(string)Agent performing the call

Returns

Wrapped function with same signature
const tracedAnswer = ag.wrap(
  async (question: string) => {
    const res = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: question }],
    });
    return res.choices[0].message.content;
  },
  { agentId: 'support-bot' }
);

// Usage — fully traced automatically
const answer = await tracedAnswer('How do I upgrade?');

shutdown

ag.shutdown(): Promise<void>

Flush all buffered traces and close connections. Call on process exit.

Returns

Promise<void>
process.on('SIGTERM', async () => {
  await ag.shutdown();
  process.exit(0);
});

Error Types

AgentPausedError

Thrown when a trace is started for an agent that has been paused via the kill switch. Your app should catch this and return a graceful fallback to the user.

PolicyBlockedError

Thrown when a pre-execution policy check blocks the request. Contains the violated policy name and enforcement mode.

Privacy & PII Scrubbing

The TypeScript SDK supports client-side prompt injection scanning. PII scrubbing is handled server-side by the processing service.

const ag = new Execlave({
  apiKey: process.env.EXECLAVE_API_KEY!,
  enableInjectionScan: true,  // scan inputs for injection patterns
});

OpenTelemetry Integration

The TypeScript SDK exports an OTel span exporter for integration into existing observability stacks:

import { ExeclaveSpanExporter } from '@execlave/sdk';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';

const provider = new NodeTracerProvider();
provider.addSpanProcessor(
  new SimpleSpanProcessor(
    new ExeclaveSpanExporter({ apiKey: process.env.EXECLAVE_API_KEY! })
  )
);
provider.register();