@arcgis/ai-components 5.1.0-next.4 → 5.1.0-next.41

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

@@ -1,25 +1,26 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
-import { c as y } from "../../chunks/runtime.js";
-import { css as v, html as p } from "lit";
-import f from "@arcgis/core/core/Collection.js";
-import { whenOnce as _, watch as w, when as b } from "@arcgis/core/core/reactiveUtils.js";
-import $ from "@arcgis/core/portal/Portal.js";
-import { LitElement as E } from "@arcgis/lumina";
-import { createRef as g, ref as m } from "lit/directives/ref.js";
-import { Orchestrator as C } from "@arcgis/ai-orchestrator";
+import { c as _ } from "../../chunks/runtime.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";
+import { createRef as m, ref as y } from "lit/directives/ref.js";
+import { Orchestrator as S } from "@arcgis/ai-orchestrator";
 import L from "@arcgis/core/core/Accessor.js";
-import { property as c, subclass as O } from "@arcgis/core/core/accessorSupport/decorators.js";
-import { g as P } from "../../chunks/utils2.js";
-import { u as S } from "../../chunks/useT9n.js";
-const k = v`:host{height:100%}`;
-var H = Object.defineProperty, M = Object.getOwnPropertyDescriptor, a = (l, t, e, r) => {
-  for (var s = r > 1 ? void 0 : r ? M(t, e) : t, n = l.length - 1, o; n >= 0; n--)
-    (o = l[n]) && (s = (r ? o(t, e, s) : o(s)) || s);
-  return r && s && H(t, e, s), s;
+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 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 && x(e, t, s), s;
 };
-let i = class extends L {
-  constructor(l) {
-    super(l), this.view = null, this.loading = !1, this.processing = !1, this.processingStep = "";
+let a = class extends L {
+  constructor(c) {
+    super(c), this.view = null, this.loading = !1, this.processing = !1, this.processingStep = "";
   }
   async load() {
     this._set("loading", !0);
@@ -33,69 +34,73 @@ let i = class extends L {
     this.orchestrator?.dispose(), super.destroy();
   }
   async _initialize() {
-    this.removeHandles(), await Promise.all([this.portal.load(), this.view?.when()]), this.view && await _(() => !this.view.updating), this._set(
+    this.removeHandles(), await Promise.all([this.portal.load(), this.view?.when()]), this.view && await w(() => !this.view.updating), this._set(
       "orchestrator",
-      await C.init({
+      await S.init({
         agents: [...this.agents],
-        portal: this.portal,
         view: this.view ?? void 0
       })
     ), this.addHandles([
-      w(
+      E(
         () => [this.view, this.agents],
         () => void this._initialize()
       )
     ]);
   }
-  async *ask(l, t) {
+  clearChatHistory() {
+    this.orchestrator?.newConversation();
+  }
+  async *ask(c, e) {
     if (!this.orchestrator)
       throw new Error("Orchestrator not initialized yet.");
     this._set("processing", !0), this._set("processingStep", "");
-    let e = "";
+    const t = [];
     try {
-      const r = this.orchestrator.ask(l);
-      for await (const s of r) {
-        if (t?.aborted) {
-          yield { type: "cancelled" };
+      const i = this.orchestrator.ask(c);
+      for await (const s of i) {
+        const r = s.runId;
+        if (e?.aborted) {
+          yield { type: "cancelled", runId: r };
           break;
         }
         switch (s.type) {
           case "trace": {
-            this._set("processingStep", s.data.text), e += `${s.data.text}
-
-`;
+            this._set("processingStep", s.data.text), t.push(s.data.text);
             break;
           }
           case "completed": {
             if (!s.result.content.length) {
-              yield { type: "completed", error: "Could not process the request.", log: e };
+              yield { type: "completed", error: "Could not process the request.", log: t, runId: r };
               return;
             }
-            const n = s.result.content;
-            this._set("processingStep", ""), yield { type: "completed", response: n, log: e };
+            const o = s.result.content;
+            this._set("processingStep", ""), yield { type: "completed", response: o, log: t, runId: r };
             return;
           }
           case "interrupt": {
-            console.log("Orchestrator interrupt:", s);
-            const { kind: n, message: o, metadata: u } = s.interrupt, h = Array.isArray(u) ? [...u] : [], d = (() => {
-              switch (n) {
+            const { kind: o, message: g, metadata: d } = s.interrupt, u = Array.isArray(d) ? [...d] : [], f = (() => {
+              switch (o) {
                 case "booleanChoice":
-                  return { type: "boolean-choice", message: o, options: h };
+                  return { type: "boolean-choice", message: g, options: u };
                 case "singleSelection":
-                  return { type: "single-select", message: o, options: h };
+                  return { type: "single-select", message: g, options: u };
                 case "multipleSelection":
-                  return { type: "multi-select", message: o, options: h };
+                  return { type: "multi-select", message: g, options: u };
                 case "textInput":
-                  return { type: "text-input", message: o };
+                  return { type: "text-input", message: g };
                 default:
-                  return { type: n, message: o, options: h };
+                  return { type: o, message: g, options: u };
               }
             })();
-            this._set("processingStep", "Waiting for user input..."), yield { type: "interrupt", payload: d };
+            this._set("processingStep", "Waiting for user input..."), yield { type: "interrupt", payload: f, runId: r };
             break;
           }
           case "cancelled": {
-            yield { type: "cancelled" };
+            yield { type: "cancelled", runId: r };
+            return;
+          }
+          case "error": {
+            yield { type: "completed", error: s.error.message, log: t, runId: r };
             return;
           }
           default: {
@@ -104,145 +109,170 @@ let i = class extends L {
           }
         }
       }
-    } catch (r) {
-      console.warn("Error during message processing:", r), yield { type: "completed", error: "An error occurred during message processing.", log: e };
+    } catch (i) {
+      console.warn("Error during message processing:", i), yield { type: "completed", error: "An error occurred during message processing.", log: t, runId: "error" };
       return;
     } finally {
       this._set("processing", !1);
     }
   }
 };
-a([
-  c({ readOnly: !0 })
-], i.prototype, "orchestrator", 2);
-a([
-  c()
-], i.prototype, "agents", 2);
-a([
-  c()
-], i.prototype, "portal", 2);
-a([
-  c()
-], i.prototype, "view", 2);
-a([
-  c({ readOnly: !0 })
-], i.prototype, "loading", 2);
-a([
-  c({ readOnly: !0 })
-], i.prototype, "processing", 2);
-a([
-  c({ readOnly: !0 })
-], i.prototype, "processingStep", 2);
-i = a([
-  O("OrchestratorController")
-], i);
-class A extends E {
+l([
+  h({ readOnly: !0 })
+], a.prototype, "orchestrator", 2);
+l([
+  h()
+], a.prototype, "agents", 2);
+l([
+  h()
+], a.prototype, "portal", 2);
+l([
+  h()
+], a.prototype, "view", 2);
+l([
+  h({ readOnly: !0 })
+], a.prototype, "loading", 2);
+l([
+  h({ readOnly: !0 })
+], a.prototype, "processing", 2);
+l([
+  h({ readOnly: !0 })
+], a.prototype, "processingStep", 2);
+a = l([
+  P("OrchestratorController")
+], a);
+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 = S({ blocking: !0 }), this.#e = g(), this.#s = g(), this.#t = null, this.#r = null, this.#n = /* @__PURE__ */ new Map(), this.#i = (t) => {
-      t.stopPropagation(), this.orchestrator?.cancelInterrupt(), this._interrupt = null;
-    }, this.#o = (t) => {
-      t.stopPropagation();
-      const e = t.detail;
-      this.orchestrator?.resumeInterrupt(e), this._interrupt = null;
-    }, this.#a = (t) => {
-      t.stopPropagation(), this.suggestedPrompts = [];
-      const e = t.detail;
-      this.#h(e);
-    }, this.#l = (t) => {
-      if (t.stopPropagation(), this._interrupt) {
+    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();
+      const t = e.detail;
+      this.arcgisInterruptSubmit.emit(t), this.orchestrator?.resumeInterrupt(t), this._interrupt = null;
+    }, this.#n = (e) => {
+      e.stopPropagation(), this.keepSuggestedPrompts || (this.suggestedPrompts = []);
+      const t = e.detail;
+      this.arcgisSubmit.emit(t), this.submitMessage(t);
+    }, this.#l = (e) => {
+      if (e.stopPropagation(), this.arcgisCancel.emit(), this._interrupt) {
         this.orchestrator?.cancelInterrupt(), this._interrupt = null;
         return;
       }
-      this.#r?.abort();
-    }, this._interrupt = null, this._chatHistory = new f([]), this._error = null, this.referenceElement = null, this.portal = new $(), this.suggestedPrompts = [];
+      this.#s?.abort();
+    }, this.#c = (e) => {
+      e.stopPropagation();
+      const t = e.detail;
+      this.arcgisFeedback.emit(t);
+    }, 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 = { _interrupt: 16, _chatHistory: 16, _error: 16, orchestrator: 32, entryMessage: 1, heading: 1, description: 1, referenceElement: 1, portal: 0, suggestedPrompts: 0 };
+    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 = k;
+    this.styles = R;
   }
   #e;
-  #s;
   #t;
+  #s;
+  #o;
   #r;
-  #n;
   #i;
-  #o;
   #a;
+  #n;
   #l;
-  get orchestrator() {
-    return this.#t?.orchestrator;
+  #c;
+  async #h() {
+    try {
+      const e = I(this.el, this.referenceElement);
+      await e?.componentOnReady();
+      const t = [...this.#o.values()];
+      return t.length ? (this._orchestratorController = new a({
+        agents: t,
+        portal: this.#r,
+        view: e?.view
+      }), await this._orchestratorController.load(), !0) : (this._error = "No agents found.", !1);
+    } catch (e) {
+      return this._error = e?.message ?? "Error initializing orchestrator.", O(this)(e), !1;
+    }
   }
-  register(t) {
-    this.#n.set(t.agent.id, t);
+  get _user() {
+    return this.#r?.user?.fullName || this.#r?.user?.username;
   }
-  load() {
-    this.manager.onLifecycle(() => () => {
-      this.#r?.abort(), this._interrupt = null, this._chatHistory.removeAll(), this._error = null;
-    });
+  get orchestrator() {
+    return this._orchestratorController?.orchestrator;
   }
-  loaded() {
-    this.manager.onLifecycle(() => {
-      this.#e.value?.addEventListener("arcgisSubmit", this.#a), this.#e.value?.addEventListener("arcgisCancel", this.#l);
-      const t = b(() => !!this._interrupt && !!this.#s.value, () => {
-        const e = this.#s.value;
-        e.removeEventListener("arcgisSubmit", this.#o), e.removeEventListener("arcgisCancel", this.#i), e.addEventListener("arcgisSubmit", this.#o, { once: !0 }), e.addEventListener("arcgisCancel", this.#i, { once: !0 });
-      });
-      return queueMicrotask(() => void this.#c()), () => {
-        t.remove(), this.#s.value?.removeEventListener("arcgisSubmit", this.#o), this.#s.value?.removeEventListener("arcgisCancel", this.#i), this.#e.value?.removeEventListener("arcgisSubmit", this.#a), this.#e.value?.removeEventListener("arcgisCancel", this.#l), this.#t?.destroy(), this.#t = null;
-      };
-    });
+  async clearChatHistory() {
+    this._reset(), this._orchestratorController?.clearChatHistory();
   }
-  async #c() {
-    try {
-      const t = P(this.referenceElement);
-      await t?.componentOnReady();
-      const e = [...this.#n.values()];
-      this.#t = new i({
-        agents: e,
-        portal: this.portal,
-        view: t?.view
-      }), await this.#t.load();
-    } catch (t) {
-      console.warn(t), this._error = "Error initializing orchestrator.";
-    }
+  register(e) {
+    this.#o.set(e.agent.id, e);
   }
-  async #h(t) {
-    const e = t.trim();
-    if (!e || (this._chatHistory.push({
-      type: "prompt",
-      content: e
-    }), !this.#t))
+  async submitMessage(e) {
+    const t = e.trim();
+    if (!t || (this.messages.push({
+      id: Date.now().toString(),
+      // TODO: Replace with a more robust ID generation method or get from orchestrator
+      role: "user",
+      content: t
+    }), !this._orchestratorController))
       return;
-    this.#r = new AbortController();
-    const r = this.#t.ask(e, this.#r.signal);
-    for await (const s of r)
+    const i = this._orchestratorController.ask(t, this.#s?.signal);
+    for await (const s of i) {
+      const r = s.runId;
       switch (s.type) {
         case "completed":
-          this._chatHistory.push({
-            type: "response",
+          this.messages.push({
+            role: "assistant",
             content: s.response,
             log: s.log,
-            error: s.error
+            error: s.error,
+            id: r
           });
           break;
         case "interrupt":
-          this._interrupt = s.payload;
+          this._interrupt = { ...s.payload, id: r };
           break;
         case "cancelled":
-          this._chatHistory.push({
-            type: "response",
-            error: "Request cancelled."
+          this.messages.push({
+            role: "assistant",
+            error: "Request cancelled.",
+            id: r
           });
           break;
       }
+    }
+  }
+  load() {
+    this.manager.onLifecycle(this._reset.bind(this));
+  }
+  loaded() {
+    this.manager.onLifecycle(() => {
+      this.#e.value?.addEventListener("arcgisSubmit", this.#n), this.#e.value?.addEventListener("arcgisCancel", this.#l), this.#e.value?.addEventListener("arcgisFeedback", this.#c);
+      const e = C(() => !!this._interrupt && !!this.#t.value, () => {
+        const t = this.#t.value;
+        t.removeEventListener("arcgisSubmit", this.#a), t.removeEventListener("arcgisCancel", this.#i), t.addEventListener("arcgisSubmit", this.#a, { once: !0 }), t.addEventListener("arcgisCancel", this.#i, { once: !0 }), this._interrupt && this.arcgisInterrupt.emit(this._interrupt);
+      });
+      return queueMicrotask(() => {
+        this.#h().then((t) => {
+          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;
+      };
+    });
+  }
+  _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 p`<arcgis-assistant-shell .loading=${this.#t?.loading} .heading=${this.heading ?? this._messages.assistantLabel} .description=${this.description} .entryMessage=${this.entryMessage} .entryMessageClosed=${this._chatHistory.length > 0} .awaitingResponse=${this.#t?.processing} .suggestedPrompts=${this.suggestedPrompts} .status=${this.#t?.processing ? "working" : this._error ? "error" : "ready"} ${m(this.#e)}>${this._error ? p`<calcite-notice slot=entry-message open kind=danger icon width=full><div slot=message>${this._error}</div></calcite-notice>` : null}${this._interrupt ? p`<arcgis-assistant-interrupt slot=entry-message .type=${this._interrupt.type} .message=${this._interrupt.message} .options=${this._interrupt.options} ${m(this.#s)}></arcgis-assistant-interrupt>` : null}<arcgis-assistant-chat .loading=${this.#t?.processing} .loadingMessage=${this.#t?.processingStep || ""} .messages=${this._chatHistory} .user=${this.portal?.user?.fullName || this.portal?.user?.username}><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>`;
+    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>`;
   }
 }
-y("arcgis-assistant", A);
+_("arcgis-assistant", D);
 export {
-  A 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/types.d.ts

@@ -0,0 +1,97 @@
+/** An interrupt is a UI mechanism used by an agent to prompt the user for additional input or clarification. */
+export interface Interrupt {
+  /**
+   * The unique identifier of the message associated with the interrupt. This is used to associate the interrupt
+   * with specific messages.
+   */
+  id?: string;
+  /**
+   * The type of interrupt, which determines how the assistant will prompt the user for input. The available types are:
+   *
+   * - `boolean-choice`: Presents the user with a yes/no question.
+   * - `multi-select`: Allows the user to select multiple options from a list using a checkbox interface.
+   * - `single-select`: Allows the user to select a single option from a list using a radio button interface.
+   * - `text-input`: Prompts the user to enter free-form text input.
+   *
+   * The assistant will use the specified type to determine how to display the prompt and collect the user's response.
+   * For example, a `boolean-choice` interrupt might be used to confirm an action, while a `text-input`
+   * interrupt could be used to ask for more details about a request.
+   */
+  type: "boolean-choice" | "multi-select" | "single-select" | "text-input";
+  /**
+   * The message to display to the user when prompting for input. This should provide clear instructions or questions
+   * related to the interrupt, guiding the user on what information is needed or what action they should take in response
+   * to the prompt.
+   *
+   * For example, if the interrupt type is `boolean-choice`, the message might be "Do you want to proceed with this
+   * action?" If the type is `text-input`, the message could be "Please provide more details about your request."
+   */
+  message?: string;
+  /**
+   * The options to present to the user for selection when the interrupt type is `multi-select` or `single-select`.
+   * This should be an array of strings representing the available choices. For `boolean-choice`,
+   * the options are implicitly "Yes" and "No" and do not need to be provided.
+   * For `text-input`, options are not applicable and should be omitted.
+   *
+   * For example, if the interrupt type is `multi-select`, the options might be ["Option 1", "Option 2", "Option 3"].
+   * If the type is `single-select`, the options could be ["Choice A", "Choice B", "Choice C"].
+   */
+  options?: string[];
+}
+
+/** A chat message sent by the assistant. */
+export interface AssistantMessage extends ChatMessageBase {
+  role: "assistant";
+  /** The content of the assistant's message. This can include text generated by the assistant in response to the user's message. The content is displayed in the chat interface for the user to read and interact with. */
+  content?: string;
+  /**
+   * Log messages related to the assistant's processing of the user's request. This can include information about
+   * the agents or tools it invoked, the parameters generated by the LLM, and any relevant details about how it
+   * arrived at its response. Log messages are primarily intended for debugging and transparency purposes, allowing
+   * developers and users to understand the assistant's behavior and decision-making process.
+   */
+  log?: string[];
+  /**
+   * An error message indicating any issues that occurred while the assistant was processing the user's request.
+   * The error message may be displayed in the chat interface to inform the user of the issue and can also be used for
+   * debugging and improving the assistant's performance.
+   */
+  error?: string;
+  /**
+   * Feedback provided by the user for this specific assistant message. This allows users to indicate whether the
+   * assistant's response was helpful or not, which the app developer can capture and use to improve the assistant's
+   * performance over time.
+   */
+  feedback?: Feedback;
+}
+
+/**
+ * A chat message from the user or the assistant. Messages include all relevant information such as content,
+ * logs, errors, and feedback.
+ */
+export type ChatMessage = AssistantMessage | UserMessage;
+
+/** The base interface for chat messages exchanged between the user and the assistant. */
+export interface ChatMessageBase {
+  /**
+   * The unique identifier for the message. This is used to associate messages with interrupts and feedback.
+   * If not provided, a unique ID will be generated automatically.
+   */
+  id: string;
+}
+
+/** A chat message sent by the user. */
+export interface UserMessage extends ChatMessageBase {
+  role: "user";
+  /**
+   * The content of the user's message. This is the text input provided by the user in the chat interface.
+   * This content is sent to the assistant and its agents for processing and generating responses.
+   */
+  content: string;
+}
+
+/** Feedback provided by the user for a specific message. */
+export interface Feedback {
+  /** Indicates whether the feedback is positive or negative. */
+  positive: boolean;
+}

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
 };