> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agnost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Spectrum-TS

> Capture traces from Photon Spectrum-TS with native OpenTelemetry telemetry

## 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

<Note>
  **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.
</Note>

Install the skill once in your coding-agent environment:

```bash theme={null}
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.

```text theme={null}
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

```bash theme={null}
npm install agnostai
```

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

```typescript theme={null}
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.

```bash theme={null}
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:

```dotenv theme={null}
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

```typescript theme={null}
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

```bash theme={null}
npm create spectrum-project@latest clank -- --providers telegram
cd clank
```

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

```dotenv theme={null}
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

* [Spectrum-TS telemetry](https://photon.codes/docs/spectrum-ts/getting-started#telemetry)
* [Spectrum-TS repository](https://github.com/photon-hq/spectrum-ts)

## Next steps

* [Conversations](/using-conversations): review the complete Spectrum interaction.
* [Events](/using-events): inspect provider and message lifecycle activity.
* [Intents](/using-intents): organize production conversations by what users wanted.