AI Agent for QGIS: The Complete Guide
AI Agent is a chat panel inside 
. You describe the task. It does the work in the project you already have open, with your layers, your CRS, your selection and the extent on screen. We build it, so this guide is about our own tool.
It covers what the agent produced in one sitting, how to install it, your first run, and the three things that keep it under control.
Three prompts, one project
Everything below came out of a single conversation, starting from an empty QGIS. Each caption opens with the sentence that produced it. Nothing was touched by hand.
Install and sign in
In QGIS, open Plugins -> Manage and Install Plugins, search for AI Agent, and click Install. It runs on QGIS 3.28 and later, QGIS 4 included, on Windows, macOS and Linux.
Open the panel from the TerraLab toolbar and click Sign in / Sign up. Your browser opens, you create an account, and the plugin connects itself. No API key, no credit card, ten free runs to start.
Your first run
Describe the result, not the procedure
“Colour the buildings by height” beats “open the properties, pick a graduated renderer, choose the height field”. The agent reads the project before it acts, so naming layers, fields and paths is usually wasted typing.
Read the steps, not just the answer
A grey line under your message counts the work: 4 steps, 39.6s. Unfold it and every tool call is there, with its arguments and what came back. This is how you tell a good result from a plausible one.
Answer when it asks
A run can stop on a small card with two to four options. Ours asked twice: the view held 6,355 OSM features, and only 117 of 3,124 buildings carried a height tag. Both were real forks in the work, and both stay visible in the trace afterwards.
Check what changed
Chips under the answer name the layers the run created or touched. Click one for the usual QGIS menu: show in the Layers panel, zoom to it, open the attribute table, layer properties.
One prompt is one run, however many QGIS steps it takes. A run stops itself at 60 tool calls or 40 minutes, so a task that has gone sideways cannot run all afternoon.
What it reaches
Data. Local files, remote files, WFS, WMS, XYZ, STAC and COG imagery, OpenStreetMap extracts, geocoding, routing. Drop a GeoPackage on the panel and it loads as a layer.
Analysis. Any Processing algorithm, with the parameter names and the known pitfalls looked up rather than guessed. Buffers, joins, zonal statistics, topology checks, isochrones from OSM roads, elevation profiles along a line.
Cartography. Symbology, categorized and graduated renderers, labels, print layouts with a map, a legend, a scale bar and a north arrow, then an export to PDF or PNG.
Editing. Adding, updating and deleting features, geometry repair, vertex edits, merges and splits, inside a real QGIS edit session you can roll back.
Answers. Where a QGIS setting lives, and how to do the thing by hand, from the official documentation, with the link. Ask how to fix invalid geometries and you get an answer, not a run.
Open data is its own skill. The agent carries a catalogue of about 190 sources with the licence, the attribution line and the coverage of each, so “can I use it commercially” comes back with a licence name instead of a guess.
If AI Edit or AI Segmentation is installed, the agent drives those too: transform imagery from a prompt, or vectorize every instance of an object inside a zone.
It checks its own work
At Medium effort and above, the agent renders the map and looks at what it produced. In the layout run it did exactly that, decided the result was not readable, and fixed the drawing order before finishing.
That behaviour is worth watching in both directions. It reported that only 186 of 3,124 buildings had a usable height instead of quietly styling a field full of nulls. It can also be confidently wrong. The trace stays the thing to read.
Staying in control
Three things sit between the model and your project.
The permission chip, next to the + in the composer, decides when it stops to ask.
| Level | It asks before |
|---|---|
| Ask first | Every change |
| Balanced (default) | Deleting and overwriting |
| Autopilot | Nothing, except spending credits and running Python |
Autopilot is a session choice: restart QGIS and you are back on Balanced, whatever you picked last time. Two things ask at every level, Autopilot included: anything that spends credits, and running raw Python, which you see before it runs.
The approval card is what asking looks like. One sentence saying what is about to happen, your answer, then it collapses to a single line so a long run stays readable.
Undo. Every run leaves a checkpoint. The arrow in the panel header opens the list, newest first, with the row your project is on ticked.
Pick a row and the project goes back to it. The restore saves the state it is leaving first, so it can itself be undone, and Ctrl+Alt+Z steps back without opening anything.
Giving it the right context
The agent already reads the project: layer names, types, CRS, feature counts, field names, extents, the canvas, your selection. What you add is what it cannot see.
- Attach a photo or a data file, or a layer of this project.
- Drag a layer straight from the QGIS Layers panel onto the chat.
- Drop files anywhere on the panel: data loads as a layer, pictures go to the model.
- Type
@to name a data source or one of your installed QGIS plugins inside the message.
Each project keeps its own chats. The magnifier in the header searches them by title and by message text, and any chat exports as Markdown.
The two settings worth changing
Effort, the chip before Send, is not a model picker. It names how much thinking you are buying.
| Level | What it does | Plan |
|---|---|---|
| Instant | Starts working straight away. No planning, no research | Free |
| Medium | Plans, checks its results, looks up algorithms and documentation | Pro |
| High | Deeper planning, research and independent direction on hard tasks | Pro |
Instant suits “what CRS is this project in” and a single styling change; it is what produced the ten-second run in the video above. Medium produced everything else in this guide, questions and self-checks included. High is for the task you would otherwise have blocked out an afternoon for.
Connectors, the first page of Settings, decides where data comes from. Thirty-nine sources, ten on by default: OpenStreetMap, Overture, Natural Earth, NASA, Copernicus, the Planetary Computer, the national mapping agencies, and more. Each states what it needs before you switch it on, and most need nothing at all.
Your installed QGIS plugins get rows on the same page, so the agent can reach them by name.
Personalisation is the other page worth a visit: what the AI should call you, what you do, a paragraph about your work, standing instructions, your GIS experience, metric or imperial, how new layers should be named, and the notes it keeps between chats.
What leaves your machine
Every message goes to our hosted service.
Sent. Your request. A description of the project: CRS, extent, and per layer the name, type, geometry type, visibility, feature count, field names and extent, plus one sample row of the active layer. The project file path, your recent Processing runs, the newest QGIS warnings, and whatever you attached.
Not sent. The contents of your raster and vector files, the project file itself, feature geometries, whole attribute tables, and any project you have not asked about. Your activation key never appears in a tool result, and database passwords inside layer URIs are scrubbed from every result and traceback.
Free vs Pro
| Free | Pro, 49 EUR / month | |
|---|---|---|
| Runs | 10 a month | 250 a month |
| Effort | Instant | Instant, Medium, High |
| Tools, connectors, plugins | All | All |
| Memory and standing instructions | No | Yes |
| Use | Personal | Commercial |
Nothing is metered per tool call. The 60-step run and the 3-step run cost the same.
Questions
Can it break my project?
It changes it, which is the point, and the change is reversible. Balanced asks before anything destructive, and the run checkpoint puts the project back even after you approved something you should not have. Save your project before a long session anyway, the way you would before any batch of edits.
Does it write Python into my QGIS?
It can run Python when a task needs it, and that is the one thing every level asks about, Autopilot included. You see the code before it runs.
What happens when it is wrong?
It is a language model, so it can be wrong, and confidently. That is what the activity block is for: unfold it, look at the arguments it chose and the counts that came back. Our own run said only 186 of 3,124 buildings had a usable height, which is the kind of line worth reading before you trust the map.
How long does a run take?
Seconds for a question, minutes for real work. In this guide: ten seconds for the basemap at Instant, 43 at Medium, 6 minutes 30 for the buildings and their height ramp, 2 minutes 37 for the layout, under a minute for each question. QGIS stays usable while a fetch runs.
Does it work offline?
No. There is no local model and no offline mode. The plugin runs on your machine, the model runs on ours.
Is my data used to train a model?
No. The service plans the QGIS steps, and nothing else.
Is it open source?
The plugin is, under GPL-2.0-or-later: the tool executor, the permission model, the file and network guards, the panel. So what runs on your computer is auditable in full. The hosted service, its prompt and the open data catalogue are not.
What to remember
- Describe the result, not the procedure. It reads the project first, so naming layers and paths is usually wasted typing.
- The activity block is the product. Unfolding it is how you tell a good result from a plausible one.
- Every run leaves a checkpoint, and a restore can itself be undone, so approving something you regret is not a dead end.
- Effort buys planning and checking, not a different personality. Instant answers, Medium works and verifies, High thinks first.
- Connectors decide what it can find. Turning on your national mapping agency is worth more than any prompt wording.
