GeoAgent

GeoAgent is a shared AI agent layer for geospatial Python packages, live map widgets, and QGIS plugins. With one consistent interface, projects such as leafmap, anymap, geoai, geemap, STAC, and NASA Earthdata can expose their tools to large language models, so each library no longer needs to build and maintain its own agent stack.

Built on Strands Agents, GeoAgent adds geospatial context, structured tool metadata, optional package adapters, provider configuration, and confirmation hooks that pause the agent before destructive, expensive, or otherwise irreversible operations.

See it in action:

• Short demo: QGIS OpenGeoAgent Plugin Demo
• Full tutorial: OpenGeoAgent: A Multimodal AI Agent for Automated Geospatial Analysis and Visualization

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, OpenRouter, LiteLLM, vLLM, 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

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:

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:

Bedrock is not auto-detected. Pass provider="bedrock" explicitly; it then uses the AWS credential chain, configured region, and Bedrock model access, with optional BEDROCK_MODEL.

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

vLLM support expects a running vLLM server. When using GeoAgent tools, start the server with vLLM tool-calling support enabled for the selected model and chat template.

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")

OpenRouter can be used for DeepSeek and Qwen models:

agent = GeoAgent(
    config=GeoAgentConfig(
        provider="openrouter",
        model="deepseek/deepseek-chat",
    )
)

qwen_agent = GeoAgent(
    config=GeoAgentConfig(
        provider="openrouter",
        model="qwen/qwen3-32b",
    )
)

Quickstart

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

from geoagent import GeoAgent, GeoAgen