@carto/agentic-deckgl

@carto/agentic-deckgl is a framework-agnostic TypeScript library that provides tool definitions, system prompt generation, and SDK converters for building AI-powered CARTO + deck.gl map applications. For an introduction to the concepts, see AI-powered map interaction.

Installation

npm install @carto/agentic-deckgl

Peer dependencies: @deck.gl/json (^9.2.0) and zod (^4.3.6).

buildSystemPrompt

Generates a system prompt for the AI agent, including tool-specific instructions, current map state, and optional user context.

Usage

import { buildSystemPrompt, TOOL_NAMES } from '@carto/agentic-deckgl';

const systemPrompt = buildSystemPrompt({
  toolNames: [TOOL_NAMES.SET_DECK_STATE, TOOL_NAMES.SET_MARKER, TOOL_NAMES.SET_MASK_LAYER],
  initialState: {
    viewState: { latitude: 40.7128, longitude: -74.006, zoom: 12 },
    layers: [{ id: 'my-layer', type: 'VectorTileLayer', visible: true }],
    activeLayerId: 'my-layer',
  },
});

Options

interface BuildSystemPromptOptions {
  toolNames: string[];          // List of tool names available to the agent
  initialState?: MapState;      // Current map state for context
  userContext?: UserContext;     // User context for business analysis
  semanticContext?: string;     // Pre-rendered data catalog markdown
  mcpToolNames?: string[];      // MCP tool names (enables MCP instructions)
  additionalPrompt?: string;    // Additional prompt text to append
}

• toolNames: The tools the agent is allowed to use. Use the TOOL_NAMES constant for type safety: TOOL_NAMES.SET_DECK_STATE, TOOL_NAMES.SET_MARKER, TOOL_NAMES.SET_MASK_LAYER.

• initialState (optional): The current map state, so the AI has context about what the user is viewing. Includes viewState (lat/lng/zoom/pitch/bearing), layers (array of layer state), and activeLayerId.

• userContext (optional): Business context such as country, business type, demographics, and proximity priorities. This shapes the AI's analytical responses.

• semanticContext (optional): A pre-rendered markdown string describing the available data tables and their columns. This is typically generated from a YAML-based data catalog.

• mcpToolNames (optional): When provided, the prompt includes MCP-specific instructions for the listed tool names.

• additionalPrompt (optional): Custom text appended to the end of the system prompt.

Supporting types

interface MapState {
  viewState?: MapViewState;
  layers?: LayerState[];
  activeLayerId?: string;
}

interface MapViewState {
  longitude: number;
  latitude: number;
  zoom: number;
  pitch?: number;
  bearing?: number;
}

interface LayerState {
  id: string;
  type?: string;
  visible?: boolean;
  [key: string]: unknown;
}

Helper functions

import { buildMapStateSection, buildUserContextSection } from '@carto/agentic-deckgl';

// Build just the map state portion of the prompt
const mapSection = buildMapStateSection({
  viewState: { latitude: 40.7128, longitude: -74.006, zoom: 12 },
  layers: [{ id: 'layer-1', type: 'VectorTileLayer' }],
  activeLayerId: 'layer-1',
});

// Build just the user context portion of the prompt
const userSection = buildUserContextSection({
  country: 'Spain',
  businessType: 'Retail',
});

Tool definitions

The library defines 3 tools, each with a Zod validation schema. These tools are what the AI calls to manipulate the map.

set-deck-state

Full deck.gl state control: navigation, basemap, layers, widgets, and effects.

// Parameters (all optional — include only what you want to change)
{
  initialViewState?: {
    latitude: number;       // -90 to 90
    longitude: number;      // -180 to 180
    zoom: number;           // 0 to 22
    pitch?: number;         // 0 to 85
    bearing?: number;       // -180 to 180
    transitionDuration?: number;
  };
  mapStyle?: 'dark-matter' | 'positron' | 'voyager';
  layers?: Record<string, unknown>[];      // deck.gl JSON layer configs
  widgets?: Record<string, unknown>[];     // deck.gl JSON widget configs
  effects?: Record<string, unknown>[];     // deck.gl JSON effect configs
  layerOrder?: string[];                   // layer IDs in render order
  removeLayerIds?: string[];               // layer IDs to remove
  removeWidgetIds?: string[];              // widget IDs to remove
}

set-marker

Places, removes, or clears location marker pins on the map.

{
  action: 'add' | 'remove' | 'clear-all';  // default: 'add'
  latitude?: number;    // required for add/remove
  longitude?: number;   // required for add/remove
}

set-mask-layer

Manages an editable mask layer for spatial filtering.

{
  action: 'set' | 'enable-draw' | 'clear';
  geometry?: GeoJSON;    // GeoJSON geometry (mutually exclusive with tableName)
  tableName?: string;    // CARTO table containing mask geometry
}

Accessing tool definitions

import {
  tools,
  getToolNames,
  getTool,
  getConsolidatedToolDefinitions,
  validateToolParams,
  TOOL_NAMES,
} from '@carto/agentic-deckgl';

// Get all tool names
const names = getToolNames();
// ['set-deck-state', 'set-marker', 'set-mask-layer']

// Get a specific tool definition
const deckTool = getTool(TOOL_NAMES.SET_DECK_STATE);

// Get all tools in OpenAI function calling format
const openAITools = getConsolidatedToolDefinitions();

// Validate parameters against a tool's schema
const result = validateToolParams(TOOL_NAMES.SET_MARKER, {
  action: 'add',
  latitude: 40.7128,
  longitude: -74.006,
});

SDK converters

Convert tool definitions into the format expected by each AI SDK. All converters return tool definitions with built-in Zod validation and a frontend tool marker, so the backend knows the tool should be executed on the client.

getToolsForOpenAIAgents

import { getToolsForOpenAIAgents } from '@carto/agentic-deckgl';

const toolDefs = getToolsForOpenAIAgents();
// Returns OpenAIAgentToolDef[] with name, description, parameters (Zod), execute

getToolsForVercelAI

import { getToolsForVercelAI, getToolsRecordForVercelAI } from '@carto/agentic-deckgl';

// As an array
const toolDefs = getToolsForVercelAI();

// As a record (for streamText({ tools: ... }))
const toolsRecord = getToolsRecordForVercelAI();

getToolsForGoogleADK

import { getToolsForGoogleADK } from '@carto/agentic-deckgl';

const toolDefs = getToolsForGoogleADK();
// Returns GoogleADKToolDef[] with name, description, parameters (Zod), execute

All converters accept an optional toolNames parameter to convert only specific tools:

const subset = getToolsForVercelAI([TOOL_NAMES.SET_DECK_STATE, TOOL_NAMES.SET_MARKER]);

Custom tool executors

The SDK converters provide default execute functions that validate parameters and return a frontend tool marker. On the frontend, you need a tool executor — a function that receives the tool name and validated parameters and applies them to your deck.gl map state.

The reference frontends in the repository each include a tool-executor that you can use as a starting point and customize for your application. The pattern is a factory function that maps each tool name to your own execution logic:

import { TOOL_NAMES } from '@carto/agentic-deckgl';

function createToolExecutor(deckActions) {
  const executors = {
    [TOOL_NAMES.SET_DECK_STATE]: (params) => {
      // Apply view state, basemap, layers, widgets, effects
      // to your deck.gl instance using params
      if (params.initialViewState) {
        deckActions.setViewState(params.initialViewState);
      }
      if (params.layers) {
        deckActions.updateLayers(params.layers);
      }
      return { success: true, message: 'State updated' };
    },

    [TOOL_NAMES.SET_MARKER]: (params) => {
      // Add, remove, or clear markers on your map
      return { success: true, message: 'Marker placed' };
    },

    [TOOL_NAMES.SET_MASK_LAYER]: (params) => {
      // Apply spatial mask geometry, enable draw mode, or clear
      return { success: true, message: 'Mask applied' };
    },
  };

  return async (toolName, params) => {
    const executor = executors[toolName];
    if (!executor) return { success: false, message: `Unknown tool: ${toolName}` };
    return executor(params);
  };
}

This is where you control exactly how each tool call affects your application — for example, how layers are merged, how markers are rendered, or how mask geometries are fetched from CARTO tables. See the frontend examples for complete implementations in React, Vue, Angular, and Vanilla JS.