@arcgis/ai-components 5.2.0-next.11 → 5.2.0-next.111

package/LICENSE.md

@@ -1,12 +1,14 @@
 # Licensing
 
-COPYRIGHT © Esri
+COPYRIGHT Esri
 
 All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.
 
-This material is licensed for use under the [Esri Master License Agreement (MLA)](https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf), and is bound by the terms of that agreement.
+This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement.
 You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
 
+See use restrictions at https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf.
+
 For additional information, contact:
 Environmental Systems Research Institute, Inc.
 Attn: Contracts and Legal Services Department

package/README.md

@@ -6,5 +6,5 @@ The ArcGIS Maps SDK for JavaScript provides a suite of ready-to-use UI component
 
 ## License
 
-This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package, and at https://js.arcgis.com/5.1/LICENSE.txt.
-For third party notices, see https://js.arcgis.com/5.1/third-party-notices.txt.
+This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package, and at https://js.arcgis.com/5.2/LICENSE.txt.
+For third party notices, see https://js.arcgis.com/5.2/third-party-notices.txt.

package/dist/agent-utils/LLMAgent.d.ts

@@ -1,7 +1,10 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
 import type { BaseAgent } from "./BaseAgent.js";
 import type { FunctionToolLike } from "./tools/FunctionTool.js";
 import type { AgentCustomState, AgentData, ZodObjectSchema } from "./types.js";
 
+export type LLMAgentTool = FunctionToolLike | StructuredToolInterface;
+
 /**
  * LLMAgent uses a language model to generate its output based on a provided prompt template and optional tools.
  * It supports structured input and output through Zod schemas, allowing for validation and type safety. The agent's logic is defined by the prompt and the tools it has access to, making it a flexible option for a wide range of use cases.
@@ -11,9 +14,8 @@ import type { AgentCustomState, AgentData, ZodObjectSchema } from "./types.js";
 export class LLMAgent<TInput extends AgentData = AgentData, TOutput extends AgentData = AgentData> extends BaseAgent<AgentCustomState<TInput, TOutput>> {
   constructor(properties?: LLMAgentConstructProperties<TInput, TOutput>);
   /**
-   * The inputSchema property is an optional Zod schema describing the expected structured input for the agent.
-   * This can be used for validation of the input state before execution and also to extract variables from the input
-   * state for prompt formatting.
+   * Defines the structured input fields available in the agent's graph state.
+   * Prompt variables are resolved directly from graph state and do not need to be declared in this schema.
    */
   accessor inputSchema: ZodObjectSchema<TInput> | undefined;
   /**
@@ -30,17 +32,17 @@ export class LLMAgent<TInput extends AgentData = AgentData, TOutput extends Agen
   accessor outputSchema: ZodObjectSchema<TOutput> | undefined;
   /**
    * Defines the prompt template the agent will use to generate its output.
-   * This prompt can include variables that are populated from the agent's state at runtime through the input schema,
+   * This prompt can include variables that are populated directly from the agent's state at runtime,
    * allowing for dynamic and context-aware responses from the language model.
    *
-   * In this example below, {location} and {weather} would be variables extracted from the agent's state according to the input schema.
+   * In this example below, {location} and {weather} would be variables extracted from the agent's state.
    *
    * @example "Generate a weather report for {location} based on the current {weather} conditions."
    * @required
    */
   accessor prompt: string;
-  /** The tools property is an optional array of FunctionTools that the agent can use during execution. */
-  accessor tools: FunctionToolLike[] | undefined;
+  /** The tools property is an optional array of tools that the agent can use during execution. */
+  accessor tools: LLMAgentTool[] | undefined;
   /**
    * Rebuilds internal workspace and createGraph wiring. This is automatically called during initialization and whenever
    * the name or description properties change, but can also be called manually if needed to refresh the agent's graph definition.

package/dist/agent-utils/LLMAgent.js

@@ -1,27 +1,30 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
 import "@arcgis/core/identity/IdentityManager.js";
 import "@arcgis/core/portal/Portal.js";
+import "@arcgis/core/request.js";
 import { isGraphInterrupt as f } from "@langchain/langgraph/web";
-import { c as u } from "../chunks/generateLayerDescriptions.js";
+import "@arcgis/toolkit/string";
+import "../chunks/generateLayerDescriptions.js";
 import "@langchain/core/messages";
 import "@langchain/core/callbacks/dispatch/web";
+import "@langchain/core/callbacks/base";
+import { c } from "../chunks/aiFactory.js";
 import { watch as w } from "@arcgis/core/core/reactiveUtils.js";
 import "@arcgis/core/layers/FeatureLayer.js";
-import "@arcgis/core/request.js";
-import { ChatPromptTemplate as S } from "@langchain/core/prompts";
-import { property as m, subclass as _ } from "@arcgis/core/core/accessorSupport/decorators.js";
-import { createAgent as h } from "langchain";
-import { BaseAgent as v } from "./BaseAgent.js";
+import { ChatPromptTemplate as u } from "@langchain/core/prompts";
+import { property as n, subclass as v } from "@arcgis/core/core/accessorSupport/decorators.js";
+import { createAgent as h, providerStrategy as _ } from "langchain";
+import { BaseAgent as S } from "./BaseAgent.js";
 import { convertToLangChainMiddlewares as l } from "./middlewares/middleware.js";
-import { c as y } from "../chunks/graph.js";
-import { c as T } from "../chunks/state.js";
-import { c as d, h as M, g as x } from "../chunks/utils.js";
-var P = Object.defineProperty, b = Object.getOwnPropertyDescriptor, n = (t, r, s, e) => {
-  for (var o = e > 1 ? void 0 : e ? b(r, s) : r, p = t.length - 1, i; p >= 0; p--)
-    (i = t[p]) && (o = (e ? i(r, s, o) : i(o)) || o);
-  return e && o && P(r, s, o), o;
+import { c as T } from "../chunks/graph.js";
+import { c as y } from "../chunks/state.js";
+import { c as d, h as x } from "../chunks/utils.js";
+var M = Object.defineProperty, P = Object.getOwnPropertyDescriptor, m = (t, e, r, s) => {
+  for (var o = s > 1 ? void 0 : s ? P(e, r) : e, p = t.length - 1, a; p >= 0; p--)
+    (a = t[p]) && (o = (s ? a(e, r, o) : a(o)) || o);
+  return s && o && M(e, r, o), o;
 };
-let a = class extends v {
+let i = class extends S {
   //#region Lifecycle
   constructor(t) {
     super(t), this.modelTier = "default";
@@ -51,13 +54,16 @@ let a = class extends v {
     return [this.inputSchema, this.outputSchema].filter(Boolean);
   }
   generate() {
-    const t = T(this.getSchemas());
-    this._set("workspace", t);
-    const r = this.id, s = { [r]: this._invoke.bind(this) }, e = [{ from: r, decide: () => {
+    const t = this.prompt ? u.fromTemplate(this.prompt).inputVariables : [], e = y(
+      this.getSchemas(),
+      t
+    );
+    this._set("workspace", e);
+    const r = this.id, s = { [r]: this._invoke.bind(this) }, o = [{ from: r, decide: () => {
     } }];
     this._set(
       "createGraph",
-      () => y(s, e, t, {
+      () => T(s, o, e, {
         agent: this,
         entryNode: r,
         middlewares: this.middlewares
@@ -66,74 +72,71 @@ let a = class extends v {
   }
   //#endregion
   //#region Private Methods
-  async _invoke(t, r) {
+  async _invoke(t, e) {
     try {
-      return this.outputSchema ? await this._invokeStructured(t, r) : await this._invokeUnstructured(t, r);
-    } catch (s) {
-      if (f(s))
-        throw s;
-      const e = s instanceof Error ? s.message : String(s);
-      return d({ outputMessage: e }, "failed", e);
+      return this.outputSchema ? await this._invokeStructured(t, e) : await this._invokeUnstructured(t, e);
+    } catch (r) {
+      if (f(r))
+        throw r;
+      const s = r instanceof Error ? r.message : String(r);
+      return d({ outputMessage: s }, "failed", s);
     }
   }
-  async _invokeStructured(t, r) {
+  async _invokeStructured(t, e) {
     if (!this.outputSchema)
       throw new Error("Output schema is required for structured invocation.");
-    const e = await h({
-      model: await u({ modelTier: this.modelTier }),
+    const s = await h({
+      model: await c({ modelTier: this.modelTier }),
       systemPrompt: await this._getPromptWithInputVariables(t),
       tools: this._getTools(),
       checkpointer: !0,
       middleware: l(this.middlewares),
-      responseFormat: this.outputSchema
-    }).invoke({ messages: t.agentExecutionContext.messages }, r);
-    if (!("structuredResponse" in e) || e.structuredResponse === void 0)
+      responseFormat: _(this.outputSchema)
+    }).invoke({ messages: t.agentExecutionContext.messages }, e);
+    if (!("structuredResponse" in s) || s.structuredResponse === void 0)
       throw new Error("LLMAgent did not receive structured output from createAgent.");
-    return M(e.structuredResponse, this.outputSchema, e.messages);
+    return x(s.structuredResponse, this.outputSchema, s.messages);
   }
-  async _invokeUnstructured(t, r) {
+  async _invokeUnstructured(t, e) {
     const o = (await h({
-      model: await u({ modelTier: this.modelTier }),
+      model: await c({ modelTier: this.modelTier }),
       systemPrompt: await this._getPromptWithInputVariables(t),
       tools: this._getTools(),
       checkpointer: !0,
       middleware: l(this.middlewares)
-    }).invoke({ messages: t.agentExecutionContext.messages }, r)).messages, i = o.at(-1)?.content ?? "", c = typeof i == "string" ? i : JSON.stringify(i), g = c.trim() || "LLMAgent completed.";
+    }).invoke({ messages: t.agentExecutionContext.messages }, e)).messages, a = o.at(-1)?.text ?? "", g = a.trim() || "LLMAgent completed.";
     return d(
-      { agentExecutionContext: { ...t.agentExecutionContext, messages: o }, outputMessage: c },
+      { agentExecutionContext: { ...t.agentExecutionContext, messages: o }, outputMessage: a },
       "success",
       g
     );
   }
   async _getPromptWithInputVariables(t) {
-    const r = x(t, this.inputSchema);
-    for (const { outputKey: e } of this.middlewares)
-      e && (r[String(e)] = t[e]);
-    return await S.fromTemplate(this.prompt).format(r);
+    return await u.fromTemplate(this.prompt).format(t);
   }
   _getTools() {
-    return this.tools?.map((t) => t.getTool()) ?? [];
+    return this.tools?.map((t) => "getTool" in t ? t.getTool() : t) ?? [];
   }
   //#endregion
 };
-n([
-  m()
-], a.prototype, "prompt", 2);
-n([
-  m()
-], a.prototype, "tools", 2);
-n([
-  m()
-], a.prototype, "inputSchema", 2);
-n([
-  m()
-], a.prototype, "outputSchema", 2);
-n([
-  m()
-], a.prototype, "modelTier", 2);
-a = n([
-  _("LLMAgent")
-], a);
+m([
+  n()
+], i.prototype, "prompt", 2);
+m([
+  n()
+], i.prototype, "tools", 2);
+m([
+  n()
+], i.prototype, "inputSchema", 2);
+m([
+  n()
+], i.prototype, "outputSchema", 2);
+m([
+  n()
+], i.prototype, "modelTier", 2);
+i = m([
+  v("LLMAgent")
+], i);
 export {
-  a as LLMAgent
+  i as LLMAgent
 };

package/dist/agent-utils/WorkflowAgent.js

@@ -3,13 +3,12 @@ import { property as h, subclass as c } from "@arcgis/core/core/accessorSupport/
 import { watch as l } from "@arcgis/core/core/reactiveUtils.js";
 import { BaseAgent as m } from "./BaseAgent.js";
 import { c as u } from "../chunks/graph.js";
-import "../chunks/BaseWorkflow.js";
-var f = Object.defineProperty, w = Object.getOwnPropertyDescriptor, n = (e, r, s, o) => {
-  for (var t = o > 1 ? void 0 : o ? w(r, s) : r, i = e.length - 1, a; i >= 0; i--)
-    (a = e[i]) && (t = (o ? a(r, s, t) : a(t)) || t);
+var f = Object.defineProperty, w = Object.getOwnPropertyDescriptor, p = (e, r, s, o) => {
+  for (var t = o > 1 ? void 0 : o ? w(r, s) : r, a = e.length - 1, i; a >= 0; a--)
+    (i = e[a]) && (t = (o ? i(r, s, t) : i(t)) || t);
   return o && t && f(r, s, t), t;
 };
-let p = class extends m {
+let n = class extends m {
   //#region Lifecycle
   constructor(e) {
     super(e);
@@ -38,7 +37,7 @@ let p = class extends m {
       this._set("createGraph", r);
     else {
       const s = this.id, o = {
-        [s]: async (i, a) => await r().compile().invoke(i, a)
+        [s]: async (a, i) => await r().compile().invoke(a, i)
       }, t = [{ from: s, decide: () => {
       } }];
       this._set(
@@ -53,18 +52,18 @@ let p = class extends m {
   }
   //#endregion
 };
-n([
+p([
   h()
-], p.prototype, "workflow", 2);
-n([
+], n.prototype, "workflow", 2);
+p([
   h()
-], p.prototype, "inputSchema", 2);
-n([
+], n.prototype, "inputSchema", 2);
+p([
   h()
-], p.prototype, "outputSchema", 2);
-p = n([
+], n.prototype, "outputSchema", 2);
+n = p([
   c("WorkflowAgent")
-], p);
+], n);
 export {
-  p as WorkflowAgent
+  n as WorkflowAgent
 };

package/dist/agent-utils/index.d.ts

@@ -9,15 +9,93 @@ import type { ParallelWorkflow, ParallelWorkflowConstructProperties } from "./wo
 import type { RouterWorkflow, RouterWorkflowConstructProperties } from "./workflows/RouterWorkflow.js";
 import type { SequentialWorkflow, SequentialWorkflowConstructProperties } from "./workflows/SequentialWorkflow.js";
 import type { SwitchWorkflow, SwitchWorkflowConstructProperties } from "./workflows/SwitchWorkflow.js";
+import type { RunnableConfig } from "@langchain/core/runnables";
 
 /**
  * Creates a Zod schema from a plain object schema definition.
  *
+ * Supports all schema field variants:
+ * - `string` (with optional `enum`)
+ * - `number`
+ * - `boolean`
+ * - `array` with primitive or nested item definitions
+ * - `object` with nested `fields`
+ *
  * @param definition
+ * @example
+ * ```ts
+ * const primitiveSchema = await createSchema({
+ *   name: { type: "string", description: "Search location name", required: true },
+ *   radius: { type: "number", description: "Search radius in miles" },
+ *   active: { type: "boolean", description: "Whether the search is enabled" },
+ * });
+ * ```
+ * @example
+ * ```ts
+ * const nestedObjectSchema = await createSchema({
+ *   query: { type: "string", description: "User search text", required: true },
+ *   options: {
+ *     type: "object",
+ *     description: "Search options",
+ *     required: true,
+ *     fields: {
+ *       center: {
+ *         type: "object",
+ *         description: "Map center point",
+ *         fields: {
+ *           latitude: { type: "number", description: "Center latitude", required: true },
+ *           longitude: { type: "number", description: "Center longitude", required: true },
+ *         },
+ *       },
+ *       categories: { type: "array", description: "Selected categories", itemType: "string" },
+ *     },
+ *   },
+ * });
+ * ```
+ * @example
+ * ```ts
+ * const arrayOfObjectsSchema = await createSchema({
+ *   constraints: {
+ *     type: "array",
+ *     description: "Constraint rules",
+ *     itemType: {
+ *       type: "object",
+ *       description: "Single constraint rule",
+ *       fields: {
+ *         key: { type: "string", description: "Constraint key", required: true },
+ *         enabled: { type: "boolean", description: "Whether this rule is active" },
+ *         values: { type: "array", description: "Rule values", itemType: "string" },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
  * @since 5.1
  */
 export function createSchema<const TDefinition extends SchemaDefinition>(definition: TDefinition): Promise<ZodObjectSchema<SchemaDefinitionData<TDefinition>>>;
 
+/**
+ * The suggestions emitted by the agent to the user interface.
+ *
+ * @since 5.1
+ */
+export type UXSuggestion = {
+  /** The type of suggestion being made. */
+  type: string;
+  /** Optional additional data associated with the suggestion. */
+  data?: Record<string, unknown>;
+};
+
+/**
+ * Sends an optional UX suggestion from an agent run to the host application.
+ * Use this for non-blocking hints (for example, recommended next actions or UI prompts) that the app may choose to display.
+ *
+ * @param suggestion
+ * @param config
+ * @since 5.1
+ */
+export function sendUXSuggestion(suggestion: UXSuggestion, config?: RunnableConfig): Promise<void>;
+
 /**
  * Creates a FunctionAgent instance from the existing agent implementation.
  *