AI Map Agent Plugin

The AI Map Agent plugin gives a language model conversational control over a TomTom map and its services. You bring the LLM and optionally a chat UI — the plugin handles the tool loop, agent state, and map coordination.

import { MapAgentChat } from './chat/MapAgentChat';
import { useMapAgent } from './useMapAgent';

export function App() {
    const chat = useMapAgent();

    return (
        <div id="app">
            <div id="sdk-map" />
            <div id="chat-panel">
                {chat.transport ? (
                    <MapAgentChat transport={chat.transport} />
                ) : (
                    <div id="chat-loading">Initializing assistant...</div>
                )}
            </div>
        </div>
    );
}

What it is

@tomtom-org/maps-sdk-plugin-ai-agent 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 manages the multi-step tool loop via ToolLoopAgent.

You bring:

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

The plugin provides:

• 30+ built-in tools covering map control, search, routing, traffic, and utilities
• An intent classifier that selects the right tool subset per message
• Plugin state that persists places, routes, and waypoints across tool calls
• A composable API to add, remove, or replace any tool

How it works

Every user message goes through two phases before a response is sent:

1. Intent classification

Before the model sees the full tool list, a lightweight pre-pass selects only the tools relevant to this turn. Fewer tools in the prompt means fewer wrong choices and lower token usage.

The classifier is built from each tool’s classificationPrompt — a one-liner that describes when to activate that tool. When you add a custom tool, it participates in classification automatically as long as it has a classificationPrompt.

The default classifier reuses your main model. For cost-sensitive deployments, swap it for a smaller model:

1
import { createMapAgent, createDefaultClassifier } from '@tomtom-org/maps-sdk-plugin-ai-agent';
2
import { openai } from '@ai-sdk/openai';
3

4
const agent = createMapAgent(map, {
5
    model: openai('gpt-4o'),
6
    classifier: createDefaultClassifier({ model: openai('gpt-4o-mini') }),
7
});

Or disable classification entirely (all tools always visible):

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    classifier: false,
4
});

2. Tool loop

The model calls tools — geocode, search, route, show on map — in sequence or in parallel until it can form a complete answer. Tools never return raw GeoJSON to the model; they return compact summaries (counts, names, labels, status). Full geospatial data is kept in plugin state for follow-up use.

State persists across turns, so the user can say “add a stop after the first one” or “what were those restaurants again?” without repeating context. The agent retrieves prior results from its internal stores via dedicated recall tools.

The tool registry

The plugin ships a DEFAULT_TOOLS registry — a flat record of named ToolEntry objects. Each entry defines what the tool does and how the agent should use it:

1
{
2
    description: string;          // Full tool description for the model
3
    inputSchema: ZodType;         // Validated input parameters
4
    outputSchema?: ZodType;       // Structured output (improves reliability)
5
    execute: (input, state) => Promise<any>;
6

7
    // Classifier metadata
8
    classificationPrompt?: string; // One-liner: when to activate this tool
9
    tags?: string[];               // Category labels (e.g. 'route', 'traffic')
10
    examples?: string[];           // Usage examples shown in the help tool
11
    examplePrompts?: string[];     // Natural-language prompts shown in the help tool
12
    relatedTools?: string[];       // Tools often used together
13
    dependsOn?: string[];          // Tools that must run first
14
}

Tools are grouped by what they do, not which API they wrap:

The help tool

The built-in help tool is available to the model at runtime. When a user asks “what can you do?” or “show me routing examples”, the model calls help to surface tool descriptions, usage examples, and example prompts filtered by tag. Users discover capabilities through natural conversation — no documentation browsing required.

Tools that read state vs. fetch data

A key design distinction: some tools fetch fresh data from TomTom services; others read from plugin state. The recall tools (recallPlaces, recallRoutes, recallRanges) exist 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.

Plugin state

The plugin maintains structured state across the full conversation, organized by feature area:

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

You can inspect live state at any time from your application:

1
agent.state.routing.currentRoutes;   // most recent route results
2
agent.state.places.currentPlaces;    // most recent place results
3
agent.state.baseMap.mapLibreMap;     // raw MapLibre Map instance

Installation

1
npm install @tomtom-org/maps-sdk-plugin-ai-agent

Add a Vercel AI SDK provider for your chosen model:

1
npm install ai @ai-sdk/openai   # or @ai-sdk/anthropic, @ai-sdk/azure, etc.

Quick start

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-ai-agent';
4
import { openai } from '@ai-sdk/openai';
5
import { DirectChatTransport } from 'ai';
6
import { useChat } from 'ai/react';
7

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

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

12
const agent = createMapAgent(map, { model: openai('gpt-4o') });
13

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

Once wired, users can interact naturally:

• “Route from Berlin to Munich avoiding tolls”
• “Show coffee shops near the map center”
• “What traffic incidents are on this route?”
• “Switch to dark mode”
• “How far is the second stop?”

Customizing tools

Tools are resolved by merging the DEFAULT_TOOLS registry with your tools option. You can add, replace, or remove individual entries — the rest remain untouched.

Remove a default tool

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    tools: { setLanguage: false },
4
});

Replace a default tool

Pass a ToolEntry with the same key to swap the built-in implementation with yours:

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    tools: {
4
        getCurrentLocation: {
5
            description: 'Returns the user position from the company fleet system.',
6
            inputSchema: z.object({}),
7
            execute: async (_input, state) => {
8
                const position = await fleetApi.getDriverPosition();
9
                state.baseMap.userPosition = position;
10
                return { position };
11
            },
12
            classificationPrompt: 'Get the driver\'s current GPS position from the fleet system.',
13
            tags: ['location'],
14
        },
15
    },
16
});

Add a custom tool (BYOD blending)

Bring your own data sources alongside the built-in TomTom tools. Custom tools receive the same state object, so they can display results using SDK modules without any extra wiring:

1
import { z } from 'zod';
2
import type { ToolEntry, ToolState } from '@tomtom-org/maps-sdk-plugin-ai-agent';
3

4
const getFleetVehicle: ToolEntry = {
5
    description: 'Get the current map position of a fleet vehicle by ID and show it as a place marker.',
6
    classificationPrompt: 'Locate or display a fleet vehicle on the map by its ID.',
7
    inputSchema: z.object({ vehicleId: z.string().describe('The fleet vehicle identifier') }),
8
    execute: async ({ vehicleId }, state) => {
9
        const position = await fleetApi.getPosition(vehicleId);
10
        const placesModule = await state.places.getPlacesModule();
11
        placesModule.show({ type: 'FeatureCollection', features: [toFeature(position)] });
12
        return { vehicleId, position, status: 'shown' };
13
    },
14
    tags: ['location'],
15
    examplePrompts: ['Where is vehicle TT-001?', 'Show fleet vehicle on the map'],
16
};
17

18
const agent = createMapAgent(map, {
19
    model: openai('gpt-4o'),
20
    tools: { getFleetVehicle },
21
});

The custom tool participates in intent classification automatically. If the user says “Where is vehicle TT-001?”, the classifier activates getFleetVehicle alongside any other tools needed to answer the question.

Start from a blank slate

Set includeDefaultTools: false to begin with no built-in tools. Useful when building a narrowly scoped agent that should not stray into general map control:

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    includeDefaultTools: false,
4
    tools: {
5
        getFleetVehicle,
6
        locatePlace,    // selectively re-add built-in tools you do want
7
    },
8
});

Extending the system prompt

Append to the built-in prompt

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    systemPromptSuffix: 'Always respond in Spanish. Never show more than 5 places at once.',
4
});

Full replacement

Import BASE_SYSTEM_PROMPT as a baseline to extend rather than starting from scratch. The base prompt contains coordinate order rules, tool-usage guidance, and response formatting instructions that are important for reliability:

1
import { createMapAgent, BASE_SYSTEM_PROMPT } from '@tomtom-org/maps-sdk-plugin-ai-agent';
2

3
const agent = createMapAgent(map, {
4
    model: openai('gpt-4o'),
5
    systemPrompt: BASE_SYSTEM_PROMPT + `
6

7
ADDITIONAL INSTRUCTIONS:
8
- This is a logistics application. Prioritize route efficiency over scenery.
9
- Always show estimated arrival times in responses.
10
- When a vehicle ID is mentioned, call getFleetVehicle before anything else.
11
`,
12
});

Per-tool classification prompts

If your custom tool is being activated too broadly or not activated when it should be, tune its classificationPrompt. This is the one-liner the classifier uses to decide whether a user message needs this tool:

1
// Too broad — activates for any location question
2
classificationPrompt: 'Get fleet vehicle data.'
3

4
// Precise — activates only for explicit vehicle ID references
5
classificationPrompt: 'Locate a fleet vehicle by its ID (e.g. "TT-001"); not for general location queries.'

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-ai-agent';
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;

Observing classification

Use onClassify to inspect which tools were selected for each turn — useful for debugging classification behaviour or building a dev panel:

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    onClassify: (result) => {
4
        if (result) {
5
            console.log('Selected tools:', result.activeToolNames);
6
            console.log('Classification took:', result.timeMs, 'ms');
7
        }
8
    },
9
});

Cleanup

1
agent.destroy();  // resets all built-in and custom state slices that implement reset()

API Reference

Map Agent 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