GeoAgent Documentation

The OpenGeoAgent QGIS plugin provides a dockable AI assistant within QGIS. It allows users to:

• Inspect projects and layers.
• Navigate the map canvas and load data.
• Run processing workflows and style layers.
• Execute confirmation-gated PyQGIS scripts via natural language.
• Use vision-capable models with screenshot capture (canvas, window, or screen regions).
• Generate images using the generate_image tool (requires OPENAI_API_KEY).

Interactive adapters for controlling maps and GIS software are located in the geoagent.tools module.

Available adapters include:

• leafmap_tools, anymap_tools, qgis_tools, nasa_opera_tools, whitebox_tools (bound to live map or QGIS instances).
• Optional stubs: stac, geoai, earthengine, nasa_earthdata (planned for future releases).

When developing custom tools, use the @geo_tool decorator from geoagent.core.decorators to ensure tools register Strands-compatible metadata, which is required for safety hooks.

The GeoAgentContext object is the central container for runtime state passed into every agent invocation. It provides the agent with access to the environment in which it is operating, allowing it to interact with spatial interfaces and local files.

Key components carried by the context include:

• Live Map Widget: Access to the current map state and interface.
• QGIS Interface and Project: Access to the active QGIS application and the current project data.
• Working Directory: The filesystem path where the agent is currently operating.
• User Preferences: Free-form configuration or settings provided by the user.

GeoAgent provides a unified interface to bind AI agents to geospatial contexts (like maps or QGIS).

• GeoAgent: The high-level facade used to interact with the agent.
• GeoAgentConfig: Defines the settings for the LLM provider (model, temperature, etc.).
• GeoAgentContext: Holds the runtime objects the agent is bound to, such as a leafmap.Map or a QGIS interface.
• @geo_tool: A decorator used to turn Python functions into structured tools that the agent can call.
• Factories (for_leafmap, for_qgis, etc.): Specialized functions that simplify creating a GeoAgent by automatically binding it to a specific geospatial context and configuration.

OpenGeoAgent uses a confirmation hook for destructive, persistent, or long-running operations (e.g., deleting layers, saving projects, or running processing jobs).

Permission Profiles:

• Trusted auto-approve: The default profile on first run. It allows tools to run without individual confirmation prompts.
• Inspect only: A restricted profile that limits tool access for higher security.

Users can select a narrower profile in the settings when they want to restrict the agent's ability to modify the QGIS environment.

GeoAgent provides a safety mechanism for tools that are destructive, persistent, or long-running (e.g., deleting layers, saving projects, or incurring costs). You can implement a confirm callback to intercept these calls.

To automatically approve all tools (useful for testing, but use caution in production):

from geoagent import auto_approve_all, for_leafmap

agent = for_leafmap(m, confirm=auto_approve_all)

In a real application, you should pass a custom confirm function that triggers a user interface prompt (like a Qt dialog, a notebook modal, or a CLI prompt) to ask for permission before the tool executes.

The Tool Registry is a capability-tagged registry used by downstream packages to publish tools decorated with @geo_tool.

When assembling an agent's tool list, the registry factory pulls a filtered subset of available tools based on two primary criteria:

1. Category: Filtering tools by their specific functional category.
2. Package Availability: Filtering tools based on whether the required package is currently available in the environment.

This mechanism allows the agent to dynamically compose its capabilities by only including tools that are both relevant to the task and supported by the installed software.

::: geoagent.core.registry

When calling GeoAgent.chat, the returned object is a GeoAgentResponse dataclass. This object contains the results of the agent's reasoning and tool execution.

Key attributes include:

• answer_text: The final text response from the agent.
• success: A boolean indicating if the chat operation completed successfully.
• error_message: Contains error details if success is False.
• execution_time: The time taken to process the request.
• images: A collection of image content blocks returned by supported multimodal models.
• content_blocks: The original top-level assistant content blocks.
• Tool execution metadata and access to raw provider results are also available for debugging or advanced processing.

GeoAgent implements a safety mechanism by tagging tools with specific metadata: requires_confirmation, destructive, or long_running.

At runtime, the ConfirmationHookProvider intercepts tool calls by listening for BeforeToolCallEvent within the Strands framework. When a tool call matches these safety tags, the provider triggers your defined ConfirmCallback. If the user or system denies the action via the callback, the provider sets the cancel_tool flag on the event to prevent execution.

By default, the Web UI denies tools that require confirmation (e.g., actions that remove or clear layers, save maps, or other gated/destructive/long-running actions).

To allow these actions to execute without manual intervention, enable the Auto-approve confirmation tools toggle in the workspace.

Warning: Use auto-approve only for trusted sessions, as it grants the agent permission to execute potentially destructive tools automatically.

Tools can be marked as requires_confirmation, destructive, or long_running. By default, confirmation-required tools are denied unless a confirmation callback is provided.

To automatically approve all tools (e.g., in a trusted local session), use auto_approve_all from the geoagent package.

from geoagent import auto_approve_all, for_leafmap

# Automatically approve all tools
agent = for_leafmap(m, confirm=auto_approve_all)

If a requested task is not covered by a dedicated GeoAgent tool, the agent uses the run_pyqgis_script fallback. This allows the agent to perform arbitrary PyQGIS operations (e.g., changing raster band renderers, updating labels, or adjusting the layer tree).

Safety and Workflow:

• Confirmation: The plugin will always ask for user confirmation before executing a fallback script.
• Context: The script runs in the QGIS GUI context with access to iface, project, canvas, and active_layer.
• Reproducibility: You can use the Copy Script action to copy the generated PyQGIS code. The snippet includes a QGIS-console-ready preamble, making it easy to inspect, share, or rerun manually in the QGIS console.