Help
Admin & Config Guide ← Back to map

Getting the most out of the GeoAI assistant

The assistant answers questions about your data — the layers on the map and the services you've registered. The better that data is described, the better it works. This page explains how to prepare a map for the AI, and what the Layer Reference and Embeddings tools do.

1. Signing in & your maps

You sign in with a username and password (an administrator sets up your account). Your workspace is private to you: the layers you add, your current selection, and the maps you save are yours — each person works on their own live map, and nothing leaks between accounts.

What you can do depends on your role:

Saving & sharing a map. When you save a map (Map → Save map as…) you become its owner. In the map's properties you set who else can see it:
Signed out or need an account? Ask your administrator — sign-up is managed, not self-service.

2. How the assistant sees your map

On every question, the assistant is given a live snapshot of the map — the basemap and view, the layers (with their fields, geometry type, feature count, and your AI instructions), the current selection, your last click, and any saved-map instructions. It then answers using the ArcGIS REST API against your layers. It never invents data: if something isn't on the map or registered, it says so rather than guessing.

3. Prepare a map for the AI

  1. Add the layers you care about. Use the slide-out menu → Layers → + Add layer (a Feature Service URL), or ask the assistant to add a registered layer by name.
  2. Save the map with AI Instructions. Menu → Map → Save map as…. The AI Instructions box is sent to the assistant on every request for this map — use it to explain domain terms and preferences, e.g. "This is the Riyadh flood-risk map; treat 'risk' as the RISK_LEVEL field; prefer the parcels layer for property questions."
  3. Ask in plain language. Counts, filters, "where is X", "buffer this 500 m", charts, styling — in English or Arabic.
Tip: you can switch the language model (local or cloud) from the ☰ menu in the chat box, and re-ask the same question to compare answers.

4. AI Instructions (map & layer)

Two places let you steer the assistant with plain-language instructions that are always included in requests:

Per-map — the AI Instructions box in Save map as…. Best for map-wide context: what this map is about, which layers to prefer, domain vocabulary.
Per-layer — the AI Instructions box on the Layer Reference page (see below). Best for layer-specific guidance: the exact field names, what a code means, related tables, gotchas.

5. Reference layers — what they are & why they matter

The Layer Reference page (slide-out menu → Layer Reference, admins only) is where you register and curate the layers the assistant should know about. For each layer you can set:

Why it helps: registered layers are discoverable (the assistant can find and add them by meaning), and they come with curated fields + aliases + instructions, so the model writes correct queries on the first try instead of guessing column names. When you add a layer by URL that isn't registered yet, the app auto-registers a default entry you can refine later.

6. Embeddings — what they are & what they provide

Behind the scenes, every registered layer, every documentation snippet, and every tool is turned into a semantic embedding — a numeric fingerprint of its meaning — stored in a local catalog. When you ask a question, the assistant embeds it and finds the closest matches, so it can pick the right layer, field, or API call by meaning, not just by exact keyword. This is what lets "flooding" find your "Hazard Zones" layer, or an Arabic question match an English layer.

The Embeddings page (slide-out menu → Embeddings, admins only) lets you view, add, edit, and delete every catalog entry, and export the whole catalog as Markdown for analysis. Most entries are created automatically (registering a layer, or seeding docs); you'd add entries by hand to teach the assistant extra domain knowledge or API references.

What an embedding entry contains

Every entry is one row in the catalog. These are the fields you'll see on the Embeddings form:

How the assistant uses it

When you ask something, the assistant turns your question into a vector and compares it to every entry, keeping the closest few. Layer matches tell it which dataset to query; doc matches are handed to the working specialist as reference so it uses the correct API names and parameters; the Agent tag decides which specialist receives which doc. Better-described entries → better first-try answers.

Add an embedding (admins)

  1. Open ☰ menu → Embeddings, then click + New.
  2. Give it a unique ID and choose a Kind — usually doc to teach a piece of knowledge.
  3. For a doc, set Subkind (rest for data-query knowledge, sdk for map/visual knowledge) and the Lang.
  4. Set Agent(s) so it reaches the right specialist — e.g. a data-query tip → DataExploration; a styling/map tip → MapControl. You can list several, comma-separated. (Leave blank for a layer.)
  5. Write a clear Title and the Text (the knowledge to embed), then Save — it's embedded immediately and live on the next question.
Layers are normally added on the Layer Reference page, not here — that page also lets you trim fields and add per-layer instructions. Use Embeddings for knowledge and API references.

The assistant's agents (specialists)

The assistant works as a team: an Orchestrator reads your question and the map, plans the steps, and hands each step to a specialist. When you tag a doc/tool with an Agent, you're choosing which specialist gets that knowledge.

Bilingual: layers can have separate English/Arabic entries for sharper same-language matching; the embedding model also bridges across languages, so you don't need to duplicate everything.

7. For administrators

If you manage this deployment, the Admin & Configuration Guide covers every configuration surface: user accounts & roles, the admin pages, the config files, how to edit the assistant's skills (instructions), and how to manage the embeddings catalog and its command-line tools. It also explains how to let external apps authenticate to the API via OAuth and how to connect Claude Desktop to drive the map. (Admin role required for the management pages.)

8. Quick checklist

← Back to the map