Instrument TypeScript and JavaScript agents

This guide shows you how to install the AI Observability JavaScript SDK, instrument an LLM call, and verify that generation data reaches AI Observability.

Note
AI Observability is referred to as “Sigil” in SDKs, package names, and configuration. For example, the npm package is @grafana/sigil-sdk-js.

Before you begin

A running AI Observability instance or Grafana Cloud stack with AI Observability enabled.
Node.js 22 or later.
Your AI Observability generation export endpoint URL.

Install the SDK

npm install @grafana/sigil-sdk-js

Use a framework integration

If you use LangChain, LangGraph, OpenAI Agents, LlamaIndex, Google ADK, or Vercel AI SDK, import the framework sub-module for automatic generation capture:

@grafana/sigil-sdk-js/langchain
@grafana/sigil-sdk-js/langgraph
@grafana/sigil-sdk-js/openai-agents
@grafana/sigil-sdk-js/llamaindex
@grafana/sigil-sdk-js/google-adk
@grafana/sigil-sdk-js/vercel-ai-sdk

Each integration attaches callbacks or hooks that capture generations automatically. Refer to Instrument agents with frameworks for setup details.

Capture a generation manually

To instrument calls without a framework:

import { SigilClient } from "@grafana/sigil-sdk-js";

const client = new SigilClient({
  generationExport: {
    protocol: "http",
    endpoint: "<SIGIL_ENDPOINT>/api/v1/generations:export",
    auth: { mode: "tenant", tenantId: "<TENANT_ID>" },
  },
});

await client.startGeneration(
  {
    conversationId: "conv-1",
    model: { provider: "openai", name: "gpt-4o" },
  },
  async (recorder) => {
    recorder.setResult({
      output: [{ role: "assistant", content: "Hello from Sigil" }],
    });
  },
);

await client.shutdown();

Replace SIGIL_ENDPOINT and TENANT_ID with your values.

Use a provider helper

The SDK includes helpers for OpenAI, Anthropic, and Gemini. For example, with OpenAI:

import { SigilClient, openai } from "@grafana/sigil-sdk-js";

const sigil = new SigilClient({
  /* config */
});

const response = await openai.chat.completions.create(sigil, openaiClient, {
  model: "gpt-4o",
  messages: [{ role: "user", content: "What is observability?" }],
});

await sigil.shutdown();

Configure authentication

For Grafana Cloud:

const client = new SigilClient({
  generationExport: {
    protocol: "http",
    endpoint: "<SIGIL_ENDPOINT>/api/v1/generations:export",
    auth: {
      mode: "basic",
      tenantId: "<INSTANCE_ID>",
      basicPassword: "<API_KEY>",
    },
  },
});