Agent Toolkit state

The Agent Toolkit maintains structured state across the full conversation. As a rule, tools return compact summaries instead of raw GeoJSON, and keep the underlying data in state — so the next tool call (or the next user turn) can read it without the model having to re-derive or hallucinate it. The opt-in recallState tool (scoped via kind) intentionally returns full feature collections when the caller asks for an entry by id, but day-to-day discovery / analyse / process tools stay summary-shaped.

State slices

State is organized by feature area:

Slices flagged entries own an append-only history of results; the rest are flat configuration. Entry-bearing slices share a uniform shape — entries, entryMode, setEntryMode(mode) — so the same code paths handle them all (see Entry mode).

Sharing across tools

State is shared across all tools. A place resolved by locatePlace is immediately available to addWaypointsToRoute without the model having to pass it along — tools read directly from shared stores. This prevents the hallucination-prone “read then pass” pattern.

The recallState tool exists because tool results are not retained in conversation history. If a user asks “what were those places?” an hour into a session, the model calls a recall tool — it does not guess or hallucinate prior results.

Entry mode

Every entry-bearing slice exposes an entry mode: multiple (default) lets several entries render side-by-side; single keeps only the most recent one and auto-drops older entries when flipped. The set of slices that support it is captured in the EntryModeSliceName union — slice names there match the keys on agent.state exactly (routing, not routes; customGeometries, not geometries), so the same name flows through every layer:

The model surfaces entry-mode changes through the setEntryMode tool when the user asks to “only show one at a time” or “let me overlay multiple”. It accepts any of the slice names above.

Defaults via createMapAgent

Set per-kind defaults at construction time with the dataEntries option. Each kind accepts { enabled?, entryMode? }. Keys are LLM-facing kind names (routes, incidents) — not slice names (routing, trafficIncidents); the slice mapping is internal.

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
});

Omit a kind to leave it at its defaults (enabled: true, entryMode: 'multiple'). Setting enabled: false is aggressive: the kind disappears from the agent’s tool surface entirely — it is removed from analyseData / processData scope and input fields, and the slice’s recall / display / fetch tools are dropped from the registry. See TOOLS_BY_DATA_ENTRY_KIND for the exact tool list per kind.

Modes can also be flipped at any time after construction:

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

Working with the union from your own code

The reusable EntryModeSliceName type and the runtime list ENTRY_MODE_SLICE_NAMES are exported so custom tools and dev UIs can iterate every entry-mode-aware slice without hard-coding the 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

You can read live state at any time:

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

Custom state slices

If your custom tools need to share data across calls, extend ToolState with your own slice. Implement reset() to participate in agent.destroy() cleanup:

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;

For the tools that read and write these slices, see Tool registry.

State lives in the page, so everything in it is visible and editable by the person using your application. Securing your agent covers what follows from that.