Customizing the system prompt

The base system prompt teaches the LLM how to behave as a map assistant: who it is, what it can do, how to decline out-of-scope asks, how to format answers, how to read incomplete data, how to call tools, and how session state works. You rarely need to replace it wholesale — instead you can prepend a preamble, append instructions, or override individual sections while every other section keeps its default.

How a prompt is assembled

The base prompt is split into seven named sections (exported as SYSTEM_PROMPT_SECTIONS). createMapAgent assembles the final prompt top-to-bottom: your optional systemPromptPrefix, then the (possibly overridden) base sections, then your optional systemPromptSuffix under an ADDITIONAL INSTRUCTIONS: heading.

A full-string systemPrompt replaces the entire grey box (and ignores the prefix and suffix); the prefix, suffix, and section overrides otherwise all compose together.

The sections

Per-tool mechanics — coordinate order, "near me" vs "in this area" routing — deliberately live in the tool descriptions and the classifier prompt, not the base prompt, so they stay correct as tools change.

Four ways to shape it

Prefer the least invasive option that does the job: nudge with the prefix/suffix, retune with section overrides, and reach for a full replacement only when you must remove base behaviour.

Prepend or append

systemPromptPrefix and systemPromptSuffix keep the whole base prompt live — future SDK releases can refine the base sections and your agent picks them up on upgrade.

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

Override individual sections

Pass a SystemPromptSectionOverrides object as systemPrompt. Each key replaces just that section’s body — the heading is added for you — and omitted sections keep their defaults:

1
const agent = createMapAgent(map, {
2
    model: openai('gpt-4o'),
3
    systemPrompt: {
4
        identity: 'You are a delivery fleet dispatcher built on the TomTom map.',
5
        responseFormatting: 'Reply in Dutch, metric units, one short paragraph.',
6
        // capabilities, rejectionRules, dataConfidence, toolExecution, sessionState stay default
7
    },
8
});

Extend a default section

To add to a section rather than replace it, read its default from SYSTEM_PROMPT_SECTIONS and derive a new value — handy for appending one rule, or for handing the default to a coding agent to rewrite under some criteria:

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

3
const agent = createMapAgent(map, {
4
    model: openai('gpt-4o'),
5
    systemPrompt: {
6
        rejectionRules: `${SYSTEM_PROMPT_SECTIONS.rejectionRules}\n- Decline weather questions.`,
7
    },
8
});

composeSystemPrompt(overrides) performs the same composition explicitly if you need the assembled string elsewhere — logging, diffing, or a token-budget check.

Full replacement

The escape hatch: you own the entire prompt and re-check the base on each SDK upgrade. Import BASE_SYSTEM_PROMPT as a baseline to extend rather than starting from scratch — it carries the identity, capability summary, scope/rejection, formatting, data-confidence, tool-execution, and session-state guidance that matter for reliability.

1
import { createMapAgent, BASE_SYSTEM_PROMPT } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
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
});

A full-string systemPrompt ignores systemPromptPrefix and systemPromptSuffix — the caller owns the whole prompt.

Keeping a persona prompt lean

Section overrides add the base scope/formatting scaffolding around your persona text, so an override object can assemble into a larger prompt than an equivalent full-string version. If prompt size matters, lean on the base sections (don’t restate what they already cover) and override only where the persona genuinely differs — overriding rejectionRules with a one-liner, for instance, instead of inheriting the multi-bullet default. composeSystemPrompt(overrides).length gives you the assembled character count to compare against.