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, any OpenAI-compatible server, 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.

The openai-compatible provider talks to any server that exposes the OpenAI Chat Completions API, including llama.cpp, LM Studio, Text Generation WebUI, and vLLM. Point it at the server's /v1 URL. A model id is required because a generic endpoint has no default, and the API key is optional since most local servers ignore it:

from geoagent import GeoAgent

agent = GeoAgent(
    provider="openai-compatible",
    model="qwen3-8b",
    openai_compatible_base_url="http://localhost:8000/v1",
)

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.

The dedicated vllm provider depends on strands-vllm, which pins openai<2.0 and therefore cannot be installed alongside the openai>=2.0 that the default openai-codex provider requires. GeoAgent[vllm] is consequently excluded from GeoAgent[providers] and GeoAgent[all]. Prefer the openai-compatible provider pointed at your vLLM server's /v1 URL, which needs no extra dependency.

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

GeoAgen