How SpatialAgents work.

A chat runs as a chain of question and answer, and every answer is an endpoint.

A coding agent is not a language model but a working environment with a language model inside. The environment provides the tools: reading and writing files, running commands and looking things up. And it provides the loop, which leads from the task through the plan to a tool call, checks the result and returns to the plan.

Inside that loop the model plans, calls a tool and reads the result. If the first route fails, it tries another and plans again.

The loop ends at a checked, usable result or at a question to the person. A check alone does not end it, and after an answer it carries on.

A single run can take several hundred tool calls and last more than two hours without anyone intervening; permission is granted once at the start, not at every step.

Nobody has to build such an environment; they come ready-made.

A language model cannot carry anything out; it can only write. A tool call is therefore a message with a fixed structure that names the tool and its inputs, and the environment runs the tool and writes the result back.

That result lands in the context, the text the model has in front of it at every step. The context is limited.

It is measured in tokens. A token is a word or a part of a word, and a language model reads and writes in such units.

Every result takes up part of the context, so what counts is how much a tool gives back.

How much that adds up to depends on the model. On the same task the mean use of a single run ranges from three million to almost a hundred million tokens, and the higher figure does not mean the better map.

For geodata, such tools do not have to be built first; they have existed for decades.

Open-source GIS tools have one property that is decisive for agents: you operate them with text.

On the command line, GDAL and OGR read, write, reproject and clip geodata with a single command, and GRASS GIS brings its modules in the same form. QGIS Processing runs its geoalgorithms through the command qgis_process. Those algorithms in turn drive GDAL, the programming interface of QGIS or GRASS modules. Anyone who prefers Python writes the same work with PyQGIS as a script.

A coding agent writes exactly such commands, and no translator is needed in between, because the tool is already there.

What such a command produces is a file, called a layer in the trade, a single plane of data. A layer holds geometries or raster cells and their values, but it is not a picture yet. The map is made in QGIS, and that is a step of its own.

So one thing is still missing: the way to QGIS itself.

For an agent to operate an application, it needs a list of its tools. The Model Context Protocol, MCP for short, lays down how an application supplies that list.

Every entry names three things: the name of the tool, what it is good for and which inputs it expects.

An agent reads this list as soon as it starts. From then on it sits in the context, and it knows what the application can do.

For QGIS there is such a server, the SpatialAgents bridge. It offers 67 tools arranged in nine groups. They reach from opening a project and reading its state, through loading layers and querying their features, to the map, the print layout and longer-running jobs. The bridge runs as a process on the same machine as QGIS.

That settles which tools are available. How work is done in a project is written in a file of its own.

Before an agent works, it reads a file of instructions that lies in the project; each of the three coding agents knows such a file under its own name. It says how work is done in the project.

Four things are usually in it: the rules of the work, the layout of the directory, the available tools and the checks a result has to pass.

In SpatialAgents this domain context exists only once. Codex, Claude Code and OpenCode read the same text and work to the same rules, and changing the way of working means changing one file instead of three configurations.

That holds for the whole project. Domain knowledge for single tasks sits elsewhere and is loaded only when it is needed.

A skill is domain knowledge in a folder: a description, plus references and scripts. An agent system reads only the descriptions to begin with, and only when a task fits a skill does it load it into the context.

The gain lies in the context, because what is not loaded takes up no room.

Four skills belong to the system. The first describes the tools of the bridge, the second the styling of layers, the third the print layouts and the fourth the diagrams in the map.

The user says in ordinary language what they need, and the domain knowledge for it sits in the skill; nobody has to know QML or the internals of a layout.

That describes what an agent system knows. How it turns this into a plan for a large task is what agentic planning shows.

A hazard analysis for a city is not a single-step task. SpatialAgents break it down into four sub-tasks, namely obtain data, check geometries, compute indices and produce the map, and they lay this breakdown down as a plan. They work through the four sub-tasks one after another: three of them with Python or on the command line in the workspace, the map through the QGIS plugin and the bridge. The plan stays at the centre of the work and is carried forward after every partial result. A check that does not add up leads back to the task and produces a further step. The plan comes before the work begins.

The plan is approved. What happens then has three stations and a check.

First the tool loop runs: the coding agent calls tools, and files appear in the workspace. The workspace is the shared directory for SpatialAgents and QGIS, and computing there is done with Python and on the command line.

Then the bridge acts in QGIS, where the files become layers and the layers become a map.

At the end comes the check the plan names for this sub-task. The bridge fetches a screenshot and the details of the layers from QGIS, and if the result does not fit, it goes back into the loop.

The time is spread unevenly. For Opus, of a good forty minutes of runtime, more than two thirds went to the model on average, just under a third to geoprocessing and only a few seconds to QGIS.

How short the computing part turns out depends on the library it is done with.

The Geospatial API, Geo-API for short, is a Python library, written to be used by agents. One call fetches data, a second computes, and a third writes the result as a file.

Without it, the same work becomes a long chain of single steps, in which every step delivers an intermediate result and every intermediate result lands in the context.

Four properties lower the token cost. The calls are declarative and can be chained. How many features a query matches can be counted before anything is loaded. Error messages name the next sensible step. And the call goes straight out of Python or from the command line, with no detour through a tool wrapper.

The Geo-API was available in the runs of the measurement series.

That describes the computing part. The way back into QGIS runs through the plugin and the bridge.

The plugin makes the open QGIS project reachable for SpatialAgents. It opens a connection that is valid only on this machine and demands an access key.

Tool calls arrive through this connection, and the bridge turns them into QGIS operations: it loads layers, styles them, moves the map and builds print layouts.

Three things go back, namely the state of the project, the list of layers and an image of the map. That image is how a coding agent looks at its own result.

Two limits apply here. QGIS puts any step that changes the project to the user for confirmation, and no arbitrary program code runs in QGIS, only the declared operation.

The computing therefore happens somewhere else.

SpatialAgents separate two kinds of work: the control of QGIS and the computing with geodata.

Control runs through the bridge: loading layers, styling them, moving the map, building a print layout, fetching a screenshot.

Computing runs in the workspace: Python libraries, command-line tools, plus web search, downloading geodata and inspecting existing vector and raster data.

That has two consequences. QGIS stays usable, because no long computation holds up the interface. And every result lies there as a file that can be opened and recomputed independently of the project.

At one point the two lanes meet. A GeoPackage is created in the workspace, and the bridge loads it as a layer into the project.

One question is still open. Where the language model does its computing.

Which language model does the work is a setting. The same task runs with a model in the cloud or with a model on your own notebook, while tools, skills and the connection to QGIS stay the same.

The final section presents a series of measurements, Benchmark 8. It measured both routes and scored every run against the same criteria on a scale of a hundred points. Seven systems of agent and model solved the same hazard and climate analysis for Stuttgart, each of them three times.

One of these models sat on a desk: Qwen ran on a notebook, reached almost 84 of a hundred points and so finished ahead of all three cloud models from OpenAI.

In local operation no request leaves your own network, and both routes lead to the same QGIS map.

Whether a system solves the task is decided by the measurement.

Whether a system solves a task is shown by a measurement series, and that is what benchmarks are for.

A benchmark is a fixed domain task with an assessment framework. Every model works on it several times, every run is assessed by the same criteria, and from the points comes a medal.

Two dossiers are published. The first is called Benchmark 8: seven systems of agent and model solve the same hazard and climate analysis for Stuttgart, each system three times.

The second is the Alpen dossier, the Behördenakte Alpen, with eight tasks from the daily work of an office on open cadastral data, ALKIS, of the municipality of Alpen on the Lower Rhine. Sonnet from the cloud met Qwen on a notebook, and the local model took gold in every assessed run.

The runs used the research system with additional domain skills for geoprocessing and the Geospatial API.

The two dossiers show the results in detail.