Build an AI-powered map application

Add natural language map interaction to your CARTO + deck.gl application using AI-powered tool calling

Here you will learn how to set up an application where users interact with a CARTO + deck.gl map through natural language chat. The AI translates user messages into tool calls that manipulate the map — adding layers, navigating, placing markers, and applying spatial filters.

After completing this guide you will be familiar with the following concepts:

• Installing and building @carto/agentic-deckgl

• Configuring a backend server that connects to an AI model

• Starting a frontend that renders the map and chat interface

• Integrating the library into your own application

Prerequisites

• A CARTO organization with at least one connection to a data warehouse

• CARTO AI enabled in your organization settings (this provides the AI provider API keys used by the backend)

• Node.js 18+ installed

Clone and build the library

git clone https://github.com/CartoDB/carto-agentic-deckgl.git
cd carto-agentic-deckgl
npm install && npm run build

Start a backend

The repository includes backend implementations for three AI SDKs. Pick the one that matches your stack:

Backend	Directory	AI SDK
OpenAI Agents SDK (default)	examples/backend/openai-agents-sdk/	@openai/agents
Vercel AI SDK	examples/backend/vercel-ai-sdk/	Vercel AI SDK v6
Google ADK	examples/backend/google-adk/	@google/adk

All backends use the same environment variables and run on port 3003. To start the OpenAI Agents SDK backend:

cd examples/backend/openai-agents-sdk
npm install
cp .env.example .env

Edit .env with your CARTO AI configuration, then start the server:

npm run dev

The server will be available at http://localhost:3003.

All backends speak the same WebSocket protocol, so any frontend works with any backend. You can switch backends without changing the frontend code.

Start a frontend

The repository includes reference frontends for four frameworks, all implementing the same chat-to-map experience:

Framework	Directory	Start command	URL
Angular 20	examples/frontend/angular/	pnpm start	http://localhost:4200
Vue 3	examples/frontend/vue/	pnpm dev	http://localhost:5174
React 19	examples/frontend/react/	pnpm dev	http://localhost:5173
Vanilla JS	examples/frontend/vanilla/	pnpm dev	http://localhost:5173

For example, to start the React frontend:

cd examples/frontend/react
pnpm install
cp .env.example .env

Edit .env with your CARTO credentials (API Base URL and API Access Token), then:

pnpm dev

Open the URL in your browser. You should see a map with a chat interface. Try typing a message like "Show me counties in California colored by population" to verify everything works.

Integrating in your own application

Once you've verified the example works, you can integrate the library into your own CARTO + deck.gl application. Install it from NPM:

npm install @carto/agentic-deckgl

Backend integration

On the server side, use the library to build the system prompt and convert tool definitions for your AI SDK:

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

// Build the system prompt with the current map state
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: [],
  },
});

// Get tool definitions in the format your AI SDK expects
const tools = getToolsForVercelAI();

Frontend integration

On the client side, use the response utilities to handle tool calls from the AI:

import { parseToolResponse, isSuccessResponse } from '@carto/agentic-deckgl';

websocket.on('tool_call', async (message) => {
  const result = await executeToolOnMap(message.tool, message.parameters);
  const parsed = parseToolResponse(result);

  if (isSuccessResponse(parsed)) {
    console.log('Tool executed:', parsed.message);
  }
});

The tool calls generate deck.gl JSON specifications. Use JSONConverter from @deck.gl/json to resolve them into deck.gl layers and props.

What's next?

• Read about AI-powered map interaction in our key concepts section

• Check the Library API Reference for the full list of exports and types

• Explore the frontend examples and backend examples for implementation details specific to each framework and AI SDK