TomTom Maps for JavaScript
    Preparing search index...

    Type Alias MapAgentOptions<CS>

    Options for creating an agent toolkit.

    interface MyState extends ToolState {
        fleet: FleetState;
    }

    createMapAgent<MyState>(map, {
        model,
        state: { fleet: new FleetState() },
    });
    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]?: ToolDefinition<CS> | false };
    }

    Type Parameters

    • CS extends ToolState = ToolState

      Full state type. Must extend ToolState. Defaults to base ToolState (no custom slices).

    Index
    byod? classifier? codeExecution? dataEntries? featureFlags? includeDefaultTools? maxSteps? model onClassify? onToolExecute? outputSchemas? prepareStep? providerOptions? state? stepProviderOptions? systemPrompt? systemPromptPrefix? systemPromptSuffix? tools?
    byod?: { validateSourceUrl?: ByodSourceUrlValidator }

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

    Type Declaration

    • OptionalvalidateSourceUrl?: ByodSourceUrlValidator

      Authorises each addByodSource URL before it is fetched (see ByodSourceUrlValidator). Return { valid: true } to allow or { valid: false, reason } to block (sync or async). It 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 the data tools' sandbox execution (see CodeExecutionConfig). The environment, not this option, chooses where the code runs (off-thread iframe-worker in the browser, main thread in Node/SSR). 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 its slice-specific display / fetch tools (TOOLS_BY_DATA_ENTRY_KIND) are dropped from the registry. recallState stays. 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 }, // drops addByodSource, setByodLayers, updateByodDisplay + byod scope on analyse/process
            ranges: { enabled: false }, // drops findReachableAreas
        },
    });
    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

    Maximum multi-step tool loop iterations. Defaults to 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, since built-in slices are created automatically. Custom tools read them in 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 honour both.

    systemPromptPrefix?: string

    Text prepended above the whole prompt as a preamble, separated by a blank line and carrying no heading. It applies on top of the base prompt or section overrides, unless systemPrompt is a full replacement string.

    systemPromptSuffix?: string

    Additional text appended under an ADDITIONAL INSTRUCTIONS heading. It applies on top of the base prompt or section overrides, unless systemPrompt is a full replacement string.

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

    Tool overrides merged with default tools.

    • ToolDefinition values (a ToolEntry, a builder, or a DEFAULT_TOOLS value) 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