AI-powered map interaction

With @carto/agentic-deckgl, you can add natural language interaction to your CARTO + deck.gl applications. Users type messages in a chat interface, and an LLM translates them into tool calls that manipulate the map — adding layers, navigating to locations, placing markers, and applying spatial filters.

The library is framework-agnostic and works with any JavaScript frontend. It builds on the same data sources, layers, and authentication you already use.

How it works

User message --> Frontend (WebSocket) --> Backend server
                                              |
                                    AI SDK (streaming + tool calling)
                                              |
                              text chunks + tool_call messages
                                              |
                Frontend: display text + execute tool calls
                                              |
                              deck.gl state update --> map renders

The library provides the backend with tool definitions and a system prompt so the LLM knows how to control the map. When the user sends a natural language message, the LLM generates tool calls that the frontend executes to update the deck.gl state.

The AI never accesses your data directly. It generates deck.gl JSON specifications that the frontend renders using the same CARTO data sources and layers your application already uses.

Consolidated tools

The AI controls the map through 3 tools:

Tool	Description
set-deck-state	Full deck.gl state control: navigation, basemap, layers, widgets, and effects. Layer updates are deep-merged by ID, so partial updates preserve existing properties.
set-marker	Places a location marker pin at specified coordinates. Markers accumulate across calls; duplicates at the same position are skipped.
set-mask-layer	Editable mask layer for spatial filtering. Set a GeoJSON geometry or CARTO table name, enable draw mode, or clear. When active, all data layers are clipped to the mask area via MaskExtension.

What the library provides

@carto/agentic-deckgl is an isomorphic TypeScript library (works in both Node.js and browser) with the following modules:

• Tool definitions — Zod schemas for each tool, ready to be passed to an AI SDK.

• System prompt builder — Generates a prompt that includes tool instructions, current map state, and optional user context (country, business type, etc.).

• SDK converters — Adapters that convert tool definitions for OpenAI Agents SDK, Vercel AI SDK, and Google ADK.

• Schemas — deck.gl JSON validation for layers and view state.

• Response utilities — Parsing and formatting helpers for tool execution results.

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

Tree-shakeable subpath exports are also available:

import { ... } from '@carto/agentic-deckgl/definitions';
import { ... } from '@carto/agentic-deckgl/prompts';
import { ... } from '@carto/agentic-deckgl/converters';
import { ... } from '@carto/agentic-deckgl/schemas';
import { ... } from '@carto/agentic-deckgl/executors';

Get started

• Follow our guide: Build an AI-powered map application

• Library API Reference

• @carto/agentic-deckgl on Github

• @carto/agentic-deckgl on NPM