# 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](/carto-for-developers/key-concepts/data-sources.md), [layers](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl), and [authentication](/carto-for-developers/key-concepts/authentication-methods.md) 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](/carto-for-developers/guides/build-an-ai-powered-map-application.md)
* [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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/carto-for-developers/key-concepts/ai-powered-map-interaction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.