Agent Toolkit state

The Agent Toolkit keeps structured state for the whole conversation. Tools return compact summaries and keep the underlying data in state, so the next tool call or turn reads it instead of the model re-deriving or inventing it. The model reads it back with recallState, which also returns summaries.

State slices

State is organized by feature area:

Slices flagged entries own an append-only history of results. The rest hold the map’s shared modules. Entry slices share one shape (entries, entryMode, setEntryMode(mode)), and each entry owns SDK modules, which the toolkit creates lazily on first display. See Entry mode.

The entry slices also hold the look of their modules as a SliceKnobs: routing.knobs, places.knobs and places.geometriesKnobs, ranges.knobs, ranges.geometriesKnobs and ranges.placesKnobs, customGeometries.knobs, trafficAreaAnalytics.knobs and trafficIncidents.knobs. set(id, value) takes an id of the module’s knob catalogue and sets it on every module of that kind the slice holds, and on each one it creates later. setMapStyling writes through them. For example, agent.state.routing.knobs.set('color', '#e11d48') recolours every route, shown now or later.

Beside the slices, agent.state holds every analyseData result (analyses), the trackers and the sandbox that runs generated code (codeExecution).

Sharing across tools

All tools share state. A place that locatePlace resolves is available to addWaypointsToRoute without the model passing it along. Tools pass entry ids, not data, which avoids the error-prone “read then pass” pattern.

Tool results carry summaries, not the data. When a user asks “what were those places?” an hour into a session, the model calls recallState instead of guessing.

Entry mode

Every entry slice has an entry mode. multiple, the default, renders several entries side by side. single keeps only the most recent one, and switching to it drops the older ones. The EntryModeSliceName union names these slices by their keys on agent.state (routing, not routes; customGeometries, not geometries):

The model switches modes with the setEntryMode tool when the user asks to “only show one at a time” or “let me overlay multiple”. The state playground example shows every slice’s entries and mode live.

Defaults via createMapAgent

Set per-kind defaults with the dataEntries option. Each kind accepts { enabled?, entryMode? }. Keys are data kinds (routes, incidents), not slice names (routing, trafficIncidents).

1
import { createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
2

3
const agent = createMapAgent(map, {
4
    model: openai('gpt-4o'),
5
    dataEntries: {
6
        routes: { entryMode: 'single' },          // only one route on the map
7
        incidents: { entryMode: 'single' },       // each refresh replaces the previous snapshot
8
        byod: { enabled: false },                 // hide byod from analyse/process scope + drop addByodSource / setByodLayers / updateByodDisplay
9
    },
10
});

Omitted kinds keep their defaults (enabled: true, entryMode: 'multiple'). enabled: false removes the kind from the agent. The kind drops out of the analyseData / processData inputs, and the agent drops its fetch and display tools. TOOLS_BY_DATA_ENTRY_KIND lists them per kind. The agent keeps a tool you pass under one of those names in tools.

Switch a mode at any time after construction:

1
await agent.state.customGeometries.setEntryMode('single');

Working with the union from your own code

EntryModeSliceName and its runtime list ENTRY_MODE_SLICE_NAMES let custom tools and dev UIs iterate every entry slice without hard-coding names:

1
import {
2
    ENTRY_MODE_SLICE_NAMES,
3
    type EntryModeSliceName,
4
} from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
5

6
for (const slice of ENTRY_MODE_SLICE_NAMES) {
7
    console.log(slice, agent.state[slice].entryMode);
8
}

Inspecting state from your application

Read live state at any time:

1
agent.state.routing.currentRoutes;            // most recent route results
2
agent.state.places.latestPlace;               // places of the most recent entry
3
agent.state.places.shownEntryIds;             // entries currently on the map
4
agent.state.places.entries;                   // full history of place entries
5
agent.state.trafficIncidents.entries;         // fetched incident entries
6
agent.state.trafficAreaAnalytics.entries;     // historical analytics entries
7
agent.state.customGeometries.entries;         // derived polygon entries
8
agent.state.byod.entries;                     // bring-your-own-data layer entries
9
agent.state.baseMap.mapLibreMap;              // raw MapLibre Map instance

Telling the model what the user changed

If your UI changes the map between turns, such as hiding a layer or picking another route, the model doesn’t know. getStateDigest snapshots what is shown. formatStateDigestDiff turns two snapshots into a short note to prepend to the next message, or returns null when nothing changed:

1
import { formatStateDigestDiff, getStateDigest } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
2

3
let baseline = getStateDigest(agent.state); // after each assistant reply
4

5
// … before sending the user's next message:
6
const diff = formatStateDigestDiff(baseline, getStateDigest(agent.state));
7
const content = diff ? `${diff}\n${userText}` : userText;

What state holds, and how to wipe it

State lives in memory only. The toolkit writes nothing to browser storage. State holds every entry of the session, meaning the places, routes, ranges, BYOD layers, incidents, analyses and trackers the user produced, until one of these clears it:

• The resetState tool, which the agent calls when the user asks to start over.
• agent.destroy() from your code.

The chat history is not part of state. It lives in your chat component. To erase a user’s data, clear that history and call agent.destroy(). See What the agent sends, and where.

Custom state slices

If your custom tools need to share data across calls, extend ToolState with your own slice. Implement reset() to take part in agent.destroy() cleanup, and give the model a tool that reads the slice back:

1
import type { ToolState, StateSlice } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
2

3
class FleetState implements StateSlice {
4
    vehicles: Map<string, VehiclePosition> = new Map();
5
    reset() { this.vehicles.clear(); }
6
}
7

8
interface MyState extends ToolState {
9
    fleet: FleetState;
10
}
11

12
const agent = createMapAgent<MyState>(map, {
13
    model: openai('gpt-4o'),
14
    state: { fleet: new FleetState() },
15
    tools: { getFleetVehicle: myFleetTool },
16
});
17

18
// Access live state from your application
19
agent.state.fleet.vehicles;
20
agent.state.routing.currentRoutes;

The site selection agent example adds a custom slice. The tool registry lists the tools that read and write the built-in ones.

State lives in the page, so the person using your application can see and edit everything in it. Securing your agent covers what follows from that.