Spatial Agent

The Spatial Agent is FSQ Spatial Desktop's built-in AI assistant, purpose-built for geospatial analysis. Instead of writing SQL by hand, you describe what you want in natural language and the Spatial Agent explores your data, fetch geospatial data from , writes queries and create reports. All queries run against your project's DuckDB instance on your machine. Only prompts and small metadata leave the app.

Opening the Spatial Agent

1. Click the Spatial Agent icon in the side panel (or use the keyboard shortcut).
2. The chat panel opens on the right.
3. Type a question or instruction in natural language.

What the Spatial Agent Can Do

The Spatial Agent has direct access to your project data, DuckDB with the spatial and H3 extensions, the Foursquare H3 Hub, and a set of specialized tools. It can:

• Query your data — Run SQL against your local tables and return results as tables or charts.
• Analyze datasets — Explore, explain, summarize, and identify patterns, trends, and anomalies in your data.
• Create map layers — Turn any query result into a Point, Heatmap, H3, Polygon, or 3D layer with appropriate styling.
• Look up Foursquare Places, H3 Hub, Overture — Access public datasets like population, weather, find POIs, categories, and place metadata.

Example Prompts

Real-world data:

• "Get all restaurants in downtown Chicago from Foursquare Places."
• "Show me the population density of Manhattan using H3 Hub data."
• "Fetch the building footprints for central Tokyo."

Exploration:

• "What columns are in my trips table?"
• "Show me the top 10 pickup neighborhoods by trip count."
• "Are there any duplicates in stores?"

Visualization:

• "Show all earthquakes as a heatmap colored by magnitude."
• "Aggregate my customers into H3 resolution 8 cells and color by average spend."
• "Plot San Francisco buildings as a 3D extrusion using the height column."

Spatial analysis:

• "How many stores are within 500 meters of a subway station?"
• "Which census tracts have the highest sales?"
• "Draw a 10-minute driving isochrone around each hospital."

Chat Interface

The chat sidebar surfaces a few features worth knowing about:

• Chat context badge — Controls which maps the Spatial Agent uses as chat context. When you start a new chat, the currently active map is automatically selected as the primary map (shows an blue) when you send your first prompt. You can add additional maps with the + button for analysis and context, but the Spatial Agent always creates new layers in the primary map. Chat context badges can be reordered, and the first chat in the row will be selected as primary.

  

• Context consumption indicator — Tracks how much of the model's context window your conversation is using. When it exceeds the safe threshold, the icon turns into a red circle. Click it to start a fresh chat that automatically inherits a summary of the current conversation.

• Fork conversation — Duplicates the current chat with all previous messages, useful for exploring a variation without losing your original thread.

• Suggested questions — At the start of a chat, suggestions are static examples. Once a chat is underway, click the lightbulb icon to get context-aware follow-up suggestions based on your current data and conversation.

• Recent chats — Open recent conversations from the button in the top-left of the chat sidebar.

  

• Search chats — Press Ctrl/Cmd + F inside the chat sidebar to search across your conversations.

  

Settings

Configure Spatial Agent behavior from the settings panel in the left sidebar

• Max tool steps — Maximum number of tool calls the orchestrator can make in a single turn (each SQL query, layer creation, or lookup counts as one step). Increase for complex, multi-step analyses.
  creation, or lookup counts as one step). Increase for complex, multi-step analyses.
• Additional instructions — Text automatically injected into every chat session, so you don't have to repeat guidance ("always use metric units", "prefer H3 resolution 8", etc.).
• Instructions file — Upload a Markdown file whose contents replace the additional-instructions text. When present, the uploaded file overrides the text field.

Best Practices

• Say "continue" if the Spatial Agent stops mid-task. If a response is cut short or a tool call fails, replying with continue prompts the Spatial Agent to resume where it left off.
• Start a new chat for unrelated work. Long conversations grow the context window and slow the Spatial Agent down. For a new question that doesn't build on the current thread, open a fresh chat.
• Watch the context consumption icon. When it flips to an X, click it to migrate into a summarized new chat before running into context limits.
• Fork to branch your analysis. When you want to try a different approach without losing progress, fork the conversation instead of overwriting it.
• Attach only the maps you need. Add extra maps to the chat context only when the Spatial Agent needs to read from them — more context means slower responses and higher token usage.

Tip: Conversations are stored inside your project file, so you can return to previous analysis sessions or share them with collaborators by exporting the project.

Budget usage

Spatial Agent requests are billed against your subscription type budget. Open Settings in the left sidebar, then select the Account tab.

When your budget is exhausted, Spatial Agent responses stop and the chat shows a budget-exceeded message with your current cost and max budget.

Manage Subscription — Opens the billing portal to upgrade or change your plan (and increase available AI budget).

Tip: Check AI usage before long multi-step analyses. Complex prompts with many tool calls consume budget faster than simple questions.