Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana Assistantbreadcrumb arrow SDKbreadcrumb arrow 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 prebuilt buttons and prompt cards that open the Assistant.
  • Generate inline content: Add AI-powered text inputs and text areas to forms.
  • 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:

Bash 
npm install @grafana/assistant

The package contains TypeScript type definitions, helper functions, hooks, and UI components for Grafana plugin code.

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:

typescript 
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:

typescript 
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:

typescript 
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:

typescript 
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.

Add query-editor assistance

Use QueryWithAssistantButton in data source query editors. The component passes the selected data source, current query, and other non-empty queries to Assistant:

typescript 
import { CoreApp } from '@grafana/data';
import { QueryWithAssistantButton } from '@grafana/assistant';

export function QueryEditorActions() {
  return (
    <QueryWithAssistantButton
      currentQuery={query}
      queries={queries}
      dataSourceInstanceSettings={dataSourceInstanceSettings}
      datasourceApi={datasourceApi}
      app={CoreApp.Explore}
      title="Query with Assistant"
    />
  );
}

The component opens Assistant with a prompt to create or update a query and automatically hides when Assistant is unavailable.

Add a prompt card

Use AssistantPromptCard to embed an Assistant prompt entry point in a plugin surface:

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

const context = [
  createAssistantContextItem('dashboard', {
    dashboardUid: 'abc123',
    dashboardTitle: 'Service health',
  }),
];

export function AssistantEntryPoint() {
  return (
    <AssistantPromptCard
      origin="grafana/my-plugin/dashboard"
      context={context}
      mode="dashboarding"
      placeholder="Ask Assistant about this dashboard"
      examplePrompts={[
        'Find panels with high error rates',
        'Suggest dashboard improvements',
      ]}
    />
  );
}

The prompt card opens Assistant with the user’s typed prompt and provided context. It renders nothing when Assistant is unavailable.

Generate inline form content

Use AITextInput and AITextArea when you want Assistant to generate content inside an existing form instead of opening the Assistant sidebar. These components are controlled inputs and call your onChange handler as generated text is applied.

typescript 
import { AITextInput, AITextArea } from '@grafana/assistant';
import { useState } from 'react';

export function PanelMetadataEditor() {
  const [title, setTitle] = useState('');
  const [description, setDescription] = useState('');

  return (
    <>
      <AITextInput
        value={title}
        onChange={setTitle}
        origin="grafana/my-plugin/panel-title"
        systemPrompt="Generate a concise panel title. Return only the title text."
        placeholder="Ask AI to generate a title"
        autoGenerate
        streaming
      />
      <AITextArea
        value={description}
        onChange={setDescription}
        origin="grafana/my-plugin/panel-description"
        systemPrompt="Generate a clear panel description in 2 sentences."
        getUserPrompt={(text) => `Write a panel description using this context: ${text}`}
        rows={4}
        streaming
      />
    </>
  );
}

Use autoGenerate to generate once on mount when the value is empty, streaming to stream generated text into the input, and getUserPrompt to transform the user’s input into the prompt sent to Assistant.

Register page context

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

typescript 
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:

typescript 
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:

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

Data source context

Provide the active data source to scope Assistant suggestions:

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

Structured data context

Provide arbitrary JSON to describe custom state or metadata:

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

All context item helpers accept bypassLimits. Use bypassLimits: true only for fixed-size static content such as bounded metadata, static instructions, or small configuration objects. Keep the default for query results, logs, user-generated content, or any content that can grow unexpectedly.

Try interactive examples

Explore interactive, working examples in Grafana Assistant:

  1. Open Grafana Assistant from the main navigation
  2. Click Integration hub
  3. 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

Next steps

Continue by exploring these resources: