Agent-driven grid with A2UI

In this tutorial, you will let an AI agent describe a grid in A2UI JSON and have Handsontable render it. You will build a custom A2UI component, HotGrid, that evaluates agent-authored formulas with HyperFormula in the browser, applies the agent’s follow-up updates in place, and sends the user’s edits back to the agent.

View the code · Open in the demo runner

The grid above is not hand-coded in the page. An agent described it in A2UI JSON: a HotGrid component from a custom catalog, bound to /rows in the surface data model. HotGrid renders it with Handsontable and evaluates the = cells with HyperFormula, in the browser. Edit a cell and click Send to agent: the action carries both the formulas (rows) and the computed numbers (values) back to the agent, and the agent answers with new messages. Here it adds a volume-discount line to the rows you sent, so your edits stay, and every reply is appended to the list under the grid. The two panels below the grid show the agent-to-client message stream and the client-to-agent actions.

Note: in this demo the agent’s messages come from a fixed script and a small reply function 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

A2UI is an open protocol, led by Google, in which an agent sends a declarative description of a user interface instead of code. The description names components from a catalog that the client controls, so the agent can only render what you allow. The client keeps a data model per surface, components bind to paths in it, and user actions carry parts of it back to the agent.

The A2UI basic catalog has no table or grid component. This recipe adds one. HotGrid is a catalog component whose props are a Zod schema (the API the agent sees) and whose implementation mounts Handsontable with the HyperFormula engine. The agent writes columns, rows, and = formulas. The grid computes the numbers. The agent never does arithmetic.

Difficulty: Intermediate Time: ~25 minutes Stack: React, @a2ui/react 0.12 (A2UI v0.9 protocol), Handsontable, HyperFormula

What You’ll Build

A HotGrid A2UI component with a typed API: column labels, optional cell types, rows bound to the data model, and a values binding for computed results.
A catalog that contains the A2UI basic components plus HotGrid, which the agent selects by id.
A page that feeds agent messages to the A2UI message processor, renders the surface, forwards every user action to a reply function that stands in for the model, and logs both directions.
A second message script in which the agent keeps editing the grid it already rendered, one cell at a time.

Before you begin

This recipe assumes a React app built with Vite. Install the dependencies:

1
npm install handsontable hyperformula @a2ui/react @a2ui/web_core zod@3

@a2ui/react declares a peer dependency on Zod 3, so pin that major.

Define the HotGrid component

1
import { useEffect, useRef } from 'react';
2
import { z } from 'zod';
3
import { CommonSchemas } from '@a2ui/web_core/v0_9';
4
import { createComponentImplementation } from '@a2ui/react/v0_9';
5
import Handsontable from 'handsontable/base';
6
import { registerAllModules } from 'handsontable/registry';
7
import { HyperFormula } from 'hyperformula';
8
import 'handsontable/styles/handsontable.min.css';
9
import 'handsontable/styles/ht-theme-main.min.css';
10
import { currentMode, onModeChange, type Mode } from './theme';
11

12
registerAllModules();
13

14
type Cell = string | number | boolean | null;
15
const themeFor = (mode: Mode) => (mode === 'dark' ? 'ht-theme-main-dark' : 'ht-theme-main');
16
const cellSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
17

18
// 1. The component API: what the agent is allowed to send.
19
//    `rows` and `values` accept a literal 2D array or a `{ path }` binding into the
20
//    surface data model. Cells that start with "=" are HyperFormula formulas.
21
export const HotGridApi = {
22
  name: 'HotGrid',
23
  schema: z
24
    .object({
25
      accessibility: CommonSchemas.AccessibilityAttributes.optional(),
26
      weight: z.number().optional(),
27
      columns: CommonSchemas.DynamicStringList.describe('Column header labels.'),
28
      columnTypes: CommonSchemas.DynamicStringList.optional().describe(
29
        'Handsontable cell type per column, in column order: "text", "numeric", "checkbox" or "date". Defaults to text.',
30
      ),
31
      rows: z
32
        .union([z.array(z.array(cellSchema)), CommonSchemas.DataBinding])
33
        .describe('Source cells. A string starting with "=" is a formula, evaluated by HyperFormula in the browser.'),
34
      values: z
35
        .union([z.array(z.array(cellSchema)), CommonSchemas.DataBinding])
36
        .optional()
37
        .describe('Computed cell values, written back by the grid after every edit. Bind it to a path so an action can send it to the agent.'),
38
      readOnly: CommonSchemas.DynamicBoolean.optional(),
39
      height: z.number().optional().describe('Grid height in pixels. Defaults to 260.'),
40
    })
41
    .strict(),
42
};
43

44
// 2. The React implementation. The generic binder resolves `{ path }` bindings before
45
//    render and injects `setRows` / `setValues` setters for two-way binding.
46
export const HotGrid = createComponentImplementation(HotGridApi, ({ props }) => {
47
  const containerRef = useRef<HTMLDivElement>(null);
48
  const hotRef = useRef<Handsontable | null>(null);
49
  const propsRef = useRef(props);
50
  propsRef.current = props;
51

52
  const rows = (Array.isArray(props.rows) ? props.rows : []) as Cell[][];
53
  const rowsKey = JSON.stringify(rows);
54
  // What the grid last wrote to the data model. When `rows` comes back equal to
55
  // it, the change is our own echo and the grid must not be reloaded.
56
  const lastSyncedKey = useRef<string | null>(null);
57

58
  // Push the grid's state into the A2UI data model. `rows` keeps the formulas,
59
  // `values` holds what HyperFormula computed, so the agent can read either.
60
  const syncToDataModel = () => {
61
    const hot = hotRef.current;
62
    if (!hot) return;
63
    const source = hot.getSourceData() as Cell[][];
64
    lastSyncedKey.current = JSON.stringify(source);
65
    propsRef.current.setRows?.(source);
66
    propsRef.current.setValues?.(hot.getData() as Cell[][]);
67
  };
68

69
  // Mount Handsontable once. The grid owns its data after this.
70
  useEffect(() => {
71
    if (!containerRef.current) return;
72
    const hot = new Handsontable(containerRef.current, {
73
      data: rows.map((r) => [...r]),
74
      colHeaders: props.columns,
75
      columns: props.columnTypes?.map((type) => ({ type: String(type) })),
76
      rowHeaders: true,
77
      themeName: themeFor(currentMode()),
78
      height: props.height ?? 260,
79
      stretchH: 'all',
80
      readOnly: props.readOnly ?? false,
81
      formulas: { engine: HyperFormula },
82
      // Structural changes are off on purpose. Sorting, filtering and row
83
      // moving break aggregate formulas such as =SUM(D1:D4) that live in the
84
      // grid, and inserting or removing rows or columns shifts the ranges those
85
      // formulas cover. That covers every path: the context menu, a paste that
86
      // is taller than the grid, and dragging the fill handle past the last row.
87
      // The user edits values; the agent owns the shape of the sheet and
88
      // rewrites the formulas when it adds or removes rows.
89
      columnSorting: false,
90
      filters: false,
91
      manualRowMove: false,
92
      allowInsertRow: false,
93
      allowRemoveRow: false,
94
      allowInsertColumn: false,
95
      allowRemoveColumn: false,
96
      fillHandle: { autoInsertRow: false },
97
      contextMenu: ['undo', 'redo'],
98
      afterChange: (_changes, source) => {
99
        if (source !== 'loadData' && source !== 'updateData') syncToDataModel();
100
      },
101
      licenseKey: 'non-commercial-and-evaluation',
102
    });
103
    hotRef.current = hot;
104
    // Publish the initial computed values so `values` is never empty.
105
    propsRef.current.setValues?.(hot.getData() as Cell[][]);
106
    // Follow the page's light/dark mode.
107
    const unsubscribe = onModeChange((mode) => hot.useTheme(themeFor(mode)));
108

109
    return () => {
110
      unsubscribe();
111
      hot.destroy();
112
      hotRef.current = null;
113
    };
114
    // eslint-disable-next-line react-hooks/exhaustive-deps
115
  }, []);
116

117
  // The agent changed `rows` (a full replacement or a patch to one path):
118
  // load the new cells into the existing grid instead of rebuilding it.
119
  useEffect(() => {
120
    const hot = hotRef.current;
121
    if (!hot || rowsKey === lastSyncedKey.current) return;
122
    hot.updateData(rows.map((r) => [...r]));
123
    propsRef.current.setValues?.(hot.getData() as Cell[][]);
124
    // eslint-disable-next-line react-hooks/exhaustive-deps
125
  }, [rowsKey]);
126

127
  useEffect(() => {
128
    hotRef.current?.updateSettings({
129
      colHeaders: props.columns,
130
      columns: props.columnTypes?.map((type) => ({ type: String(type) })),
131
      readOnly: props.readOnly ?? false,
132
    });
133
    // eslint-disable-next-line react-hooks/exhaustive-deps
134
  }, [JSON.stringify(props.columns), JSON.stringify(props.columnTypes), props.readOnly]);
135

136
  return <div ref={containerRef} />;
137
});

What’s happening: the file has two halves. HotGridApi is the contract: a name and a Zod schema. createComponentImplementation pairs that contract with a React function and returns a component the catalog can register.

The schema uses the common A2UI types where they exist, so the agent gets the same binding rules as the basic catalog:

1
columns: CommonSchemas.DynamicStringList,
2
rows: z.union([z.array(z.array(cellSchema)), CommonSchemas.DataBinding]),
3
values: z.union([z.array(z.array(cellSchema)), CommonSchemas.DataBinding]).optional(),
4
readOnly: CommonSchemas.DynamicBoolean.optional(),

A DynamicStringList accepts a literal array or a { path } into the data model. rows and values do the same for a 2D array of cells. Before the React function runs, the A2UI generic binder resolves every { path } to its current value, and for each bound prop it injects a setter: props.setRows and props.setValues. Calling a setter writes to the data model, which is how the grid reports its state back.

Why DynamicStringList and not z.array(z.string()): the binder treats a plain array of strings as a list of child component ids and tries to resolve each one as a component. DynamicStringList is the A2UI type for an ordinary list of strings.

The React function mounts Handsontable once and never rebuilds it:

1
const hot = new Handsontable(containerRef.current, {
2
  data: rows.map((r) => [...r]),
3
  colHeaders: props.columns,
4
  columns: props.columnTypes?.map((type) => ({ type: String(type) })),
5
  formulas: { engine: HyperFormula },
6
  columnSorting: false,
7
  filters: false,
8
  manualRowMove: false,
9
  afterChange: (_changes, source) => {
10
    if (source !== 'loadData' && source !== 'updateData') syncToDataModel();
11
  },
12
  // ...
13
});

formulas: { engine: HyperFormula } turns every cell that starts with = into a live formula. After each user edit, syncToDataModel writes two things: getSourceData() (the cells with their formulas intact) into rows, and getData() (the computed values) into values. The agent can read whichever it needs.

Light and dark mode: the component passes themeName at construction and calls useTheme() whenever the page’s mode changes, switching between ht-theme-main and ht-theme-main-dark. The mode comes from a small theme.ts module that reads a ?theme= query parameter, a postMessage from the embedding page, or the OS preference, in that order, and forces the page’s color-scheme so the A2UI components and the grid agree. demos.handsontable.com’s embed wrapper speaks the same message protocol, which is how the demos on this page follow the docs theme.

1
// Light/dark mode for the page. Three sources, in priority order:
2
// 1. `?theme=light|dark` in the URL.
3
// 2. A message from the embedding page. demos.handsontable.com's embed wrapper
4
//    speaks this protocol: the iframe posts `{ source, ready: true }` to its
5
//    parent and the parent replies with `{ source, mode }`.
6
// 3. The OS preference (`prefers-color-scheme`).
7
export type Mode = 'light' | 'dark';
8

9
const SOURCE = 'hot-runner-scheme';
10
const media = window.matchMedia('(prefers-color-scheme: dark)');
11
const listeners = new Set<(mode: Mode) => void>();
12

13
const asMode = (value: unknown): Mode | null => (value === 'light' || value === 'dark' ? value : null);
14
let forced: Mode | null = asMode(new URLSearchParams(window.location.search).get('theme'));
15

16
export const currentMode = (): Mode => forced ?? (media.matches ? 'dark' : 'light');
17

18
export const onModeChange = (listener: (mode: Mode) => void) => {
19
  listeners.add(listener);
20
  return () => listeners.delete(listener);
21
};
22

23
const apply = () => {
24
  const mode = currentMode();
25
  // Forces every `light-dark()` color on the page, including the A2UI
26
  // components, to the chosen side.
27
  document.documentElement.style.colorScheme = mode;
28
  document.documentElement.dataset.mode = mode;
29
  listeners.forEach((listener) => listener(mode));
30
};
31

32
media.addEventListener('change', apply);
33
window.addEventListener('message', (event: MessageEvent) => {
34
  const data = event.data as { source?: string; mode?: string } | null;
35
  if (!data || data.source !== SOURCE || typeof data.mode !== 'string') return;
36
  forced = asMode(data.mode);
37
  apply();
38
});
39
apply();

Why structural changes are off: sorting, filtering, and row moving operate on visual indexes and rewrite in-grid aggregate formulas such as =SUM(D1:D4), so an agent-authored total would silently change. Inserting or removing rows shifts the ranges those formulas cover, so a line added below the last item would fall outside the total. The component therefore turns those plugins off, sets allowInsertRow, allowRemoveRow, allowInsertColumn, and allowRemoveColumn to false so that a paste taller than the grid or a fill-handle drag past the last row cannot add rows either, and limits the context menu to undo and redo. The user edits values; the agent owns the shape of the sheet and rewrites the formulas when it adds or removes rows, as the reply in Step 5 does.

Register a catalog

1
import { Catalog } from '@a2ui/web_core/v0_9';
2
import { basicCatalog } from '@a2ui/react/v0_9';
3
import { HotGrid } from './HotGrid';
4

5
// A custom catalog: everything from the A2UI basic catalog, plus HotGrid.
6
// The agent selects it by this id in `createSurface`.
7
export const CATALOG_ID = 'https://handsontable.com/a2ui/catalogs/hot-grid/v0_9';
8

9
export const hotCatalog = new Catalog(
10
  CATALOG_ID,
11
  '0.9',
12
  [...basicCatalog.components.values(), HotGrid],
13
  [...basicCatalog.functions.values()],
14
  basicCatalog.themeSchema,
15
);

What’s happening: a Catalog is an id, a protocol version, and the components and functions it contains. This one copies everything from the basic catalog that ships with @a2ui/react and adds HotGrid. The id is a string the agent quotes in createSurface; by convention it looks like a URL, but nothing is fetched from it.

Keep the id stable. Once a surface is created with a catalog id, that id is fixed for the surface’s lifetime.

Process messages and render the surface

1
import { useEffect, useRef, useState } from 'react';
2
import { createRoot } from 'react-dom/client';
3
import { MessageProcessor, type ActionPayload, type ProcessableMessage, type SurfaceModel } from '@a2ui/web_core/v0_9';
4
import { A2uiSurface, type ReactComponentImplementation } from '@a2ui/react/v0_9';
5
import { hotCatalog } from './catalog';
6
import { agentMessages, replyTo } from './agentMessages';
7
import './theme';
8
import './styles.css';
9

10
const STREAM_DELAY_MS = 900;
11
// createSurface + updateComponents + the first updateDataModel.
12
const OPENING_MESSAGES = 3;
13
const AGENT_THINKING_MS = 1200;
14

15
const App = () => {
16
  const [actions, setActions] = useState<ActionPayload[]>([]);
17
  const [sent, setSent] = useState(0);
18
  // Every message the agent has sent so far, in order, for the stream panel.
19
  const [stream, setStream] = useState<ProcessableMessage[]>([]);
20
  const [surfaces, setSurfaces] = useState<SurfaceModel<ReactComponentImplementation>[]>([]);
21

22
  // The processor turns agent messages into surface state. The second argument
23
  // receives every action a user triggers; a real app forwards it to the agent.
24
  const processorRef = useRef<MessageProcessor<ReactComponentImplementation> | null>(null);
25
  if (!processorRef.current) {
26
    processorRef.current = new MessageProcessor<ReactComponentImplementation>([hotCatalog], (action) => {
27
      setActions((prev) => [action, ...prev]);
28
      // The agent answers the action. `replyTo` stands in for the model call.
29
      setTimeout(() => {
30
        const reply = replyTo(action);
31
        processorRef.current?.processMessages(reply);
32
        setStream((prev) => [...prev, ...reply]);
33
      }, AGENT_THINKING_MS);
34
    });
35
  }
36
  const processor = processorRef.current;
37

38
  useEffect(() => {
39
    const sync = () => setSurfaces(Array.from(processor.model.surfacesMap.values()));
40
    const created = processor.onSurfaceCreated(sync);
41
    const deleted = processor.onSurfaceDeleted(sync);
42
    return () => {
43
      created.unsubscribe();
44
      deleted.unsubscribe();
45
    };
46
  }, [processor]);
47

48
  // Replay the agent's messages. The three that open the surface (create it,
49
  // define the components, fill the data model) arrive together, the way a
50
  // model's first response does. Any later messages are paced out so the
51
  // agent's follow-up edits are visible one at a time.
52
  useEffect(() => {
53
    if (sent >= agentMessages.length) return;
54
    const batch = sent === 0 ? agentMessages.slice(0, OPENING_MESSAGES) : [agentMessages[sent]];
55
    const timer = setTimeout(() => {
56
      processor.processMessages(batch);
57
      setStream((prev) => [...prev, ...batch]);
58
      setSent(sent + batch.length);
59
    }, sent === 0 ? 0 : STREAM_DELAY_MS);
60
    return () => clearTimeout(timer);
61
  }, [sent, processor]);
62

63
  const latestAction = actions[0];
64
  const latestValues = latestAction?.context?.values as unknown[][] | undefined;
65

66
  return (
67
    <main className="demo">
68
      <section className="surface-host">
69
        {surfaces.length === 0 && <p className="muted">Waiting for the agent…</p>}
70
        {surfaces.map((surface) => (
71
          <A2uiSurface key={surface.id} surface={surface} />
72
        ))}
73
      </section>
74

75
      <section className="panels">
76
        <div className="panel">
77
          <h3>
78
            Agent → client <span className="pill">{stream.length} messages</span>
79
          </h3>
80
          <ol className="stream">
81
            {stream.map((m, i) => (
82
              <li key={i}>
83
                <details>
84
                  <summary>{Object.keys(m).filter((k) => k !== 'version')[0]}</summary>
85
                  <pre>{JSON.stringify(m, null, 2)}</pre>
86
                </details>
87
              </li>
88
            ))}
89
          </ol>
90
        </div>
91
        <div className="panel">
92
          <h3>
93
            Client → agent <span className="pill">{actions.length} actions</span>
94
          </h3>
95
          {!latestAction && <p className="muted">Click a button in the surface to dispatch an action.</p>}
96
          {latestValues && (
97
            <p>
98
              Grand total the agent will receive:{' '}
99
              <strong>{String(latestValues[latestValues.length - 1]?.[3])}</strong>
100
            </p>
101
          )}
102
          <ol className="stream">
103
            {actions.map((a, i) => (
104
              <li key={a.timestamp + i}>
105
                <details>
106
                  <summary>{a.name}</summary>
107
                  <pre>{JSON.stringify(a, null, 2)}</pre>
108
                </details>
109
              </li>
110
            ))}
111
          </ol>
112
        </div>
113
      </section>
114
    </main>
115
  );
116
};
117

118
createRoot(document.getElementById('root')!).render(<App />);

What’s happening: MessageProcessor is the A2UI client runtime. It takes the catalogs it may render from and an action handler. Every message from the agent goes through processMessages, which creates or updates surfaces. The page subscribes to onSurfaceCreated and onSurfaceDeleted, keeps the surface list in React state, and renders each one with A2uiSurface.

The action handler receives an ActionPayload each time the user triggers an action in the surface: the action name, the surface and component ids, a timestamp, and the resolved context. The demo’s handler logs the payload, then calls replyTo(action) after a short delay and feeds the returned messages back into the processor. In a real app the handler forwards the payload to the agent over your transport, and the agent’s response arrives the same way the first messages did.

The page’s styling is plain CSS in styles.css. The one part worth noting is that it reserves the surface’s height, for the reason the next paragraph gives.

The replay loop sends the three opening messages together, the way a model’s first response arrives, and paces any later messages out so the agent’s follow-up edits are visible one at a time. Sending the opening messages one by one made the page jump three times as the surface, then the components, then the data appeared; the page also reserves the surface’s height in CSS for the same reason.

What the agent sends

1
import type { ActionPayload, ProcessableMessage } from '@a2ui/web_core/v0_9';
2
import { CATALOG_ID } from './catalog';
3

4
export const SURFACE_ID = 'purchase-order-review';
5

6
type Cell = string | number | boolean | null;
7
type LogEntry = { text: string };
8

9
// The messages an agent streams to the client to open the surface. In a real
10
// app they arrive over A2A, AG-UI, or MCP. Here they are hardcoded so the demo
11
// runs without a backend or an API key. The format is A2UI v0.9.
12
export const agentMessages: ProcessableMessage[] = [
13
  {
14
    version: 'v0.9',
15
    createSurface: {
16
      surfaceId: SURFACE_ID,
17
      catalogId: CATALOG_ID,
18
      // Ask the client to attach the whole data model to every action it sends.
19
      sendDataModel: true,
20
    },
21
  },
22
  {
23
    version: 'v0.9',
24
    updateComponents: {
25
      surfaceId: SURFACE_ID,
26
      components: [
27
        { id: 'root', component: 'Column', children: ['title', 'intro', 'grid', 'actions', 'log'] },
28
        { id: 'title', component: 'Text', text: 'Purchase order PO-4471: workstation refresh', variant: 'h3' },
29
        {
30
          id: 'intro',
31
          component: 'Text',
32
          text: 'Adjust any quantity or unit price. The Total column and the grand total are formulas; HyperFormula recalculates them in your browser.',
33
          variant: 'body',
34
        },
35
        {
36
          id: 'grid',
37
          component: 'HotGrid',
38
          columns: ['Item', 'Qty', 'Unit price', 'Total'],
39
          columnTypes: ['text', 'numeric', 'numeric', 'numeric'],
40
          rows: { path: '/rows' },
41
          values: { path: '/values' },
42
          height: 230,
43
        },
44
        { id: 'actions', component: 'Row', children: ['send_button'], justify: 'end' },
45
        {
46
          id: 'send_button',
47
          component: 'Button',
48
          child: 'send_label',
49
          variant: 'primary',
50
          action: {
51
            event: {
52
              name: 'submit_purchase_order',
53
              // Resolved from the data model when the button is clicked.
54
              context: { rows: { path: '/rows' }, values: { path: '/values' }, log: { path: '/log' } },
55
            },
56
          },
57
        },
58
        { id: 'send_label', component: 'Text', text: 'Send to agent' },
59
        // Every message the agent has written, rendered as a list. `List` expands
60
        // the `log_item` template once per entry of the array at `/log`.
61
        { id: 'log', component: 'List', children: { path: '/log', componentId: 'log_item' } },
62
        { id: 'log_item', component: 'Text', text: { path: 'text' }, variant: 'caption' },
63
      ],
64
    },
65
  },
66
  {
67
    version: 'v0.9',
68
    updateDataModel: {
69
      surfaceId: SURFACE_ID,
70
      path: '/',
71
      value: {
72
        log: [{ text: 'Agent: here is the order as requested. Change anything, then send it to me for review.' }],
73
        rows: [
74
          ['Standing desk', 4, 480, '=B1*C1'],
75
          ['27" monitor', 8, 219, '=B2*C2'],
76
          ['Docking station', 8, 145, '=B3*C3'],
77
          ['Cable kit', 20, 12.5, '=B4*C4'],
78
          ['Grand total', null, null, '=SUM(D1:D4)'],
79
        ],
80
      },
81
    },
82
  },
83
];
84

85
// A stand-in for the model: what the agent sends back after it receives an
86
// action. It reads the rows the user sent, so the user's edits are kept, and
87
// inserts a discount line before the grand total the first time it sees an
88
// order above the discount threshold.
89
export function replyTo(action: ActionPayload): ProcessableMessage[] {
90
  const rows = (action.context.rows as Cell[][] | undefined) ?? [];
91
  const values = (action.context.values as Cell[][] | undefined) ?? [];
92
  const log = (action.context.log as LogEntry[] | undefined) ?? [];
93
  const grandTotal = values[values.length - 1]?.[3];
94
  const hasDiscount = rows.some((r) => String(r[0]).startsWith('Volume discount'));
95

96
  if (hasDiscount || typeof grandTotal !== 'number' || grandTotal < 2500) {
97
    return [
98
      {
99
        version: 'v0.9',
100
        updateDataModel: {
101
          surfaceId: SURFACE_ID,
102
          path: '/log',
103
          value: [...log, { text: `Agent: received. Grand total ${grandTotal}. I will route PO-4471 for approval.` }],
104
        },
105
      },
106
    ];
107
  }
108

109
  const lineItems = rows.slice(0, -1);
110
  const n = lineItems.length;
111
  return [
112
    {
113
      version: 'v0.9',
114
      updateDataModel: {
115
        surfaceId: SURFACE_ID,
116
        path: '/rows',
117
        value: [
118
          ...lineItems,
119
          ['Volume discount (8%)', null, null, `=-SUM(D1:D${n})*0.08`],
120
          ['Grand total', null, null, `=SUM(D1:D${n + 1})`],
121
        ],
122
      },
123
    },
124
    {
125
      version: 'v0.9',
126
      updateDataModel: {
127
        surfaceId: SURFACE_ID,
128
        path: '/log',
129
        value: [...log, { text: 'Agent: orders over 2,500 get an 8% volume discount, so I added it as a line. Send again if you change anything.' }],
130
      },
131
    },
132
  ];
133
}

What’s happening: three message types build the surface.

createSurface names the surface, picks the catalog by id, and sets sendDataModel: true. With that flag the client attaches the surface’s whole data model to every message it sends to the agent, so the agent always sees the current state.
updateComponents is a flat list of components with ids. root is required. Containers such as Column and Row reference their children by id, which is why the list can stream incrementally. The HotGrid entry binds rows to /rows and values to /values. The List at the bottom binds to /log and expands its log_item Text template once per entry, so every message the agent writes appears in order under the grid.
updateDataModel writes a value at a path. Here it fills the root with log (one entry) and rows.

The row data holds formulas as strings. =B1*C1 is a per-row formula and =SUM(D1:D4) an aggregate. HyperFormula evaluates both.

After these three messages the agent waits. Nothing else happens until the user acts.

Send edits back to the agent

The button’s action lists the paths whose values should travel with the event:
```
1
action: {
2
  event: {
3
    name: 'submit_purchase_order',
4
    context: { rows: { path: '/rows' }, values: { path: '/values' } },
5
  },
6
},
```
What’s happening: in A2UI, two-way binding is local. Typing in the grid updates the data model through setRows and setValues, but nothing leaves the client until an action fires. When the user clicks Send to agent, the client resolves each entry in context against the data model at that moment and sends the result. The agent receives the formulas the user may have edited and the numbers HyperFormula computed from them, in one payload. Edit a quantity in the demo, click the button, and compare the two arrays in the Client → agent panel.

The agent then answers. In the demo, replyTo in agentMessages.ts stands in for the model:
```
1
export function replyTo(action: ActionPayload): ProcessableMessage[] {
2
  const rows = (action.context.rows as Cell[][] | undefined) ?? [];
3
  // ...
4
  return [
5
    { version: 'v0.9', updateDataModel: { surfaceId: SURFACE_ID, path: '/rows', value: [...lineItems, discountRow, totalRow] } },
6
    { version: 'v0.9', updateDataModel: { surfaceId: SURFACE_ID, path: '/log', value: [...log, { text: 'Agent: ...' }] } },
7
  ];
8
}
```
It reads the rows from the action, so the user’s edits survive, inserts a volume-discount line before the grand total, and rewrites the total’s formula to cover the new range. The reply is an ordinary list of updateDataModel messages fed to the same MessageProcessor, which is what a real agent streams back. HotGrid applies the new rows with updateData() (Example 2 explains how), and HyperFormula recomputes the totals. Each reply also appends a line to the log. The action’s context includes log: { path: '/log' }, so the agent receives the current list and sends it back with one more entry; updateDataModel replaces the value at a path, so appending means sending the whole array. A second send gets a log entry only.

Example 2: Let the agent keep editing the grid

View the code · Open in the demo runner

Here the agent renders a reorder plan, then keeps editing it. Watch the message stream under the grid: after the first three messages the agent sends only partial updateDataModel messages. One targets a single cell (/rows/2/2), one replaces the row list to add a SKU. The grid applies each one with updateData(), so it is never rebuilt, and HyperFormula recomputes the order quantities and totals. Edit any number and click Approve plan or Ask for changes: the action carries the formulas and the computed values to the agent, which appends its answer to the list.

Note: as in the first demo, the agent is a fixed script plus a reply function, so there is no backend and no API key.

The component, catalog, and page are the same. Only the message script and the reply function change. Here the agent does not wait for the user: it renders the plan, then keeps sending partial updates on its own, and answers Approve plan or Ask for changes with a new line in the log.

1
import type { ActionPayload, ProcessableMessage } from '@a2ui/web_core/v0_9';
2
import { CATALOG_ID } from './catalog';
3

4
export const SURFACE_ID = 'reorder-plan';
5

6
type Cell = string | number | boolean | null;
7
type LogEntry = { text: string };
8

9
// Example 2: the agent keeps editing a grid it already rendered. Every message
10
// after the first three is a partial `updateDataModel` aimed at one path inside
11
// the data model, so the grid updates in place instead of being rebuilt.
12
export const agentMessages: ProcessableMessage[] = [
13
  {
14
    version: 'v0.9',
15
    createSurface: { surfaceId: SURFACE_ID, catalogId: CATALOG_ID, sendDataModel: true },
16
  },
17
  {
18
    version: 'v0.9',
19
    updateComponents: {
20
      surfaceId: SURFACE_ID,
21
      components: [
22
        { id: 'root', component: 'Column', children: ['title', 'grid', 'actions', 'log'] },
23
        { id: 'title', component: 'Text', text: 'Reorder plan for next week', variant: 'h3' },
24
        {
25
          id: 'grid',
26
          component: 'HotGrid',
27
          columns: ['SKU', 'On hand', 'Reorder point', 'Order qty', 'Unit cost', 'Line cost'],
28
          columnTypes: ['text', 'numeric', 'numeric', 'numeric', 'numeric', 'numeric'],
29
          rows: { path: '/rows' },
30
          values: { path: '/values' },
31
          height: 230,
32
        },
33
        { id: 'actions', component: 'Row', children: ['approve', 'reject'], justify: 'end' },
34
        {
35
          id: 'approve',
36
          component: 'Button',
37
          child: 'approve_label',
38
          variant: 'primary',
39
          action: { event: { name: 'approve_plan', context: { rows: { path: '/rows' }, values: { path: '/values' }, log: { path: '/log' } } } },
40
        },
41
        { id: 'approve_label', component: 'Text', text: 'Approve plan' },
42
        {
43
          id: 'reject',
44
          component: 'Button',
45
          child: 'reject_label',
46
          action: { event: { name: 'reject_plan', context: { values: { path: '/values' }, log: { path: '/log' } } } },
47
        },
48
        { id: 'reject_label', component: 'Text', text: 'Ask for changes' },
49
        // Every message the agent has written, rendered as a list. `List` expands
50
        // the `log_item` template once per entry of the array at `/log`.
51
        { id: 'log', component: 'List', children: { path: '/log', componentId: 'log_item' } },
52
        { id: 'log_item', component: 'Text', text: { path: 'text' }, variant: 'caption' },
53
      ],
54
    },
55
  },
56
  {
57
    version: 'v0.9',
58
    updateDataModel: {
59
      surfaceId: SURFACE_ID,
60
      path: '/',
61
      value: {
62
        log: [{ text: 'Agent: here is the plan from the current stock levels.' }],
63
        rows: [
64
          ['SKU-1041', 12, 40, '=MAX(0,C1*2-B1)', 3.2, '=D1*E1'],
65
          ['SKU-2210', 55, 30, '=MAX(0,C2*2-B2)', 11.5, '=D2*E2'],
66
          ['SKU-3307', 4, 25, '=MAX(0,C3*2-B3)', 42, '=D3*E3'],
67
          ['Total', null, null, '=SUM(D1:D3)', null, '=SUM(F1:F3)'],
68
        ],
69
      },
70
    },
71
  },
72
  // The agent changes one cell: the reorder point of the third SKU.
73
  {
74
    version: 'v0.9',
75
    updateDataModel: { surfaceId: SURFACE_ID, path: '/rows/2/2', value: 60 },
76
  },
77
  {
78
    version: 'v0.9',
79
    // Appending to the log: the agent sends the whole array, since A2UI's
80
    // updateDataModel replaces the value at a path.
81
    updateDataModel: {
82
      surfaceId: SURFACE_ID,
83
      path: '/log',
84
      value: [{ text: 'Agent: here is the plan from the current stock levels.' }, { text: 'Agent: SKU-3307 sells out weekly, so I raised its reorder point to 60.' }],
85
    },
86
  },
87
  // The agent inserts a row. The totals row moves down and its formulas are rewritten.
88
  {
89
    version: 'v0.9',
90
    updateDataModel: {
91
      surfaceId: SURFACE_ID,
92
      path: '/rows',
93
      value: [
94
        ['SKU-1041', 12, 40, '=MAX(0,C1*2-B1)', 3.2, '=D1*E1'],
95
        ['SKU-2210', 55, 30, '=MAX(0,C2*2-B2)', 11.5, '=D2*E2'],
96
        ['SKU-3307', 4, 60, '=MAX(0,C3*2-B3)', 42, '=D3*E3'],
97
        ['SKU-4102', 0, 15, '=MAX(0,C4*2-B4)', 7.75, '=D4*E4'],
98
        ['Total', null, null, '=SUM(D1:D4)', null, '=SUM(F1:F4)'],
99
      ],
100
    },
101
  },
102
  {
103
    version: 'v0.9',
104
    updateDataModel: {
105
      surfaceId: SURFACE_ID,
106
      path: '/log',
107
      value: [{ text: 'Agent: here is the plan from the current stock levels.' }, { text: 'Agent: SKU-3307 sells out weekly, so I raised its reorder point to 60.' }, { text: 'Agent: SKU-4102 is out of stock, so I added it. Approve, or edit the plan and ask for changes.' }],
108
    },
109
  },
110
];
111

112
// A stand-in for the model: what the agent sends back after an action.
113
export function replyTo(action: ActionPayload): ProcessableMessage[] {
114
  const values = (action.context.values as Cell[][] | undefined) ?? [];
115
  const log = (action.context.log as LogEntry[] | undefined) ?? [];
116
  const total = values[values.length - 1];
117
  const text =
118
    action.name === 'approve_plan'
119
      ? `Agent: approved. I will raise purchase orders for ${values.length - 1} SKUs, ${total?.[3]} units, ${total?.[5]} total cost.`
120
      : 'Agent: understood. Edit the plan in the grid and click Approve plan when it looks right.';
121
  return [{ version: 'v0.9', updateDataModel: { surfaceId: SURFACE_ID, path: '/log', value: [...log, { text }] } }];
122
}

What’s happening: after the surface exists, the agent sends only partial updateDataModel messages. One targets a single cell:

1
{ version: 'v0.9', updateDataModel: { surfaceId, path: '/rows/2/2', value: 60 } }

The bound rows prop re-resolves with that one cell changed. HotGrid compares the new rows with what it last wrote to the data model, sees that this change did not come from the grid, and calls updateData() on the existing instance:

1
useEffect(() => {
2
  const hot = hotRef.current;
3
  if (!hot || rowsKey === lastSyncedKey.current) return;
4
  hot.updateData(rows.map((r) => [...r]));
5
  propsRef.current.setValues?.(hot.getData() as Cell[][]);
6
}, [rowsKey]);

updateData replaces the cells without destroying the instance, so column widths and the HyperFormula engine survive, and the order quantities and totals recompute from the new reorder point. The later message that adds a row works the same way with a full /rows replacement.

Why compare against lastSyncedKey: the grid’s own setRows call also changes /rows, which re-resolves the prop. Without the guard, every user edit would be echoed back into updateData and interrupt the editor.

Connect a real agent

The demos replay a script. To drive HotGrid from a model, keep the component and catalog, and replace the replay loop with a transport:

CopilotKit ships an A2UI renderer that accepts a custom catalog. Define the component with createCatalog(definitions, renderers) from @copilotkit/a2ui-renderer and pass it as a2ui={{ catalog }} on the <CopilotKit> provider. See the CopilotKit A2UI guide.
A2A and AG-UI carry A2UI messages between a remote agent and your client. The A2UI documentation has a guide for each transport, and the Python a2ui-agent-sdk package generates the messages on the agent side.
Give the agent the catalog schema. hotCatalog.catalogSchema returns the JSON Schema for every registered component, including HotGrid, which is what the model needs in its context to produce valid messages.

The model call and its API key belong on a server. The client only ever receives A2UI JSON, which is data, not code.

Match your design system

An A2UI catalog is meant to reflect the host application’s own components, so an agent-rendered grid should look like every other grid in your product. HotGrid uses the default ht-theme-main theme. Swap the imported theme stylesheet, or register a custom theme that maps your design tokens to Handsontable’s, and every surface the agent creates follows it.

Known limitations

Two-way binding is client-local. The agent learns about edits only when an action fires or, with sendDataModel: true, when the client sends its next message.
Sorting, filtering, row moving, and user-driven row or column insert or remove, including through paste and the fill handle, all change what aggregate formulas in the grid cover, so HotGrid disables them and leaves row changes to the agent.
The A2UI protocol is at v0.9.1, with v1.0 a release candidate. This recipe targets the v0.9 import paths of @a2ui/react and @a2ui/web_core.

Formula calculation

Theme customization

Real-time updates via WebSocket

What you learned

How an A2UI catalog component pairs a Zod schema with a React implementation, and how the generic binder resolves { path } bindings and injects setters.
How to give an agent a grid that computes: Handsontable renders, HyperFormula evaluates the agent’s formulas, and the agent never does arithmetic.
How updateDataModel messages reach the grid and why updateData() keeps the instance alive across them.
How an action’s context carries both formulas and computed values back to the agent.
Why sorting, filtering, and user-driven row changes stay off when the grid holds formulas the agent depends on.

Next steps

Register HotGrid in a CopilotKit catalog and let a model choose it from a chat prompt.
Add a checks rule to the schema so the surface can validate a row before the action fires.
Compare with the Liveblocks multiplayer recipe, where the other editor is a person instead of an agent.