Getting started

1. Browse without signing in. These docs, the About page, the Products page, and the legal pages are public. The Chat and Scripts tabs only appear in the navbar after you sign in — that's expected, not a bug.
2. Sign in. Click the Sign In arrow at the top-right and pick the Google account your operator added to the access list. After consent you land back on the chat page within a few seconds.
3. Open the welcome screen. The center shows a short greeting and a few starter prompts — clickable example questions. Click any one to send it as your first message, or type your own into the chat box at the bottom.
4. Watch the agent work. Text streams in as it's written; tool calls appear as collapsible blocks; maps, charts, and thumbnails render inline as the agent produces them. Most analyses take 10–60 seconds.
5. Interact with the outputs. Click maps to query pixels, toggle layers, and animate time-lapses; click chart points to inspect; click any artifact title to open it full-screen in a new tab.
6. Refine with follow-ups. The chat remembers your study area, dates, intermediate variables, and previous outputs across turns in the same session — say "now show me the same thing for 2010" or "make a chart of the area in each class."

How a session works

In plain English: your message becomes a series of tool calls; each tool runs in its own sandbox; outputs stream back as they're produced. Here's the same flow with the moving parts named — useful when you're debugging a stuck turn or evaluating where work happens.

1. Chat UI sends your message to the backend over Server-Sent Events (/run_sse).
2. Gemini reads your message, the recent history, and the registered tool list, then decides which tools to call (often several in sequence).
3. MCP server(s) execute the tools the model called — most commonly the geeViz MCP, a sandboxed Python REPL that holds your session's variables across turns. The agent can also call remote MCPs, Python functions, and grounding sources from the same tool list.
4. Earth Engine does the geospatial compute. The framework's credential proxy — a small in-process module that holds the service account and mints short-lived bearer tokens server-side — means your browser never holds EE credentials, and every call is stamped with a per-user workload tag for attribution.
5. Artifact service writes maps, charts, thumbnails, and reports to per-session storage (local filesystem in dev, GCS in prod) and serves them from stable URLs that survive tabs and reloads.
6. Streamed back — the Chat UI receives the agent's narrative text, the tool-call blocks, and artifact links on the same SSE channel as they arrive, so you see the answer assemble in real time instead of waiting for a final blob.

The framework

What you're using is one tenant of a reusable, multi-tenant agent framework — geeViz Agent. ASKTERRA is the deployment; geeViz Agent is the framework that runs it. Each tenant has its own brand, access policy, AI tools, and Cloud Run service — but shares a single, battle-tested conversation engine, artifact pipeline, sandbox, and Earth Engine auth proxy.

Single agent, multi-agent, sub-agents, and A2A

The framework treats agent topology as configuration. The same engine that runs a single root agent runs a constellation of specialists — operators choose what fits the use case.

• Single root agent (the default) — one strong agent handles the entire conversation: dataset choice, code generation, visualization, narrative. Simplest to operate; best when the work is broadly geospatial and a single model context is sufficient.
• In-process sub-agents — declare a sub_agents list under any agent spec. Each sub-agent has its own model, tools, MCP servers, instructions, and even its own sub-agents (recursive). Use this for specialists the root delegates to — a fact-checker, a citation-finder, an output-quality reviewer, a domain expert (forestry, hydrology, urban planning). Sub-agents share the parent's session context.
• Agent-to-Agent (A2A) connectors — declare an a2a list with the URL of a remote agent. Each connector becomes an ask_<name>(question) tool the root can call. Use this when the specialist runs as a separate service — a different tenant's agent, a customer's in-house GIS agent, a partner's analytical model.
• Hierarchies — sub-agents can themselves have sub-agents and A2A connectors. The framework handles orchestration, context-passing, per-event token accounting, streaming, and tool-call attribution at every layer.

A deployment that begins as a single agent grows into a multi-agent system as its use cases broaden — without rewriting code, only by editing tenant.yaml.

Custom tools — Python, MCP, or both

Every agent in the framework reads its tool surface from configuration. Operators have three ways to add custom tools — and they compose freely on the same agent.

• Plain Python functions (agent.tools block) — drop a Python file into the tenant package, point the agent's tools entry at it, and your function becomes a tool the model can call. The simplest path for proprietary calculations, internal APIs, lookup tables, or domain-specific transformations. Lives in-process — no separate server to deploy.
• Local MCP servers (type: stdio) — declare an MCP server the agent process launches as a subprocess at startup. The framework's reference geeViz MCP works this way: a sandboxed Python REPL exposing the full Earth Engine + geeViz tool surface. See this instance for the actual tool roster bound here.
• Remote MCP servers (type: streamable_http) — declare an MCP server reachable over HTTP. The framework's reference gmaps MCP works this way: Google Maps Platform for place search, geocoding, routing, Street View, weather, and air quality. The same pattern plugs in any internal GIS service, third-party analytics API, specialty model, or partner data feed that speaks MCP.

The agent doesn't distinguish a built-in capability from a custom Python function from a remote MCP tool. They appear in the same tool list, get called the same way, contribute to the same conversation. Custom tools are how a single framework serves dramatically different verticals — forestry, finance, defense, infrastructure — without forking.

Architecture

A deployed tenant is a single FastAPI process built around Google ADK:

• FastAPI + Google ADK — serves the chat UI, the SSE streaming endpoint (/run_sse), the artifact + map proxy routes, the admin endpoints, the auth middleware, and the Earth Engine credential proxy.
• Tenant config — a single tenant.yaml declares brand, theme, agent hierarchy, MCP servers, A2A connectors, RAG sources, sub-agents. The framework reads it at startup and constructs the ADK Agent tree.
• MCP subprocess(es) — every tool surface the agent uses is exposed via Model Context Protocol. The framework supports both stdio (local subprocess) and streamable_http (remote MCP server) transports, with sandboxed REPLs and built-in audit logging.
• Earth Engine via geeViz.eeAuth — holds service-account credentials in-memory, mints per-request bearer tokens, and stamps every EE call with a workload tag (agent__map__<tenant>__<user>__<session>) so usage is attributable per-user.
• Artifact service — local filesystem in dev, GCS in prod. Every map, chart, thumbnail, PDF, and dashboard is written here and served from a stable per-session URL that survives across tabs and reloads.
• Auth middleware — gates every non-public path with a signed session cookie. The cookie is set by Google Sign-In, with Cloud IAP available as a legacy fallback.
• Per-tenant Cloud Run service — each instance runs in its own GCP project (or sub-project), with its own runtime service account, Cloud SQL session store, GCS artifact bucket, Secret Manager entries, and Cloud Logging sink. The setup wizard provisions all of it on first deploy.

RAG sources

Any agent can be grounded with retrieval-augmented generation via the rag_sources list. Supported source types:

• vertex_search — Vertex AI Search datastores (PDFs, web crawls, structured data).
• gemini_file_search — Gemini's File API for ad-hoc document grounding.
• google_search — built-in Google Search grounding for fresh web context.
• custom_http — any HTTP endpoint that returns documents matching the framework's RAG response schema.

RAG results appear inline in the model's response with citation chips that link to the source document.

Auth and access model

The framework supports two sign-in paths simultaneously:

1. Google Sign-In — the primary path. Configured by an OAuth client ID; gated by per-environment ADMIN_EMAILS and USER_EMAILS lists. Each list entry can be a single email or a Google Group email — group membership is checked at sign-in via the Cloud Identity API and cached briefly. Manage access by editing the group in Workspace; no redeploy needed.
2. Cloud IAP — legacy / internal deployments can stay on Identity-Aware Proxy. The framework reads the X-Goog-Authenticated-User-Email header as a fallback.

Role on the session is either admin or user; admins see the /admin dashboard, users see chat + scripts only. Public pages (/, /about, /products, /docs, /privacy, /terms, /eula) render without sign-in so anonymous visitors can learn about the deployment before they sign in.

Customization (tenant.yaml)

Almost everything an operator usually wants to change lives in one file: tenant.yaml. The framework reads it at startup; restart the service to pick up changes — no recompile, no migration. The blocks group naturally into three concerns:

Brand & visuals

• slug, name, short_name, title — brand identifiers used in the navbar, page titles, and email subjects.
• theme — dark + light palettes, each ~20 CSS variables (surface, text, accent, dividers, etc.). Written into a :root block at request time so the entire UI is themed without forking CSS.
• typography, logos, ui.starter_questions, footer — the rest of the brand surface.

Agent & tools

• agent — the root agent spec (recursive): model, temperature, tools, MCP servers, sub-agents, A2A connectors, RAG sources, instructions addendum.
• ee, model_armor — Earth Engine tier + quota project, content-screening template + RAI filter thresholds.

Access & contact

• auth — public path list, session cookie config, optional Workspace-domain restriction.
• contact — support email, label, docs URL, mail-subject prefix.

A real tenant.yaml is ~150–300 lines; what follows is the spine — enough structure to recognize the shape, not a full schema:

slug: askterra
name: Geospatial Agent
short_name: ASKTERRA
title: ASKTERRA Geospatial Agent

theme:
  dark:  { bg: "#1e1e1e", text: "#d6d1ca", accent: "#48848f", ... }
  light: { bg: "#f5f1ec", text: "#372e2c", accent: "#00897b", ... }

agent:
  model:
    api_default_name: gemini-3.5-flash
    thinking_budget: 16384
    temperature: 0.3
  mcp_servers:
    - { name: geeviz, type: stdio, script: geeViz/mcp/server.py }
    - { name: gmaps,  type: streamable_http, url: https://mapstools... }
  sub_agents: []
  a2a: []
  rag_sources: []

auth:
  enabled: true
  public_exact: [/, /about, /products, /docs, /privacy, /terms, /eula]

For things that change between environments — secrets, OAuth client IDs, allow-lists — the framework uses per-environment .env.test and .env.prod files that the deploy script forwards as Cloud Run environment variables. Editing the env file and redeploying is the canonical "update access" workflow.

This instance (ASKTERRA)

Specifically for the deployment you're using right now:

• URL pattern — the Chat tab lives at / (or /chat, which redirects there). After you start or open a session your URL looks like /?session=<id> — that <id> is your session identifier.
• Topology — single root agent (no sub-agents, no A2A connectors, no RAG sources). The full conversation runs end-to-end on one agent.
• Brand — ASKTERRA Geospatial Agent, operated by RedCastle Resources.
• Model — gemini-3.5-flash with a 16384-token thinking budget (temperature 0.3).
• MCP servers — the geeviz stdio MCP (the full Earth Engine + geeViz tool surface) plus the gmaps streamable_http MCP (Google Maps + places + routes + Street View + weather + air quality).
• Built-in grounding — Gemini's native Google Search tool is enabled in addition to all MCP-provided tools.
• Access — Google Sign-In gated by ADMIN_EMAILS + USER_EMAILS (each entry can be an individual email or a Google Group).
• Hosting — Cloud Run with Cloud SQL session store, GCS artifact bucket, and Model Armor content screening at the HIGH threshold.

geeViz MCP tool roster

The geeviz MCP exposes 12 tools to the agent. User-visible marks tools you'll typically see as tool-call blocks in the chat; Background marks tools the agent uses invisibly to set up an answer.

• run_code User-visible — sandboxed Python REPL (the workhorse).
• search_geeviz Background — look up geeViz functions, modules, examples.
• search_datasets Background — query the Earth Engine catalog.
• inspect_asset Background — bands, dtypes, class properties.
• env_info Background — runtime environment + package versions.
• export_image User-visible — long-running EE image exports.
• get_streetview User-visible — Street View imagery for a lat/lng.
• geeviz_search_places Background — geocode and place lookup.
• manage_asset User-visible — create / move / delete user assets.
• map_control User-visible — center, layer order, basemap, legend.
• save_session User-visible — snapshot the current REPL state.
• view_output User-visible — open the rendered map/chart/report.

Other tenants of the same framework swap any of these out — different model, different MCP servers, different brand, different access policy — without modifying the framework code.

Extending: your own tenant

If you operate the framework (or are evaluating it), the typical lifecycle for a new tenant breaks into three phases. Time estimates assume a fresh GCP organization and someone reasonably comfortable with Cloud Run.

1. Run the setup wizard (~30–60 min the first time, ~10 min on re-runs) — python -m geeviz_agent.create_tenant walks you through GCP project creation, API enables, IAM, Cloud Logging, Model Armor template, Maps + Gemini API keys, ADC, scaffold of tenants/<slug>/, Google Sign-In OAuth client setup, and end-to-end verification. Most steps are idempotent; re-run with --resume <slug> picks up where you left off.
2. Customize tenants/<slug>/tenant.yaml (~30 min for a baseline) — brand, palette, agent config, MCP servers, custom Python tools, sub-agents, A2A connectors, access policy. Most operators edit ~30 lines for a baseline deployment.
3. Drop your logos (~10 min) into tenants/<slug>/static/ — light and dark wordmarks plus a favicon.
4. Wire your tools (~30 min to several hours) — add a Python module under tenants/<slug>/tools/ for in-process functions, or declare a custom MCP server (local or remote) under agent.mcp_servers. Add sub-agents under agent.sub_agents or A2A connectors under agent.a2a.
5. Set .env.test / .env.prod (~10 min) — at minimum ADMIN_EMAILS and GOOGLE_OAUTH_CLIENT_ID.

1. Deploy (~5–15 min per push) — ./deploy.sh test builds a container, pushes a Cloud Run revision, and (first run) provisions Cloud SQL + GCS bucket + Secret Manager entries. ./deploy.sh prod does the same for production.
2. Map a custom domain (~15 min + DNS propagation) — Cloud Run domain mapping or an external load balancer with managed TLS.

1. Grant & revoke access — add team members to ADMIN_EMAILS / USER_EMAILS, or (better) put a Google Group on those lists and manage membership in Workspace so access changes don't require a redeploy.
2. Monitor — per-tenant Cloud Logging sink captures the FastAPI + agent process logs; per-tenant BigQuery dataset captures Gemini per-event token usage for cost attribution. The /admin dashboard (admins only) surfaces recent sessions, live token counts, and tool-call errors.
3. Roll model upgrades — edit agent.model.api_default_name in tenant.yaml, redeploy. Per-event token accounting makes it easy to compare cost/latency of the old vs new model on real traffic before switching production over.
4. Rotate secrets — OAuth client secret, Cloud SQL password, signing key, and the Maps Platform key all live in Secret Manager. Rotate via gcloud secrets versions add; Cloud Run picks up new versions on the next revision.
5. Scale Cloud Run — tune min-instances upward for zero cold-start latency, or max-instances upward if a tenant outgrows the default ceiling. Earth Engine compute cost dwarfs Cloud Run cost in practice, so watch EE quota, not container instance hours.
6. Watch Gemini cost — the per-tenant BigQuery usage table records every Gemini API call with token counts.

Prompting tips

• Study area: "Sandy County, Wyoming" beats "the western US." A named place, a county/state, or a bounding box all work.
• Time window: "From 2018 to 2024", "summer 2024 (Jun–Aug)", or "the most recent cloud-free image" are clearer than "recently."
• Dataset: name it if you know it. "Use NLCD 2021" or "use LCMS v2024-10" beats "use the standard land cover."
• One output at a time: a map, then a chart of the same data, then a thumbnail for a report — easier to verify than asking for everything in one shot.
• Push back: when something looks wrong, say so — "Are you sure those are the correct date ranges?"
• Verify: "What asset ID did you use? How many features in the FeatureCollection? What's the date of the most recent image?"

Anti-example

Vague prompts force the agent to guess; specific prompts get useful answers in one turn.

The agent has to ask follow-up questions or guess — either wastes a turn.

Study area, dataset, time window, and desired output are all specified — the agent can act in one turn.

Use cases

Real prompt-to-output sequences. Open the Chat tab and paste any prompt to try it. Adapt the study area, dates, and datasets to your domain.

Click any case to expand or collapse.

Saved scripts

Once an analysis is working, save it as a parameterized script anyone with access can re-run without going through the chat — no LLM in the loop, no token cost. Useful for hand-offs, dashboards, and "run this every Monday" workflows.

1. In the chat, hover over a successful code block; a + Save as script button appears in the block's toolbar. (Alternative: open the Scripts tab and click + New from Chat.)
2. Name your script and add a description so collaborators understand what it does.
3. Edit parameter values (study area, dates, scale, output filename) and click Run Script.
4. Outputs render below — re-run any time with new parameter values.

# 'aoi' and 'lcms' were defined in earlier chat turns — gone now
classes = lcms.filter(ee.Filter.eq('year', 2024)).first()
Map.addLayer(classes.clip(aoi), {}, 'LCMS 2024')

aoi = ee.Geometry.BBox(-112.1, 40.6, -111.7, 40.9)
lcms = ee.ImageCollection('USFS/GTAC/LCMS/v2024-10')
classes = lcms.filter(ee.Filter.eq('year', 2024)).first()
Map.addLayer(classes.clip(aoi), {}, 'LCMS 2024')

Reports + exports

Output types

• Maps are standalone HTML files that include the layer state and the legend — share the link with anyone who has access to your session.
• Charts are Plotly HTML — interactive, with download buttons for PNG / CSV.
• Thumbnails (single-image PNG, animated GIF, filmstrip) include legends, scale bars, inset locators, and basemaps.
• Reports bundle multiple sections (map thumb, chart, table, narrative paragraph) into one HTML page suitable for emailing or printing to PDF via your browser's Cmd/Ctrl + P → Save as PDF.
• Tables render as markdown in the chat; the agent can produce CSV via df.to_csv(...) if you ask.
• Runnable Python — every analysis is exportable as a standalone script.

Where outputs live

Every artifact appears inline in the chat and is listed in the session's artifacts panel. Each one has a stable per-session URL that survives tab reloads and works for anyone with access to your session. Artifacts persist for the life of the session.

Troubleshooting

Long-running analysis fails — Earth Engine "Computation timed out"

EE-side compute timeout. Fix at the analysis level — coarsen the scale, shrink the AOI, or shorten the time window. See the Top tip on coarsening scale.

Long-running analysis fails — ADK / agent timeout (chat hangs > 5 minutes)

Framework-side timeout: the agent's heartbeat to the MCP subprocess didn't return. Any saved scripts survive a refresh (they live in the database). Refresh, start a new session, and if the same analysis hangs again, treat it as the EE case above and coarsen the scale.

"Memory limit exceeded"

Same family as the EE timeout. Coarsen scale, shrink AOI, or shorten time window.

Empty / blank map

Usually means a filter returned 0 features or images. Ask: "how many features matched the filter?" — the agent will add a .size().getInfo() probe.

Map shows but my polygon outline is invisible

The polygon is probably bigger than the visible map area. Zoom out, or ask the agent to "center the map on the study area."

Map or chart renders, but the legend is wrong

Ask: "use the dataset's official class names and colors for the legend" or "inspect the asset's class properties and rebuild the legend from those."

Agent referenced a dataset that doesn't exist (made-up asset ID)

If you don't see a search_datasets or inspect_asset call before the agent uses an asset ID, treat the ID as unverified — ask "did you verify that asset exists?" Pre-empt it by naming the dataset in your prompt ("use NLCD 2021").

"Wrong" classification or numbers that don't match a published source

Ask: "what asset ID did you use? what version? what date range? what scale?" — most disagreements trace back to a different dataset version or window.

"You're not authorized for this app"

Your email isn't in the access list. Contact the AskTerra team at askterra@redcastleresources.com.

Get help

Stuck or have a feature request? Email the AskTerra team at askterra@redcastleresources.com. Including your session ID and a screenshot of the failure makes triage roughly 10x faster.

Additional documentation: https://docs.askterra.io. For a product overview, see the About page. Legal documents: Terms, Privacy, EULA.