▾
AI components available in @arcgis/ai-components enable developers to build agentic web mapping applications. An agentic mapping application is an application whose primary UI is a natural language interface that allows users to interact with a web map and its data through conversational prompts. This has the benefit of allowing end users to interact with web maps with a simplified, accessible UX.
The arcgis-assistant component provides the chat interface that allows users to interact with a web map using natural language.
Explore the AI Assistant sample shown in the video.
Agents
Agents carry out tasks on behalf of the user. At least one agent must be registered with the arcgis-assistant component for it to process user requests.
The JavaScript SDK provides out-of-the-box ArcGIS agents for common tasks like map navigation and data exploration, but developers can also create custom agents to provide additional or specialized capabilities to the web application. Currently, the following agents are provided as part of the AI components package. Click the links below to learn more about each agent, their capabilities, and examples of how they work:
The web-map agents support navigation, statistic queries, attribute queries, and spatial queries. The Knowledge agent explores knowledge graph data from a service, map, or link chart. See the AI Assistant Knowledge Agent sample for its setup.
How requests are processed
When a user submits a natural language question or request, the arcgis-assistant component uses an orchestrator to determine the user’s intent and route the work to appropriate agents. A single request may involve multiple agents, each handling a different part of what the user wants to accomplish.
The agents carry out their tasks, which may include retrieving information, analyzing data, preparing information for another agent to use, or interacting with the map. Results can be presented through the assistant or used to update the map, data, or other parts of the application.

The following diagram shows how a user’s request to navigate the map is handled.

Prepare web maps for ArcGIS agents
The arcgis-assistant component needs a prepared web map only when it uses web-map-based ArcGIS agents. This requirement does not apply to custom agents or agents that use another context.
- Generate vector embeddings for the web map used by
arcgis-assistant. You need write access to the web map item to create them. For the full workflow, see Setup your web map for agentic applications. - Configure AI access for the organization and confirm that app users meet the AI components access requirements.
- Use meaningful layer names, field aliases, and field descriptions, then review the metadata so ArcGIS agents can match prompts to the correct layers and fields.
Best practices for application developers
When designing and deploying an agentic mapping application, consider the following practices:
- Set clear expectations. Describe the assistant’s capabilities and provide example requests that reflect what its registered agents can do.
- Keep custom agents focused. Design each agent for specific tasks or workflows rather than building a single agent that attempts to handle every request.
- Design maps for the intended tasks. Organize layers and metadata to support the interactions your application offers. Follow the Web map setup guide where applicable.
- Review access requirements and costs. Before deployment, check the access and security requirements and costs and pricing, including beta conditions.
- Review data handling. For custom agents, review what prompts, context, and tool results your implementation sends to its model or backend, and apply your organization’s data-handling rules.
- Test unsuccessful requests as well as successful ones. Include unavailable services, denied access, and failed actions. Do not present an unverified response as a completed action.