GeoDaoyuGeoDaoyu/arcgis-maps-sdk-js-ai-context/skills/arcgis-ai-components/SKILL.md

arcgis-ai-components

Skill0 starsChanged 7 months agoMITView on GitHub

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.

1 other project uses a version of this.

Adopted by

Most recently taken up by

geoai-latam/SKILL_JS5_ARCGIStheir own version, first seen Nov 8, 2026

Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
geoai-latam/SKILL_JS5_ARCGIS★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository47 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/arcgis-ai-components/AGENTS.mdAGENTS.md
- skills/arcgis-authentication/AGENTS.mdAGENTS.md
- skills/arcgis-charts/AGENTS.mdAGENTS.md
- skills/arcgis-coding-components/AGENTS.mdAGENTS.md
- skills/arcgis-core-maps/AGENTS.mdAGENTS.md
- skills/arcgis-editing/AGENTS.mdAGENTS.md
- skills/arcgis-embeddable-maps/AGENTS.mdAGENTS.md
- skills/arcgis-interaction/AGENTS.mdAGENTS.md
- skills/arcgis-layers/AGENTS.mdAGENTS.md
- skills/arcgis-starter-app/AGENTS.mdAGENTS.md
- skills/arcgis-visualization/AGENTS.mdAGENTS.md
- skills/arcgis-widgets-ui/AGENTS.mdAGENTS.md
- arcgis-3d-layersSkill
- arcgis-advanced-layersSkill
- arcgis-arcadeSkill
- arcgis-authenticationSkill
- arcgis-chartsSkill
- arcgis-cim-symbolsSkill
- arcgis-coding-componentsSkill
- arcgis-coordinates-projectionSkill
- arcgis-core-mapsSkill
- arcgis-core-utilitiesSkill
- arcgis-custom-renderingSkill
- arcgis-editingSkill
- arcgis-embeddable-mapsSkill
- arcgis-feature-effectsSkill
- arcgis-geometry-operationsSkill
- arcgis-imagerySkill
- arcgis-interactionSkill
- arcgis-knowledge-graphsSkill
- arcgis-layersSkill
- arcgis-map-toolsSkill
- arcgis-performanceSkill
- arcgis-popup-templatesSkill
- arcgis-portal-contentSkill
- arcgis-rest-servicesSkill
- arcgis-scene-environmentSkill
- arcgis-smart-mappingSkill
- arcgis-spatial-analysisSkill
- arcgis-starter-appSkill
- arcgis-tables-formsSkill
- arcgis-time-animationSkill
- arcgis-utility-networksSkill
- arcgis-visualizationSkill
- arcgis-widgets-advancedSkill
- arcgis-widgets-uiSkill

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use this skill when adding AI assistant capabilities to a web map, enabling users to interact with map data through natural language chat.
line 8
Very specific:
Use arcgis-assistant-agent to register a custom agent with the assistant.
line 256

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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:

<!-- Load ArcGIS Maps SDK (includes ai-components registration) -->
<script type="module" src="https://js.arcgis.com/5.0/"></script>

Direct ESM Imports (Build Tools)

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

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)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>AI Assistant</title>
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>
  </head>
  <body>
    <calcite-shell>
      <arcgis-map id="my-map" item-id="c13bffcad4a244a99062e915e9bc1dc3">
        <arcgis-zoom slot="top-left"></arcgis-zoom>
      </arcgis-map>
      <calcite-shell-panel slot="panel-end" width="l">
        <calcite-panel>
          <arcgis-assistant
            reference-element="#my-map"
            heading="Map Assistant"
            description="Ask questions about the data on this map."
            entry-message="Hello! I can help you explore this map."
          >
            <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
            <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
            <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
          </arcgis-assistant>
        </calcite-panel>
      </calcite-shell-panel>
    </calcite-shell>
  </body>
</html>

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<this>`	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.

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
</arcgis-assistant>

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.

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
</arcgis-assistant>

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.

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
</arcgis-assistant>

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)

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

<arcgis-assistant
  reference-element="#my-map"
  log-enabled
  copy-enabled
  feedback-enabled
  heading="Data Explorer"
  description="Ask questions about the map data."
  entry-message="Welcome! Try asking about the data."
>
  <!-- agents -->
</arcgis-assistant>

Listening for Events

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

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

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);
      },
    },
  ],
};

<arcgis-assistant reference-element="#my-map">
  <arcgis-assistant-agent></arcgis-assistant-agent>
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
</arcgis-assistant>

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:

Layer metadata - Layers must have good metadata (descriptions, field aliases, tags).
Embeddings - The web map should have embeddings stored as an item resource. See the Web map setup guide for details.
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)

<calcite-shell>
  <arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
    <arcgis-zoom slot="top-left"></arcgis-zoom>
    <arcgis-expand slot="top-left">
      <arcgis-legend></arcgis-legend>
    </arcgis-expand>
  </arcgis-map>
  <calcite-shell-panel slot="panel-end" width="l">
    <calcite-panel>
      <arcgis-assistant
        reference-element="#map"
        heading="Map Assistant"
        entry-message="Ask me anything about this map."
      >
        <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
        <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
        <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
      </arcgis-assistant>
    </calcite-panel>
  </calcite-shell-panel>
</calcite-shell>

Expand Widget Layout

<arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
  <arcgis-expand slot="top-right">
    <arcgis-assistant
      reference-element="#map"
      heading="Assistant"
      entry-message="How can I help?"
    >
      <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
      <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
      <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
    </arcgis-assistant>
  </arcgis-expand>
</arcgis-map>

Common Pitfalls

Missing reference-element: The assistant requires a reference to an arcgis-map element to provide context to agents.

<!-- Anti-pattern: no reference-element -->
<arcgis-assistant heading="Assistant">
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
</arcgis-assistant>
<arcgis-map id="map" item-id="abc123"></arcgis-map>

<!-- Correct: point to the map element -->
<arcgis-assistant reference-element="#map" heading="Assistant">
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
</arcgis-assistant>
<arcgis-map id="map" item-id="abc123"></arcgis-map>

Impact: Agents have no map context and cannot execute navigation or data queries. They will fail silently or return errors.

No agents registered: The assistant itself has no built-in intelligence - you must slot at least one agent component.

<!-- Anti-pattern: assistant with no agents -->
<arcgis-assistant reference-element="#map" heading="Assistant">
</arcgis-assistant>

<!-- Correct: register agents as children -->
<arcgis-assistant reference-element="#map" heading="Assistant">
  <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
  <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
  <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
</arcgis-assistant>

Impact: The user can type messages but they are never processed. No responses are generated.

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.
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.

suggestedPrompts set as HTML attribute: The suggestedPrompts property accepts an array and can only be set via JavaScript, not as an HTML attribute.

<!-- Anti-pattern: HTML attribute (won't work) -->
<arcgis-assistant suggested-prompts="What is the total?"></arcgis-assistant>

// 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).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free

Adopted by

Most recently taken up by

Word for word · 0

Edited · 0

Wrote their own version · 1

The file

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

ArcGIS AI Components

Import Patterns

CDN (Recommended for AI Components)

Direct ESM Imports (Build Tools)

Utility Functions

Core Architecture

Basic Setup

Minimal Example (CDN)

arcgis-assistant Component

Properties

Methods

Events

Built-in Agents

arcgis-assistant-navigation-agent

arcgis-assistant-data-exploration-agent

arcgis-assistant-help-agent

Configuring the Assistant

Setting Suggested Prompts (JavaScript)

Enabling Developer Features

Listening for Events

Programmatic Message Submission

Custom Agents

Defining a Custom Agent

Utility Functions for Custom Agents

Web Map Requirements for AI Agents

Layout Patterns

Side Panel Layout (Recommended)

Expand Widget Layout

Common Pitfalls

Reference Samples

Related Skills

Does it work?

No reviews yet

Your trail

Now do this for your own.