Connect your first assistant

The assistant needs an interpret function: it receives the user’s prompt and permitted grid context, and returns a structured result describing what to do or say. Use your application’s existing API client to call your backend, keeping its authentication and error handling in one place.

1. Complete RevoGrid Pro installation and create a working grid.
2. Provide an authenticated backend route that returns the result described below. The backend guide includes a runnable reference service.
3. Connect your API client and add the assistant configuration to your existing grid. Keep your other plugins in the array.
4. Submit “Only Europe”, inspect the filter, then try “Sort by amount descending”.

Connect your existing API client

This example assumes an Axios-style client: post(url, body, options) returns an object whose data property is the parsed response body. apiClient is your application’s client, not a RevoGrid export. Use your real import path and adapt the call to its interface.

import {
  AdvanceFilterPlugin,
  AiAssistantPlugin,
  type AiViewInterpreter,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/styles.css';
import { apiClient } from './api-client'; // Your existing authenticated client.

const interpret: AiViewInterpreter = async (request, { signal }) => {
  const response = await apiClient.post('/api/ai/interpret', request, { signal });
  return response.data; // Return the assistant result, not the HTTP wrapper.
};

grid.columns = [
  { prop: 'amount', name: 'Amount', filter: 'number', sortable: true },
  { prop: 'region', name: 'Region', filter: 'string', sortable: true },
];
grid.filter = true;
grid.plugins = [AdvanceFilterPlugin, AiAssistantPlugin];
grid.aiAssistant = {
  interpret,
  exclude: ['internalNotes', 'customerEmail'],
  overrides: {
    amount: { operators: ['greaterThan', 'lessThan', 'equal'] },
    region: {
      description: 'Sales territory',
      allowedValues: ['Europe', 'Asia', 'North America'],
    },
  },
  ui: { suggestions: ['Show orders above 1000', 'Only Europe'] },
};

/api/ai/interpret is an example route you implement on your server. Its name is your choice; RevoGrid does not create the route or provide a hosted model. If your client already returns the parsed body, return that value directly instead of response.data.

What does interpret receive?

The plugin calls interpret(request, { signal }) when a user submits a prompt. You assign the function once; you do not send the function itself to the server.

request is an AiViewRequest from @revolist/revogrid-pro:

Property	Meaning
prompt	The user’s submitted text, such as “Sort by amount descending”.
fields	Disclosed field IDs, labels, types and permitted operators, rather than full column definitions.
view	The current disclosed filter and sort criteria.
locale, timeZone, now	Language/date context and a reference instant for interpreting requests.
actions, grid	Available action descriptors and projected grid context, when configured. Execution callbacks stay local.
samples, history	Row samples and previous conversation, only when explicitly enabled.
answerOnly, evidence	Present for an opted-in follow-up that asks for an answer from a completed action result.

The second argument contains an AbortSignal. Pass it to your API client so Stop, disposal and cancelled work can abort the request. Authentication is handled separately by your client; a user ID in this body is not a login credential. See data disclosure before enabling samples, memory or evidence.

What must interpret return?

Return a promise resolving to one complete assistant result. Your backend interprets the prompt and produces that result; your browser adapter extracts it from the HTTP response. The supported shapes are described by AiViewResponse from @revolist/revogrid-pro:

kind	Result
command	A supported filter/sort change or view reset.
action	A registered action name and its validated input.
answer	A message to display without changing the grid.
clarification	A message asking for more detail, with optional choices or suggestions.
unsupported	A message explaining that the request cannot be handled, with optional suggestions.

For “Sort by amount descending”, your route could return this JSON body:

{
  "kind": "command",
  "sort": {
    "mode": "replace",
    "items": [{ "field": "amount", "direction": "desc" }]
  }
}

A message-only result could be { "kind": "answer", "message": "You can sort Amount and Region." }.

Return the result object, rather than a JSON string, a Fetch Response, an Axios response wrapper or a raw model-provider response. AiViewInterpreter intentionally returns Promise<unknown> because external results must be checked at runtime. The assistant validates the result against its permitted fields and capabilities before executing it. Partial streamed output does not execute. Let request failures reject the promise so the assistant can report the error.

For a provider integration, use the backend response contract. Loading database rows is a separate integration.

Where are the user and authentication tokens?

Your existing API client should send your application’s normal session cookie or user bearer token, just as it does for other API calls. Keep its token-refresh and request-protection handling in that client. Your route validates the credential, identifies the user and checks their permissions.

The prompt tells the server what the user wants; authentication tells it who is asking. RevoGrid does not sign users in or issue tokens. Model provider credentials and the reference service’s private AI_ACCESS_TOKEN stay on the server. See backend authentication.

Optional alternative: the HTTP helper

If you do not have an API client, createAiViewHttpInterpreter supplies a small Fetch-based adapter for the same interpret contract:

import { createAiViewHttpInterpreter } from '@revolist/revogrid-pro';

const interpret = createAiViewHttpInterpreter('/api/ai/interpret');
// Use this function as grid.aiAssistant.interpret instead of your client adapter.

It posts the request as JSON, forwards the cancellation signal, rejects non-success HTTP responses and returns the parsed JSON body. It does not create your route, manage login or refresh tokens. With a same-origin URL, the browser sends applicable cookies using normal Fetch defaults.

For an application API that uses a user bearer token:

const interpret = createAiViewHttpInterpreter('/api/ai/interpret', {
  headers: () => ({
    Authorization: `Bearer ${getCurrentUserAccessToken()}`,
  }),
});

getCurrentUserAccessToken() is your application’s function. The headers callback reads the token on each request; your application owns acquiring and refreshing it. Never put a model provider key or private service token here. For cross-origin cookies, see transport configuration.

How fields and placement are configured

The plugin derives fields from your leaf columns. You do not need to maintain a second column list. exclude always takes precedence. overrides can supply aliases, descriptions, declared values and narrower operator permissions. Declared values are host-authored hints; the assistant never scans rows to discover them. Descriptions are bounded to 2,000 characters and declared values to 100 scalars per field.

A string column name becomes its label; a non-text header falls back to its property name. Filter families supply types and canonical operators. Unknown filter types receive no inferred filter permission. Explicit fields remains available for a stricter allowlist. Standalone controllers and servers can use createAiViewFields(columns, { exclude, overrides }) to derive their own authoritative policy.

By default, the prompt mounts in the grid’s header slot. Use mountTo for an application-owned toolbar. Replacing the configuration or removing the plugin disposes its UI and aborts pending work. Framework usage is demonstrated in the four framework examples. Vue uses :ai-assistant.prop.camel; the Angular demo supplies a directive for the plugin-defined property.

Next: Use the assistant.