---
title: "TypeScript SDK for Grafana plugins | Grafana Cloud documentation"
description: "Use the @grafana/assistant package to integrate AI assistance into your Grafana plugins and apps."
---
> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).
# 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:
Bash  Copy
```bash
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:
typescript  Copy
```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  Copy
```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  Copy
```typescript
import { useAssistant } from '@grafana/assistant';
export function MyComponent() {
const { isLoading, isAvailable, openAssistant, closeAssistant } = useAssistant();
if (isLoading || !isAvailable) {
return null;
}
return (
);
}
```
### Use UI components
Use the `OpenAssistantButton` component for drop-in integration:
typescript  Copy
```typescript
import { OpenAssistantButton } from '@grafana/assistant';
export function MyComponent() {
return (
);
}
```
The button automatically hides when the Assistant is unavailable.
### Register page context
Automatically provide context to the Assistant based on the current URL:
typescript  Copy
```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  Copy
```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  Copy
```typescript
createAssistantContextItem('dashboard', {
dashboardUid: 'abc123',
dashboardTitle: 'My Dashboard',
});
```
### Data source context
Provide the active data source to scope Assistant suggestions:
typescript  Copy
```typescript
createAssistantContextItem('datasource', {
datasourceUid: 'prom-123',
});
```
### Structured data context
Provide arbitrary JSON to describe custom state or metadata:
typescript  Copy
```typescript
createAssistantContextItem('structured', {
data: {
// Any JSON-serializable data
name: 'Custom Context',
metadata: { ... }
}
})
```
## Try interactive examples
Explore interactive, working examples in Grafana Assistant:
1. Open **Grafana Assistant** from the main navigation
2. Click **For developers**
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:
- Open **Grafana Assistant** and click **For developers** to try interactive SDK examples
- View the [package on npm](https://www.npmjs.com/package/@grafana/assistant)
- Learn about [Grafana plugin development](/docs/grafana/latest/developers/plugins/)