Creating your Agent

To create an AI Agent, start with a map that represents your use case. Create a new map or adapt an existing one as needed.

Navigate to the AI tab to create your AI Agents (ensure CARTO AI is enabled in your organization). Click "Create AI Agent" to open the configuration dialog. Once you've provided at least the Use Case, you can save your Agent and test it using Test in Preview — Builder will switch to Preview mode so you can interact with the agent exactly as your viewers will.

Use the Agent Config Assistant to configure your Agent through conversation. Describe your goals, iterate on the configuration, and let the Assistant generate and refine the use case, instructions, model selection, tools, and more.

If your Agent will query data (see Query sources for insights / execute_query), we recommend adding a semantic model. It tells the Agent what your metrics mean, which keys to join on, and how your spatial data is structured, so it writes correct SQL and applies your definitions consistently.

Creating an AI Agent is an iterative process - you'll refine the map, adjust the Agent configuration, publish, and maintain your Agent to ensure all components work as expected.

Important considerations

Timeout limits:

• Synchronous Workflows MCP and query sources tools: 1 minute.

• Geocoding tool: 3 minutes.

• CARTO AI Service API: 5 minutes.

• Use asynchronous tools to overcome synchronous limitations.

Access considerations:

• Maps with QuerySources-enabled AI Agents cannot be made public.

• Enable QuerySources to access execute_query and add_source tools.

• When adding Workflows MCP Tools, you can inspect results from workflows.