Sessions

Spect records each instrumented call as its own trace, with a fresh trace ID per turn. To connect several turns into one conversation, pass a conversationId. Traces that share a conversationId are grouped into a single session, so you can follow a whole conversation instead of reading each turn in isolation.

The shape is:

conversation (session)
  └── traces (one per turn)
        └── spans (one per operation)

Use any stable string that identifies the conversation, such as your chat, thread, or session ID. Reuse the same value across every turn of that conversation, and use a different value for unrelated conversations. conversationId is optional: leave it out and the trace stays ungrouped.

Usage on SDKs

AI SDK

Set it per call under providerOptions.spect:

await generateText({
  model: wrappedModel,
  prompt: 'hello',
  providerOptions: {
    spect: {
      conversationId: thread.id, 
    }, 
  },
});

Or set it once at wrap time when every call on that model belongs to the same conversation:

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

A per-call providerOptions.spect.conversationId takes precedence over the value set at wrap time.

Spect never generates a conversationId for you. If your app does not pass one, the trace is stored without session grouping.

Claude Agent SDK

import { query } from '@anthropic-ai/claude-agent-sdk';
import { wrapQuery } from '@spect-tools/track';

const spectQuery = wrapQuery(query, {
  organizationId: 'your-org-id',
  apiKey: 'your-spect-api-key',
  conversationId: thread.id, 
});

Manual observer API

const session = observer.startSession({
  name: 'custom.agent',
  model: { modelId: 'my-model', provider: 'custom' },
  conversationId: thread.id, 
});