Agent Toolkit plugin

The Agent Toolkit lets your users talk to a TomTom map. Add an LLM and a chat box, and they can 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, such as “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, such as “Show me where congestion is worst right now, and chart how many of our vehicles are in it.” The traffic tools work next to custom tools that read your own fleet data.
• Self-explaining field tools, such as “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 of places, routes, ranges, incidents, derived polygons and your own layers. It survives across turns, so “add a stop after the second one” 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

Install

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

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

Wire it up

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
3
import { createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
4
import { openai } from '@ai-sdk/openai';
5
import { useChat } from '@ai-sdk/react';
6
import { DirectChatTransport } from 'ai';
7

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

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

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

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

Without a chat UI, call the agent directly:

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

To stream the reply into a chat box of your own, call agent.stream() instead and keep the conversation in a messages array. The demo below does that in plain TypeScript, with no framework:

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

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

Options

createMapAgent(map, options) takes one required option, model. The pages in the table explain the other options.

Building with an AI coding assistant

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

Where to next

Read them in this order to learn enough to ship something:

• How it works — the two-phase turn and how the classifier picks tools.
• State — what the agent remembers across turns, entry mode and 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 and examples

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

Related examples

• Minimal map agent — a map, a chat box and createMapAgent, in plain TypeScript
• Map chat agent — the same agent behind a React chat