Instrument TypeScript and JavaScript agents

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

Before you begin

A Grafana Cloud stack with Agent Observability enabled.
Node.js 22 or later.
Your Agent Observability generation export endpoint URL.
A Cloud Access Policy Token. Refer to Collect credentials from Grafana Cloud for step-by-step instructions.

Install the SDK

npm install @grafana/agento11y

Use a framework integration

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

@grafana/agento11y/langchain
@grafana/agento11y/langgraph
@grafana/agento11y/openai-agents
@grafana/agento11y/llamaindex
@grafana/agento11y/google-adk
@grafana/agento11y/strands
@grafana/agento11y/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 { Agento11yClient } from "@grafana/agento11y";

const client = new Agento11yClient({
  generationExport: {
    protocol: "http",
    endpoint: "<AGENTO11Y_ENDPOINT>",
    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" }],
    });
  },
);

await client.shutdown();

Replace AGENTO11Y_ENDPOINT and TENANT_ID with your values.

Use environment variables instead

If you set AGENTO11Y_ENDPOINT, AGENTO11Y_PROTOCOL, AGENTO11Y_AUTH_MODE, AGENTO11Y_AUTH_TENANT_ID, and AGENTO11Y_AUTH_TOKEN, the SDK reads them at client construction. Refer to Configure your SDK.

const client = new Agento11yClient();

Use a provider helper

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

import { Agento11yClient, openai } from "@grafana/agento11y";

const client = new Agento11yClient({
  generationExport: {
    protocol: "http",
    endpoint: "<AGENTO11Y_ENDPOINT>",
    auth: { mode: "tenant", tenantId: "<TENANT_ID>" },
  },
});

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

await client.shutdown();

Configure authentication in code

For Grafana Cloud, use basic auth with your Cloud Access Policy Token:

const client = new Agento11yClient({
  generationExport: {
    protocol: "http",
    endpoint: "<AGENTO11Y_ENDPOINT>",
    auth: {
      mode: "basic",
      tenantId: "<INSTANCE_ID>",
      basicPassword: "<API_KEY>",
    },
  },
});

Set up traces and metrics

The SDK emits OpenTelemetry spans and metrics alongside generation data. To export them, configure a TracerProvider and MeterProvider in your application before creating the client. Without this, traces and metrics are silently lost.

Refer to Set up traces and metrics for Grafana Cloud OTLP options and SDK configuration for setup snippets.

Verify data

Open Agent Observability in Grafana Cloud and navigate to Conversations. Your generation should appear within a few seconds. Check your Traces and Metrics data sources for SDK-emitted spans and metrics.