TomTom Maps for JavaScript
    Preparing search index...

    Type Alias MapAgentOptions<CS>

    type MapAgentOptions<CS extends ToolState = ToolState> = {
        byod?: { validateSourceUrl?: ByodSourceUrlValidator };
        classifier?: Classifier | false;
        codeExecution?: CodeExecutionConfig;
        dataEntries?: Partial<Record<DataEntryKind, DataEntryConfig>>;
        featureFlags?: FeatureFlags;
        includeDefaultTools?: boolean;
        maxSteps?: number;
        model: LanguageModel;
        onClassify?: (result: ClassificationResult | null) => void;
        onToolExecute?: OnToolExecute;
        outputSchemas?: boolean;
        prepareStep?: PrepareStepFunction;
        providerOptions?: ProviderOptions;
        state?: Omit<CS, keyof ToolState>;
        stepProviderOptions?: (
            info: { activeTools: string[] | undefined; stepNumber: number },
        ) => ProviderOptions | undefined;
        systemPrompt?: string | SystemPromptSectionOverrides;
        systemPromptPrefix?: string;
        systemPromptSuffix?: string;
        tools?: { [K in ToolNameHint]?: ToolEntry<CS> | false };
    }

    Type Parameters

    Index

    Properties

    byod? classifier? codeExecution? dataEntries? featureFlags? includeDefaultTools? maxSteps? model onClassify? onToolExecute? outputSchemas? prepareStep? providerOptions? state? stepProviderOptions? systemPrompt? systemPromptPrefix? systemPromptSuffix? tools?

    Properties

    byod?: { validateSourceUrl?: ByodSourceUrlValidator }

    BYOD (bring-your-own-data) options.

    Type Declaration

    • OptionalvalidateSourceUrl?: ByodSourceUrlValidator

      Authorize each addByodSource URL before it is fetched — see ByodSourceUrlValidator. Return { valid: true } to allow or { valid: false, reason } to block (sync or async). Runs in addition to the built-in scheme / size / timeout policy.

    createMapAgent(map, {
        model: openai('gpt-4o'),
        byod: {
            // Refuse cloud-metadata / private addresses; allow only known hosts.
            validateSourceUrl: (url) =>
                url.hostname === 'data.example.com'
                    ? { valid: true }
                    : { valid: false, reason: `Host "${url.hostname}" is not allowed.` },
        },
    });
    classifier?: Classifier | false

    Pluggable classifier for automatic tool selection.

    • Omit to use the default LLM-based classifier (uses main model)
    • Pass a Classifier function for custom logic
    • Pass false to disable classification entirely
    codeExecution?: CodeExecutionConfig

    Tunes analyseData / processData sandbox execution — see CodeExecutionConfig. Where the code runs is chosen by environment (off-thread iframe-worker in the browser, main thread in Node/SSR), not configured here; these options only adjust the isolated browser run (timeoutMs, loadWorkerLibrarySource).

    dataEntries?: Partial<Record<DataEntryKind, DataEntryConfig>>

    Per-kind data-entry configuration. Each DataEntryKind accepts { enabled?, entryMode? }. Setting enabled: false removes the kind from the agent's tool surface entirely — it disappears from analyseData / processData scope and input fields, and the slice-specific recall / display / fetch tools are dropped from the registry. entryMode is applied to the underlying slice right after the agent state is built — before any tool runs.

    Keys are LLM-facing kind names (routes, incidents) — not slice names (routing, trafficIncidents). The slice mapping is internal.

    createMapAgent(map, {
        model: openai('gpt-4o'),
        dataEntries: {
            routes: { entryMode: 'single' },
            incidents: { entryMode: 'single' },
            byod: { enabled: false }, // disables recallState, addByodSource, setByodLayers, updateByodDisplay + byod scope on analyse/process
            ranges: { enabled: false }, // disables findReachableAreas + recallState
        },
    });
    featureFlags?: FeatureFlags

    Opt into in-flight or experimental agent-toolkit behaviour. Stability varies per flag — see FeatureFlags and each flag's own doc.

    includeDefaultTools?: boolean

    Whether to include all built-in default tools. Defaults to true. Set to false to start with no defaults and provide only custom tools via tools.

    maxSteps?: number

    Max multi-step tool loop iterations. Default: 10.

    model: LanguageModel

    AI SDK language model instance. REQUIRED — no default provider.

    onClassify?: (result: ClassificationResult | null) => void

    Called after each classification. Use to observe selected tools or log.

    onToolExecute?: OnToolExecute

    Called after each tool's execute settles (success or throw), with its wall-clock duration and whether it failed. Use to observe per-tool latency and error rates (e.g. telemetry). Errors are detected both from a thrown exception and from the standardized { error: string } return shape.

    outputSchemas?: boolean

    Whether to include output schemas on tools. Defaults to true. Set to false for providers that don't support structured tool outputs.

    prepareStep?: PrepareStepFunction

    Custom prepareStep hook, composed with internal classification step. Your activeTools are intersected with the classifier's selection.

    providerOptions?: ProviderOptions

    Provider-specific options forwarded to the AI SDK on every step. Keyed by provider id (openai, azure, anthropic, ...).

    Use this to enable reasoning summaries for gpt-5.x via the Responses API — without reasoningSummary the model thinks but returns no reasoning text:

    createMapAgent(map, {
        model: azure.responses(deploymentId),
        providerOptions: {
            openai: { reasoningEffort: 'low', reasoningSummary: 'auto' },
        },
    });
    state?: Omit<CS, keyof ToolState>

    Custom state slices merged alongside built-in state. Only custom slices need to be provided — built-in slices are created automatically. Accessible in custom tool execute via the state parameter.

    stepProviderOptions?: (
        info: { activeTools: string[] | undefined; stepNumber: number },
    ) => ProviderOptions | undefined

    Per-step providerOptions override. Called once per step with the classifier-narrowed active toolset; the returned object is merged on top of providerOptions for that step. Use it to bump reasoning effort on turns that include a code-execution tool without paying the cost on simple fetch/toggle turns.

    stepProviderOptions: ({ activeTools }) =>
        activeTools?.some((t) => CODE_EXEC.has(t))
            ? { openai: { reasoningEffort: 'medium' } }
            : undefined,
    systemPrompt?: string | SystemPromptSectionOverrides

    Either a full prompt string that replaces the default entirely, or a SystemPromptSectionOverrides map whose entries override individual sections of the built-in prompt (omitted sections keep their defaults).

    To extend a single section rather than replace it, read its default from the exported SYSTEM_PROMPT_SECTIONS map and override with a derived value (e.g. responseFormatting: `${SYSTEM_PROMPT_SECTIONS.responseFormatting}\n- Answer in Spanish.` ).

    A full string ignores systemPromptPrefix and systemPromptSuffix; section overrides still honor both.

    systemPromptPrefix?: string

    Text prepended above the whole prompt as a preamble, separated by a blank line and carrying no heading. Applied on top of the base prompt or section overrides; ignored only when systemPrompt is a full replacement string.

    systemPromptSuffix?: string

    Additional text appended under an ADDITIONAL INSTRUCTIONS heading. Applied on top of the base prompt or section overrides; ignored only when systemPrompt is a full replacement string.

    tools?: { [K in ToolNameHint]?: ToolEntry<CS> | false }

    Tool overrides merged with default tools.

    • ToolEntry values add a new tool or replace a default.
    • false values exclude a default tool.

    When omitted, all default tools are used as-is.

    // Add a custom tool (defaults included automatically)
    createMapAgent(map, {
        model,
        tools: { getCustomLocation: myTool },
    });

    // Remove a default tool
    createMapAgent(map, {
        model,
        tools: { setLanguage: false },
    });

    Settings

    Member Visibility

    On This Page

    Properties