> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-user-manual/maps/ai-assistant-in-builder.md).

# AI Assistant in Builder

The AI Assistant in Builder helps Editors create and refine maps by describing what they want. It finds the data in your connections, adds and styles the layers, and sets up widgets, popups and filters.

Use it to start a map from scratch, or to change a map you already have: restyle a layer, add a widget, or set up filters for your viewers.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-7a53d26961b60fb543ffc1aeeecec0fe6d88ea10%2Fai-assistant-in-builder.png?alt=media" alt="The AI Assistant in Builder next to a Hurricane Milton map with rainfall, affected places, the storm path, SQL parameters and floating widgets"><figcaption><p><em>A Hurricane Milton map built by the Assistant from one message</em></p></figcaption></figure>

### Enabling the Assistant

The AI Assistant in Builder is off by default. Admins turn it on from **Settings > CARTO AI** with the **AI Assistant in Builder** switch, where they also choose its default model. Learn more in the [CARTO AI](https://docs.carto.com/carto-user-manual/settings/carto-ai.md) documentation.

The Assistant is available to Editors. Viewers and guests don't see it.

### Getting started

1. Open a map in Builder, or create a new one.
2. Open the **Assistant** from the left bar.
3. Describe what you want: the data, the question the map should answer, and who will use it.

If you already know which table to use, attach it to your message with **Add data source**.

Map editing pauses while the Assistant works on your map, and you can stop it at any time.

### What you can ask

Anything you can do in Builder, you can ask for in the conversation. Add data and layers, change the style, set up widgets, popups and SQL parameters, or write the map description.

You can also use another map you have access to as a starting point, for example "build a map like our store coverage one, but for the new region".

{% hint style="info" %}
The Assistant asks before changes such as who can open the map.
{% endhint %}

### Versions

Every change the Assistant makes is saved in the map's [version history](https://docs.carto.com/carto-user-manual/maps/version-history.md), so you can go back at any point. Use the **Assistant versions** filter to see only its changes.

### Choosing a model

The Assistant uses the default model your Admin set. You can pick a different one in the message field. Changing the model starts a new conversation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.carto.com/carto-user-manual/maps/ai-assistant-in-builder.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
