Quickstart

Installation

npm install @spect-tools/track
# or
pnpm add @spect-tools/track

Peer Dependencies

# For Vercel AI SDK
npm install ai @ai-sdk/provider

# For OpenTelemetry export
npm install @opentelemetry/core @opentelemetry/sdk-trace-base

# For Claude Agent SDK
npm install @anthropic-ai/claude-agent-sdk

API key

You can get your API key from the Spect settings page.

AI SDK integration

Wrap your language model to enable automatic trace collection:

import { wrap } from '@spect-tools/track';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const wrappedModel = wrap(openai('gpt-4o'), {
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
});

const result = await generateText({
  model: wrappedModel,
  prompt: 'Hello!',
});

Claude Agent SDK integration

Track Claude Agent sessions:

import { streamClaudeAgentSession } from '@spect-tools/track';

const session = streamClaudeAgentSession({
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
  prompt: 'Build a hello world app',
  claudeOptions: {
    // Claude Agent SDK options
  },
});

for await (const message of session) {
  console.log(message);
}

Customizing Spect

Custom Trace IDs

We recommend to pass trace metadata via provider options:

await generateText({
  model: wrappedModel,
  prompt: 'Hello!',
  experimental_providerMetadata: {
    spect: {
      traceId: 'custom-trace-id',
      name: 'my-operation',
    },
  },
});

Configuration Options

Option	Type	Required	Description
`organizationId`	`string`	Yes	Your organization identifier
`apiKey`	`string`	Yes*	Spect API key (*not required if `local: true`)
`provider`	`string`	No	Provider name override (e.g., `'openai'`, `'anthropic'`)
`operationName`	`string`	No	Custom operation name for traces
`local`	`boolean`	No	Local-only mode, skip sending to collector

Quickstart

On this page