Documentation

Grafana Cloud

AI and machine learning

Grafana Assistant

SDKs and APIs

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 Cloud stack with the Grafana Assistant app installed and enabled.
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 { isAvailable, openAssistant, closeAssistant } = useAssistant();

  if (!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 the For developers button
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