Agent Toolkit plugin

The Agent Toolkit turns a TomTom map into something a user can talk to. Bring an LLM and a chat box, and your users plan routes, search for places, inspect traffic and reshape the map with sentences instead of clicks.

What you can build with it

Conversational route planning. "Drive me from Berlin to Munich avoiding tolls, and stop for coffee halfway." — the agent chains geocoding, routing, place search and route edits, and renders the result.
Operational dashboards. "Show me where congestion is worst right now, and chart how many of our vehicles are in it." — the traffic tools next to custom tools that read your own fleet data.
Self-explaining field tools. "Outline every neighbourhood unreachable from the hospital in 20 minutes." — isochrones plus generated code produce and render a derived polygon.
Exploring your own data. Load a GeoJSON file and ask "keep only the points inside the congested tiles" — the agent registers it as a BYOD layer and filters it.

What's in the box

@tomtom-org/maps-sdk-plugin-agent-toolkit is a headless plugin built on Vercel AI SDK v6. createMapAgent returns a ToolLoopAgent wired to a TomTomMap and the TomTom services.

You bring:

A model from any Vercel AI SDK provider (OpenAI, Anthropic, Azure, Google, …).
A chat UI, or programmatic agent.generate() / agent.stream() calls.

The plugin provides:

A tool registry covering search, routing, traffic, isochrones, your own GeoJSON, base-map control, MapLibre access and generated analysis.
An intent classifier that offers only the tools each turn needs.
Shared state — places, routes, ranges, incidents, derived polygons, your own layers — that survives across turns, so "add a stop after the second one" just works.
Data tools that run model-written JavaScript over that state in a sandbox.
Ways to add, remove or replace tools and to shape the system prompt.

Quickstart

All plugins use @tomtom-org/maps-sdk as a peer dependency — ensure the SDK is installed first. See the Project Setup guide if needed.

Install

npm install @tomtom-org/maps-sdk-plugin-agent-toolkit ai zod
npm install @ai-sdk/react @ai-sdk/openai   # or @ai-sdk/anthropic, @ai-sdk/azure, …

The plugin's other peer dependencies — @tomtom-org/maps-sdk-plugin-map-theme, maplibre-gl, @turf/turf, chart.js, h3-js — are installed automatically by npm 7+ and pnpm 8+; add them yourself with other package managers.

Wire it up

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
import { createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
import { openai } from '@ai-sdk/openai';
import { useChat } from '@ai-sdk/react';
import { DirectChatTransport } from 'ai';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

const map = new TomTomMap({ mapLibre: { container: 'map' } });

const agent = createMapAgent(map, {
    model: openai('gpt-4o'),
    dataEntries: {
        routes: { entryMode: 'single' }, // one route on the map at a time
        byod: { enabled: false },        // no bring-your-own-data tools in this deployment
    },
});

const { messages, sendMessage } = useChat({
    transport: new DirectChatTransport({ agent }),
});

Without a chat UI, call the agent directly:

const { text } = await agent.generate({
    messages: [{ role: 'user', content: 'Find coffee shops near Dam Square' }],
});

Try it out

"Route from Berlin to Munich avoiding tolls."
"Show coffee shops near the map centre."
"What traffic incidents are on this route?"
"Switch to dark mode."
"How far is the second stop?"
"Chart the incidents along the route by category."

Clean up

agent.destroy(); // resets every built-in and custom state slice that implements reset()

Options

createMapAgent(map, options) takes one required option, model; each other option is explained on the page that owns it.

Option	What it controls	Read
`tools`, `includeDefaultTools`	Add, remove, replace or hand-pick tools	Customizing tools
`systemPrompt`, `systemPromptPrefix`, `systemPromptSuffix`	The system prompt	Customizing the system prompt
`classifier`, `onClassify`	Per-turn tool selection	How it works
`prepareStep`, `maxSteps`, `stepProviderOptions`, `providerOptions`, `outputSchemas`	The tool loop	How it works
`onToolExecute`	Per-tool timing and errors	How it works
`state`, `dataEntries`	Custom state slices; which data kinds exist and their entry mode	State
`byod`	Which URLs the agent may fetch	Bring your own data
`codeExecution`	Sandbox timeout and worker libraries	Code generation

Building with an AI coding assistant

The tomtom-maps-sdk-js skill covers this plugin; drop a public API name such as createMapAgent or analyseData into your question. AI coding with the SDK explains how to install and use it.

Where to next

In "learn enough to ship something" order:

How it works — the two-phase turn and how the classifier picks tools.
State — what the agent remembers across turns, entry mode, custom slices.
Tool registry — every built-in tool, grouped by what it does.
Customizing tools — remove, replace, add.
Customizing the system prompt — prefix, suffix and per-section overrides.
Bring your own data — feeding your GeoJSON to the agent.
Scope-aware data tools — how analyseData and processData stay small per turn.
Code generation — what generated code can reach, and the threat model.
Securing your agent — the model provider key and what the toolkit bounds.
What the agent sends, and where — inputs for your privacy notice.

API reference

Agent Toolkit Plugin API Reference

Related guides

How the SDK works — the Map and Services bundles the agent builds on
Places module — renders search results
Routing module — renders routes
Traffic — the traffic layers the agent toggles
AI in the SDK — AI capabilities in and around the SDK