AI Assistant

Connect the existing shared AI assistant to your board with createKanbanAiActions from @revolist/kanban. The adapter calls the native Kanban APIs; it does not introduce another card store, movement engine or UI.

Try it without a backend

Try the Kanban assistant

Choose a suggested request below. This scripted demo runs entirely in your browser, with no backend, model key or model calls. It recognizes only the suggested requests.

Try it: Read the cards, then choose “Move Research to In progress”. Cancel keeps Research in To do; submit again and Apply to move it. You can also preview a card rename.

The demo loads when visible.

Reset demo

Reset demo restores the original sample data and clears its conversation. To use your own prompts, follow the API-client setup guide.

What you will connect

Your existing Kanban board remains the data and behavior owner. The assistant plugin supplies the prompt/chat and approval UI. createKanbanAiActions connects the assistant to your actual KanbanPlugin instance. Your API client sends prompts and action descriptors to an authenticated application route, which returns a supported action.

If you do not have a working Kanban board yet, complete the first-app guide first. Use a local board without configured persistence to try updates and moves. Remote or persisted boards can use reads and selection; saved mutations need application-owned service actions. Replace id, title, status, priority and the todo/doing/done column IDs with your board’s actual mapping. Replace card-a with a real stable card ID.

Use compatible Pro and Kanban package versions that export AiAssistantPlugin and createKanbanAiActions. If an import is missing, check the installed versions; in a source checkout, rebuild stale generated packages and restart your app.

1. Include the assistant during grid initialization

Add AiAssistantPlugin alongside your existing Kanban and other plugins before mounting the grid. Keep your current configuration and source setup:

import { KanbanPlugin } from '@revolist/kanban';
import { AiAssistantPlugin } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/styles.css';
import '@revolist/kanban/styles.css';

grid.plugins = [KanbanPlugin, AiAssistantPlugin]; // Keep your other plugins too.
// Continue your existing Kanban configuration, source and mount setup.

Add a container alongside your existing grid in the application template:

<div id="kanban-assistant"></div>

2. Connect the active Kanban instance and your API client

Call this after the grid has mounted and the initial Kanban board is loaded. A mounted component alone does not guarantee that application data has finished loading.

import { KanbanPlugin, createKanbanAiActions } from '@revolist/kanban';
import {
  AiAssistantPlugin,
  type AiViewInterpreter,
} from '@revolist/revogrid-pro';
import { apiClient } from './api-client'; // Your existing authenticated client.

// Axios-style example: .data is the parsed assistant result.
const interpret: AiViewInterpreter = async (request, { signal }) => {
  const response = await apiClient.post('/api/ai/kanban', request, { signal });
  return response.data;
};

export async function connectKanbanAssistant(
  grid: HTMLRevoGridElement,
  host: HTMLElement,
  interpret: AiViewInterpreter,
) {
  const plugins = await grid.getPlugins();
  const kanban = plugins.find(
    (plugin): plugin is KanbanPlugin => plugin instanceof KanbanPlugin,
  );
  const assistant = plugins.find(
    (plugin): plugin is AiAssistantPlugin => plugin instanceof AiAssistantPlugin,
  );
  if (!kanban || !assistant) {
    throw new Error('Install KanbanPlugin and AiAssistantPlugin on this grid.');
  }
  if (!kanban.getConfig() || !kanban.getProjection()) {
    throw new Error('Load the Kanban board before connecting its assistant.');
  }

  grid.aiAssistant = {
    interpret,
    mountTo: host,
    fields: [], // Keep ordinary flat-grid fields and commands disabled.
    executor: {
      read: () => ({ sort: [] }),
      async apply() {
        throw new Error('Use native Kanban actions for this view.');
      },
    },
    actions: createKanbanAiActions(kanban, {
      read: { fields: ['id', 'title', 'status'], maxCards: 20 },
      select: {},
      update: { fields: { title: 'string', priority: 'number' } },
      move: { columns: ['todo', 'doing', 'done'] },
    }),
    ui: {
      mode: 'chat',
      suggestions: [
        'Read up to three cards',
        'Move card card-a to doing',
      ],
    },
  };

  return () => { grid.aiAssistant = undefined; };
}

// Call from your app after the existing Kanban board is ready.
const host = document.getElementById('kanban-assistant');
if (!host) throw new Error('Missing Kanban assistant container.');
const disconnectAssistant = await connectKanbanAssistant(grid, host, interpret);
// Call disconnectAssistant() when this application view unmounts.

grid is your existing grid element. apiClient and /api/ai/kanban are application-owned; replace the import path and route with your own. This example assumes an Axios-style client. If your client returns the parsed body directly, return that instead of response.data. Forward signal so Stop and disposal can cancel pending requests. Your client supplies its usual user session or bearer token and handles token refresh; provider keys stay on your backend.

interpret receives the prompt, permitted context and enabled action descriptors. It must resolve to one structured assistant result. See the request/response contract. createAiViewHttpInterpreter is an optional Fetch alternative.

The top-level fields: [] keeps this an action-only assistant. The adapter options separately allow native Kanban operations and disclose their schemas. Do not enable generic gridActions, dataActions or schemaActions against the product projection. Recreate the adapter when field/permission policies change. Cleanup disposes the assistant and cancels pending work without destroying your Kanban board.

3. Return native actions from your backend

Implement the example /api/ai/kanban route in your application. Installing the plugin does not create it. Authenticate the user, enforce your server-owned field/action policy and constrain your model to the approved action schemas from request.actions. The request’s top-level fields list is intentionally empty in this setup; native capabilities are described by their action descriptors. Browser descriptors do not grant server permissions.

For “Move card card-a to doing”, return this JSON body:

{
  "kind": "action",
  "name": "kanban.moveCards",
  "input": { "ids": ["card-a"], "columnProp": "doing" }
}

The client returns that object to the assistant, which validates it and displays a preview. Apply calls the existing native Kanban API; Cancel changes nothing. Use actual card IDs from your app. A read request can return { "kind": "action", "name": "kanban.readCards", "input": { "limit": 3 } } instead.

The backend guide explains the reference service and authentication. Replace its orders fixture metadata with your own approved board policy. Return the assistant result itself, rather than a provider response or HTTP-client wrapper. Read results appear locally in the assistant UI; sending them back to the model for a prose answer requires explicit evidence configuration.

4. Test the connection without a model

Replace the final connection call above with this deterministic interpreter. Do not run both connection calls at once:

const readThree: AiViewInterpreter = async () => ({
  kind: 'action',
  name: 'kanban.readCards',
  input: { limit: 3 },
});
const disconnectAssistant = await connectKanbanAssistant(grid, host, readThree);

Submit any prompt: the fixed interpreter always reads up to three permitted cards. Check that the prompt appears and the returned fields match your disclosure policy. This verifies the UI and native adapter without an HTTP route or model key. It does not test natural-language understanding.

Reconnect with your API-client interpreter, then submit the update example using a real record ID. Check Cancel first, then Apply and the native board result. For HTTP failures, check your route and user authentication. If the prompt is missing, check the host and installed plugin. If the board is not ready, wait for successful application data loading. For missing update/move actions, check whether the board has remote loading or persistence configured.

Supported actions

Use your board’s actual source fields and column IDs. Update fields support bounded strings, finite numbers and booleans. Identity, ordering, column and swimlane fields cannot be patched through kanban.updateCard; use kanban.moveCards for placement.

Action	Behavior	Input example
kanban.readCards	Read only explicitly disclosed scalar fields.	{ "ids": ["card-a"], "limit": 1 }
kanban.selectCards	Replace native selection; an empty list clears it.	{ "ids": ["card-a"] }
kanban.updateCard	Preview one card patch, then Apply or Cancel.	{ "id": "card-a", "patch": { "title": "Review release" } }
kanban.moveCards	Preview a batch move through native board rules.	{ "ids": ["card-a"], "columnProp": "doing" }

The table shows the input inside a typed action response. Your interpreter returns, for example, { kind: 'action', name: 'kanban.moveCards', input: { ids: ['card-a'], columnProp: 'doing' } }. It must choose an advertised action; the adapter validates the input again before execution.

On a board with a swimlane field, moves must also specify swimlaneId. Optional move.columns and move.swimlanes restrict destinations; omitting them allows the native destination catalog. Moves append cards using native rank ordering.

Permissions, approvals and history

Optional read.canRead, select.canSelect, update.canUpdate and move.canMove callbacks narrow your application policy. Read permission is also checked for explicitly targeted cards when configured. Native edit permissions, drag permissions, transitions, WIP policy and cancelable before-change events still apply. Edit and drag permissions remain separate.

Updates and moves show the existing shared preview with Apply and Cancel. Preparation does not change cards. Apply rechecks the board revision, permissions and cancellation; a stale preview must be requested again. WIP warnings appear in the move preview, while blocking WIP rules reject it.

Include HistoryPlugin in your board setup to record native changes. The existing Kanban history controls can undo them. To show Undo/Redo inside the assistant, connect AiAssistantConfig.actionHistory to that same installed History instance. See Kanban Undo and Redo and the shared assistant guide.

Keep this an action-only assistant configuration: use fields: [] and an executor that rejects flat-grid view commands, as shown in the connection example above. Kanban owns its projected rows, filtering and sorting; ordinary grid row/filter commands must not operate on that projection.

Disclosure and limits

Reads follow Kanban’s filter-visible loaded cards, including cards in collapsed columns or lanes. They exclude filtered-out cards and noninteractive placeholders; they are not a query over an entire remote dataset.

• Read results contain at most 50 cards and 16 KiB. Configure a smaller read.maxCards when appropriate.
• Selection and moves accept at most 100 explicit stable card IDs. Numeric and string IDs remain distinct.
• Patches accept only declared scalar fields; strings are limited to 500 characters. Previews are limited to 16 KiB.
• Results stay in the host UI by default. Sending selected evidence back to the model requires the separate answerFromAction opt-in and your backend’s evidence policy.

Prompt text and explicitly disclosed fields may contain business data. Your backend must enforce its own authentication, action/field policies and usage limits. Recognizing a client action descriptor does not authorize business-data access. The reference backend uses an orders fixture policy; replace it with your approved board policy for real cards.

Remote and persisted boards

Remote or persisted boards can use bounded reads and native selection. Built-in AI update/move actions are registered only for local boards without configured persistence, and this condition is checked again before Apply.

For saved business data, supply application-owned prepared actions through your existing service. That service owns authorization, versions, commits and any supported undo. See server-side saving and managed saving.

This initial adapter does not add card creation/deletion, search/filter commands, highlighting, column controls or a board-reload action.