Talk to your web map: the Maps SDK’s new AI components (beta)

ArcGIS Maps SDK for JavaScript 5.0 quietly shipped something bigger than a new layer type: a beta package of AI components that puts a conversational assistant inside your web map. Users type “zoom to the parcels near the river” or “which sites had more than 40 inspections last year?” — and agents running in the browser translate that into map navigation and live layer queries. Here’s what actually shipped, how to wire it up, and the part the demos skip: the quality of the answers is decided by your web map, not by the model.

What actually shipped

The AI components (beta) package (@arcgis/ai-components) centers on one component: arcgis-assistant, a chat interface bound to a WebMap. Esri calls the pattern an agentic mapping application — an app whose primary UI is natural language rather than toolbars and filter widgets.

The assistant itself has no built-in smarts. It requires one or more agents registered to it, and 5.0 ships three ArcGIS agents out of the box:

• Navigation agent — moves the map: zoom, pan, go to a place or feature.
• Data exploration agent — runs attribute, statistic, and spatial queries against the web map’s feature layers.
• Help agent — answers questions about what the assistant can do.

When a user submits a prompt, an orchestration agent classifies intent and routes each part of the request to the right registered agent. The agent’s logic runs in the browser; it calls an LLM to resolve intent and parameters, then executes real SDK operations — a goTo(), a layer query — against your map. The response comes back as chat text, a map action, or both.

Wiring one up is genuinely small

For the pre-built agents, the CDN build is enough. Load the SDK’s single module entry point:

<!-- index.html -->
<script type="module" src="https://js.arcgis.com/5.0/"></script>

Then compose the app declaratively — a map component, the assistant referencing it, and the agents you want slotted inside (this is the pattern straight from Esri’s Get started guide):

<arcgis-map id="main-map" item-id="49ecd45c57e246c2afa63ca254c5b6c4"></arcgis-map>

<arcgis-assistant
  reference-element="#main-map"
  heading="My Assistant"
  description="Explore and navigate this map using natural language">
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
  <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
</arcgis-assistant>

Building with npm instead? Install @arcgis/ai-components and import each component individually. One licensing-relevant nuance from the docs: the CDN may only be used with the pre-built agents — if you want to author your own agents, you must build via npm.

Your web map is the prompt

This is the section that decides whether your assistant feels sharp or embarrassing. The agents’ entire context is the web map — and Esri’s web map setup guide is unusually blunt about what that requires:

• Only feature layers are discoverable. Every other layer type — including basemap layers — can sit in the map for display, but agents can’t see it.
• Simpler is better. Include only the layers the assistant is meant to reason about; every extra layer dilutes agent accuracy.
• Trim wide layers with views. A layer with 80 fields covering six subjects confuses intent-matching. Create hosted feature layer views exposing just the fields the assistant should use — the same governance tool we covered in our feature-layer-views post, now doing AI-context duty.
• Metadata is functional, not decorative. Layer names, field aliases, and field descriptions feed directly into how agents pick layers and fields. The Item details assistant (beta) can draft descriptions for hosted layers you own — review before accepting.

If you’ve been treating item metadata as paperwork, this flips the incentive: documentation quality is now answer quality.

Embeddings: the step you can’t skip

Before the assistant can use a web map, the map item needs embeddings — vector representations of every feature layer’s title and field metadata, stored as a resource on the web map item. They let the agents shortlist relevant layers and fields before anything is sent to the LLM, which is what keeps answers accurate on maps with many layers. Generating them takes owner or admin rights on the item:

1. Open the web map item in ArcGIS Online and go to its Settings page.
2. Scroll to “Manage AI vector embeddings” under the Web map section.
3. Click Generate Embeddings and let the job finish — time scales with layer and field counts.

One caveat worth knowing: for layers you don’t manage (Living Atlas, other orgs), missing descriptions get LLM-generated during embedding — and those generated descriptions are not reviewable, editable, or persisted to the item. Prefer well-documented layers.

The fine print before you demo this to a client

The beta’s access model is the sharpest constraint, and it’s all documented in the AI components FAQ:

Custom agents are where this gets interesting

The pre-built agents cover navigation and exploration, but the real product opportunities are domain-specific: an agent that knows your permitting workflow, your asset hierarchy, your inspection rules. The SDK supports custom agents (npm builds only), and ships utility functions — invokeTextPrompt, invokeStructuredPrompt, and invokeToolPrompt — for making LLM calls with a choice of model tier. You can even bring your own LLM behind your own backend for custom agents; the pre-built ArcGIS agents and the orchestrator, however, stay on Esri’s models.

Esri’s own best-practice guidance matches what we’d tell a client: build narrow agents for specific workflows rather than one agent that tries to do everything, and tell users clearly what the assistant can and cannot do — example prompts in the UI go a long way.

Where this fits today

Our read: this beta is ready for internal, named-user applications — an operations dashboard where field supervisors ask questions instead of learning filter widgets, an executive view where “show me last quarter’s closures by district” just works. It is not yet a fit for public-facing products: no anonymous access, no API-key path, no Enterprise support until roughly 12.2.

The work that makes an assistant good is mostly not AI work. It’s GIS housekeeping — scoped web maps, layer views that expose the right fields, aliases and descriptions that say what the data means, embeddings kept current as schemas change. Organizations that already treat their portal like a product will get sharp assistants almost for free. Organizations with 80-field layers named Export_Output_final_v3 will get an assistant that guesses. The gap between those two outcomes is exactly the kind of work we do.

Disclosure: this article is about AI tooling, and AI assistance was used in drafting it. Every technical claim was verified against the Esri documentation cited below.

References

• AI components (beta) — ArcGIS Maps SDK for JavaScript
• Intro to building agentic mapping applications
• Setup your web map for agentic applications
• Custom agents guide
• AI components — Frequently Asked Questions
• AI Assistant component sample
• Release notes for 5.0 (February 2026)