@arcgis/ai-components 5.1.0-next.20 → 5.1.0-next.21

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

@@ -1,7 +1,7 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
 import { c as _ } from "../../chunks/runtime.js";
-import { css as v, html as u } from "lit";
-import b from "@arcgis/core/core/Collection.js";
+import { css as b, html as p } from "lit";
+import v from "@arcgis/core/core/Collection.js";
 import { whenOnce as w, watch as E, when as C } from "@arcgis/core/core/reactiveUtils.js";
 import k from "@arcgis/core/portal/Portal.js";
 import { LitElement as $, createEvent as n } from "@arcgis/lumina";
@@ -10,13 +10,13 @@ import { Orchestrator as S } from "@arcgis/ai-orchestrator";
 import L from "@arcgis/core/core/Accessor.js";
 import { property as h, subclass as P } from "@arcgis/core/core/accessorSupport/decorators.js";
 import { g as I } from "../../chunks/utils2.js";
-import { u as O } from "../../chunks/useT9n.js";
-import { rethrowError as M } from "@arcgis/toolkit/log";
-const x = v`:host{display:block;width:var(--arcgis-internal-panel-width, 100%);height:var(--arcgis-internal-expand-max-height, 100%)}`;
-var R = Object.defineProperty, A = Object.getOwnPropertyDescriptor, l = (c, e, t, i) => {
+import { u as M } from "../../chunks/useT9n.js";
+import { rethrowError as O } from "@arcgis/toolkit/log";
+const R = b`:host{display:block;width:var(--arcgis-internal-panel-width, 100%);height:var(--arcgis-internal-expand-max-height, 100%)}`;
+var x = Object.defineProperty, A = Object.getOwnPropertyDescriptor, l = (c, e, t, i) => {
   for (var s = i > 1 ? void 0 : i ? A(e, t) : e, r = c.length - 1, o; r >= 0; r--)
     (o = c[r]) && (s = (i ? o(e, t, s) : o(s)) || s);
-  return i && s && R(e, t, s), s;
+  return i && s && x(e, t, s), s;
 };
 let a = class extends L {
   constructor(c) {
@@ -78,18 +78,18 @@ let a = class extends L {
             return;
           }
           case "interrupt": {
-            const { kind: o, message: p, metadata: d } = s.interrupt, g = Array.isArray(d) ? [...d] : [], f = (() => {
+            const { kind: o, message: g, metadata: d } = s.interrupt, u = Array.isArray(d) ? [...d] : [], f = (() => {
               switch (o) {
                 case "booleanChoice":
-                  return { type: "boolean-choice", message: p, options: g };
+                  return { type: "boolean-choice", message: g, options: u };
                 case "singleSelection":
-                  return { type: "single-select", message: p, options: g };
+                  return { type: "single-select", message: g, options: u };
                 case "multipleSelection":
-                  return { type: "multi-select", message: p, options: g };
+                  return { type: "multi-select", message: g, options: u };
                 case "textInput":
-                  return { type: "text-input", message: p };
+                  return { type: "text-input", message: g };
                 default:
-                  return { type: o, message: p, options: g };
+                  return { type: o, message: g, options: u };
               }
             })();
             this._set("processingStep", "Waiting for user input..."), yield { type: "interrupt", payload: f, runId: r };
@@ -141,9 +141,10 @@ l([
 a = l([
   P("OrchestratorController")
 ], a);
-class z extends $ {
+const z = "Embeddings resource 'embeddings-v01.json' not found in the webmap portal item.", H = "Embeddings not found for this web map.", j = "https://developers.arcgis.com/javascript/latest/agentic-apps/ai-webmap-setup/#embeddings";
+class D extends $ {
   constructor() {
-    super(...arguments), this._messages = O({ blocking: !0 }), this.#e = m(), this.#t = m(), this.#s = null, this.#o = /* @__PURE__ */ new Map(), this.#r = k.getDefault(), this.#i = (e) => {
+    super(...arguments), this._messages = M({ blocking: !0 }), this.#e = m(), this.#t = m(), this.#s = null, this.#o = /* @__PURE__ */ new Map(), this.#r = k.getDefault(), this.#i = (e) => {
       e.stopPropagation(), this.arcgisInterruptCancel.emit(), this.orchestrator?.cancelInterrupt(), this._interrupt = null;
     }, this.#a = (e) => {
       e.stopPropagation();
@@ -163,13 +164,13 @@ class z extends $ {
       e.stopPropagation();
       const t = e.detail;
       this.arcgisFeedback.emit(t);
-    }, this._orchestratorController = null, this._interrupt = null, this._error = null, this.messages = new b([]), this.referenceElement = null, this.suggestedPrompts = [], this.feedbackEnabled = !1, this.keepSuggestedPrompts = !1, this.logEnabled = !1, this.copyEnabled = !1, this.arcgisCancel = n(), this.arcgisError = n(), this.arcgisFeedback = n(), this.arcgisInterrupt = n(), this.arcgisInterruptCancel = n(), this.arcgisInterruptSubmit = n(), this.arcgisReady = n(), this.arcgisSubmit = n();
+    }, this._orchestratorController = null, this._interrupt = null, this._error = null, this.messages = new v([]), this.referenceElement = null, this.suggestedPrompts = [], this.feedbackEnabled = !1, this.keepSuggestedPrompts = !1, this.logEnabled = !1, this.copyEnabled = !1, this.arcgisCancel = n(), this.arcgisError = n(), this.arcgisFeedback = n(), this.arcgisInterrupt = n(), this.arcgisInterruptCancel = n(), this.arcgisInterruptSubmit = n(), this.arcgisReady = n(), this.arcgisSubmit = n();
   }
   static {
     this.properties = { _orchestratorController: 16, _interrupt: 16, _error: 16, _user: 16, messages: 0, orchestrator: 32, entryMessage: 1, heading: 1, description: 1, referenceElement: 1, suggestedPrompts: 0, feedbackEnabled: 5, keepSuggestedPrompts: 5, logEnabled: 5, copyEnabled: 5 };
   }
   static {
-    this.styles = x;
+    this.styles = R;
   }
   #e;
   #t;
@@ -192,7 +193,7 @@ class z extends $ {
         view: e?.view
       }), await this._orchestratorController.load(), !0) : (this._error = "No agents found.", !1);
     } catch (e) {
-      return this._error = e?.message ?? "Error initializing orchestrator.", M(this)(e), !1;
+      return this._error = e?.message ?? "Error initializing orchestrator.", O(this)(e), !1;
     }
   }
   get _user() {
@@ -201,12 +202,12 @@ class z extends $ {
   get orchestrator() {
     return this._orchestratorController?.orchestrator;
   }
-  register(e) {
-    this.#o.set(e.agent.id, e);
-  }
   async clearChatHistory() {
     this._reset(), this._orchestratorController?.clearChatHistory();
   }
+  register(e) {
+    this.#o.set(e.agent.id, e);
+  }
   async submitMessage(e) {
     const t = e.trim();
     if (!t || (this.messages.push({
@@ -254,7 +255,7 @@ class z extends $ {
       });
       return queueMicrotask(() => {
         this.#h().then((t) => {
-          t ? this.arcgisReady.emit() : this.arcgisError.emit(new Error(this._error || "Unknown error initializing assistant."));
+          t ? this.arcgisReady.emit() : this._error && this.arcgisError.emit(new Error(this._error));
         });
       }), () => {
         e.remove(), this.#t.value?.removeEventListener("arcgisSubmit", this.#a), this.#t.value?.removeEventListener("arcgisCancel", this.#i), this.#e.value?.removeEventListener("arcgisSubmit", this.#n), this.#e.value?.removeEventListener("arcgisCancel", this.#l), this.#e.value?.removeEventListener("arcgisFeedback", this.#c), this._orchestratorController?.destroy(), this._orchestratorController = null;
@@ -264,11 +265,14 @@ class z extends $ {
   _reset() {
     this.#s?.abort(), this._interrupt = null, this.messages.removeAll(), this._error = null;
   }
+  _renderErrorNotice() {
+    return this._error ? p`<calcite-notice closable slot=entry-message open kind=danger icon width=full>${this._error === z ? p`<div slot=message>${H}</div><calcite-link slot=link .href=${j} target=_blank title="Learn about web map embeddings">Read more</calcite-link>` : p`<div slot=message>${this._error}</div>`}</calcite-notice>` : null;
+  }
   render() {
-    return u`<arcgis-assistant-shell .loading=${!this._orchestratorController && !this._error || this._orchestratorController?.loading} .heading=${this.heading ?? this._messages.assistantLabel} .description=${this.description} .entryMessage=${this.entryMessage} .entryMessageClosed=${this.messages.length > 0} .awaitingResponse=${this._orchestratorController?.processing} .suggestedPrompts=${this.suggestedPrompts} .messages=${this.messages} ${y(this.#e)}>${this._error ? u`<calcite-notice slot=entry-message open kind=danger icon width=full><div slot=message>${this._error}</div></calcite-notice>` : null}${this._interrupt ? u`<arcgis-assistant-interrupt slot=entry-message .type=${this._interrupt.type} .message=${this._interrupt.message} .options=${this._interrupt.options} ${y(this.#t)}></arcgis-assistant-interrupt>` : null}<arcgis-assistant-chat .loading=${this._orchestratorController?.processing} .loadingMessage=${this._orchestratorController?.processingStep || ""} .messages=${this.messages} .user=${this._user} .feedbackEnabled=${this.feedbackEnabled} .logEnabled=${this.logEnabled} .copyEnabled=${this.copyEnabled}><slot></slot></arcgis-assistant-chat><slot name=header-actions-end slot=header-actions-end></slot>${this.entryMessage ? null : u`<slot name=entry-message slot=entry-message></slot>`}<slot name=entry-actions-start slot=entry-actions-start></slot><slot name=footer-content slot=footer-content></slot></arcgis-assistant-shell>`;
+    return p`<arcgis-assistant-shell .loading=${!this._orchestratorController && !this._error || this._orchestratorController?.loading} .heading=${this.heading ?? this._messages.assistantLabel} .description=${this.description} .entryMessage=${this.entryMessage} .entryMessageClosed=${this.messages.length > 0} .awaitingResponse=${this._orchestratorController?.processing} .suggestedPrompts=${this.suggestedPrompts} .messages=${this.messages} ${y(this.#e)}>${this._renderErrorNotice()}${this._interrupt ? p`<arcgis-assistant-interrupt slot=entry-message .type=${this._interrupt.type} .message=${this._interrupt.message} .options=${this._interrupt.options} ${y(this.#t)}></arcgis-assistant-interrupt>` : null}<arcgis-assistant-chat .loading=${this._orchestratorController?.processing} .loadingMessage=${this._orchestratorController?.processingStep || ""} .messages=${this.messages} .user=${this._user} .feedbackEnabled=${this.feedbackEnabled} .logEnabled=${this.logEnabled} .copyEnabled=${this.copyEnabled}><slot></slot></arcgis-assistant-chat><slot name=header-actions-end slot=header-actions-end></slot>${this.entryMessage ? null : p`<slot name=entry-message slot=entry-message></slot>`}<slot name=entry-actions-start slot=entry-actions-start></slot><slot name=footer-content slot=footer-content></slot></arcgis-assistant-shell>`;
   }
 }
-_("arcgis-assistant", z);
+_("arcgis-assistant", D);
 export {
-  z as ArcgisAssistant
+  D as ArcgisAssistant
 };

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

@@ -1,5 +1,6 @@
-import "../arcgis-assistant-shell/index.js";
 import "@esri/calcite-components/components/calcite-notice";
+import "@esri/calcite-components/components/calcite-link";
+import "../arcgis-assistant-shell/index.js";
 import "../arcgis-assistant-interrupt/index.js";
 import "../arcgis-assistant-chat/index.js";
 export * from "./customElement.js";

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

@@ -14,6 +14,9 @@ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
  * 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.
  *
  * ```html
@@ -45,7 +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 [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 {
   /**
@@ -56,10 +64,12 @@ export abstract class ArcgisAssistantAgent<TContext = Record<string, unknown>> e
    * 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 [Custom Agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/) 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

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

@@ -70,9 +70,14 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * - "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 {
   /**

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

@@ -32,8 +32,7 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  *
  * - "What kind of questions can I ask?"
  * - "What layers are in this map?"
- * - "What does this symbol mean?"
- * - "How do I use the navigation agent?"
+ * - "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:
@@ -43,14 +42,19 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * - "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 view on which to
+   * 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

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

@@ -27,11 +27,11 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  *
  * The navigation agent provides the following capabilities related to map navigation:
  *
- * - **Geocoding** - Navigate to an address using Esri's World Geocoding Service and zooms the map to that location.
+ * - **Geocoding** - Navigate to an address using Esri's World Geocoding Service.
  * - **Go to extent** - Navigate to the extent of a bookmark in the map, the home extent of the web map,
  *   or the extent of a layer.
- * - **Go to features** - Navigates the map to a specified feature or set of features.
- * - **Go to viewpoint** - Navigates the map to a specified viewpoint, which can include center, zoom, and/or
+ * - **Go to features** - Navigate to a specified feature or set of features.
+ * - **Go to viewpoint** - Navigate to a specified viewpoint, which can include center, zoom, and/or
  *   rotation.
  *
  * ### Example questions
@@ -39,7 +39,7 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * The following are example questions a user can ask within the bounds of the navigation agent:
  *
  * - "Go to the Golden Gate Bridge"
- * - "Zoom to a 1:24,000 scale"
+ * - "Zoom to a 1 to 24,000 scale"
  * - "Zoom in"
  * - "Go to the parks layer"
  *
@@ -50,14 +50,19 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * - "Make this map 3D and tilt the view to a 45 degree angle" (3D navigation is currently not supported)
  * - "Where am I?" (the navigation agent does not have access to the user's location)
  *
+ * > 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 ArcgisAssistantNavigationAgent extends LitElement {
   /**
    * The reference element to the map that provides context for the navigation agent. Currently,
-   * this is only scoped to `arcgis-map` elements. This shows the navigation agent which view on which to
+   * this is only scoped to `arcgis-map` elements. This shows the navigation agent which map on which to
    * perform navigation actions. This is required for the navigation agent to function properly.
    *
    * Setting this property is not necessary if you set the reference element on the parent