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 (places, routes, incidents, geometries, trafficAreaAnalytics, byod). 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/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 { DirectChatTransport, useChat } from 'ai/react';

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()

In this section

• How it works — the two-phase turn (intent classification, tool loop), system-prompt extension, and classifier observability.
• State — what the plugin remembers across turns, entry mode, the dataEntries option, and how to add your own slice.
• Tools — the tool registry, how to customise it with BYOD tools, and the experimental code-generation pattern (analyseData / processData).

Coding skills for Claude Code

If you're using Claude Code to build against this plugin, the repo ships two skills that load focused context on demand:

• tomtom-maps-sdk-js — orientation for building with the SDK and the agent-toolkit: createMapAgent, scopable tools, analyseData / processData, BYOD, traffic monitors, classifiers, and the broader map / services surface.
• tomtom-maps-sdk-js-contribution — orientation for contributing to the SDK itself: workspace layout, build commands, and the agent-toolkit's internal architecture.

Both skills sit in .claude/skills/ and are invoked automatically when Claude detects a relevant question or file.

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