Understanding Agent behavior
Your AI Agent operates within a structured framework designed by CARTO that determines how it interprets and responds to queries. This agentic framework helps AI Agents navigate the map, gather context, and use tools to deliver geospatial insights for your use case.
Understanding this framework will help you write more effective instructions and make agent behavior more predictable.
How instructions work together
The agent follows a three-tier hierarchy:
System guardrails (managed by CARTO, cannot be overridden): Security constraints and tool availability checks.
Core instructions (managed by CARTO, default behaviors): Built-in geospatial reasoning patterns.
Your instructions (managed by you, can override default behaviors): Your Use Case and Instructions from the configuration panel.
Your instructions override Core Instructions but cannot bypass System guardrails.
Core instructions: default agent behaviors
Your AI Agent comes with built-in intelligence about how to handle geospatial queries and interact with map elements. These default behaviors ensure consistent, predictable responses across all agents while allowing your custom instructions to override them when needed.
These are the default agent behaviors that we've included in our Core Instructions, available even when you don't provide any instruction.
Spatial context (area of interest)
The agent automatically determines the user's area of interest:
If the user explicitely mentions an administrative boundary, such as "Texas": In this case, the agent will retrieves the area of interest from the map data sources when possible, and will geocode it otherwise.
If the user provides a specific address, such as "123 Main Street, Anytown, CA 90210": The agent will geocode the address and will display the output (point) as a new layer in the map.
If the user mentions parts of the screen or region in the map: Then, the agent will use the area of the map visible in the screen, or any drawn mask polygon when user mentions "this region", "drawn area", etc.
If the user does not specify an area of interest: In this case, the agent will default to the current visible area of the map, or a drawn polygon if exists, as the area of interest.
Map configuration awareness
The agent automatically understands your map's structure and available elements:
Data Sources: The agent knows all about your map data sources, connection names, schemas, and spatial columns
Layers: It recognizes existing layers with their styles, labels, and properties
Widgets: It identifies available widgets including their types, data sources, and operations
SQL Parameters: The agent understands SQL parameters in your map, and the values used at any point in time
Map settings for viewers: The agent is aware of viewer tools like the search input, basemap options, and drawing capabilities
The agent only references and interacts with elements that either existed already in your map, or elements that it creates during the session.
Tool selection logic
In our core instructions, we've embedded set of preferences and priorities for the agent:
Filtering: The agent prefers filtering via SQL parameters over widgets when both available.
Analysis: The agent uses SQL queries for complex calculations if available, and uses existing widgets for quick insights.
Visualization: The agent automatically adds layers to the map after doing calculations or when obtaining results.
Navigation: The agent auto-zooms to new layers and filtered results.
For clarity, the agent can only reference and interact with elements that exist in your configuration or that it creates during the session.
Response patterns and style
We embedded a few conversational style instructions for the agent. Remember you can always override this style in your custom instructions.
Give direct insights without conversational padding.
Use markdown formatting with bullets and tables.
Suggest next actions only when tools support them.
Translate technical concepts: no H3/quadbin jargon.
Last updated
Was this helpful?