Multi-Agent Geospatial Analysis
Quick start · Demos · Documentation
GeoFaham combines PostGIS records, OpenStreetMap features, satellite imagery, and raster computation to answer geospatial questions about places, infrastructure, and imagery. Its evaluation focuses on disaster-response tasks, including schools within flood extents, building damage, and pre- and post-fire imagery.
Four agents handle spatial queries, map features, imagery search, and raster analysis. An Orchestrator maintains a task plan, tracks progress, and revises the plan when execution stalls. The Response Store saves outputs as files; later steps refer to response IDs and metadata rather than passing full geometries or rasters through the model context.
Static diagram · Agent reference · Response Store
- Python 3.11 or later.
- PostgreSQL and PostGIS; the supplied snapshot requires PostgreSQL 18.
- API access for your configured models.
- An Azure Maps subscription key for the web map.
git clone https://github.com/microsoft/GeoFaham.git
cd GeoFaham
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .envOn Windows, activate the environment with venv\Scripts\activate.
Edit .env with your credentials and database connection:
OPENAI_API_KEY=your_api_key
AZURE_MAPS_KEY=your_maps_key
GEOFAHAM_DEFAULT_MODEL_CLIENT='{"provider":"autogen_ext.models.openai.OpenAIChatCompletionClient","config":{"model":"gpt-4o","api_key":"$OPENAI_API_KEY"}}'
GEOFAHAM_REASONING_MODEL_CLIENT='{"provider":"autogen_ext.models.openai.OpenAIChatCompletionClient","config":{"model":"gpt-5.1","api_key":"$OPENAI_API_KEY","reasoning_effort":"medium"}}'
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=geofaham
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_passwordAzure OpenAI, custom endpoints, per-agent models, and path overrides are covered
in configuration. The frontend loads AZURE_MAPS_KEY
from the server's /api/config endpoint.
Place your copy of geofaham_data_v1.sql.gz in data/backups/, then follow
database setup to verify and restore them:
python3 scripts/db_init.py --dry-run
python3 scripts/db_init.pyThe loader creates the configured database and refuses an existing one. The snapshot includes the schema and data. The Vector Agent and full team require a populated database; Maps, STAC, and Raster can also run individually through the Python API.
python server.pyBefore accepting requests, startup checks validate model-client configuration, PostGIS, required tables, metadata files, and writable runtime paths. See startup checks.
Open http://localhost:8010. For development:
uvicorn server:app --reload --host 127.0.0.1 --port 8010The demo gallery contains flood-and-schools, building damage, imagery timeline, and burn-severity examples. Recordings are edited to skip waiting and processing time.
Click the figure for the full-size view. See web interface for controls and rendering details.
| Topic | Reference |
|---|---|
| Agents and orchestration | Agent reference |
| Model clients and environment variables | Configuration |
| Database restore | Database setup |
| Files and state | Data directories |
| Artifact storage and SQL placeholders | Response Store |
| Raster code execution | Raster Agent |
| Response fields | Tool response schemas |
| Python, HTTP, and tools | API reference |
| Contributing and tests | Development |
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
- Microsoft Planetary Computer for satellite data access
- AutoGen for multi-agent framework
- OpenStreetMap contributors for map data
- TiTiler for raster tile serving


