# Build an AI-powered map application

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](https://docs.carto.com/carto-user-manual/overview/creating-your-carto-organization) with at least one [connection](https://docs.carto.com/carto-for-developers/key-concepts/connections) to a data warehouse
* [CARTO AI](https://docs.carto.com/carto-user-manual/settings/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

```bash
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:

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

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

```bash
npm run dev
```

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

{% hint style="info" %}
All backends speak the same WebSocket protocol, so **any frontend works with any backend**. You can switch backends without changing the frontend code.
{% endhint %}

## 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:

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

Edit `.env` with your CARTO credentials ([API Base URL](https://docs.carto.com/carto-user-manual/developers/managing-credentials/api-base-url) and [API Access Token](https://docs.carto.com/carto-for-developers/key-concepts/authentication-methods/api-access-tokens)), then:

```bash
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:

```bash
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:

```typescript
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:

```typescript
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](https://deck.gl/docs/api-reference/json/overview) 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](https://docs.carto.com/carto-for-developers/key-concepts/ai-powered-map-interaction) in our key concepts section
* Check the [Library API Reference](https://github.com/CartoDB/carto-agentic-deckgl/blob/main/LIBRARY.md) for the full list of exports and types
* Explore the [frontend examples](https://github.com/CartoDB/carto-agentic-deckgl/tree/main/examples/frontend) and [backend examples](https://github.com/CartoDB/carto-agentic-deckgl/tree/main/examples/backend) for implementation details specific to each framework and AI SDK