Skip to main content

TypeScript SDK

Availability

Open core · self-host + all Splyntra Cloud plans

npm install @splyntra/sdk — the Apache-2.0 SDK for TypeScript and JavaScript. It captures every agent step, LLM call, and tool invocation as an OpenTelemetry trace, enriched with risk scoring, plus trace-correlated logs, an inline guard, evaluation, and governance helpers. Compatible with Node.js ≥ 18, ESM or CommonJS.

Install​

npm install @splyntra/sdk
# or: pnpm add @splyntra/sdk / yarn add @splyntra/sdk

Initialize​

Construct new Splyntra({...}) once at process start. The instrument array enables automatic tracing for supported frameworks with no per-call changes.

import { Splyntra } from "@splyntra/sdk";

new Splyntra({
  apiKey: process.env.SPLYNTRA_API_KEY!,
  project: "support-agent",
  endpoint: process.env.SPLYNTRA_ENDPOINT ?? "http://localhost:4318",
  environment: "production",
  instrument: ["openai", "langgraph"],
});

// Use the OpenAI SDK / LangGraph.js as usual — spans are captured automatically.

CommonJS:

const { Splyntra } = require("@splyntra/sdk");
new Splyntra({ apiKey: "...", project: "my-app", instrument: ["openai"] });

Constructor options​

OptionDefaultDescription
apiKeyrequiredSplyntra API key, sent as a Bearer token
projectrequiredProject slug
endpointhttp://localhost:4318Collector base URL
environmentdevelopmentDeployment environment label
serviceNamevalue of projectOpenTelemetry service.name resource
framework—Framework label shown on the Agents page
redactByDefaulttrueStrip secrets from spans before export
instrument[]Array of frameworks to auto-instrument
guard"off"Inline guardrail: "off", "monitor", "block"
guardFailOpentrueOn a guard-service error, proceed vs. block

See the SDK overview for the full list of instrument names.

Manual instrumentation: wrappers vs. decorators​

For custom functions beyond auto-instrumented frameworks, there are two approaches.

Function wrappers (TypeScript & JavaScript)​

import { wrapAgent, wrapTool, wrapLLM } from "@splyntra/sdk";

const readCustomer = wrapTool(
  async (id: string) => db.get(id),
  "crm.read",
);

const callLLM = wrapLLM(
  async (prompt: string) =>
    openai.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: prompt }] }),
  "gpt-4o",
  "openai",
);

const runAgent = wrapAgent(
  async (query: string) => {
    await readCustomer("42");
    return callLLM(query);
  },
  "support_agent",
  "refund",
);

wrapLLM reads token usage from a returned object with a usage field ({ prompt_tokens, completion_tokens }) for cost analytics.

Decorators (TypeScript only)​

Requires "experimentalDecorators": true in tsconfig.json:

import { traceAgent, traceTool, traceLLM } from "@splyntra/sdk";

class SupportAgent {
  @traceAgent("support_agent", "refund")
  async run(query: string) { /* ... */ }

  @traceTool("crm.read")
  async readCustomer(id: string) { /* ... */ }

  @traceLLM("gpt-4o", "openai")
  async complete(prompt: string) { /* ... */ }
}

See Manual instrumentation.

Structured logs​

Emit trace-correlated logs to the same collector — auto-attached to the active span and redacted like spans.

import { log } from "@splyntra/sdk";

log.info("charged card", { amount: 42 });
log.warn("rate limited", { server: "stripe" });
log.error("payment failed", { code: "card_declined" });

Inline guard​

The guard runs a fast, high-confidence check before a model or tool call completes. Enable it at init with guard: "monitor" (log only) or guard: "block" (throws on a high-confidence prompt-injection match).

import { Splyntra, SplyntraBlocked } from "@splyntra/sdk";

new Splyntra({ apiKey: "...", project: "my-app", guard: "block", instrument: ["openai"] });

try {
  await runAgent(userInput);
} catch (e) {
  if (e instanceof SplyntraBlocked) handleBlocked(e); // high-precision injection pre-flight
  else throw e;
}

guardFailOpen: true (default) proceeds if the guard service is unreachable — set false to fail closed. See Guardrails.

Graceful shutdown​

Spans are batched and flushed asynchronously. For short-lived scripts, flush before exit. The SDK also registers SIGTERM and SIGINT handlers for automatic flush.

const splyntra = new Splyntra({ apiKey: "...", project: "my-app" });
// ...work...
await splyntra.shutdown();

Evaluation​

Push datasets and gate CI on regressions, programmatically or via the CLI.

import { pushDataset, runEval } from "@splyntra/sdk";

await pushDataset("support-qa", [{ input: "capital of France?", expected_output: "Paris" }]);
const res = await runEval(datasetId, [{ input: "capital of France?", actual: "Paris" }], { gate: true });
if (!res.passed) process.exit(1); // regression

See Evaluation.

Governance​

Ask the control plane whether an agent may act, and record consequential actions to the tamper-evident ledger (served by Splyntra Cloud and Enterprise).

import { authorize, logAction } from "@splyntra/sdk";

const d = await authorize("payments.refund", { agentId: "support", context: { amount: 80 } });
if (d.decision === "allow") { /* proceed */ }
else if (d.decision === "needs_approval") { /* wait for a human */ }

await logAction("payments.refund", { actor: "support", resource: "order_123", metadata: { amount: 80 } });

authorize(...) resolves to { decision: "allow" | "deny" | "needs_approval" }. See Governance overview.

Next steps​