Spectrum-TS

Choose a setup method

Method	Use it when
Agnost AI skill	You want your coding agent to inspect the app, make the change, and verify it.
Agnost AI SDK	You want explicit control over the interaction boundaries and fields.
OpenTelemetry	The framework already emits useful spans or you operate an OTel pipeline.

Start with one method for a call path. Combining SDK tracking with framework OpenTelemetry on the same call can create duplicate interactions.

Recommended: Agnost AI skill

Recommended. Choose this path when you want your coding agent to inspect the project, select a supported transport, make the smallest instrumentation change, send a test event, and verify that it reached Agnost AI.

Install the skill once in your coding-agent environment:

npx skills add AgnostAI/skills --skill agnost-ai

Run the framework-specific prompt below from the application root. Review the resulting diff before deploying it.

Use the agnost-ai skill to add Agnost AI analytics to this Spectrum-TS application.
Org ID: your-org-id
Instrument the real message-handling path and verify one fresh interaction.

Manual setup: Agnost AI SDK

npm install agnostai

Wrap the handler that turns an incoming provider message into the reply sent by your Spectrum application:

import * as agnost from 'agnostai';

agnost.init('your-org-id');
const interaction = agnost.begin({
  userId: message.userId,
  conversationId: message.conversationId,
  agentName: 'spectrum-assistant',
  input: message.text,
});
try {
  const reply = await createReply(message);
  interaction.end(reply.text);
  return reply;
} catch (error) {
  interaction.end(String(error), false);
  throw error;
}

Call await agnost.shutdown() during application shutdown so buffered events flush.

Manual setup: OpenTelemetry

Spectrum-TS has built-in OpenTelemetry instrumentation. Enable it with telemetry: true, then route its OTLP exporter to Agnost AI with standard OTEL_EXPORTER_OTLP_* environment variables. Note: Spectrum telemetry is exported by the spectrum-ts package itself, so the app must have spectrum-ts installed. The umbrella package includes the official provider packages; install a scoped @spectrum-ts/* package only if the app imports that provider directly.

1. Install

Already have spectrum-ts installed? Skip.

npm install spectrum-ts

Official provider imports:

Provider	Umbrella import	Direct package
Telegram	`spectrum-ts/providers/telegram`	`@spectrum-ts/telegram`
Slack	`spectrum-ts/providers/slack`	`@spectrum-ts/slack`
WhatsApp Business	`spectrum-ts/providers/whatsapp-business`	`@spectrum-ts/whatsapp-business`
iMessage	`spectrum-ts/providers/imessage`	`@spectrum-ts/imessage`
Terminal	`spectrum-ts/providers/terminal`	`@spectrum-ts/terminal`

2. Point Spectrum telemetry at Agnost AI

Set these environment variables before starting the Spectrum app. Use your runtime’s environment configuration, a .env file, container configuration, or your deployment platform:

AGNOST_ORG_ID=<your-org-id>
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.agnost.ai/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="X-Agnost-Org-ID=<your-org-id>"

3. Enable Spectrum telemetry

import { Spectrum } from "spectrum-ts";
import { telegram } from "spectrum-ts/providers/telegram";

const app = await Spectrum({
  projectId: process.env.PROJECT_ID!,
  projectSecret: process.env.PROJECT_SECRET!,
  providers: [
    // Telegram is only an example. Any official Spectrum provider works with
    // the same telemetry config.
    telegram.config({ botToken: process.env.TELEGRAM_BOT_TOKEN! }),
  ],
  telemetry: true,
});

// Optional smoke-test loop only. Spectrum telemetry is enabled above; keep this
// only if you want the sample app to reply to messages.
for await (const [space, message] of app.messages) {
  if (message.content.type !== "text") continue;

  const output = `Echo: ${message.content.text}`;
  await space.send(output);
}

telemetry: true sends Spectrum’s native spans for provider, space, message, content type, and lifecycle metadata. Current Spectrum native spans do not include raw transcript text. If Agnost AI Chat View must render the actual user/bot messages, emit one additional app-level turn span with agnost.session_id, agnost.user_id, input, and output from your message loop.

Local Sample

npm create spectrum-project@latest clank -- --providers telegram
cd clank

Set the sample’s environment variables using the mechanism appropriate for your local runtime:

PROJECT_ID=<spectrum-project-id>
PROJECT_SECRET=<spectrum-project-secret>
TELEGRAM_BOT_TOKEN=<telegram-bot-token>
AGNOST_ORG_ID=<your-org-id>
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.agnost.ai/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="X-Agnost-Org-ID=<your-org-id>"

Use the provider you need, for example telegram, slack, whatsapp-business, imessage, or terminal. Then set telemetry: true in the generated Spectrum(...) config. Native Spectrum telemetry is enough for Trace View and Metadata. Add a separate turn span only if you need transcript text in Chat View.

References

Next steps

Conversations: review the complete Spectrum interaction.
Events: inspect provider and message lifecycle activity.
Intents: organize production conversations by what users wanted.

Getting started

Agent frameworks

Voice agents

Custom applications

MCP server analytics

Platforms

Choose a setup method

Recommended: Agnost AI skill

Manual setup: Agnost AI SDK

Manual setup: OpenTelemetry

1. Install

2. Point Spectrum telemetry at Agnost AI

3. Enable Spectrum telemetry

Local Sample

References

Next steps

​Choose a setup method

​Recommended: Agnost AI skill

​Manual setup: Agnost AI SDK

​Manual setup: OpenTelemetry

​1. Install

​2. Point Spectrum telemetry at Agnost AI

​3. Enable Spectrum telemetry

​Local Sample

​References

​Next steps

Choose a setup method

Recommended: Agnost AI skill

Manual setup: Agnost AI SDK

Manual setup: OpenTelemetry

1. Install

2. Point Spectrum telemetry at Agnost AI

3. Enable Spectrum telemetry

Local Sample

References

Next steps