Documentation

Grafana Cloud

AI and machine learning

Grafana Assistant

SDK

TypeScript SDK

Grafana Cloud

TypeScript SDK for Grafana plugins

The @grafana/assistant package provides a lightweight TypeScript SDK for integrating Grafana Assistant into your Grafana plugins and applications.

What you’ll achieve

This article helps you integrate the Assistant into your plugin UI in a few targeted ways:

Check availability: Detect whether the Assistant is available before rendering UI.
Open the Assistant: Trigger the Assistant with prompts and context.
Use React hooks: Work with Assistant state and actions in components.
Use UI components: Add a prebuilt button that opens the Assistant.
Register page context: Provide dashboard, data source, or structured context.
Update context dynamically: Adjust context in response to user actions.

Before you begin

Make sure you have the following:

A Grafana deployment with the Grafana Assistant app installed and enabled. This can be a Grafana Cloud stack or a self-managed Grafana instance connected to a Grafana Cloud Assistant backend.
An existing Grafana plugin or app project to integrate with.
Node.js 22 and npm installed locally.
Access to install the @grafana/assistant package from npm.

When to use the TypeScript SDK

Use the TypeScript SDK when:

Building Grafana plugins or extensions
Adding AI assistance to custom Grafana apps
Integrating Assistant features into Grafana UI workflows
Creating context-aware help experiences based on page location

Install the SDK

Install the package from npm:

npm install @grafana/assistant

The package contains only TypeScript type definitions and helper functions—no additional runtime dependencies.

Key capabilities

Use these capabilities to integrate Assistant entry points and context into your plugin:

Check availability

Detect if the Assistant is available in the current environment before showing UI elements:

import { isAssistantAvailable } from '@grafana/assistant';
import { firstValueFrom } from 'rxjs';

async function checkAvailability() {
  const available = await firstValueFrom(isAssistantAvailable());
  console.log('Assistant available:', available);
}

Open the Assistant programmatically

Open the Assistant with custom prompts and context from your code:

import { openAssistant } from '@grafana/assistant';

openAssistant({
  origin: 'grafana/my-plugin',
  prompt: 'Show me CPU usage over the last hour',
  autoSend: true,
});

Parameters:

origin (required): Namespace identifying your plugin (e.g., grafana/my-plugin/feature)
prompt (optional): Pre-filled prompt text
autoSend (optional): Automatically send the prompt when opening
context (optional): Additional context items (dashboards, datasources, structured data)

Use React hooks

Use the useAssistant() hook for reactive integration in React components:

import { useAssistant } from '@grafana/assistant';

export function MyComponent() {
  const { isLoading, isAvailable, openAssistant, closeAssistant } = useAssistant();

  if (isLoading || !isAvailable) {
    return null;
  }

  return (
    <button onClick={() => openAssistant?.({
      origin: 'grafana/my-plugin',
      prompt: 'Help me analyze this data'
    })}>
      Ask Assistant
    </button>
  );
}

Use UI components

Use the OpenAssistantButton component for drop-in integration:

import { OpenAssistantButton } from '@grafana/assistant';

export function MyComponent() {
  return (
    <OpenAssistantButton
      prompt="Analyze this dashboard"
      origin="grafana/my-plugin/dashboard"
    />
  );
}

The button automatically hides when the Assistant is unavailable.

Register page context

Automatically provide context to the Assistant based on the current URL:

import { providePageContext, createAssistantContextItem } from '@grafana/assistant';

// Register context for dashboard pages
const dashboardContext = createAssistantContextItem('structured', {
  data: {
    name: 'Dashboard Context',
    pageType: 'dashboard',
    capabilities: ['analyze', 'troubleshoot', 'optimize'],
    help: 'I can help you analyze dashboard data and optimize performance.',
  },
});

// Register for all dashboard URLs
providePageContext('/d/*', [dashboardContext]);

URL pattern matching:

Wildcards: /d/* matches /d/abc
Glob patterns: /explore** matches /explore and all subpaths
Regex: /^\/datasources\/edit\/[^\/]+$/ for complex patterns

Update context dynamically

Update context as users interact with your application:

const setContext = providePageContext('/d/*', [dashboardContext]);

// Update when user selects a panel
function onPanelSelect(panelId: string, panelTitle: string) {
  const panelContext = createAssistantContextItem('structured', {
    data: {
      name: 'Selected Panel',
      panelId,
      panelTitle,
      actions: ['edit', 'duplicate', 'inspect'],
    },
  });

  setContext([dashboardContext, panelContext]);
}

Choose context item types

Use context items to provide relevant information to the Assistant. The SDK supports three context types:

Dashboard context

Provide the current dashboard to give the Assistant page awareness:

createAssistantContextItem('dashboard', {
  dashboardUid: 'abc123',
  dashboardTitle: 'My Dashboard',
});

Data source context

Provide the active data source to scope Assistant suggestions:

createAssistantContextItem('datasource', {
  datasourceUid: 'prom-123',
});

Structured data context

Provide arbitrary JSON to describe custom state or metadata:

createAssistantContextItem('structured', {
  data: {
    // Any JSON-serializable data
    name: 'Custom Context',
    metadata: { ... }
  }
})

Try interactive examples

Explore interactive, working examples in Grafana Assistant:

Open Grafana Assistant from the main navigation
Click For developers
Explore the TypeScript SDK section with:
- Live code examples you can modify and test
- Complete working samples for each API
- Copy-to-clipboard code snippets
- Interactive forms to try different parameters