@arcgis/ai-components 5.2.0-next.98 → 6.0.0-next.0

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

@@ -1,7 +1,5 @@
-import type Accessor from "@arcgis/core/core/Accessor.js";
-import type { AgentMiddleware } from "./middlewares/types.js";
-import type { AgentCreateGraph, AgentData, AgentExecutionConfig, AgentGraphState, AgentStateAnnotation, EmptyAgentData, ZodObjectSchema } from "./types.js";
-import type { AgentRegistration } from "../utils/index.js";
+import type { AgentRegistration } from "../orchestrator/types.js";
+import type { AgentCreateGraph, AgentData, AgentExecutionConfig, AgentGraphState, AgentStateAnnotation, EmptyAgentData } from "./types.js";
 
 /**
  * BaseAgent serves as the foundational class for all agent implementations. It
@@ -11,29 +9,26 @@ import type { AgentRegistration } from "../utils/index.js";
  *
  * @since 5.1
  */
-export abstract class BaseAgent<TCustomState extends AgentData = EmptyAgentData> extends Accessor {
+export abstract class BaseAgent<TCustomState extends AgentData = EmptyAgentData> {
   /**
    * The createGraph function defines the internal graph structure of the agent,
    * including its nodes, edges, and associated state.
    *
-   * @internal
+   * @since 5.2
    */
-  get createGraph(): AgentCreateGraph<TCustomState>;
+  accessor createGraph: AgentCreateGraph<TCustomState>;
   /**
    * Description of the agent's purpose and functionality. This can be used in registration metadata to provide context about the agent's functionality. A good description is clear and concise. Use bullet points to describe tasks the agent can accomplish. Provide examples of user questions or prompts that could be answered by the agent.
    *
    * @default ""
    */
-  accessor description: string;
-  /** The unique identifier for the agent, derived from the name property. This ID is used for registration and invocation purposes. */
-  get id(): string;
+  description: string;
   /**
-   * An optional array of middleware functions that can be used to extend or modify the agent's
-   * behavior during execution.
-   * This allows for flexible customization of the agent's execution logic. For example, middlewares
-   * can be used to implement trace messages (i.e. logging), human-in-the-loop interrupts, or other custom actions.
+   * The unique identifier for the agent. When not provided, it is derived from the name property.
+   * This ID is used for registration and invocation purposes.
    */
-  accessor middlewares: AgentMiddleware<TCustomState>[];
+  get id(): string;
+  set id(value: string | undefined);
   /**
    * A name for the agent, which is used in the registration metadata and can be displayed in tooling.
    * It should be unique across agents to avoid registration conflicts. A good agent name clearly
@@ -45,39 +40,28 @@ export abstract class BaseAgent<TCustomState extends AgentData = EmptyAgentData>
    *
    * @required
    */
-  accessor name: string;
+  name: string;
   /**
    * The registration property assembles the necessary metadata and graph definition for this agent,
    * which is consumed by the orchestrator during registration.
    */
   get registration(): AgentRegistration;
   /**
-   * The workspace property serves as the agent's internal state storage, which is used to maintain
-   * context across graph node executions.
-   * This is where the agent's state is read from and written to during graph execution, allowing for
-   * dynamic behavior based on previous steps in the graph.
+   * The workspace defines the state channels available to the agent's graph. Graph invocations use
+   * this annotation to create and update state as nodes execute.
    *
-   * @internal
+   * @since 5.2
    */
-  get workspace(): AgentStateAnnotation<TCustomState>;
+  accessor workspace: AgentStateAnnotation<TCustomState>;
   /**
-   * 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.
+   * Rebuilds internal workspace and createGraph wiring. Concrete agent constructors call this after assigning their
+   * configuration. Call it manually after changing graph-defining properties.
    *
    * The agent implementation is responsible for defining the createGraph function and workspace structure in this method, which are then used during execution.
    *
-   * @internal
+   * @since 5.2
    */
   abstract generate(): void;
-  /**
-   * Returns all schemas required by this agent implementation.
-   *
-   * @returns An array of Zod object schemas that define the structure of the agent's expected input and output data.
-   * These schemas are used for validation and type inference during graph execution.
-   * @internal
-   */
-  abstract getSchemas(): ZodObjectSchema<object>[];
-  initialize(): void;
   /**
    * Executes the agent's graph with the provided state and configuration. This method is responsible
    * for invoking the compiled graph and returning the resulting state after execution.

package/dist/agent-utils/BaseAgent.js

@@ -1,37 +1,60 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
-import m from "@arcgis/core/core/Accessor.js";
-import { property as i, subclass as l } from "@arcgis/core/core/accessorSupport/decorators.js";
-import { a as u } from "../chunks/state.js";
-import { watch as h } from "@arcgis/core/core/reactiveUtils.js";
-var y = Object.defineProperty, w = Object.getOwnPropertyDescriptor, t = (s, a, o, p) => {
-  for (var r = p > 1 ? void 0 : p ? w(a, o) : a, n = s.length - 1, c; n >= 0; n--)
-    (c = s[n]) && (r = (p ? c(a, o, r) : c(r)) || r);
-  return p && r && y(a, o, r), r;
-};
-const d = () => {
+import { a } from "../chunks/state.js";
+const t = () => {
   throw new Error("createGraph method not implemented.");
 };
-let e = class extends m {
+class c {
   constructor() {
-    super(...arguments), this.description = "", this.middlewares = [], this.createGraph = d, this.workspace = u();
+    this._createGraph = t, this._workspace = a(), this.description = "";
   }
-  //#region Lifecycle
-  initialize() {
-    this.addHandles([
-      h(
-        () => [this.name, this.description],
-        () => this.generate(),
-        { initial: !0, sync: !0 }
-      ),
-      h(
-        () => this.createGraph,
-        () => this._compiledGraph = void 0
-      )
-    ]);
+  _ensureGenerated() {
+    this._createGraph === t && this.generate();
   }
+  //#region Properties
+  /**
+   * The unique identifier for the agent. When not provided, it is derived from the name property.
+   * This ID is used for registration and invocation purposes.
+   *
+   * @public
+   */
   get id() {
-    return this.name.replace(/\s+/gu, "-").toLowerCase();
+    return this._id ??= this.name.replace(/\s+/gu, "-").toLowerCase();
+  }
+  set id(e) {
+    this._id = e;
+  }
+  /**
+   * The createGraph function defines the internal graph structure of the agent,
+   * including its nodes, edges, and associated state.
+   *
+   * @public
+   * @since 5.2
+   */
+  get createGraph() {
+    return this._ensureGenerated(), this._createGraph;
+  }
+  set createGraph(e) {
+    this._createGraph = e, this._compiledGraph = void 0;
   }
+  /**
+   * The workspace defines the state channels available to the agent's graph. Graph invocations use
+   * this annotation to create and update state as nodes execute.
+   *
+   * @public
+   * @since 5.2
+   */
+  get workspace() {
+    return this._ensureGenerated(), this._workspace;
+  }
+  set workspace(e) {
+    this._workspace = e;
+  }
+  /**
+   * The registration property assembles the necessary metadata and graph definition for this agent,
+   * which is consumed by the orchestrator during registration.
+   *
+   * @public
+   */
   get registration() {
     return {
       id: this.id,
@@ -53,35 +76,11 @@ let e = class extends m {
    *
    * @public
    */
-  async run(s = {}, a) {
-    return this.createGraph === d && this.generate(), this._compiledGraph = this._compiledGraph ?? this.createGraph().compile(), await this._compiledGraph.invoke(s, a);
+  async run(e = {}, r) {
+    return this._compiledGraph = this._compiledGraph ?? this.createGraph().compile(), await this._compiledGraph.invoke(e, r);
   }
   //#endregion
-};
-t([
-  i({ readOnly: !0 })
-], e.prototype, "id", 1);
-t([
-  i()
-], e.prototype, "name", 2);
-t([
-  i()
-], e.prototype, "description", 2);
-t([
-  i()
-], e.prototype, "middlewares", 2);
-t([
-  i({ readOnly: !0 })
-], e.prototype, "createGraph", 2);
-t([
-  i({ readOnly: !0 })
-], e.prototype, "workspace", 2);
-t([
-  i({ readOnly: !0 })
-], e.prototype, "registration", 1);
-e = t([
-  l("BaseAgent")
-], e);
+}
 export {
-  e as BaseAgent
+  c as BaseAgent
 };

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

@@ -1,4 +1,5 @@
 import type { BaseAgent } from "./BaseAgent.js";
+import type { AgentMiddleware } from "./middlewares/types.js";
 import type { AgentCustomState, AgentData, AgentExecutionConfig, AgentNodeState, ZodObjectSchema } from "./types.js";
 
 /**
@@ -18,7 +19,7 @@ export type FunctionAgentExecute<TInput extends AgentData, TOutput extends Agent
  * @since 5.1
  */
 export class FunctionAgent<TInput extends AgentData = AgentData, TOutput extends AgentData = AgentData> extends BaseAgent<AgentCustomState<TInput, TOutput>> {
-  constructor(properties?: FunctionAgentConstructProperties<TInput, TOutput>);
+  constructor(properties: FunctionAgentConstructProperties<TInput, TOutput>);
   /**
    * The execute function contains the core logic of the FunctionAgent.
    * It receives the current agent state and an optional execution configuration,
@@ -29,36 +30,29 @@ export class FunctionAgent<TInput extends AgentData = AgentData, TOutput extends
    *
    * @required
    */
-  accessor execute: FunctionAgentExecute<TInput, TOutput>;
+  execute: FunctionAgentExecute<TInput, TOutput>;
   /**
    * The input schema defines the expected structure of the agent state when the execute function is invoked.
    * If provided, the agent will validate incoming state against this schema and throw an error if validation fails.
    */
-  accessor inputSchema: ZodObjectSchema<TInput> | undefined;
+  inputSchema?: ZodObjectSchema<TInput>;
+  /** Middleware functions that extend or modify the agent's execution behavior. */
+  middlewares: AgentMiddleware<AgentCustomState<TInput, TOutput>>[];
   /**
    * The output schema defines the expected structure of the result returned by the execute function.
    * If provided, the agent will validate the output against this schema and handle it accordingly.
    */
-  accessor outputSchema: ZodObjectSchema<TOutput> | undefined;
+  outputSchema?: ZodObjectSchema<TOutput>;
   /**
-   * 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.
+   * Rebuilds internal workspace and createGraph wiring. Concrete agent constructors call this after assigning their
+   * configuration. Call it manually after changing graph-defining properties.
    *
    * The agent implementation is responsible for defining the createGraph function and workspace structure in this method, which are then used during execution.
    *
-   * @internal
+   * @since 5.2
    */
   generate(): void;
-  /**
-   * Returns all schemas required by this agent implementation.
-   *
-   * @returns An array of Zod object schemas that define the structure of the agent's expected input and output data.
-   * These schemas are used for validation and type inference during graph execution.
-   * @internal
-   */
-  getSchemas(): ZodObjectSchema<object>[];
-  initialize(): void;
 }
 
-export type FunctionAgentConstructProperties<TInput extends AgentData, TOutput extends AgentData> = Partial<Pick<FunctionAgent<TInput, TOutput>, "description" | "inputSchema" | "middlewares" | "outputSchema">>
+export type FunctionAgentConstructProperties<TInput extends AgentData, TOutput extends AgentData> = Partial<Pick<FunctionAgent<TInput, TOutput>, "description" | "id" | "inputSchema" | "middlewares" | "outputSchema">>
   & Pick<FunctionAgent<TInput, TOutput>, "execute" | "name">;

package/dist/agent-utils/FunctionAgent.js

@@ -1,77 +1,53 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
-import { property as u, subclass as p } from "@arcgis/core/core/accessorSupport/decorators.js";
-import { isGraphInterrupt as m } from "@langchain/langgraph/web";
-import { BaseAgent as d } from "./BaseAgent.js";
-import { c as l } from "../chunks/graph.js";
-import { c as f } from "../chunks/state.js";
-import { watch as S } from "@arcgis/core/core/reactiveUtils.js";
-import { c as h, h as g, g as v } from "../chunks/utils.js";
-var w = Object.defineProperty, _ = Object.getOwnPropertyDescriptor, o = (t, e, s, r) => {
-  for (var i = r > 1 ? void 0 : r ? _(e, s) : e, a = t.length - 1, c; a >= 0; a--)
-    (c = t[a]) && (i = (r ? c(e, s, i) : c(i)) || i);
-  return r && i && w(e, s, i), i;
-};
-let n = class extends d {
+import { isGraphInterrupt as o } from "@langchain/langgraph/web";
+import { BaseAgent as c } from "./BaseAgent.js";
+import { c as u } from "../chunks/graph.js";
+import { c as h } from "../chunks/state.js";
+import { c as i, h as d, g as m } from "../chunks/utils.js";
+class v extends c {
   //#region Lifecycle
   constructor(t) {
-    super(t);
-  }
-  initialize() {
-    this.addHandles(
-      S(
-        () => [this.name, this.description, this.inputSchema, this.outputSchema, this.execute],
-        () => {
-          this.generate();
-        },
-        { initial: !0, sync: !0 }
-      )
-    );
+    super(), this.middlewares = [], Object.assign(this, t), this.generate();
   }
   //#endregion
   //#region Public Methods
-  getSchemas() {
-    return [this.inputSchema, this.outputSchema].filter(Boolean);
-  }
   generate() {
-    const t = f(this.getSchemas());
-    this._set("workspace", t);
-    const e = `${this.id}-execute`, s = { [e]: this._invokeExecuteNode.bind(this) }, r = [{ from: e, decide: () => {
+    const t = h(
+      [this.inputSchema, this.outputSchema].filter(Boolean)
+    ), e = `${this.id}-execute`, r = { [e]: this._invokeExecuteNode.bind(this) }, s = [{ from: e, decide: () => {
     } }];
-    this._set(
-      "createGraph",
-      () => l(s, r, t, { agent: this, entryNode: e, middlewares: this.middlewares })
-    );
+    this.workspace = t, this.createGraph = () => u(r, s, t, { agent: this, entryNode: e, middlewares: this.middlewares });
   }
   //#endregion
   //#region Private Methods
   async _invokeExecuteNode(t, e) {
     try {
       return this.outputSchema ? await this._invokeStructured(t, e) : await this._invokeUnstructured(t, e);
-    } catch (s) {
-      if (m(s))
-        throw s;
-      const r = s instanceof Error ? s.message : String(s);
-      return h({ outputMessage: r }, "failed", r);
+    } catch (r) {
+      if (o(r) || e?.signal?.aborted || r instanceof Error && r.name === "AbortError")
+        throw r;
+      const s = r instanceof Error ? r.message : String(r);
+      return i({ outputMessage: s }, "failed", s);
     }
   }
   async _invokeStructured(t, e) {
     if (!this.outputSchema)
       throw new Error("Output schema is required for structured invocation.");
-    const s = this._validateInputState(t), r = await this.execute(s, e);
-    if (typeof r == "string")
+    const r = this._validateInputState(t), s = await this.execute(r, e);
+    if (typeof s == "string")
       throw new Error(
         "Expected execute function to return an object matching the output schema, but received a string."
       );
-    return g(r, this.outputSchema, t.agentExecutionContext.messages);
+    return d(s, this.outputSchema, t.agentExecutionContext.messages);
   }
   async _invokeUnstructured(t, e) {
-    const s = this._validateInputState(t), r = await this.execute(s, e), i = typeof r == "string" ? r : JSON.stringify(r), a = i.trim() || "FunctionAgent completed.";
-    return h({ outputMessage: i }, "success", a);
+    const r = this._validateInputState(t), s = await this.execute(r, e), a = typeof s == "string" ? s : JSON.stringify(s), n = a.trim() || "FunctionAgent completed.";
+    return i({ outputMessage: a }, "success", n);
   }
   _validateInputState(t) {
     if (!this.inputSchema)
       return t;
-    const e = this.inputSchema.safeParse(v(t, this.inputSchema));
+    const e = this.inputSchema.safeParse(m(t, this.inputSchema));
     if (!e.success)
       throw new Error(`FunctionAgent input schema validation failed: ${e.error.message}`);
     return {
@@ -80,19 +56,7 @@ let n = class extends d {
     };
   }
   //#endregion
-};
-o([
-  u()
-], n.prototype, "inputSchema", 2);
-o([
-  u()
-], n.prototype, "outputSchema", 2);
-o([
-  u()
-], n.prototype, "execute", 2);
-n = o([
-  p("FunctionAgent")
-], n);
+}
 export {
-  n as FunctionAgent
+  v as FunctionAgent
 };

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

@@ -1,7 +1,9 @@
 import type { StructuredToolInterface } from "@langchain/core/tools";
 import type { BaseAgent } from "./BaseAgent.js";
+import type { AgentMiddleware } from "./middlewares/types.js";
 import type { FunctionToolLike } from "./tools/FunctionTool.js";
 import type { AgentCustomState, AgentData, ZodObjectSchema } from "./types.js";
+import type { ChatModelTier } from "../orchestrator/models/chatModel.js";
 
 export type LLMAgentTool = FunctionToolLike | StructuredToolInterface;
 
@@ -12,57 +14,49 @@ export type LLMAgentTool = FunctionToolLike | StructuredToolInterface;
  * @since 5.1
  */
 export class LLMAgent<TInput extends AgentData = AgentData, TOutput extends AgentData = AgentData> extends BaseAgent<AgentCustomState<TInput, TOutput>> {
-  constructor(properties?: LLMAgentConstructProperties<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;
+  inputSchema?: ZodObjectSchema<TInput>;
+  /** Middleware functions that extend or modify the agent's execution behavior. */
+  middlewares: AgentMiddleware<AgentCustomState<TInput, TOutput>>[];
   /**
    * The tier of the model to use for the agent. This can affect the capabilities and performance of the agent.
    *
    * @default "default"
    */
-  accessor modelTier: "advanced" | "default" | "fast";
+  modelTier: ChatModelTier;
   /**
    * The outputSchema property is an optional Zod schema describing the expected structured output from the agent.
    * If provided, the agent will attempt to parse the language model's response according to this schema and return structured data.
    * If not provided, the agent will treat the language model's response as an unstructured string message.
    */
-  accessor outputSchema: ZodObjectSchema<TOutput> | undefined;
+  outputSchema?: ZodObjectSchema<TOutput>;
   /**
    * 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;
+  prompt: string;
   /** The tools property is an optional array of tools that the agent can use during execution. */
-  accessor tools: LLMAgentTool[] | undefined;
+  tools?: LLMAgentTool[];
   /**
-   * 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.
+   * Rebuilds internal workspace and createGraph wiring. Concrete agent constructors call this after assigning their
+   * configuration. Call it manually after changing graph-defining properties.
    *
    * The agent implementation is responsible for defining the createGraph function and workspace structure in this method, which are then used during execution.
    *
-   * @internal
+   * @since 5.2
    */
   generate(): void;
-  /**
-   * Returns all schemas required by this agent implementation.
-   *
-   * @returns An array of Zod object schemas that define the structure of the agent's expected input and output data.
-   * These schemas are used for validation and type inference during graph execution.
-   * @internal
-   */
-  getSchemas(): ZodObjectSchema<object>[];
-  initialize(): void;
 }
 
-export type LLMAgentConstructProperties<TInput extends AgentData, TOutput extends AgentData> = Partial<Pick<LLMAgent<TInput, TOutput>, "description" | "inputSchema" | "middlewares" | "modelTier" | "outputSchema" | "tools">>
+export type LLMAgentConstructProperties<TInput extends AgentData, TOutput extends AgentData> = Partial<Pick<LLMAgent<TInput, TOutput>, "description" | "id" | "inputSchema" | "middlewares" | "modelTier" | "outputSchema" | "tools">>
   & Pick<LLMAgent<TInput, TOutput>, "name" | "prompt">;