arcgis-assistant | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/ai-components/components/arcgis-assistant";

Inheritance:: ArcgisAssistant→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 5.0

beta

The ArcGIS Assistant component provides a chat-based natural language interface for interacting with web map data via agents. This component uses an orchestrator, which relies on a large language model (LLM) for determining user intent. Once the intent is determined, the assistant routes the user's request to an agent that uses an LLM to generate text and structured responses.

By default, the arcgis-assistant component does not include any agents. You must register at least one agent for the assistant to function. You can register agents declaratively using any of the available agent components, or you can register custom agents.

Register agents

To register agents declaratively, include one or more agent components as children of the arcgis-assistant component. This can be done in HTML or programmatically using JavaScript.

<arcgis-map id="my-map"></arcgis-map>
<arcgis-assistant reference-element="#my-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>

const assistant = document.querySelector("arcgis-assistant");
const navigationAgent = document.createElement("arcgis-assistant-navigation-agent");
const dataExplorationAgent = document.createElement("arcgis-assistant-data-exploration-agent");
assistant.appendChild(navigationAgent);
assistant.appendChild(dataExplorationAgent);

Note that the reference-element property on the arcgis-assistant component must point to a valid arcgis-map element for the included ArcGIS agents to function properly, as they rely on the map context to perform their tasks. This is not a requirement for custom agents.

Context

Use the referenceElement property to provide a web map as context to the assistant and its agents. This should be a reference to the map that the assistant will interact with, and is required for the included ArcGIS agents to function properly.

To learn more about this component, try out the demo

Important considerations and best practices

Due to the non-deterministic nature of generative AI, there may be inaccuracies or unexpected behavior when using the out-of-the-box agents. Therefore, it is important to set clear expectations for end users and provide guidance on how to interact with the assistant to help mitigate these issues. Some ways to do this include:

Provide suggestedPrompts. This helps users understand the bounds of the assistant and gives them an idea of how to phrase questions to get the best results.
Use the entryMessage property to provide an entry message with instructions and guidance.

See also

Demo

Properties

Property	Attribute	Type
`copyEnabled`	`copy-enabled`	`boolean`
`description`	`description`	`string \| undefined`
`entryMessage`	`entry-message`	`string \| undefined`
`feedbackEnabled`	`feedback-enabled`	`boolean`
`heading`	`heading`	`string \| undefined`
`keepSuggestedPrompts`	`keep-suggested-prompts`	`boolean`
`logEnabled`	`log-enabled`	`boolean`
`messages`		`Collection<ChatMessage>`
`referenceElement`	`reference-element`	`ArcgisMap \| string \| null`
`suggestedPrompts`		`string[]`

copyEnabled

Property

Type: boolean

When true, enables the copy action that, when clicked, copies the content of the message to the clipboard. This can be helpful for users to easily copy and share information provided by the assistant, such as a summary of findings, a set of instructions, or any other relevant details. Enabling this property can enhance the user experience by providing a convenient way for users to capture and utilize the information generated by the assistant.

Attribute: copy-enabled
Default value: false

Examples

<arcgis-assistant copy-enabled></arcgis-assistant>

const assistant = document.querySelector("arcgis-assistant");
assistant.copyEnabled = true;

description

Property

Type: string | undefined

The description text displayed below the heading in the assistant. This text provides additional context about the assistant's capabilities and how users can interact with it.

Attribute: description

Examples

<arcgis-assistant description="Explore parcel data ownership, zoning designations, and other relevant information."></arcgis-assistant>

const assistant = document.querySelector("arcgis-assistant");
assistant.description = "Explore parcel data ownership, zoning designations, and other relevant information.";

entryMessage

Property

Type: string | undefined

The instructions to display when the assistant is first loaded. This is intended to be a welcome or entry message that provides guidance to users on how to interact with the assistant. Once the user submits their first message, the entry message will be closed and replaced with the chat interface. You can use this property to provide instructions, suggest prompts, or simply welcome users to the assistant.

Attribute: entry-message

Examples

<arcgis-assistant entry-message="I can answer questions about parcel ownership, zoning, and other relevant information."></arcgis-assistant>

const assistant = document.querySelector("arcgis-assistant");
assistant.entryMessage = "I can answer questions about parcel ownership, zoning, and other relevant information.";

feedbackEnabled

Property

Type: boolean

When true, enables the feedback action in the chat interface, allowing developers to capture user feedback on the assistant's responses. The action simply provides a thumbs up and thumbs down experience for users to indicate whether a response was helpful or not. When the user submits feedback, the @arcgisFeedback event is emitted allowing the app developer to capture additional feedback through a custom interface and log it to a database or service for later analysis.

Attribute: feedback-enabled
Default value: false

Examples

<arcgis-assistant feedback-enabled></arcgis-assistant>

const assistant = document.querySelector("arcgis-assistant");
assistant.feedbackEnabled = true;
assistant.addEventListener("arcgisFeedback", (event) => {
  const feedback = event.detail;
  // Capture additional feedback from the user and log it to a database or service for later analysis
});

heading

Property

Type: string | undefined

The heading text displayed at the top of the assistant. This name should be concise and descriptive of the assistant's purpose.

For applications where the primary interface is the assistant, this heading could also be used as the application title. In cases where the assistant could be collapsed or is a secondary interface to a standard GUI, the heading should be more specific to the assistant's function to avoid confusion with the overall application title.

Attribute: heading

Examples

<arcgis-assistant heading="Parcel Viewer"></arcgis-assistant>

const assistant = document.querySelector("arcgis-assistant");
assistant.heading = "Zoning Assistant";

keepSuggestedPrompts

Property

Type: boolean

When true, keeps suggested prompts displayed in the UI after the user submits a message. By default, suggested prompts are cleared, when the user submits a message.

Attribute: keep-suggested-prompts
Default value: false

Examples

<arcgis-assistant keep-suggested-prompts></arcgis-assistant>

const assistant = document.querySelector("arcgis-assistant");
assistant.keepSuggestedPrompts = true;

logEnabled

Property

Type: boolean

When true, enables the log action that when clicked displays log messages in the chat interface. Log messages provide detailed messages including which agents or tools were invoked, the parameters generated by the LLM, and any relevant details about how the assistant arrived at its response. Enabling logs can be helpful for developers for debugging during the development of an assistant or agentic web application. It may also be useful to end users for transparency purposes, allowing them to understand the assistant's behavior and decision-making process.

Enabling this property for a production app depends on the role of the audience. More technical audiences may benefit from having access to these logs while non-technical audiences may find them overwhelming or confusing.

Attribute: log-enabled
Default value: false

Examples

<arcgis-assistant log-enabled></arcgis-assistant>

const assistant = document.querySelector("arcgis-assistant");
assistant.logEnabled = true;

messages

Property

Type: Collection<ChatMessage>

The collection of messages exchanged between the user and the assistant. Each message includes the role (user or assistant), along with any relevant logs or errors. These messages are rendered in the chat interface and are used to provide context for the conversation. When a user submits a message, it is added to this collection with the role of "user". When the assistant generates a response, it is added to this collection with the role of "assistant", along with any logs or errors that occurred during processing.

referenceElement

Property

Type: ArcgisMap | string | null

The reference element to the map that provides context for the assistant and its agents. Currently, this is only scoped to arcgis-map elements. This is required when ArcGIS agents are registered to the assistant. For example, this allows the navigation agent to execute a map navigation tool for a specific map.

Attribute: reference-element

Example

<arcgis-map id="my-map"></arcgis-map>
<arcgis-assistant reference-element="my-map"></arcgis-assistant>

suggestedPrompts

Property

Type: string[]

Prompts to suggest to the end user on load. These are intended to help users understand which questions they can ask. This property should be set to establish boundaries for the end user. As all agents have limitations and LLMs can be unpredictable, it's important to set clear expectations for users to give them a better chance to succeed. By providing suggested prompts, you can guide users towards asking questions that are relevant to the data being used and the capabilities of the registered agents, which can help to ensure that the assistant provides accurate and helpful responses.

You should typically provide 2-3 suggested prompts.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.suggestedPrompts = [
  "What city has the highest population?",
  "What is the highest point in this area?"
];

Methods

Method	Signature
`clearChatHistory`	`clearChatHistory(): Promise<void>`
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`submitMessage`	`submitMessage(message: string): Promise<void>`

clearChatHistory

Method

Signature: clearChatHistory (): Promise<void>

Clears the chat history between the user and the assistant. This method can be used to programmatically reset the conversation, removing all messages from the chat interface.

Returns: Promise<void>

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.clearChatHistory();

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisAssistant = document.querySelector("arcgis-assistant");
document.body.append(arcgisAssistant);
await arcgisAssistant.componentOnReady();
console.log("arcgis-assistant is ready to go!");

submitMessage

Method

Signature: submitMessage (message: string): Promise<void>

Programmatically submits a message to the assistant. This method can be used to submit messages from outside the component, such as from another component or from custom JavaScript code. When a message is submitted using this method, it is added to the messages collection with the role of "user", and then processed by the assistant in the same way as if it were submitted through the chat interface. This allows for greater flexibility in how messages are sent to the assistant and can enable more complex interactions and integrations with other components or services.

Parameters

Parameter	Type	Description	Required
message	`string`	The message to submit to the assistant. This should be a string containing the user's input or question they want to ask the assistant.

Returns: Promise<void>

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.submitMessage("What is the population of New York City?");

Events

Name	Type
`arcgisCancel`	CustomEvent<void>
`arcgisError`	CustomEvent<Error>
`arcgisFeedback`	CustomEvent<AssistantMessage>
`arcgisInterrupt`	CustomEvent<Interrupt>
`arcgisInterruptCancel`	CustomEvent<void>
`arcgisInterruptSubmit`	CustomEvent<string[] \| boolean \| string>
`arcgisReady`	CustomEvent<void>
`arcgisSubmit`	CustomEvent<string>

arcgisCancel

Event

arcgisCancel: CustomEvent<void>

Emitted when the user cancels a message. This is typically invoked when a user submits a question while a previous question is still being processed. This allows app developers to capture messages cancelled by the user and respond to them in custom ways, such as by providing additional information, triggering other actions in the app, or logging them for analysis.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisCancel", (event) => {
  // Handle the cancelled message
});

arcgisError

Event

arcgisError: CustomEvent<Error>

Emitted when the assistant encounters an error. The event detail includes an Error object with information about the error that occurred. This allows app developers to capture errors that occur within the assistant and respond to them in custom ways, such as by displaying an error message to the user, logging the error for analysis, or triggering other actions in the app.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisError", (event) => {
  const error = event.detail;
  // Handle the error, such as by displaying an error message to the user or logging it for analysis
});

arcgisFeedback

Event

arcgisFeedback: CustomEvent<AssistantMessage>

Emitted when the user clicks the thumbs up or thumbs down feedback action that is displayed when feedbackEnabled is true. The event detail includes an AssistantMessage object that includes a feedback property with an object indicating whether the feedback is positive or negative. This allows the application to capture user feedback on the assistant's responses and respond to it in custom ways, such as by providing additional information, adjusting the assistant's behavior, logging the feedback for analysis, or triggering other actions in the app.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisFeedback", (event) => {
  const feedback = event.detail;
  // Handle the feedback, such as by providing additional information, adjusting the assistant's behavior, or logging it for analysis
});

arcgisInterrupt

Event

arcgisInterrupt: CustomEvent<Interrupt>

Emitted when an agent triggers an interrupt. An interrupt is a human-in-the-loop mechanism that provides a UI component prompting the user for additional information.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisInterrupt", (event) => {
  const interrupt = event.detail;
  // Handle the interrupt
});

arcgisInterruptCancel

Event

arcgisInterruptCancel: CustomEvent<void>

Emitted when the user cancels an interrupt. This is typically invoked when a user clicks the cancel button displayed in an interrupt message

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisInterruptCancel", (event) => {
  // Handle the interrupt cancellation such as logging it for analysis
});

arcgisInterruptSubmit

Event

arcgisInterruptSubmit: CustomEvent<string[] | boolean | string>

Emitted when the user submits a message during an interrupt. For example, this will be invoked if the user clicks the submit button in an interrupt message asking for confirmation, or when the user submits additional text or selects an option provided in an interrupt.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisInterruptSubmit", (event) => {
  const message = event.detail; // The message or option selected by the user for the interrupt
  // Do something with the interrupt submission
});

arcgisReady

Event

arcgisReady: CustomEvent<void>

Emitted when the assistant is ready to receive messages from the end user. This indicates that the assistant has been successfully initialized and is ready to process user input.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisReady", (event) => {
  // Handle the assistant being ready, such as by hiding a loading indicator,
  // displaying a welcome message, or enabling certain UI elements for user interaction
});

arcgisSubmit

Event

arcgisSubmit: CustomEvent<string>

Emitted when the user submits a message. This is typically invoked when a user clicks the submit button in the chat interface or hits the Enter key.

Example

const assistant = document.querySelector("arcgis-assistant");
assistant.addEventListener("arcgisSubmit", (event) => {
  const message = event.detail;
  // Do something with the submitted message, such as logging it for analysis or triggering other actions in the app
});

Slots

Name	Description
`default (unnamed)`	This is the default slot
`header-actions-end`	Slot for adding actions to the end of the header.
`entry-message`	Slot for adding a welcome or entry message on load.
`entry-actions-start`	Slot for adding actions to the start of the entry area.
`footer-content`	Slot for adding content to the footer.