# Arcgis Ai Components > Add AI-powered natural language assistants to maps using the ArcGIS AI Components package. Use for chat-based map interaction, data exploration, navigation, and custom agents. - **Type:** Skill - **Install:** `agentstack add skill-saschabrunnerch-arcgis-maps-sdk-js-ai-context-arcgis-ai-components` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [SaschaBrunnerCH](https://agentstack.voostack.com/s/saschabrunnerch) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [SaschaBrunnerCH](https://github.com/SaschaBrunnerCH) - **Source:** https://github.com/SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context/tree/master/skills/arcgis-ai-components ## Install ```sh agentstack add skill-saschabrunnerch-arcgis-maps-sdk-js-ai-context-arcgis-ai-components ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # ArcGIS AI Components Use this skill when adding AI assistant capabilities to a web map, enabling users to interact with map data through natural language chat. This is a **new package in 5.0** (`@arcgis/ai-components`) with no 4.x equivalent. > **Beta:** AI Components are in beta as of 5.0. APIs may change in future releases. ## Import Patterns ### CDN (Recommended for AI Components) AI components auto-register when loaded via the SDK CDN: ```html ``` ### Direct ESM Imports (Build Tools) ```javascript import "@arcgis/ai-components/components/arcgis-assistant"; import "@arcgis/ai-components/components/arcgis-assistant-navigation-agent"; import "@arcgis/ai-components/components/arcgis-assistant-data-exploration-agent"; import "@arcgis/ai-components/components/arcgis-assistant-help-agent"; import "@arcgis/ai-components/components/arcgis-assistant-agent"; ``` ### Utility Functions ```javascript import { invokeTextPrompt, invokeStructuredPrompt, invokeToolPrompt, sendTraceMessage, getEmbeddings, cosineSimilarity, } from "@arcgis/ai-components/utils"; ``` ## Core Architecture The AI assistant uses a **component + agent** architecture: - **`arcgis-assistant`** - The chat UI container. Manages conversation, routes user messages to registered agents, and displays responses. - **Agent components** - Slotted children of the assistant. Each agent handles a specific domain (navigation, data exploration, help). The assistant orchestrates which agent handles each query. ``` arcgis-assistant ├── arcgis-assistant-navigation-agent (pan, zoom, go to locations) ├── arcgis-assistant-data-exploration-agent (query data, statistics, charts) ├── arcgis-assistant-help-agent (answer questions about the map/agents) └── arcgis-assistant-agent (custom agent wrapper) ``` ## Basic Setup ### Minimal Example (CDN) ```html AI Assistant html, body { height: 100%; margin: 0; } ``` ## arcgis-assistant Component ### Properties | Property | Attribute | Type | Default | Description | | ---------------------- | ------------------------ | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------- | | `referenceElement` | `reference-element` | `string \| HTMLArcgisMapElement` | - | **Required.** CSS selector or element reference to an `arcgis-map`. Provides map context to agents. | | `heading` | `heading` | `string` | - | Title displayed at the top of the assistant panel | | `description` | `description` | `string` | - | Subtitle text describing the assistant's capabilities | | `entryMessage` | `entry-message` | `string` | - | Welcome message shown before the user starts chatting | | `suggestedPrompts` | - | `string[]` | - | Array of suggested prompts displayed as clickable chips (set via JS only) | | `keepSuggestedPrompts` | `keep-suggested-prompts` | `boolean` | `false` | Keep suggested prompts visible after the user submits a message | | `feedbackEnabled` | `feedback-enabled` | `boolean` | `false` | Show thumbs up/down feedback buttons on assistant messages | | `logEnabled` | `log-enabled` | `boolean` | `false` | Show agent execution logs (tool calls, reasoning steps) | | `copyEnabled` | `copy-enabled` | `boolean` | `false` | Allow users to copy assistant message content | | `messages` | - | `ChatMessage[]` | `[]` | The conversation history (read/write) | ### Methods | Method | Returns | Description | | ------------------------ | --------------- | ------------------------------------------------------- | | `clearChatHistory()` | `void` | Clears the conversation and resets the assistant | | `submitMessage(message)` | `void` | Programmatically submit a user message to the assistant | | `componentOnReady()` | `Promise` | Resolves when the component is fully loaded | ### Events | Event | Detail | Description | | ----------------------- | --------------------- | -------------------------------------------------------- | | `arcgisSubmit` | `{ message: string }` | Fired when the user submits a message | | `arcgisReady` | - | Fired when the assistant is initialized and ready | | `arcgisFeedback` | `AssistantMessage` | Fired when the user provides feedback on a message | | `arcgisError` | `Error` | Fired when an error occurs during agent execution | | `arcgisInterrupt` | - | Fired when the user interrupts an in-progress response | | `arcgisInterruptCancel` | - | Fired when an interrupt is cancelled | | `arcgisInterruptSubmit` | - | Fired when a new message is submitted while interrupting | | `arcgisCancel` | - | Fired when processing is cancelled | ## Built-in Agents ### arcgis-assistant-navigation-agent Handles map navigation requests: panning, zooming, going to specific locations or features. ```html ``` **User prompt examples:** "Zoom to New York City", "Go to the largest feature", "Pan north" **Properties:** | Property | Attribute | Type | Description | |----------|-----------|------|-------------| | `referenceElement` | `reference-element` | `string \| HTMLArcgisMapElement` | Override the map reference (inherits from parent assistant if not set) | ### arcgis-assistant-data-exploration-agent Queries and analyzes layer data: statistics, filters, feature counts, and data summaries. ```html ``` **User prompt examples:** "What is the total population?", "Show me the top 5 features by area", "How many features have value > 100?" **Properties:** | Property | Attribute | Type | Description | |----------|-----------|------|-------------| | `referenceElement` | `reference-element` | `string \| HTMLArcgisMapElement` | Override the map reference | ### arcgis-assistant-help-agent Answers questions about the map, its layers, metadata, and the capabilities of other registered agents. ```html ``` **User prompt examples:** "What layers are on this map?", "What can you help me with?", "Describe the data" **Properties:** | Property | Attribute | Type | Description | |----------|-----------|------|-------------| | `referenceElement` | `reference-element` | `string \| HTMLArcgisMapElement` | Override the map reference | ## Configuring the Assistant ### Setting Suggested Prompts (JavaScript) ```javascript const assistant = document.querySelector("arcgis-assistant"); assistant.suggestedPrompts = [ "What is the total change in wheat production from 2017 to 2022?", "Go to the county that produced the most wheat in 2022.", "How many counties produced less wheat in 2022 than in 2017?", ]; ``` ### Enabling Developer Features ```html ``` ### Listening for Events ```javascript const assistant = document.querySelector("arcgis-assistant"); assistant.addEventListener("arcgisSubmit", (event) => { console.log("User submitted:", event.detail.message); }); assistant.addEventListener("arcgisFeedback", (event) => { const { feedback } = event.detail; console.log("Feedback:", feedback); // { positive: true } or { positive: false } }); assistant.addEventListener("arcgisError", (event) => { console.error("Assistant error:", event.detail); }); ``` ### Programmatic Message Submission ```javascript const assistant = document.querySelector("arcgis-assistant"); await assistant.componentOnReady(); // Submit a message as if the user typed it assistant.submitMessage("Show me the top 10 features by population"); ``` ## Custom Agents Use `arcgis-assistant-agent` to register a custom agent with the assistant. ### Defining a Custom Agent ```javascript import { invokeTextPrompt } from "@arcgis/ai-components/utils"; const assistant = document.querySelector("arcgis-assistant"); const customAgent = document.querySelector("arcgis-assistant-agent"); customAgent.agentRegistration = { name: "weather-agent", description: "Answers questions about current weather conditions at map locations.", systemPrompt: "You are a weather assistant. Use the provided tools to get weather data.", tools: [ { name: "getWeather", description: "Get current weather for a location", parameters: { type: "object", properties: { latitude: { type: "number", description: "Latitude" }, longitude: { type: "number", description: "Longitude" }, }, required: ["latitude", "longitude"], }, execute: async ({ latitude, longitude }) => { const response = await fetch( `https://api.weather.gov/points/${latitude},${longitude}`, ); const data = await response.json(); return JSON.stringify(data.properties); }, }, ], }; ``` ```html ``` ### Utility Functions for Custom Agents | Function | Description | | --------------------------------- | -------------------------------------------------------- | | `invokeTextPrompt(options)` | Send a text prompt to the LLM and get a text response | | `invokeStructuredPrompt(options)` | Send a prompt and get a structured (JSON) response | | `invokeToolPrompt(options)` | Send a prompt with tool definitions for function calling | | `sendTraceMessage(data)` | Send trace/debug messages to the assistant log | | `getEmbeddings(texts)` | Generate text embeddings for semantic search | | `cosineSimilarity(a, b)` | Compute cosine similarity between two embedding vectors | ## Web Map Requirements for AI Agents For agents to work effectively with a web map: 1. **Layer metadata** - Layers must have good metadata (descriptions, field aliases, tags). 2. **Embeddings** - The web map should have embeddings stored as an item resource. See the Web map setup guide for details. 3. **User requirements:** - Signed-in named user of an ArcGIS Online organization (no trial/public accounts) - User must have access to the web map and its layers - AI assistants must be enabled in the organization settings - Beta apps must not be blocked in the organization settings - The user must have the role privilege to use AI assistants ## Layout Patterns ### Side Panel Layout (Recommended) ```html ``` ### Expand Widget Layout ```html ``` ## Common Pitfalls 1. **Missing `reference-element`**: The assistant requires a reference to an `arcgis-map` element to provide context to agents. ```html ``` ```html ``` **Impact:** Agents have no map context and cannot execute navigation or data queries. They will fail silently or return errors. 2. **No agents registered**: The assistant itself has no built-in intelligence - you must slot at least one agent component. ```html ``` ```html ``` **Impact:** The user can type messages but they are never processed. No responses are generated. 3. **Unauthenticated users**: AI components require a signed-in ArcGIS Online named user with AI assistant privileges. Anonymous or public users cannot use the assistant. **Impact:** The assistant panel may render but agent calls fail with authentication errors. Always check authentication status before showing the assistant UI. 4. **Poor layer metadata**: Agents rely on layer descriptions, field aliases, and embeddings to understand the map data. Layers with missing metadata produce poor or irrelevant responses. **Impact:** The data exploration agent may misidentify fields or give inaccurate summaries. 5. **`suggestedPrompts` set as HTML attribute**: The `suggestedPrompts` property accepts an array and can only be set via JavaScript, not as an HTML attribute. ```html ``` ```javascript // Correct: set via JavaScript const assistant = document.querySelector("arcgis-assistant"); assistant.suggestedPrompts = [ "What is the total population?", "Go to the largest city", ]; ``` **Impact:** Suggested prompts are silently ignored when set as an HTML attribute string. ## Reference Samples - `ai-assistant` - AI Assistant component with navigation, data exploration, and help agents ## Related Skills - See `arcgis-core-maps` for setting up the map that the assistant references. - See `arcgis-widgets-ui` for Calcite layout components (`calcite-shell`, `calcite-shell-panel`). - See `arcgis-interaction` for non-AI approaches to map interaction (popups, hit tests). ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [SaschaBrunnerCH](https://github.com/SaschaBrunnerCH) - **Source:** [SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context](https://github.com/SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-saschabrunnerch-arcgis-maps-sdk-js-ai-context-arcgis-ai-components - Seller: https://agentstack.voostack.com/s/saschabrunnerch - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.