GeoAgent is built on Strands Agents. It wraps Strands with geospatial context, tool metadata, optional package adapters, provider configuration, and confirmation hooks for operations that should not run silently.

Why GeoAgent?

Many geospatial libraries need the same agent features:

• bind an agent to a live map, QGIS session, dataset, or workflow object;
• expose package functions as structured tools with docstrings and metadata;
• support OpenAI, ChatGPT/Codex OAuth, Anthropic, Google Gemini, Bedrock, LiteLLM, and local Ollama models;
• keep optional geospatial stacks optional;
• ask for confirmation before deleting layers, saving files, or running expensive processing jobs;
• support multimodal plugin workflows such as pasted images and screenshots when the selected model provider supports vision;
• provide a stable integration point for downstream packages and plugins.

GeoAgent centralizes that layer so each package does not need to maintain its own agent framework.

Core Concepts

| Concept | Purpose | | --- | --- | | GeoAgent | High-level facade around a Strands Agent. | | GeoAgentConfig | Provider, model, temperature, token, and client settings. | | GeoAgentContext | Runtime objects bound to the agent, such as a map or QGIS iface. | | @geo_tool | Decorator that turns a Python function into a Strands tool with GeoAgent metadata. | | GeoToolRegistry | Registry for tool metadata, safety flags, categories, and fast-mode filtering. | | for_leafmap | Factory that binds tools to a leafmap.Map-compatible object. | | for_anymap | Factory that binds tools to an anymap.Map-compatible object. | | for_qgis | Factory that binds tools to qgis.utils.iface and an optional QgsProject. | | for_nasa_opera | Factory that binds NASA OPERA search/display tools plus QGIS tools. | | for_stac | Factory that binds STAC catalog search/asset tools plus optional QGIS loading. | | create_agent | Factory for custom tools or package-specific integrations. |

Installation

Install the core package:

pip install GeoAgent

Core installs only the agent framework dependencies, mainly strands-agents and pydantic. Geospatial packages and provider clients are optional extras:

| Extra | Purpose | | --- | --- | | GeoAgent[openai] | OpenAI model support through Strands. | | GeoAgent[anthropic] | Anthropic Claude model support through Strands. | | GeoAgent[gemini] | Google Gemini model support through Strands. | | GeoAgent[ollama] | Local Ollama model support. | | GeoAgent[litellm] | LiteLLM model support for many hosted and proxy providers. | | GeoAgent[leafmap] | leafmap live map integration. | | GeoAgent[anymap] | anymap live map integration. | | GeoAgent[stac] | STAC client dependencies. | | GeoAgent[earthdata] | NASA Earthdata dependencies. | | GeoAgent[nasa-opera] | NASA OPERA search dependencies. | | GeoAgent[geoai] | geoai integration dependencies. | | GeoAgent[earthengine] | Google Earth Engine dependencies. | | GeoAgent[ui] | Solara UI dependencies. | | GeoAgent[providers] | OpenAI, Anthropic, Gemini, Ollama, and LiteLLM provider clients. | | GeoAgent[all] | Most optional integrations. QGIS itself remains system-installed. |

Examples:

pip install "GeoAgent[leafmap,openai]"
pip install "GeoAgent[anymap,anthropic]"
pip install "GeoAgent[stac,earthdata,openai]"

For QGIS, install GeoAgent in the Python environment used by QGIS. The GeoAgent[qgis] extra is a marker extra; QGIS is provided by the desktop application or system package manager.

Provider Configuration

GeoAgent selects a provider from environment variables when no provider is specified:

| Provider | Environment | | --- | --- | | OpenAI | OPENAI_API_KEY, optional OPENAI_MODEL | | ChatGPT/Codex OAuth | OPENAI_CODEX_ACCESS_TOKEN, optional OPENAI_CODEX_MODEL | | Anthropic | ANTHROPIC_API_KEY, optional ANTHROPIC_MODEL | | Google Gemini | GEMINI_API_KEY or GOOGLE_API_KEY, optional GEMINI_MODEL | | LiteLLM | LITELLM_API_KEY, optional LITELLM_MODEL and LITELLM_BASE_URL | | Ollama | OLLAMA_HOST or USE_OLLAMA=1, optional OLLAMA_MODEL | | Bedrock | AWS credential chain and model access, optional BEDROCK_MODEL |

ChatGPT/Codex OAuth uses the Codex browser login flow and the Codex Responses backend.

For notebooks and Python scripts, log in once with the CLI:

geoagent codex login

or from Python/Jupyter:

from geoagent import login_openai_codex

login_openai_codex()

GeoAgent stores the refresh token in your user config directory and exports OPENAI_CODEX_ACCESS_TOKEN for the current Python process. Later sessions can reuse the stored login automatically, or explicitly call:

from geoagent import ensure_openai_codex_environment

ensure_openai_codex_environment()

You can also configure providers explicitly:

from geoagent import GeoAgentConfig, for_leafmap

agent = for_leafmap(
    m,
    config=GeoAgentConfig(
        provider="openai",
        model="gpt-5.5",
        temperature=0,
        max_tokens=4096,
    ),
)

Factories also accept provider= and model_id= shortcuts:

agent = for_leafmap(m, provider="gemini", model_id="gemini-3.1-pro-preview")

Quickstart

Use GeoAgent directly when you do not need a map or package-specific toolset:

from geoagent import GeoAgent, GeoAgentConfig

agent = GeoAgent(config=GeoAgentConfig(provider="openai", model="gpt-5.5"))
resp = agent.chat("Explain STAC in two sentences.")
print(resp.answer_text)

Stream model output as it is generated:

import asyncio
from geoagent import GeoAgent

agent = GeoAgent()

async def main():
    async for event in agent.stream_chat("Explain STAC in two sentences."):
        if "data" in event:
            print(event["data"], end="", flush=True)

asyncio.run(main())

Bind an agent to a live leafmap map:

import leafmap
from geoagent import for_leafmap

m = leafmap.Map()
agent = for_leafmap(m)

resp = agent.chat("Add a marker for Knoxville and zoom to it.")
print(resp.answer_text)
m

Bind an agent to an anymap map:

import anymap
from geoagent import for_anymap

m = anymap.Map()
agent = for_anymap(m)
agent.chat("Change the basemap and list the current layers.")

Use GeoAgent inside QGIS:

from qgis.utils import iface
from geoagent import for_qgis

agent = for_qgis(iface)
resp = agent.chat("Summarize the project layers and zoom to the active layer.")
print(resp.answer_text)

geoagent.tools.qgis is import-safe outside QGIS. It imports QGIS classes only inside tool bodies, so tests and non-QGIS environments can import the module.

The OpenGeoAgent QGIS plugin adds a dockable chat UI on top of this factory. It supports provider and model controls, streaming responses, pasted image attachments, screenshot capture from the map canvas, QGIS window, or selected screen regions, image preview and save actions, Markdown transcript copying, and copying the PyQGIS script used for an executed result.

QGIS Plugin

OpenGeoAgent is the QGIS plugin interface for GeoAgent. It adds a dockable AI assistant to QGIS so you can inspect projects, navigate the map canvas, load data, run processing workflows, style layers, and execute confirmation-gated PyQGIS scripts from natural language.

Key plugin features:

• provider and model controls for Bedrock, OpenAI, ChatGPT/Codex OAuth, Anthropic, Google Gemini, Ollama, and LiteLLM;
• project-aware QGIS tools for layers, selections, map navigation, processing, project saving, and attribute table actions;
• image-aware chat with clipboard paste and screenshot attachments for models that support vision inputs;
• screenshot capture from the map canvas, selected map regions, the QGIS window, and selected screen regions;
• image preview and save/export actions, plus inline rendering of image outputs returned by multimodal models;
• direct image generation with t