Step-by-step guide

Getting a real result out of Agent Workspace and Workflow Studio, one click at a time.

SmartModeler GIS has two ways to get work done, and they answer different questions. Agent Workspace is for “do this one thing to my project”. Workflow Studio is for “build me a process I can keep, adjust and re-run”. This guide walks through both with real screenshots of the interface and prompts you can paste.

The one rule that governs everything Nothing in this plugin touches your project until you click Apply or Run on an approval card. Inspections are read-only, proposals are inert, and every result is a temporary layer until you make it permanent. If you read nothing else, read the card before you click.

Before you start

Install the plugin from the QGIS Plugin Manager, or from the zip via Plugins → Manage and Install Plugins → Install from ZIP. QGIS 3.44 or QGIS 4 is required.
Two toolbar buttons appear. One opens Workflow Studio, one opens the Agent Workspace dock.
Connect an AI provider if you want the assistant to plan for you: AI connections… in the dock header. Without a key the plugin still works — inspections, the whole Studio, running workflows and the offline planner all run locally — but the assistant cannot compose new plans.

Your key stays yours The API key lives in session memory or the optional encrypted QGIS vault. Feature values, source paths, connection URIs and credentials are never sent as tool metadata.

Which one do I use?

You want to…	Use	Because
Buffer this layer by 250 m, once	Agent Workspace	One reviewed run, result in the Layers panel.
Answer “what is the range of this field?”	Agent Workspace, Ask mode	Read-only, costs nothing from the action budget.
Restyle a layer	Agent Workspace	A style proposal you can preview and reject.
Build a repeatable multi-step analysis	Workflow Studio	A typed graph you can save, edit and re-run on new data.
Hand a process to a colleague	Workflow Studio	Exports as a native QGIS `.model3`.
Have the AI build that graph for you	Both	Agent Workspace in Current model scope edits the open Studio graph.

Agent Workspace — how it works

The assistant can look at your project, propose one action, and explain itself. It cannot execute anything. Each request runs as a short loop: it inspects with read-only tools, then hands you a proposal; you approve or reject.

1 · Open the dock

Click the Agent Workspace toolbar button. The dock opens on the right. The header tells you which profile is connected — Offline means quick inspections work but the assistant needs a connection.

The Agent Workspace dock as it opens: scope and mode selectors, quick inspection buttons, an empty transcript and the message box. — The dock as it opens. Scope and mode sit at the top, the quick inspection row below them, the transcript in the middle, your message box at the bottom.

2 · Choose a scope and a mode

These two selectors decide what the assistant can see and how far it may go. Set them before you type.

Scope	What it can see and change
Project	Layers in the project. The everyday choice.
Active layer	Only the layer selected in the Layers panel — no need to name it.
Current model	The workflow open in Studio. Proposals are graph edits, not runs.
Plugins	Which plugins are installed and what they offer.
Workspace (Developer)	Bounded source inspection and exact patches. Not needed for GIS work.

Mode	What happens
Ask	Questions and inspections only. No proposal, no approval card, nothing to click.
Plan	A proposal is prepared and shown for review. There is no Apply or Run button.
Act	A proposal is prepared and an approval card appears. Still nothing runs until you click.

3 · Ask for one thing

Type one operation, name the layer exactly as it appears in the Layers panel, and press Ctrl+Enter. You will see it inspect first — those [tool: …] lines are it reading your project, not guessing about it.

download the buildings in the map extent

The dock transcript showing a request, the assistant's inspections, a validated proposal and a finished run. — A request, the inspections it ran, the proposal, and the finished run. Every line is what actually happened, in order.

4 · Read the approval card

This is the moment that matters. The card names the algorithm, every input it will use, and where the output goes. Check the layer is the one you meant and the numbers are the ones you asked for, then click Run.

The approval card: a status line saying nothing has run yet, a risk badge, the algorithm and its exact inputs, and Run and Reject buttons. — The approval card for a reprojection. The status line says nothing has run yet; the risk badge says what it would do; the body lists the exact inputs.

Status line — confirms that nothing has happened yet.
Risk badge — computed from the action type, not from anything the model wrote.
Body — the algorithm id and every bound input. OUTPUT: temporary layer means nothing on disk is touched.
Run / Apply — the only thing that executes. Reject discards it.

5 · Chain the next step

Results arrive as temporary layers, named after what you asked for. Refer to that name in your next message. Keep going one step at a time: a message that asks for four things fails as a whole, while four messages fail cheaply and tell you exactly where.

Reproject before you measure Downloaded data usually arrives in Web Mercator, where area is inflated about 1.76× at Turkish latitudes — a 324 m² building measures 569 m². Say “reproject to the local metric CRS” first. The plugin refuses to measure otherwise, and that refusal is protecting your numbers.

A worked session

Six messages, from an empty project to a classified result. Paste them one at a time, changing the names to match your data.

#	What you type	What you get
1	`download the buildings in the map extent`	A temporary polygon layer of buildings.
2	`reproject Buildings to the local metric CRS`	The same buildings in a metre-based CRS.
3	`add a decimal column alan_m2 with the area in square metres`	A new field holding real areas.
4	`what are the minimum and maximum of alan_m2?`	An answer, in Ask mode, free of the action budget.
5	`make a new layer with only the buildings where alan_m2 is 300 or less`	A filtered temporary layer.
6	`classify that layer by alan_m2 with jenks into 5 classes`	A style proposal you can preview before applying.

Step 4 is the one people skip Asking for the range before you filter is what stops you writing “under 300” against a field whose smallest value is 900. Questions cost nothing.

Phrasings that work

	Say this	Not this
Layer	`reproject Buildings to…` — the exact name in the panel	`reproject this layer` — after a few runs there are five similar names
Scope	One operation per message	“download the roads, buffer them, then clip the parcels”
Numbers	`buffer by 250 metres`	`buffer a bit`
Fields	`the field alan_m2`	`the area column` when three columns hold areas
Fixes	`the field is alan_m2, not alanm2`	`do it properly this time`

When you are refused

Most refusals name a specific fact and stop a run that would otherwise have succeeded and handed you a wrong answer. Correct the fact.

Message	What it means	What to do
A geometry measure was requested on a layer whose CRS does not measure in metres	You are about to measure area in degrees or in Web Mercator	Reproject to a local metric CRS first
Unavailable algorithm: `native:…`	The assistant guessed an id this QGIS build does not have	Nothing — it is told the real candidates and corrects itself
A text parameter value is required (parameter FIELD_TYPE)	A parameter was given the wrong kind of value	Nothing — the refusal names the parameter and it retries
This workflow receipt does not match the current graph	The graph moved since the plan was written	Nothing — the graph is re-read automatically
Restricted algorithm	Deliberately outside what an AI-built workflow may place	Choose another approach; this one will not be unlocked by retrying
A `<` comparison needs a numeric field	On a text field QGIS compares letter by letter, so '1097' < '400'	Convert the field, or compare on a numeric one

Workflow Studio — how it works

A workflow is a typed graph: nodes are Processing algorithms, wires carry data, and the types must match — vector cannot feed a raster input, and the Studio will not let you connect them. The graph is inert until you press Run.

1 · Open the Studio

Click the Workflow Studio toolbar button. You get the canvas in the middle, the algorithm library on the left, the node inspector on the right, and the AI copilot bar across the top.

Workflow Studio when it opens: empty canvas, algorithm library on the left, node inspector on the right, AI copilot bar at the top. — An empty Studio. The library lists every installed algorithm; the example workflows below it load complete graphs you can take apart.

2 · Describe the workflow you want

Two ways in, both ending at an approval card:

The copilot bar at the top of the Studio — type what you need and press Ctrl+Enter.
Agent Workspace in Current model scope — the assistant edits the open graph and shows you the operations before anything changes.

Calculate slope from the DEM and classify it into planning suitability bands

Agent Workspace in Current model scope with a workflow patch on the approval card: two nodes to add and one connection. — The same dock, in **Current model** scope. The card lists the exact graph edits — which nodes are added and how they are connected — before any of it happens.

3 · Read the graph you were given

Click Apply and the nodes appear, already laid out left to right in the order the data flows. Follow the wires: that is the analysis, and it is now yours to change.

Workflow Studio with a three-node workflow: DEM input feeding Slope, feeding Suitability bands. — A DEM feeding a slope calculation feeding a reclassification. Cards are placed automatically; nodes you have arranged yourself are never moved by a later AI edit.

4 · Inspect and configure a node

Select a node to see its parameters and outputs on the right. Press Enter or double-click to open the full parameter form. The outline in the inspector is also the screen-reader path through the workflow.

The node inspector showing the selected node's parameters, outputs and the workflow outline. — The node inspector for the selected node.

5 · Run setup, validate, run

Run setup — one dialog listing every input the workflow still needs. This is where you choose the actual layers; the AI never binds your data for you.
Validate — checks types, required inputs and connections before anything executes.
Run (Ctrl+R) — results are added only after the whole workflow succeeds. Esc cancels.

Results are temporary Anything worth keeping: right-click the layer → Make permanent. Save the workflow itself with Save — it writes a native QGIS .model3 file that opens in the Processing modeler too.

Building one by hand

The AI is optional. Everything it does, you can do directly:

Search the algorithm library (Ctrl+F) and press Enter to add the highlighted algorithm.
Drag from an output port to an input port to connect two nodes, or use Connect nodes (Ctrl+Shift+C) if you prefer not to drag.
Next step buttons above the canvas suggest what usually follows the node you have selected.
F fits the graph to the window; Auto layout re-arranges everything.

The algorithm library panel with its search box, provider groups and the example workflows list. — The algorithm library, with the example workflows underneath.

A worked workflow

Slope suitability, the graph in the screenshots above, from nothing:

Open Workflow Studio on a project that has a DEM.
In the copilot bar: Calculate slope from the DEM and classify it into planning suitability bands
Read the card, click Apply. Three nodes appear, connected.
Select Suitability bands and open its parameter form. Enter your own class breaks — the AI proposes a structure, you own the thresholds.
Run setup → choose your DEM for the raster input.
Validate, then Run.
Save the workflow. Next month, point it at a different DEM.

To extend it, go back to the dock in Current model scope and ask for one more step — “add distance to roads and combine it with the slope bands”. Your existing nodes keep their positions; only the new ones are placed.

Help inside QGIS

You do not have to come back here. The plugin carries a short guide of its own, and both dialogs link to this page.

The in-application Agent Workspace quick start dialog. — Agent Workspace → **Quick start**: the five rules and a set of prompts to paste.

Where to go next

The reference manual — every algorithm, every tool, the full agent protocol and the safety model.
Issues — include your QGIS version, the plugin version, the exact steps and the Processing log, with private paths removed.

Screenshots on this page are rendered from the shipped interface by docs/build_screenshots.py, so they cannot drift away from the version they document. Example conversations and workflows are illustrative.