Agent-driven grid with CopilotKit

In this tutorial, you will let an AI agent edit a Handsontable DataGrid through CopilotKit tools. You keep an ordinary grid that your app owns. The agent calls functions you register to write columns, data, and = formulas; HyperFormula computes the numbers in the browser; and one undo stack covers both the agent’s edits and the user’s.

Open in the demo runner

The grid above is a normal Handsontable instance. An agent builds the sheet, then edits one cell: it calls createSpreadsheet, then setCells. Below the grid, the panel titled “Agent tool calls” logs each call as it runs, and “What the agent sees” shows the read-only snapshot the agent reads before acting. Edit a cell yourself, then press Agent: undo — the same undo stack reverts your edit and the agent’s alike. Every = cell is computed by HyperFormula; the agent writes the formula, never the number.

Note: in this demo the agent’s calls come from a fixed script that stands in for the model, so there is no backend and no API key. The last section shows where a real agent plugs in.

Overview

CopilotKit connects an agent to a React app through two hooks. useFrontendTool registers a function the agent can call, with a Zod schema for its arguments. useAgentContext hands the agent a read-only view of your state, so it knows what it is editing. The agent runs in CopilotKit’s chat; your code decides what it can read and what it can do.

That makes the grid the opposite of a controlled component. Handsontable owns the data. The agent writes through the live instance, and your React state keeps only a read-only snapshot for the agent to read. Because every change — the agent’s and the user’s — goes through the one instance, Handsontable’s own undo covers both.

The agent writes columns, rows, and = formulas. The grid computes the numbers. The agent never does arithmetic.

This recipe is the tool-calling counterpart to the agent-driven grid with A2UI. There, the agent describes the grid in a declarative protocol and the client renders it. Here, the agent calls functions against a grid your app already owns. What this approach buys you is agent-driven undo: a tool can undo across both the agent’s and the user’s edits.

Difficulty: Intermediate Time: ~25 minutes Stack: React, CopilotKit 1.79 (v2 API), Handsontable, HyperFormula

What you’ll build

An instance-owned grid component that Handsontable renders and HyperFormula computes.
A set of grid operations with no knowledge of the agent, so one code path serves both the agent’s tools and any script or button you write.
A read-only snapshot of the sheet, exposed to the agent with useAgentContext.
Three agent tools — createSpreadsheet, setCells, and undo — registered with useFrontendTool.
A CopilotKit chat that drives all three.

Before you begin

This recipe assumes a React app. Install the dependencies:

1
npm install handsontable @handsontable/react-wrapper hyperformula @copilotkit/react-core zod

CopilotKit’s v2 API lives under the @copilotkit/react-core/v2 entry point. This recipe is written against @copilotkit/react-core 1.79. The provider, the chat component, useFrontendTool, and useAgentContext all import from that entry, and its stylesheet is @copilotkit/react-core/v2/styles.css.

Handsontable touches window, so render the grid on the client only. In the Next.js App Router, mark the file 'use client'; with a framework that renders on the server, load the grid through a client-only dynamic import.

The instance-owned grid

1
import { RefObject, memo } from 'react';
2
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4
import { HyperFormula } from 'hyperformula';
5
import 'handsontable/styles/handsontable.min.css';
6
import 'handsontable/styles/ht-theme-main.min.css';
7

8
registerAllModules();
9

10
export type GridProps = {
11
  // Lifted to the parent so the agent tools and the snapshot bridge can reach the live instance
12
  // (setDataAtCell, alter, getPlugin('undoRedo'), getSourceData, and so on).
13
  hotRef: RefObject<HotTableRef>;
14
  // Passed once, at mount, and never fed back. After this the grid owns its data: every later
15
  // change goes through the instance, not through this prop. See the memo note below.
16
  initialColumns: string[];
17
  initialData: (string | number)[][];
18
  themeName?: string;
19
  // Runs after any change that touches the source data, so the parent can re-snapshot for the agent.
20
  onMutate: () => void;
21
};
22

23
function GridImpl({ hotRef, initialColumns, initialData, themeName = 'ht-theme-main', onMutate }: GridProps) {
24
  return (
25
    <HotTable
26
      ref={hotRef}
27
      themeName={themeName}
28
      // Passed once, then left alone. All mutations go through the instance; the grid is the source
29
      // of truth for the data, and React keeps only a read-only snapshot (see the canvas in Step 3).
30
      data={initialData}
31
      colHeaders={initialColumns.length ? initialColumns : true}
32
      rowHeaders={true}
33
      height="auto"
34
      width="100%"
35
      stretchH="all"
36
      formulas={{ engine: HyperFormula }}
37
      licenseKey="non-commercial-and-evaluation"
38
      // Formula-safe interactive features: none of these reorder rows or columns, so the in-grid
39
      // formulas and the source-data snapshot stay correct.
40
      contextMenu={true}
41
      manualColumnResize={true}
42
      manualRowResize={true}
43
      // columnSorting, filters, dropdownMenu, manualRowMove, and manualColumnMove are off on purpose.
44
      // Reordering rewrites in-grid aggregate formulas: a sort turns a totals row's =SUM(D1:D3) into
45
      // =SUM(#REF!), and a manual row move silently mangles the range. See "Known limitations".
46
      afterChange={(_changes, source) => {
47
        if (source !== 'loadData') onMutate();
48
      }}
49
      afterCreateRow={onMutate}
50
      afterRemoveRow={onMutate}
51
      afterCreateCol={onMutate}
52
      afterRemoveCol={onMutate}
53
      afterUpdateData={onMutate}
54
    />
55
  );
56
}
57

58
// Memoized with referentially stable props so the parent's snapshot re-renders never re-render the
59
// grid. Without the memo, @handsontable/react-wrapper would re-apply the data prop through
60
// updateSettings on every render, overwriting the instance-owned data and resetting the undo
61
// stack. Keep the initial data in a ref and the handlers in useCallback so these props never change.
62
export const Grid = memo(GridImpl);

What’s happening: the grid takes its data once, through initialData, and never again. After mount, every change goes through the live instance, which the parent reaches with hotRef. formulas: { engine: HyperFormula } turns every cell that starts with = into a live formula. afterChange and the create and remove hooks call onMutate, so the parent can refresh its snapshot after any change, including one the user makes by hand.

Grid is wrapped in React.memo, and the memo is a correctness requirement, not an optimization. @handsontable/react-wrapper re-applies the data prop through updateSettings on every render, which would overwrite the instance-owned data and reset the undo stack. Keeping the component from re-rendering is how the grid gets to own its data while you still use the official React wrapper, so pass it only referentially stable props: a useRef for the initial data, and useCallback handlers.

Sorting, filtering, and row or column moving stay off. Those plugins work on visual indexes and rewrite the in-grid aggregate formulas — a sort turns a totals row’s =SUM(D1:D3) into =SUM(#REF!), and a manual row move silently mangles the range. See Known limitations.

1
import Handsontable from 'handsontable/base';
2

3
// Grid operations, with no knowledge of any agent framework. The scripted driver in the
4
// demo and the CopilotKit tools in Step 4 both call these functions, so a hand-written
5
// script and the agent drive the grid through one code path. Every function writes through
6
// the live instance, which is what keeps undo working across agent and user edits alike.
7

8
export type Cell = string | number;
9

10
// A model sometimes wraps a cell value in an object ({ value } or { formula }) even when the
11
// schema asks for a string or a number. Coerce anything to a primitive before it reaches a cell.
12
export function toCell(value: unknown): Cell {
13
  if (value == null) return '';
14
  if (typeof value === 'number' || typeof value === 'string') return value;
15

16
  if (typeof value === 'object') {
17
    const object = value as Record<string, unknown>;
18
    const picked = object.formula ?? object.value ?? object.text;
19

20
    if (typeof picked === 'number' || typeof picked === 'string') return picked;
21
  }
22

23
  return String(value);
24
}
25

26
export function normalizeRows(rows: unknown): Cell[][] {
27
  if (!Array.isArray(rows)) return [];
28

29
  return rows.map((row) => (Array.isArray(row) ? row.map(toCell) : [toCell(row)]));
30
}
31

32
// Build or replace the whole sheet. Clone the rows first: Handsontable binds to the array by
33
// reference, so a shared array would let later edits mutate the caller's copy.
34
export function createSpreadsheet(hot: Handsontable.Core, columns: string[], rows: unknown): void {
35
  hot.updateData(structuredClone(normalizeRows(rows)));
36
  hot.updateSettings({ colHeaders: columns.length ? columns : true });
37
}
38

39
// Set one or more cells. The agent addresses cells by physical (source) coordinates, so translate
40
// each to a visual coordinate and write with setDataAtCell. That path recomputes HyperFormula and
41
// records the change for undo; setSourceDataAtCell does neither, so it is not used here. Grow the
42
// grid first when the agent addresses a cell past the current bounds.
43
export function setCells(hot: Handsontable.Core, cells: { row: number; col: number; value: Cell }[]): void {
44
  if (cells.length === 0) return;
45

46
  hot.batch(() => {
47
    const maxRow = Math.max(...cells.map((cell) => cell.row));
48
    const maxCol = Math.max(...cells.map((cell) => cell.col));
49

50
    const sourceCols = hot.countSourceCols();
51

52
    if (maxCol >= sourceCols) {
53
      const add = maxCol - sourceCols + 1;
54

55
      if (sourceCols === 0) hot.alter('insert_col_start', 0, add);
56
      else hot.alter('insert_col_end', hot.countCols() - 1, add);
57
    }
58

59
    const sourceRows = hot.countSourceRows();
60

61
    if (maxRow >= sourceRows) {
62
      const add = maxRow - sourceRows + 1;
63

64
      if (sourceRows === 0) hot.alter('insert_row_above', 0, add);
65
      else hot.alter('insert_row_below', hot.countRows() - 1, add);
66
    }
67

68
    cells.forEach((cell) => {
69
      const visualRow = hot.toVisualRow(cell.row);
70
      const visualCol = hot.toVisualColumn(cell.col);
71

72
      if (typeof visualRow === 'number' && visualRow >= 0 && typeof visualCol === 'number' && visualCol >= 0) {
73
        hot.setDataAtCell(visualRow, visualCol, toCell(cell.value));
74
      }
75
    });
76
  });
77
}
78

79
// Append a labeled column to the right of the sheet.
80
export function addColumn(hot: Handsontable.Core, name: string): void {
81
  const headers = (hot.getColHeader() as (string | number)[]).map(String);
82

83
  hot.alter('insert_col_end', hot.countCols() - 1, 1);
84
  hot.updateSettings({ colHeaders: [...headers, name] });
85
}
86

87
// Undo the last change. It spans both agent and user edits, because every change goes through the
88
// instance. undo and redo live on the UndoRedo plugin, not on the core -- hot.undo() does not exist.
89
export function undo(hot: Handsontable.Core): boolean {
90
  const plugin = hot.getPlugin('undoRedo');
91

92
  if (!plugin.isUndoAvailable()) return false;
93

94
  plugin.undo();
95

96
  return true;
97
}

What’s happening: these functions take a Handsontable instance and change it. They know nothing about CopilotKit, so the demo’s script and the agent’s tools call the same code. Three details matter:

setDataAtCell, not setSourceDataAtCell. The source-data path skips the edit pipeline, so HyperFormula would not recompute and the change would not enter the undo stack. setDataAtCell takes visual coordinates, so each physical coordinate the agent sends is translated with toVisualRow and toVisualColumn.
alter actions are directional. The valid actions are insert_row_above, insert_row_below, insert_col_start, insert_col_end, remove_row, and remove_col. There is no bare insert_row.
undo lives on the plugin. Call hot.getPlugin('undoRedo').undo(). There is no hot.undo() on the typed core.

A model sometimes wraps a value in an object even when the schema asks for a string or a number, so toCell coerces anything to a primitive before it reaches a cell.

Expose the sheet to the agent

Hold a read-only snapshot in React state and refresh it on every change. useAgentContext hands that snapshot to the agent, with a description of what it is and how to address it:

1
const [mirror, setMirror] = useState<{ columns: string[]; data: Cell[][] }>({ columns: [], data: [] });
2

3
const getHot = useCallback(() => hotRef.current?.hotInstance ?? null, []);
4

5
const snapshot = useCallback(() => {
6
  const hot = getHot();
7
  if (!hot) return;
8
  setMirror({
9
    columns: (hot.getColHeader() as (string | number)[]).map(String),
10
    data: structuredClone(hot.getSourceData()) as Cell[][],
11
  });
12
}, [getHot]);
13

14
// Take the first snapshot after mount. The initial load fires afterChange with source
15
// 'loadData', which Grid skips, so nothing else fills the mirror until the first change.
16
useEffect(() => {
17
  snapshot();
18
}, [snapshot]);
19

20
const context = useMemo(
21
  () => ({
22
    description:
23
      "The spreadsheet the user sees. 'columns' are the headers, 'data' is the rows; a cell " +
24
      "starting with '=' is a live formula. Tools take 0-based row and col indices into the data " +
25
      '(first data row = 0). Formulas use A1 style, where the first data row is row 1. Write ' +
26
      'formulas as strings that start with =, and never compute the numbers yourself.',
27
    value: mirror,
28
  }),
29
  [mirror],
30
);
31
useAgentContext(context);

What’s happening: the snapshot reads getSourceData, so the agent sees the formulas the cells hold, not only the computed values. Pass useAgentContext a memoized value object. A fresh object literal on every render would make its effect run in a loop. Because snapshot runs on every change, the agent’s view stays current after a user edit as well as an agent edit.

The useEffect matters: without it, the agent sees an empty sheet until the first change. The initial load is not a “change” — the only afterChange it fires has source 'loadData', which Grid skips on purpose, and afterUpdateData does not fire on first load. The parent’s effect runs after HotTable has created its instance, so getHot() returns the live grid there.

Give the agent tools

Each tool pairs a Zod schema with a handler that calls one of the operations from Step 2, then refreshes the snapshot:

1
useFrontendTool({
2
  name: 'createSpreadsheet',
3
  description: 'Create or replace the whole sheet in one call, formulas included. Replacing the sheet clears the undo history.',
4
  parameters: z.object({
5
    columns: z.array(z.string()).describe('Column header labels'),
6
    rows: z.array(z.array(z.union([z.string(), z.number()]))).describe(
7
      "Rows aligned to columns; put '='-prefixed formula strings wherever a value is computed",
8
    ),
9
  }),
10
  handler: async ({ columns, rows }) => {
11
    const hot = getHot();
12
    if (!hot) return 'The grid is not ready yet';
13
    createSpreadsheet(hot, columns, rows);
14
    snapshot();
15
    return `Built a ${columns.length}-column sheet`;
16
  },
17
}, [getHot, snapshot]);
18

19
useFrontendTool({
20
  name: 'setCells',
21
  description: "Set one or more cells. A value may be a number, text, or a '='-prefixed formula.",
22
  parameters: z.object({
23
    cells: z.array(
24
      z.object({ row: z.number(), col: z.number(), value: z.union([z.string(), z.number()]) }),
25
    ),
26
  }),
27
  handler: async ({ cells }) => {
28
    const hot = getHot();
29
    if (!hot) return 'The grid is not ready yet';
30
    setCells(hot, cells);
31
    snapshot();
32
    return `Updated ${cells.length} cell(s)`;
33
  },
34
}, [getHot, snapshot]);
35

36
useFrontendTool({
37
  name: 'undo',
38
  description: 'Undo the last change. It spans both agent and user edits.',
39
  parameters: z.object({}),
40
  handler: async () => {
41
    const hot = getHot();
42
    if (!hot) return 'The grid is not ready yet';
43
    const reverted = undo(hot);
44
    snapshot();
45
    return reverted ? 'Undid the last change' : 'Nothing to undo';
46
  },
47
}, [getHot, snapshot]);

What’s happening: the handler returns a short string, which the agent reads as the result of its call. The schema is the contract the model fills, so its field descriptions double as instructions.

Keep each handler idempotent, so a repeated call does no harm. createSpreadsheet and setCells write the same result twice over; undo does not, because a second call reverts a second step. If your setup ever dispatches a tool call more than once, guard undo — ignore a repeat that arrives within a second of the previous one, or dedupe by the tool-call id.

Wire it together

The canvas holds the hotRef, registers the context and the tools, renders the grid, and adds the chat:

1
'use client';
2
import { useCallback, useMemo, useRef, useState } from 'react';
3
import { CopilotSidebar, useAgentContext, useFrontendTool } from '@copilotkit/react-core/v2';
4
import { type HotTableRef } from '@handsontable/react-wrapper';
5
import { z } from 'zod';
6
import { Grid } from './Grid';
7
import { createSpreadsheet, setCells, undo, type Cell } from './operations';
8

9
export function SpreadsheetCanvas() {
10
  const hotRef = useRef<HotTableRef>(null);
11
  // A blank starter, passed once, so the instance exists before the agent builds anything.
12
  const initialData = useRef<Cell[][]>(Array.from({ length: 5 }, () => Array(5).fill('')));
13
  const initialColumns = useRef<string[]>([]);
14

15
  // ...snapshot, context, and the three tools from Steps 3 and 4...
16

17
  return (
18
    <>
19
      <Grid
20
        hotRef={hotRef}
21
        initialColumns={initialColumns.current}
22
        initialData={initialData.current}
23
        onMutate={snapshot}
24
      />
25
      <CopilotSidebar />
26
    </>
27
  );
28
}

Wrap the app in the CopilotKit provider once, above the canvas. On Copilot Cloud a public key is all it needs, and there is no self-hosted route to run:

1
import { CopilotKit } from '@copilotkit/react-core/v2';
2
import '@copilotkit/react-core/v2/styles.css';
3

4
export default function RootLayout({ children }: { children: React.ReactNode }) {
5
  return (
6
    <html lang="en">
7
      <body>
8
        <CopilotKit publicApiKey={process.env.NEXT_PUBLIC_COPILOTKIT_API_KEY!}>
9
          {children}
10
        </CopilotKit>
11
      </body>
12
    </html>
13
  );
14
}

Ask the chat for “a three-month budget with income, expenses, and a net row”, then “raise February groceries to 900”, then “undo that”. The agent calls createSpreadsheet, then setCells, then undo, and HyperFormula recomputes after each.

Connect a real agent

The demo runs a script in place of the model. To drive the grid from a real agent, keep the grid, the operations, the context, and the tools, and give the provider a backend:

Copilot Cloud is the shortest path. Create a free key at cloud.copilotkit.ai, set it as publicApiKey on the provider, and pick a model in the dashboard. The tools and context you registered are sent to the model as-is.
A self-hosted runtime keeps the model call on your own server. Point the provider at your runtime endpoint instead of a public key, and hold the model’s API key there.

Either way, the model call and its key belong on a server or on Cloud, never in the client. The browser only decides what the agent may read and do, through the context and the tools.

Match your design system

The grid uses the default ht-theme-main theme, which adapts to light and dark. Swap the imported theme stylesheet, or register a custom theme that maps your design tokens to Handsontable’s, and the agent’s grid looks like every other grid in your product.

CopilotKit’s chat is themed separately. Its v2 stylesheet ships light and dark styles; import it once, as the provider snippet does.

Known limitations

The agent reads the sheet through the snapshot that useAgentContext exposes. It learns about a user’s edit on its next turn, once the snapshot has refreshed, not the instant the user types.
Sorting, filtering, and row or column moving all change what the in-grid aggregate formulas cover, so this recipe leaves them off and lets the agent own the shape of the sheet. Per-row relative formulas such as =B1-C1 survive a reorder; ranges and totals such as =SUM(D1:D3) do not. For column totals that survive sorting, compute them with the ColumnSummary plugin instead of an in-grid =SUM cell.
createSpreadsheet replaces the sheet through updateData, which clears the undo history — the recorded steps describe the dataset it replaced. Undo spans agent and user edits within a sheet, but it cannot restore the sheet that createSpreadsheet overwrote.
Keep tool handlers idempotent, and guard a non-idempotent action such as undo, so a tool call that arrives twice cannot revert two steps.

Agent-driven grid with A2UI

Formula calculation

Theme customization

What you learned

How useFrontendTool registers a function the agent can call, and how useAgentContext gives the agent a read-only view of the grid.
How to let Handsontable own its data and keep only a read-only snapshot in React, so the agent’s edits and the user’s share one undo stack.
How to give an agent a grid that computes: the agent writes formulas, HyperFormula evaluates them, and the agent never does arithmetic.
Why setDataAtCell keeps formulas and undo working where setSourceDataAtCell would not, and why the grid must be memoized.
Why sorting, filtering, and row moving stay off when the grid holds formulas the agent depends on.

Next steps

Add a tool for a structural edit, such as addColumn or insertRow, by copying the useFrontendTool pattern and calling one more operation.
Expose the selected cell in the context, so the user can ask the agent about “this cell”.
Compare with the agent-driven grid with A2UI, where the agent describes the grid instead of calling tools against it.