# GeoAgents []() []() []() []() **GeoAgents** is an open-source framework for building **AI agents specialized in geospatial analysis (GIS)**. It is designed to let AI agents: * understand spatial questions * select GIS tools automatically * execute spatial analysis * verify hypotheses about the results * generate natural language explanations * expose a full execution trace through API GeoAgents is oriented to: * GIS applications * geospatial platforms * telecom infrastructure analysis * digital twins * spatial intelligence systems --- ## Table of Contents * [Why GeoAgents?](#why-geoagents) * [What GeoAgents Does](#what-geoagents-does) * [Example](#example) * [Architecture](#architecture) * [Core Concepts](#core-concepts) * [Agents](#agents) * [Tools](#tools) * [Layer Catalog](#layer-catalog) * [Runs, Verification and Trace](#runs-verification-and-trace) * [Installation](#installation) * [Quick Start](#quick-start) * [API](#api) * [Official Examples and Manual Regression](#official-examples-and-manual-regression) * [Testing](#testing) * [Documentation](#documentation) * [Repository Structure](#repository-structure) * [Extending GeoAgents](#extending-geoagents) * [Roadmap](#roadmap) * [Contributing](#contributing) * [License](#license) * [Maintainer](#maintainer) * [Credits](#credits) --- ## Why GeoAgents? Most agent frameworks focus on: * text reasoning * retrieval * general APIs GeoAgents introduces **structured geospatial reasoning**. The framework provides: * spatial tool orchestration * GIS layer inference * reproducible spatial analysis * controlled LLM reasoning * verifiable multi-step execution * traceable runs through API * modular architecture --- ## What GeoAgents Does GeoAgents separates the lifecycle of a geospatial agent into explicit phases: ```text plan -> execute -> verify -> optional replan -> synthesize ``` This means the framework is not limited to “calling one tool and returning text”. It can: * build multi-step plans * pass outputs from one step to another * verify whether a hypothesis was confirmed or refuted * replan when a step fails or evidence is insufficient * persist the full execution trace for inspection and debugging --- ## Example User question: ```text Are the points located inside the zones in this area? ``` GeoAgents will typically: 1. generate a spatial plan 2. select the appropriate GIS tool, for example `spatial.intersects` 3. execute the analysis 4. verify the result if applicable 5. synthesize a final response Example response: ```text Two intersections were detected between the points and Zone 1. Points A and B intersect with the polygon area. ``` --- ## Architecture GeoAgents separates **reasoning**, **execution**, **verification**, and **explanation**. ```text User Query │ ▼ Planner (LLM) │ ▼ Plan Validation │ ▼ Plan Postprocessor / Normalization │ ▼ Runner │ ▼ GIS Tools │ ▼ Verification │ ▼ Optional Replan │ ▼ Synthesizer (LLM) │ ▼ Final Response ``` The runtime cycle can be summarized as: ```text plan -> execute -> verify -> optional replan -> synthesize ``` Detailed docs: ```text docs/architecture.md docs/diagrams.md ``` --- ## Core Concepts ### Agents Agents define: * system prompt * allowed tools * execution profile Profiles: ```text compact rich investigate ``` An agent does not execute tools by itself. It defines the reasoning and tool boundaries that the runner will use during a `Run`. More details: ```text docs/agents.md ``` --- ### Tools GeoAgents uses **GIS tools** to perform deterministic spatial operations. Current core tools include: ```text spatial.summary spatial.query_layer spatial.nearby spatial.intersects spatial.context_pack spatial.network_trace ``` Tools can participate in: * single-step analysis * multi-step workflow