# AI-powered map interaction

With `@carto/agentic-deckgl`, you can add **natural language interaction** to your [CARTO + deck.gl](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-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](https://docs.carto.com/carto-for-developers/key-concepts/data-sources), [layers](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl), and [authentication](https://docs.carto.com/carto-for-developers/key-concepts/authentication-methods) 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](https://deck.gl/docs/api-reference/json/overview) 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](https://github.com/openai/openai-agents-js), [Vercel AI SDK](https://sdk.vercel.ai/), and [Google ADK](https://google.github.io/adk-docs/).
* **Schemas** — deck.gl JSON validation for layers and view state.
* **Response utilities** — Parsing and formatting helpers for tool execution results.

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

Tree-shakeable subpath exports are also available:

```typescript
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](https://docs.carto.com/carto-for-developers/guides/build-an-ai-powered-map-application)
* [Library API Reference](https://github.com/CartoDB/carto-agentic-deckgl/blob/main/LIBRARY.md)
* [@carto/agentic-deckgl on Github](https://github.com/CartoDB/carto-agentic-deckgl)
* [@carto/agentic-deckgl on NPM](https://www.npmjs.com/package/@carto/agentic-deckgl)