@arcgis/ai-components 5.1.0-next.7 → 5.1.0-next.71

package/dist/components/arcgis-assistant-agent/customElement.d.ts

@@ -3,13 +3,19 @@ import type { AgentRegistration } from "@arcgis/ai-orchestrator";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 
 /**
- * The Assistant Agent component is a generic wrapper for adding custom AI agents into the ArcGIS Assistant component. To define
+ * The Assistant Agent component is a generic wrapper for registering custom agents to the [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/) component. To define
  * a custom agent, you must be familiar with [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview). Custom agents must
  * include a StateGraph that defines the agent's graph and subgraphs.
  *
- * > Building custom agents can only be done using modern JavaScript/TypeScript tooling and cannot be done directly in HTML using
+ * Building custom agents can only be done using modern JavaScript/TypeScript tooling and cannot be done directly in HTML using
  * CDN imports. Therefore, you must use a package manager like npm or yarn to install the required dependencies. Please refer to the
- * Creating Custom Agents guide for more instructions.
+ * [Custom Agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/) for more instructions on how to create a custom agent.
+ *
+ * Use the [utils](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/) module for helper functions and types related to building custom agents, including the `AgentRegistration`
+ * type and functions for making LLM calls, managing agent state, and setting up human-in-the-loop workflows.
+ *
+ * > We recommend that developers building custom agents have experience working with LLMs and generative AI, and have a good
+ * understanding of the limitations of these technologies when building applications for end users.
  *
  * This is an unrendered component that must be added as a child of the `arcgis-assistant` component in either HTML or JavaScript.
  *
@@ -42,6 +48,12 @@ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
  * @beta
  * @see [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/)
  * @see [LangGraph documentation](https://docs.langchain.com/oss/javascript/langgraph/overview)
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+ * @see [AI Assistant component sample](https://developers.arcgis.com/javascript/latest/sample-code/ai-assistant/)
+ * @see [AgentRegistration](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#AgentRegistration)
+ * @see [invokeStructuredPrompt](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#invokeStructuredPrompt)
+ * @see [invokeToolPrompt](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#invokeToolPrompt)
+ * @see [invokeTextPrompt](https://developers.arcgis.com/javascript/latest/references/ai-components/utils/index/#invokeTextPrompt)
  */
 export abstract class ArcgisAssistantAgent<TContext = Record<string, unknown>> extends LitElement {
   /**
@@ -49,13 +61,15 @@ export abstract class ArcgisAssistantAgent<TContext = Record<string, unknown>> e
    * This must include a StateGraph definition (defined using
    * [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview)).
    *
-   * This is an agent defined in the client and can be invoked by the assistant within the browser to perform specific tasks
+   * This is an agent defined in the client and can be invoked by the assistant from the browser to perform specific tasks
    * using functions defined in the client.
    *
-   * See the Creating Custom Agents guide for more instructions.
+   * See the [Custom Agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/) for more instructions
+   * and links to samples demonstrating how to create custom agents.
    *
    * @required
    * @see [LangGraph documentation](https://docs.langchain.com/oss/javascript/langgraph/overview)
+   * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
    * @example
    * ```js
    * // An example graph that updates a component property and replies with a confirmation message
@@ -111,17 +125,17 @@ export abstract class ArcgisAssistantAgent<TContext = Record<string, unknown>> e
    */
   accessor agent: AgentRegistration;
   /**
-   * If the agent requires context, it can be provided via this property and accessed in the
+   * If the agent requires context provided by the application or user, it can be provided via this property and accessed in the
    * agent's graph nodes.
    *
    * @example
    * ```js
    * assistantAgent.context = {
    *   myData: {
-   *    // custom context data for the agent
+   *    // data required for the custom agent
    *   },
    * };
    * ```
    */
-  accessor context: TContext | undefined;
+  accessor context: TContext | (() => Promise<TContext | undefined> | TContext | undefined) | undefined;
 }

package/dist/components/arcgis-assistant-agent/customElement.js

@@ -1,19 +1,19 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
 import { c as t } from "../../chunks/runtime.js";
 import { LitElement as s } from "@arcgis/lumina";
-import { i as e } from "../../chunks/utils.js";
-class i extends s {
+import { i as e, a as i } from "../../chunks/utils.js";
+class n extends s {
   static {
     this.properties = { agent: 0, context: 0 };
   }
-  getContext() {
-    return this.context;
+  async getContext() {
+    return e(this.context) ? await this.context() : this.context;
   }
   load() {
-    e(this);
+    i(this);
   }
 }
-t("arcgis-assistant-agent", i);
+t("arcgis-assistant-agent", n);
 export {
-  i as ArcgisAssistantAgent
+  n as ArcgisAssistantAgent
 };

package/dist/components/arcgis-assistant-chat/customElement.d.ts

@@ -1,18 +1,11 @@
 /// <reference path="../../index.d.ts" />
 import type Collection from "@arcgis/core/core/Collection.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { ChatMessage } from "../arcgis-assistant/types.js";
 
 /** @internal */
 export abstract class ArcgisAssistantChat extends LitElement {
   /** @default false */
   accessor loading: boolean;
-  /** @default "" */
-  accessor loadingMessage: string;
-  accessor messages: Collection<{
-      type: "prompt" | "response";
-      content?: string;
-      log?: string;
-      error?: string;
-  }>;
-  accessor user: string | undefined;
+  accessor messages: Collection<ChatMessage>;
 }

package/dist/components/arcgis-assistant-chat/customElement.js

@@ -1,20 +1,20 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
-import { c as a } from "../../chunks/runtime.js";
+import { c as s } from "../../chunks/runtime.js";
 import { css as e, html as t } from "lit";
 import { LitElement as i } from "@arcgis/lumina";
-import { createRef as o, ref as n } from "lit/directives/ref.js";
-import r from "@arcgis/core/core/Collection.js";
-import { watch as l } from "@arcgis/core/core/reactiveUtils.js";
-const c = e`.assistant-chat__messages-container{display:flex;flex:1;flex-direction:column}.assistant-chat__messages-list{padding:var(--calcite-spacing-lg);display:flex;flex-direction:column;gap:var(--calcite-spacing-md);flex:1 1 auto;min-height:0;justify-content:flex-end;overflow:auto}`;
-class d extends i {
+import { createRef as a, ref as o } from "lit/directives/ref.js";
+import l from "@arcgis/core/core/Collection.js";
+import { watch as r } from "@arcgis/core/core/reactiveUtils.js";
+const n = e`.messages-container{display:flex;flex:1;flex-direction:column}.messages-list{padding:var(--calcite-spacing-lg);display:flex;flex-direction:column;gap:var(--calcite-spacing-xxl);flex:1 1 auto;min-height:0;justify-content:flex-end;overflow:auto}`;
+class c extends i {
   constructor() {
-    super(...arguments), this.#s = o(), this.loading = !1, this.loadingMessage = "", this.messages = new r([]);
+    super(...arguments), this.#s = a(), this.loading = !1, this.messages = new l([]);
   }
   static {
-    this.properties = { loading: 5, loadingMessage: 1, user: 1, messages: 0 };
+    this.properties = { loading: 5, messages: 0 };
   }
   static {
-    this.styles = c;
+    this.styles = n;
   }
   #s;
   firstUpdated() {
@@ -25,7 +25,7 @@ class d extends i {
       this.messages.on("change", () => {
         this.requestUpdate(), this._scrollToEnd();
       }),
-      l(() => this.loading, () => {
+      r(() => this.loading, () => {
         this._scrollToEnd();
       })
     ]);
@@ -36,10 +36,10 @@ class d extends i {
     });
   }
   render() {
-    return t`<div class="assistant-chat__messages-container"><div class="assistant-chat__messages-list"><slot></slot>${this.messages.map((s) => t`<arcgis-assistant-chat-card .type=${s.type} .content=${s.content} .log=${s.log} .error=${s.error} .user=${this.user}></arcgis-assistant-chat-card>`)}${this.loading ? t`<arcgis-assistant-chat-card .loading=${this.loading} .loadingMessage=${this.loadingMessage} type=response></arcgis-assistant-chat-card>` : null}</div><div ${n(this.#s)}></div></div>`;
+    return t`<div class="messages-container"><div class="messages-list"><slot name=message-starter></slot><slot name=messages></slot><slot name=message-loading></slot></div><div ${o(this.#s)}></div></div>`;
   }
 }
-a("arcgis-assistant-chat", d);
+s("arcgis-assistant-chat", c);
 export {
-  d as ArcgisAssistantChat
+  c as ArcgisAssistantChat
 };

package/dist/components/arcgis-assistant-chat/index.js

@@ -1,2 +1 @@
-import "../arcgis-assistant-chat-card/index.js";
 export * from "./customElement.js";

package/dist/components/arcgis-assistant-chat-entry/customElement.d.ts

@@ -1,27 +1,30 @@
 /// <reference path="../../index.d.ts" />
+import type Collection from "@arcgis/core/core/Collection.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { ChatMessage } from "../arcgis-assistant/types.js";
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 
-/** @internal */
+/**
+ * An input bar primitive for collecting assistant prompts.
+ *
+ * @slot [entry-actions-start] - Slot for adding actions to the start of the entry area.
+ * @slot [entry-actions-end] - Slot for adding actions to the end of the entry area.
+ */
 export abstract class ArcgisAssistantChatEntry extends LitElement {
   /** @internal */
-  protected _messages: {
-      entryPlaceholder: string;
-      stopButtonLabel: string;
-      askButtonLabel: string;
-  } & T9nMeta<{
-      entryPlaceholder: string;
-      stopButtonLabel: string;
-      askButtonLabel: string;
-  }>;
+  protected _messages: { entryPlaceholder: string; } & T9nMeta<{ entryPlaceholder: string; }>;
   /** @default false */
   accessor awaitingResponse: boolean;
-  /** @default true */
-  accessor enterKeySubmits: boolean;
   accessor entryPlaceholder: string | undefined;
   /** @default "" */
   accessor inputValue: string;
+  /** @default false */
+  accessor keyboardShortcutsDisabled: boolean;
+  accessor messages: Collection<ChatMessage>;
   accessor status: "error" | "ready" | "working" | undefined;
+  /** @default false */
+  accessor voiceInputEnabled: boolean;
+  submitMessage(): Promise<void>;
   readonly arcgisCancel: import("@arcgis/lumina").TargetedEvent<this, void>;
   readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, string>;
   readonly "@eventTypes": {

package/dist/components/arcgis-assistant-chat-entry/customElement.js

@@ -1,44 +1,78 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
-import { c as e } from "../../chunks/runtime.js";
-import { css as i, html as s } from "lit";
-import { LitElement as r, createEvent as a, nothing as n } from "@arcgis/lumina";
-import { createRef as c, ref as o } from "lit/directives/ref.js";
-import { watch as l } from "@arcgis/core/core/reactiveUtils.js";
-import { u } from "../../chunks/useT9n.js";
-const h = i`.assistant-chat-entry__input-container{display:flex;flex-direction:column}.assistant-chat-entry__footer-start{display:flex;gap:var(--calcite-spacing-md);flex-wrap:wrap;align-items:center}.assistant-chat-entry__footer-end{display:flex;gap:var(--calcite-spacing-md);align-items:center}.assistant-chat-entry__status-indicator{width:9px;height:9px;border-radius:100%;background-color:var(--calcite-color-status-success)}.assistant-chat-entry__status-indicator[data-status=working]{background-color:var(--calcite-color-status-warning)}.assistant-chat-entry__status-indicator[data-status=error]{background-color:var(--calcite-color-status-danger)}.assistant-chat-entry__status-text{text-transform:capitalize}`;
-class d extends r {
+import { c as p } from "../../chunks/runtime.js";
+import { css as d, html as l } from "lit";
+import { LitElement as g, createEvent as u } from "@arcgis/lumina";
+import { createRef as c, ref as h } from "lit/directives/ref.js";
+import { u as f } from "../../chunks/useT9n.js";
+import m from "@arcgis/core/core/Collection.js";
+const y = d`.input-container{display:flex;flex-direction:column}.footer-start{display:flex;gap:var(--calcite-spacing-md);flex-wrap:wrap;align-items:center}.footer-end{display:flex;gap:var(--calcite-spacing-md);align-items:center}.status-indicator{width:9px;height:9px;border-radius:100%;background-color:var(--calcite-color-status-success)}.status-indicator[data-status=working]{background-color:var(--calcite-color-status-warning)}.status-indicator[data-status=error]{background-color:var(--calcite-color-status-danger)}.status-text{text-transform:capitalize}`;
+class v extends g {
   constructor() {
-    super(...arguments), this.#t = c(), this._messages = u({ blocking: !0 }), this.enterKeySubmits = !0, this.awaitingResponse = !1, this.inputValue = "", this.arcgisCancel = a(), this.arcgisSubmit = a();
+    super(...arguments), this.#s = c(), this.#i = c(), this.#t = -1, this.#e = "", this.#a = (t) => {
+      t.stopPropagation();
+      const s = t.detail;
+      this._setDraftValue(s.value), s.focusInput && this.#s.value && this.#s.value.setFocus();
+    }, this.#r = (t) => {
+      const s = t.target.value ?? "";
+      this.inputValue = s, this.#e = s;
+    }, this._messages = f({ blocking: !0 }), this.keyboardShortcutsDisabled = !1, this.awaitingResponse = !1, this.inputValue = "", this.voiceInputEnabled = !1, this.messages = new m([]), this.arcgisCancel = u(), this.arcgisSubmit = u();
   }
   static {
-    this.properties = { enterKeySubmits: 5, entryPlaceholder: 1, awaitingResponse: 5, inputValue: 1, status: 1 };
+    this.properties = { _userMessages: 16, keyboardShortcutsDisabled: 5, entryPlaceholder: 1, awaitingResponse: 5, inputValue: 1, status: 1, voiceInputEnabled: 5, messages: 0 };
   }
   static {
-    this.styles = h;
+    this.styles = y;
   }
+  #s;
+  #i;
   #t;
-  loaded() {
-    this.manager.onLifecycle(() => [
-      l(() => this.inputValue, (t) => {
-        this.#t.value && (this.#t.value.value = t);
-      }, { initial: !0 })
-    ]);
+  #e;
+  #a;
+  #r;
+  get _userMessages() {
+    return this.messages.toArray().filter((t) => t.role === "user").map(({ content: t }) => t);
   }
-  async _submitMessage() {
+  async submitMessage() {
     if (this.awaitingResponse) {
       this.arcgisCancel.emit();
       return;
     }
-    const t = this.#t.value?.value.trim();
-    t && (this.arcgisSubmit.emit(t), this.#t.value && (this.#t.value.value = "", await this.#t.value.setFocus()));
+    const t = this.inputValue.trim();
+    t && (this.arcgisSubmit.emit(t), this.inputValue = "", this.#t = -1, this.#e = "", this.#i.value?.clearDraftSession(), this.#s.value && await this.#s.value.setFocus());
+  }
+  loaded() {
+    this.manager.onLifecycle(() => (this.el.addEventListener("arcgisVoiceInputDraftChange", this.#a), {
+      remove: () => {
+        this.el.removeEventListener("arcgisVoiceInputDraftChange", this.#a);
+      }
+    }));
+  }
+  async _navigateHistory(t, s) {
+    const a = this.#s.value;
+    if (!a)
+      return;
+    const e = this._userMessages;
+    if (e.length === 0)
+      return;
+    const r = a.value ?? "", n = a.shadowRoot?.querySelector("textarea"), i = n?.selectionStart, o = n?.selectionEnd;
+    if (!(i == null || o == null) && !(i !== o || t === "up" && i !== 0 || t === "down" && i !== r.length)) {
+      if (t === "up") {
+        this.#t === -1 ? (this.#e = r, this.#t = e.length - 1) : this.#t = Math.max(0, this.#t - 1), this.inputValue = e[this.#t] ?? "", s.preventDefault();
+        return;
+      }
+      this.#t !== -1 && (this.#t < e.length - 1 ? (this.#t += 1, this.inputValue = e[this.#t] ?? "") : (this.#t = -1, this.inputValue = this.#e), s.preventDefault());
+    }
+  }
+  _setDraftValue(t) {
+    this.inputValue = t, this.#t = -1, this.#e = t;
   }
   render() {
-    return s`<div class="assistant-chat-entry__input-container"><calcite-text-area .value=${this.#t.value?.value} .placeholder=${this.entryPlaceholder ?? this._messages.entryPlaceholder} @keydown=${async (t) => {
-      t.key === "Enter" && !t.shiftKey && this.enterKeySubmits && (t.preventDefault(), await this._submitMessage());
-    }} ${o(this.#t)}><div slot=footer-start class="assistant-chat-entry__footer-start"><slot name=entry-actions-start></slot></div><div slot=footer-end class="assistant-chat-entry__footer-end">${this.status ? s`<div id=tooltip-status class="assistant-chat-entry__status-indicator" data-status=${this.status ?? n}></div><calcite-tooltip reference-element=tooltip-status offset-distance=12><span class="assistant-chat-entry__status-text">${this.status}</span></calcite-tooltip>` : null}<calcite-button .iconStart=${this.awaitingResponse ? "circle-stop" : "send"} slot=footer-end round @click=${() => void this._submitMessage()}>${this.awaitingResponse ? this._messages.stopButtonLabel : this._messages.askButtonLabel}</calcite-button></div></calcite-text-area></div>`;
+    return l`<div class="input-container"><calcite-text-area .value=${this.inputValue} .placeholder=${this.entryPlaceholder ?? this._messages.entryPlaceholder} resize=vertical @calciteTextAreaInput=${this.#r} @keydown=${async (t) => {
+      t.altKey || t.ctrlKey || t.metaKey || t.shiftKey || this.keyboardShortcutsDisabled || (t.key === "Enter" ? (t.preventDefault(), await this.submitMessage()) : t.key === "ArrowUp" ? await this._navigateHistory("up", t) : t.key === "ArrowDown" && await this._navigateHistory("down", t));
+    }} ${h(this.#s)}><div slot=footer-start class="footer-start"><slot name=entry-actions-start></slot></div><div slot=footer-end class="footer-end">${this.voiceInputEnabled ? l`<arcgis-assistant-speech-input .awaitingResponse=${this.awaitingResponse} .inputValue=${this.inputValue} ${h(this.#i)}></arcgis-assistant-speech-input>` : null}<slot name=entry-actions-end></slot></div></calcite-text-area></div>`;
   }
 }
-e("arcgis-assistant-chat-entry", d);
+p("arcgis-assistant-chat-entry", v);
 export {
-  d as ArcgisAssistantChatEntry
+  v as ArcgisAssistantChatEntry
 };

package/dist/components/arcgis-assistant-chat-entry/index.js

@@ -1,4 +1,3 @@
 import "@esri/calcite-components/components/calcite-text-area";
-import "@esri/calcite-components/components/calcite-tooltip";
-import "@esri/calcite-components/components/calcite-button";
+import "../arcgis-assistant-speech-input/index.js";
 export * from "./customElement.js";

package/dist/components/arcgis-assistant-data-exploration-agent/customElement.d.ts

@@ -3,14 +3,23 @@ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
 import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
 
 /**
- * The Data Exploration Agent component enables the end user to query features, statistics, and spatial proximity
- * of layer within a provided web map. Currently, this is only scoped to querying feature layers within
- * a 2D web map.
+ * The Data Exploration Agent enables the end user to query features, statistics, and spatial proximity
+ * to features in a layer within a web map. Currently, this is only scoped to querying feature layers within
+ * a 2D web map. See the list of capabilities below for more details.
+ *
+ * The data exploration agent is designed to answer questions about the data in the map, and does not have
+ * access to external data sources or the user's location. It also cannot create visualizations in the form of charts,
+ * layer renderers, new maps, or other visual outputs. It can currently only provide answers in text form based on the
+ * data in the map.
+ *
+ * This agent can change the state of the map by filtering features in a layer, but it cannot change the symbology of
+ * features or create new layers or export results of a query to a file or external source.
  *
  * This is an unrendered component that must be added as a child of the `arcgis-assistant` component in either HTML or JavaScript.
  *
  * ```html
- * <arcgis-assistant>
+ * <arcgis-map id="my-map"></arcgis-map>
+ * <arcgis-assistant reference-element="my-map">
  *   <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
  * </arcgis-assistant>
  * ```
@@ -21,14 +30,72 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * assistant.appendChild(dataExplorationAgent);
  * ```
  *
+ * Once added to the assistant, the agent is loaded and ready to receive user messages related to data exploration.
+ *
+ * ### Capabilities
+ *
+ * The data exploration agent provides the following capabilities related to exploring data in the map:
+ *
+ * - **Query features** - Ask about the attributes of features in a layer, including a single feature or a set
+ *   of features.
+ * - **Query statistics** - Ask about statistics related to features in a layer. Statistics that can be queried
+ *   include count, average, minimum, maximum, and sum. This includes asking about the top number of features based on a
+ *   particular attribute.
+ * - **Query spatial proximity** - Ask about the spatial proximity of features in a layer, such as
+ *   the number of features that intersect a polygon, or information about features within a distance of a specified location or feature.
+ *   This currently does not include questions about the closest feature, but this is planned to be included in a future release.
+ * - **Filter features** - Users can ask the agent to show a subset of features that filter by attributes, or spatial
+ *   proximity to other features. This includes asking the agent to show features that intersect a particular area,
+ *   or are within a certain distance of a location or feature.
+ *
+ * ### Example questions
+ *
+ * The following are example questions a user can ask within the bounds of the data exploration agent.
+ * These questions assume a map with layers that include cities, states, and rivers.
+ *
+ * - "What is the city with the largest population?"
+ * - "How does that population compare to the average population of the cities in this map?"
+ * - "How many cities are within 30 miles of the Colorado River?"
+ * - "Show all cities in the state of California."
+ * - "List the top 5 rivers by length."
+ * - "Emphasize the largest river on the map."
+ *
+ * The following are examples of the types of questions that fall outside the bounds of the
+ * data exploration agent and should therefore be avoided:
+ *
+ * - "What is the closest restaurant to me?" (the data exploration agent does not have access to the user's location,
+ * nor can it find the nearest feature from a location)
+ * - "What is the projected growth of Phoenix in the next 10 years?" (the data exploration agent can
+ * only answer questions about the data in the map, not external data or projections)
+ * - "Show me the population of cities in this map on a graph." (the data exploration agent can only
+ * provide answers in text form, not visualizations)
+ *
+ * > Due to the non-deterministic nature of generative AI, there may be inaccuracies or unexpected behavior when using the
+ * out-of-the-box agents.
+ *
  * @since 5.0
  * @beta
  * @see [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/)
+ * @see [Intro to building agentic mapping applications](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-introduction/)
+ * @see [AI Assistant component sample](https://developers.arcgis.com/javascript/latest/sample-code/ai-assistant/)
  */
 export abstract class ArcgisAssistantDataExplorationAgent extends LitElement {
   /**
-   * A reference to the map element or its ID string used to resolve the MapView for this agent.
-   * If not provided, the agent will attempt to find the closest parent `arcgis-map` element.
+   * The reference element to the map that provides context for the data exploration agent. Currently,
+   * this is only scoped to `arcgis-map` elements. This provides the data exploration agent with the layers
+   * needed for answering user questions about the data in the map.
+   *
+   * Setting this property is not necessary if you set the reference element on the parent
+   * `arcgis-assistant` component.
+   *
+   * @see [arcgis-assistant.referenceElement](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#referenceElement)
+   * @example
+   * ```html
+   * <arcgis-map id="my-map"></arcgis-map>
+   * <arcgis-assistant>
+   *   <arcgis-assistant-data-exploration-agent reference-element="my-map"></arcgis-assistant-data-exploration-agent>
+   * </arcgis-assistant>
+   * ```
    */
   accessor referenceElement: ArcgisMap | string | undefined;
 }

package/dist/components/arcgis-assistant-data-exploration-agent/customElement.js

@@ -1,11 +1,11 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
 import { c as t } from "../../chunks/runtime.js";
 import { LitElement as a } from "@arcgis/lumina";
-import { DataExplorationAgent as s } from "@arcgis/ai-agents";
-import { r as e, i } from "../../chunks/utils.js";
+import { DataExplorationAgent as e } from "@arcgis/ai-agents";
+import { r as s, a as i } from "../../chunks/utils.js";
 class r extends a {
   constructor() {
-    super(...arguments), this.agent = s;
+    super(...arguments), this.agent = e;
   }
   static {
     this.properties = { referenceElement: 1 };
@@ -16,8 +16,8 @@ class r extends a {
       throw new Error("arcgis-assistant-data-exploration-agent requires a mapView");
     return { mapView: this.#t };
   }
-  async load() {
-    this.#t = await e(this, "arcgis-assistant-data-exploration-agent"), i(this);
+  load() {
+    this.#t = s(this, "arcgis-assistant-data-exploration-agent"), i(this);
   }
 }
 t("arcgis-assistant-data-exploration-agent", r);

package/dist/components/arcgis-assistant-help-agent/customElement.d.ts

@@ -0,0 +1,73 @@
+/// <reference path="../../index.d.ts" />
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
+
+/**
+ * The Help Agent provides contextual assistance and guidance to the end user within an
+ * agentic web mapping application. It can provide answers to questions about the web map provided
+ * to the [referenceElement](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant-help-agent/#referenceElement) property and answer questions about other agents included
+ * as subcomponents to the [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/) component.
+ *
+ * This is an unrendered component that must be added as a child of the `arcgis-assistant` component in
+ * either HTML or JavaScript.
+ *
+ * ```html
+ * <arcgis-map id="my-map"></arcgis-map>
+ * <arcgis-assistant reference-element="my-map">
+ *   <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
+ * </arcgis-assistant>
+ * ```
+ *
+ * ```js
+ * const assistant = document.querySelector("arcgis-assistant");
+ * const helpAgent = document.createElement("arcgis-assistant-help-agent");
+ * assistant.appendChild(helpAgent);
+ * ```
+ *
+ * Once added to the assistant, the agent is loaded and ready to receive user messages related to help and guidance.
+ *
+ * ### Example questions
+ *
+ * The following are example questions a user can ask within the bounds of the help agent:
+ *
+ * - "What kind of questions can I ask?"
+ * - "What layers are in this map?"
+ * - "What kind of data can I ask questions about?"
+ *
+ * The following are examples of the types of questions that fall outside the bounds of the
+ * help agent and should therefore be avoided:
+ *
+ * - "Search the Esri documentation for ways that I can query my data."
+ * - "Log a bug related to map navigation to the Esri support team."
+ * - "How do I bake a cake?"
+ * - "How does map navigation work in ArcGIS?"
+ *
+ * > Due to the non-deterministic nature of generative AI, there may be inaccuracies or unexpected behavior when using the
+ * out-of-the-box agents.
+ *
+ * @since 5.0
+ * @beta
+ * @see [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/)
+ * @see [Intro to building agentic mapping applications](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-introduction/)
+ * @see [AI Assistant component sample](https://developers.arcgis.com/javascript/latest/sample-code/ai-assistant/)
+ */
+export abstract class ArcgisAssistantHelpAgent extends LitElement {
+  /**
+   * The reference element to the map that provides context for the help agent. Currently,
+   * this is only scoped to `arcgis-map` elements. This shows the help agent which map for which to
+   * provide assistance. This allows users to ask questions about the specific map provided to the agent.
+   *
+   * Setting this property is not necessary if you set the reference element on the parent
+   * `arcgis-assistant` component.
+   *
+   * @see [arcgis-assistant.referenceElement](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#referenceElement)
+   * @example
+   * ```html
+   * <arcgis-map id="my-map"></arcgis-map>
+   * <arcgis-assistant>
+   *   <arcgis-assistant-help-agent reference-element="my-map"></arcgis-assistant-help-agent>
+   * </arcgis-assistant>
+   * ```
+   */
+  accessor referenceElement: ArcgisMap | string | undefined;
+}

package/dist/components/arcgis-assistant-help-agent/customElement.js

@@ -0,0 +1,26 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { c as t } from "../../chunks/runtime.js";
+import { LitElement as e } from "@arcgis/lumina";
+import { HelpAgent as s } from "@arcgis/ai-agents";
+import { r as i, a as r } from "../../chunks/utils.js";
+class a extends e {
+  constructor() {
+    super(...arguments), this.agent = s;
+  }
+  static {
+    this.properties = { referenceElement: 1 };
+  }
+  #t;
+  getContext() {
+    if (!this.#t)
+      throw new Error("arcgis-assistant-help-agent requires a mapView");
+    return { mapView: this.#t };
+  }
+  load() {
+    this.#t = i(this, "arcgis-assistant-help-agent"), r(this);
+  }
+}
+t("arcgis-assistant-help-agent", a);
+export {
+  a as ArcgisAssistantHelpAgent
+};

package/dist/components/arcgis-assistant-interrupt/customElement.d.ts

@@ -20,7 +20,7 @@ export abstract class ArcgisAssistantInterrupt extends LitElement {
   accessor options: string[] | undefined;
   accessor type: "boolean-choice" | "multi-select" | "single-select" | "text-input";
   readonly arcgisCancel: import("@arcgis/lumina").TargetedEvent<this, void>;
-  readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, string[] | string>;
+  readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, string[] | boolean | string>;
   readonly "@eventTypes": {
     arcgisCancel: ArcgisAssistantInterrupt["arcgisCancel"]["detail"];
     arcgisSubmit: ArcgisAssistantInterrupt["arcgisSubmit"]["detail"];

package/dist/components/arcgis-assistant-interrupt/customElement.js

@@ -1,10 +1,10 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
-import { c as l } from "../../chunks/runtime.js";
-import { css as a, html as e } from "lit";
-import { LitElement as c, createEvent as s } from "@arcgis/lumina";
+import { c as a } from "../../chunks/runtime.js";
+import { css as c, html as e } from "lit";
+import { LitElement as l, createEvent as s } from "@arcgis/lumina";
 import { u as n } from "../../chunks/useT9n.js";
-const r = a``;
-class o extends c {
+const r = c``;
+class o extends l {
   constructor() {
     super(...arguments), this.#t = [], this._messages = n({ blocking: !0 }), this.arcgisCancel = s(), this.arcgisSubmit = s();
   }
@@ -22,16 +22,16 @@ class o extends c {
       case "multi-select":
         return e`<calcite-list selection-mode=multiple .label=${this._messages.optionsLabel} @calciteListChange=${(t) => this.#t = t.target.selectedItems.map((i) => i.value)}>${this.options?.map((t) => e`<calcite-list-item .label=${t} .value=${t}></calcite-list-item>`)}</calcite-list>`;
       case "boolean-choice":
-        return e`<calcite-list selection-mode=single-persist .label=${this._messages.optionsLabel} @calciteListChange=${(t) => this.#t = t.target.selectedItems[0]?.value}>${this.options?.map((t) => e`<calcite-list-item .label=${t} .value=${t}></calcite-list-item>`)}</calcite-list>`;
+        return null;
       case "text-input":
         return e`<calcite-input .label=${this._messages.enterTextLabel} @calciteInputInput=${(t) => this.#t = t.target.value}></calcite-input>`;
     }
   }
   render() {
-    return e`<calcite-panel .description=${this.message}>${this._renderInterruptOptions()}<calcite-button slot=footer-end appearance=outline @click=${() => this.arcgisCancel.emit()}>${this._messages.cancelButtonLabel}</calcite-button><calcite-button slot=footer-end appearance=solid @click=${() => this.arcgisSubmit.emit(this.#t)}>${this._messages.submitButtonLabel}</calcite-button></calcite-panel>`;
+    return e`<calcite-panel .description=${this.message}>${this._renderInterruptOptions()}<calcite-button slot=footer-end appearance=outline @click=${() => this.arcgisCancel.emit()}>${this._messages.cancelButtonLabel}</calcite-button><calcite-button slot=footer-end appearance=solid @click=${() => this.arcgisSubmit.emit(this.type === "boolean-choice" ? !0 : this.#t)}>${this._messages.submitButtonLabel}</calcite-button></calcite-panel>`;
   }
 }
-l("arcgis-assistant-interrupt", o);
+a("arcgis-assistant-interrupt", o);
 export {
   o as ArcgisAssistantInterrupt
 };