Agent Toolkit plugin

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

Why it exists

LLMs are great at understanding what someone wants. Maps are great at showing them where things are. The gap between the two is plumbing — a tool registry the model can call, agent state that survives multiple turns, an intent classifier that keeps the prompt small, and a sandbox for the heavy lifts. The Agent Toolkit owns that plumbing so you can focus on the experience.

You bring an LLM and (optionally) a chat UI. The plugin handles the rest.

What you can power with it

A few common shapes the toolkit is good at:

• Conversational route planning. "Drive me from Berlin to Munich avoiding tolls, stop for coffee halfway, and add a charger near the third hour of driving." — the agent fans out across geocoding, routing, place search, and route mutation tools and renders the full picture on the map.
• Operational dashboards. "Show me where congestion is worst right now, and chart how many of our delivery vehicles are stuck in it." — combine the agent's traffic-area-analytics tools with custom tools that read your own fleet state.
• Field tools that explain themselves. "Outline every neighbourhood that's unreachable from the hospital in 20 minutes." — the toolkit composes geocoding, isochrones, and a code-execution tool to produce a derived polygon, then renders it.
• Bring-your-own-data exploration. Drop a customer-authored GeoJSON file onto the map and ask "Filter this to only the points inside the high-congestion tiles" — the agent loads it as a BYOD layer and slices it in the sandbox.
• Map-aware copilots. A chat panel that lives next to a logistics, real-estate, or operations app — using your custom domain tools alongside the built-in geographic stack.

What's in the box

@tomtom-org/maps-sdk-plugin-agent-toolkit is a headless plugin built on Vercel AI SDK. It wires a TomTomMap instance and TomTom services to a curated set of LLM-callable tools and runs the multi-step tool loop via ToolLoopAgent.

You bring:

• An LLM model — any Vercel AI SDK provider (OpenAI, Anthropic, Azure, Google, …).
• A chat UI, or programmatic agent.respond() calls.

The plugin provides:

• A built-in tool registry covering search, routing, traffic, isochrones, BYOD GeoJSON layers, base-map control, MapLibre access, and code-generated analysis. See Tools.
• An intent classifier that picks the right tools per turn AND emits per-tool scopes so the heavyweight analyseData / processData schemas narrow to just the kinds of state the turn touches. See How it works and Scope-aware data tools.
• Shared agent state — places, routes, waypoints, reachable ranges, traffic incidents, derived polygons, BYOD layers — that persists across turns so the user can say "add a stop after the second one" without repeating context. See State.
• analyseData / processData — two code-execution tools that take user-authored JavaScript and run it in a sandbox against the agent's collected entries, injected as one per-entry record per kind (placesByEntry, routesByEntry, incidentsByEntry, geometriesByEntry, trafficAreaAnalyticsByEntry, byodByEntry). Lets the LLM compute aggregations, charts, hex bins, intersections, filters, and derived polygons without you predefining every operation.
• A composable API to add, remove, replace, or gate tools — including the ability to disable an entire data-entry kind (e.g. byod: { enabled: false }) and have all the related tools drop out of the registry automatically.

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
npm install ai @ai-sdk/react @ai-sdk/openai   # or @ai-sdk/anthropic, @ai-sdk/azure, etc.

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'),

    // Optional: tailor which data-entry kinds the agent can touch. Disabling
    // a kind removes it from analyseData / processData scope AND drops the
    // related recall / display tools from the registry.
    dataEntries: {
        routes: { entryMode: 'single' },          // one route at a time
        byod: { enabled: false },                 // no BYOD tools in this deployment
    },
});

// Wire to any Vercel AI SDK chat interface
const { messages, sendMessage } = useChat({
    transport: new DirectChatTransport({ agent }),
});

Try it out

Once wired, users can interact naturally:

• "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 distribution of incidents along the route by category."

Clean up

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

Working with Claude code

If you're using Claude Code to build against this plugin, install the SDK skill, which auto-loads focused context when you ask about the toolkit:

npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js

Trigger keywords include createMapAgent, ToolLoopAgent, analyseData, processData, scopeSchema, scopePrompt, dataEntries, addByodSource, and most other public API names. Drop one into your question and the skill picks it up. AI coding with the SDK covers the other topics it knows.

Where to next

The rest of this section breaks the plugin's surface area into focused topics. Roughly in "learn enough to ship something" order:

• How it works — the two-phase turn (intent classification, tool loop), per-tool classification prompts, and classifier observability.
• State — what the plugin remembers across turns, entry mode, the dataEntries option, and how to add your own slice.
• Tool registry — every built-in tool, grouped by what it does.
• Customizing tools — remove, replace, add — and how the registry is resolved.
• Customizing the system prompt — prefix, suffix, and per-section overrides over the base prompt, with an assembly diagram.
• Bring your own data — feeding customer-authored GeoJSON into the agent.
• Scope-aware data tools — how analyseData and processData narrow their per-turn schemas, and how to add your own scopable tools.
• Code generation — the JavaScript-as-parameter pattern, what gets injected into the sandbox, and the threat model worth understanding before you ship.
• Securing your agent — the model provider key, what a chat-completion route needs beyond the map proxy, and what the toolkit does and does not bound.
• What the agent sends, and where — what reaches your model provider, when the user's location is read, and which URLs the agent loads, 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 — module used internally for displaying search results
• Routing module — module used internally for rendering routes
• Traffic — traffic tools used by the agent
• AI in the SDK — overview of AI capabilities in and around the SDK