TypeScript SDK

The SideSeat TypeScript SDK (@sideseat/sdk) provides OpenTelemetry instrumentation for Node.js applications with automatic configuration and OTLP export. Stream runs into the local AI development workbench while you iterate locally.

What you’ll learn:

• Install and configure the TypeScript SDK
• Use environment variables for configuration
• Enable debug mode and custom endpoints

Prerequisites

• SideSeat running locally (sideseat)
• Node.js 18+

Installation

npm install @sideseat/sdk

Or with your package manager:

npm

npm install @sideseat/sdk

yarn

yarn add @sideseat/sdk

pnpm

pnpm add @sideseat/sdk

Quick Start

Add two lines at the top of your entry point:

import { init, Frameworks } from '@sideseat/sdk';
init({ framework: Frameworks.VercelAI });

// Your existing code
import { generateText } from 'ai';
import { bedrock } from '@ai-sdk/amazon-bedrock';

const { text } = await generateText({
  model: bedrock('us.anthropic.claude-sonnet-4-5-20250929-v1:0'),
  prompt: 'Hello!',
  experimental_telemetry: { isEnabled: true },
});

Runs flow to SideSeat at http://localhost:5388.

Features

Framework Selection

framework is required and tells SideSeat which framework you are using for accurate trace detection:

import { init, Frameworks } from '@sideseat/sdk';

init({ framework: Frameworks.VercelAI });

Available frameworks: Strands, VercelAI, LangChain, CrewAI, AutoGen, OpenAIAgents, GoogleADK, PydanticAI.

Idempotent Initialization

Safe to call multiple times:

init({ framework: Frameworks.VercelAI });  // Initializes
init({ framework: Frameworks.VercelAI });  // No-op (already initialized)

Environment Variable Support

Configure via environment variables without code changes:

SIDESEAT_ENDPOINT=http://custom:5388 \
SIDESEAT_PROJECT_ID=my-project \
SIDESEAT_API_KEY=sk-xxx \
node app.js

Debug Mode

Enable verbose logging:

init({ framework: Frameworks.VercelAI, debug: true });

Output:

[SideSeat] Initializing with endpoint: http://127.0.0.1:5388
[SideSeat] Project ID: default
[SideSeat] Service name: my-app

Resource Attributes

The SDK automatically sets these OpenTelemetry resource attributes:

Attribute	Value
service.name	From config, package.json, or "unknown-service"
service.version	From config, package.json, or "0.0.0"
telemetry.sdk.name	"sideseat"
telemetry.sdk.version	SDK version
telemetry.sdk.language	"node"

OTLP Export

The SDK uses HTTP/1.1 OTLP export with:

• Batching: Spans are batched for efficient export
• Retry: Automatic retry on transient failures
• Compression: Optional gzip compression

The endpoint URL is constructed as:

{endpoint}/otel/{projectId}/v1/traces

Example

import { init, Frameworks } from '@sideseat/sdk';

// Initialize with all options
const client = init({
  framework: Frameworks.VercelAI,
  endpoint: 'http://localhost:5388',
  projectId: 'my-project',
  apiKey: 'sk-xxx',
  serviceName: 'my-ai-agent',
  debug: true
});

// Your AI application code
import { generateText } from 'ai';
import { bedrock } from '@ai-sdk/amazon-bedrock';

const { text } = await generateText({
  model: bedrock('us.anthropic.claude-sonnet-4-5-20250929-v1:0'),
  prompt: 'Hello!',
  experimental_telemetry: { isEnabled: true },
});
console.log(text);

TypeScript Support

The SDK is written in TypeScript and includes type definitions:

import { init, Frameworks } from '@sideseat/sdk';
import type { SideSeatOptions } from '@sideseat/sdk';

const config: SideSeatOptions = {
  framework: Frameworks.VercelAI,
  endpoint: 'http://localhost:5388',
  projectId: 'my-project',
  debug: true
};

init(config);

Next Steps

• Configuration — detailed configuration options
• init() / createClient() — API reference