Defining your Agent logic

CARTO AI Agents adapt to your specific geospatial needs through two key configuration fields that define their logic and behavior. Effective Agent logic combines a focused use case with comprehensive Instructions.

The Agent Config Assistant can generate and refine your Use Case and Instructions through conversation. Use it to create, iterate, and optimize your Agent logic — then refer to this page to understand the structure and best practices behind the generated configuration.

Understanding agent logic components

• Use Case: A concise mission statement defining your Agent's primary goal and target audience

• Instructions: Detailed rules, tasks, and contextual knowledge that guide the Agent's behavior

When properly configured, these fields work together to ensure your Agent produces accurate, reliable, and actionable insights for both technical analysts and non-technical users.

Use Case and Instructions cover your Agent's behavior, and can override some of the default agent behaviors added by CARTO. What your data means such as field and metric definitions, and how datasets relate, belong in the semantic model.

Crafting the Use Case

The Use Case field contains your Agent's mission statement, a focused description of what the Agent achieves and who benefits from the results.

Best practices for the Use Case field

• Keep it concise but complete (2-4 sentences).

• Include three elements:

  • Target users and decision makers.

  • Specific analytical goal.

  • Business outcomes and measurable impact

Example:

Enable expansion managers to identify optimal store locations by analyzing demographic data, competitor presence, and foot traffic. The Agent should rank potential sites by revenue potential and provide market penetration maps for executive approval.

Writing Instructions

Instructions are your Agent's detailed playbook the comprehensive guide that defines how it behaves and the analytical steps it follows. Write your Instructions in Markdown format for better structure and readability.

Instructions Sections

Your Instructions should include these key sections, each serving a specific purpose in guiding the Agent's behavior.

1. Context & Constraints

Define operating boundaries and limitations to keep your Agent focused and reliable.

# Context & Constraints
- Geographic scope: Greater Toronto Area only
- Temporal range: Last 24 months of data
- Privacy: Minimum aggregation of 5 units
- Authority: Recommend only, cannot execute changes

2. Behavior

Define the Agent's communication style and output preferences.

# Behavior
- Always lead with business impact in dollars or percentage
- Include confidence levels for all predictions
- Default to quarterly comparisons unless specified

3. Data definition

Describe the key datasets and fields using $ to reference fields from your connected sources.

# Data Definition
- $site.location_id: unique identifier for each site
- $site.monthly_revenue: gross revenue in USD
- $site.visitor_count: monthly unique visitors
- $site.competition_density: competitors per square kilometer
- $site.accessibility_score: transit and parking availability (1-10)

4. Reasoning framework

Define how your Agent analyzes problems and makes decisions.

# Reasoning Framework
- Prioritize locations by: revenue potential > market gap > accessibility
- Minimum viability: $50K monthly revenue potential
- Confidence levels: High (>85%), Medium (60-85%), Low (<60%)
- For tied scores: prefer locations with lower competition
- Always validate against similar successful locations

5. Tasks & flows

Describe operational capabilities.

Tasks are atomic, reusable actions:

## Task: Calculate Market Potential
1. Query demographic data within trade area
2. Apply spending power coefficients
3. Adjust for local competition
4. Return monthly revenue estimate

## Task: Assess Site Accessibility  
1. Count transit stops within walking distance
2. Calculate parking availability ratio
3. Measure traffic flow patterns
4. Return accessibility score (1-10)

Flows are multi-step sequences where each step depends on the previous:

## Flow: Site Selection Analysis
1. Validate address and trade area boundaries
2. Calculate Market Potential (Task) → Revenue forecast
3. Assess Site Accessibility (Task) → Customer access
4. Query competitor locations within 3km
5. Compare metrics to top 10% performing stores
6. Generate scoring:
   - Green (recommend): All metrics above threshold
   - Yellow (conditional): Review specific concerns
   - Red (avoid): Multiple below-threshold metrics
7. Add layer style by score, including tooltip for 3-year projection

6. Handling specific scenarios

Define edge cases and error handling.

# Handling Specific Scenarios
- If trade area overlaps water: Adjust population catchment
- If no demographic data: Use county-level averages with disclaimer
- If competitor data outdated (>6 months): Flag in confidence score
- If multiple geocoding matches: Present options ranked by confidence

7. Example questions

Seed the Agent with natural queries aligned to your Use Case.

# Example Questions

Q: "Find the top 5 expansion opportunities in California"
Expected Output: 
- Ranked table with locations, scores (1-10), and key metrics
- Add styled layer (green=high, yellow=medium, red=low)
- Revenue projections for each site
- Recommendation summary with investment required

Best Practices

Write with precision

• Use imperative verbs: filter, calculate, rank, visualize

• Reference tools with /: /execute_query, /add_layer

• Reference fields with $: $sites.revenue, $sites.location_id

The / shortcut provides simplified names for:

• All Core Tools available in CARTO for your Agent

• Any MCP Tools you've added to your Agent (these appear with the same name)

While the / notation shows all Core Tools and your added MCP Tools, not all may be accessible to your Agent. Tool availability still depends on:

• Your map configuration (widgets and parameters must exist to be filtered/accessed)

• Enabled capabilities (e.g., /execute_query requires "Query sources" to be enabled)

Scope to your Use Case

• Include only relevant fields and flows

• Remove generic instructions that don't apply

• Focus on your specific business logic

Test and iterate

• Start with core functionality

• Test with real user queries

• Add edge cases as discovered

• Refine based on feedback patterns

Quick-start template

Copy and customize this template to get started quickly:

# Context & Constraints
- Scope: [Your markets/regions]
- Temporal range: [Temporal focus]
- Authority: [What agent can/cannot do]

# Behavior
- Audience: [User expertise level]
- Visualization priority: [Map/table/chart]
- Language style: [Technical/business/simple]
- Default assumptions: [Time period, filters]

# Data Definition
- $[key_metric]: [description and units]
- $[location_field]: [description]
- $[category_field]: [description]
- $[time_field]: [format and timezone]

# Reasoning Framework
- Analysis priority: [What matters most]
- Decision thresholds: [Key cutoff values]
- Confidence calculation: [How to assess certainty]

# Tasks & Flows

## Task: [Analyze Component]
1. Query specific data
2. Apply business logic
3. Return processed result

## Flow: [Complete Workflow]
1. Setup and validation
2. [Task 1] → First analysis
3. [Task 2] → Second analysis
4. Combine results
5. Generate recommendations
6. Create visualizations

# Handling Specific Scenarios
- If [common edge case]: [resolution]
- When [data issue]: [fallback approach]
- For [user variation]: [how to handle]

# Example Questions
- "[Primary use case question]"
- "[Location-specific query]"
- "[Comparison analysis]"
- "[Trend or temporal query]"