# 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](/carto-user-manual/overview/creating-your-carto-organization.md) with at least one [connection](/carto-for-developers/key-concepts/connections.md) to a data warehouse
* [CARTO AI](/carto-user-manual/settings/carto-ai.md) 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](/carto-user-manual/developers/managing-credentials/api-base-url.md) and [API Access Token](/carto-for-developers/key-concepts/authentication-methods/api-access-tokens.md)), 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](/carto-for-developers/key-concepts/ai-powered-map-interaction.md) 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


---

# 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/guides/build-an-ai-powered-map-application.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.