@arcgis/ai-components 5.1.0-next.99 → 5.1.0

package/dist/agent-utils/middlewares/trace.js

@@ -0,0 +1,42 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import { s as r } from "../../chunks/index.js";
+import { AIMessage as i, ToolMessage as s } from "@langchain/core/messages";
+import { createAgentMiddleware as c, createToolMiddleware as d } from "./middleware.js";
+const g = "agent-trace", f = "tool-trace";
+function p() {
+  return c(g, {
+    wrapModelCall: async (e, a) => {
+      const t = await a(e), o = e.runtime, l = m(t);
+      return await Promise.all(
+        l.map(
+          async (n) => await r(
+            {
+              text: `LLM requested tool call "${n.name}" with arguments: ${JSON.stringify(n.args, null, 2)}`
+            },
+            o
+          )
+        )
+      ), t;
+    }
+  });
+}
+function T() {
+  return d(f, {
+    wrapToolCall: async (e, a) => {
+      const t = await a(e), o = e.config;
+      return await r(
+        {
+          text: `Finished executing tool: ${s.isInstance(t) ? t.content.toString() : typeof t == "string" ? t : e.tool.name}`
+        },
+        o
+      ), t;
+    }
+  });
+}
+function m(e) {
+  return !i.isInstance(e) || !Array.isArray(e.tool_calls) ? [] : e.tool_calls.filter((a) => typeof a?.name == "string");
+}
+export {
+  p as createAgentTraceMiddleware,
+  T as createToolTraceMiddleware
+};

package/dist/agent-utils/middlewares/types.d.ts

@@ -0,0 +1,123 @@
+import type { FunctionToolMiddlewareHandler } from "../tools/FunctionTool.js";
+import type { AgentData, AgentExecutionConfig, AgentGraphState, EmptyAgentData } from "../types.js";
+import type { AgentMiddleware as LangChainAgentMiddleware } from "langchain";
+
+/**
+ * Handles a middleware request and returns the resulting value.
+ *
+ * @param request - The request payload for the current middleware stage.
+ */
+export type MiddlewareHandler<TRequest, TResult> = (request: TRequest) => Promise<TResult> | TResult;
+
+/**
+ * Wraps a middleware request and delegates to the next handler.
+ *
+ * @param request - The request payload for the current middleware stage.
+ * @param handler - The next handler in the middleware chain.
+ */
+export type Middleware<TRequest, TResult> = (request: TRequest, handler: MiddlewareHandler<TRequest, TResult>) => Promise<TResult> | TResult;
+
+export interface AgentMiddlewareAgent {
+  /**
+   * Description of the agent, which can be used to provide context in middleware hooks and interrupts.
+   *
+   * @since 5.1
+   */
+  description?: string;
+  /**
+   * Unique identifier for the agent, used for registration and invocation purposes.
+   *
+   * @since 5.1
+   */
+  id: string;
+  /**
+   * Name of the agent, used for display and identification purposes.
+   *
+   * @since 5.1
+   */
+  name: string;
+}
+
+export interface AgentRunRequest<TCustomState extends AgentData = EmptyAgentData> {
+  /**
+   * The agent that is being executed. This can be used in middleware hooks to access agent metadata and provide context for interrupts or other middleware behavior.
+   *
+   * @since 5.1
+   */
+  agent: AgentMiddlewareAgent;
+  /**
+   * The current execution configuration for the agent run, which may include configurable parameters, metadata, and other contextual information. This can be used in middleware
+   * hooks to make decisions based on the execution context or to store and retrieve information related to the agent run.
+   *
+   * @since 5.1
+   */
+  config?: AgentExecutionConfig;
+  /**
+   * The name of the current node being executed in the agent's workflow. This can be used in middleware hooks to provide context or make decisions based on the specific node.
+   *
+   * @since 5.1
+   */
+  nodeName: string;
+  /**
+   * The current state of the agent's workflow, which may include custom data and intermediate results. This can be used in middleware hooks to access or modify the agent's state during execution.
+   *
+   * @since 5.1
+   */
+  state: Partial<AgentGraphState<TCustomState>>;
+}
+
+export type AgentMiddlewareHandler<TCustomState extends AgentData = EmptyAgentData> = Middleware<AgentRunRequest<TCustomState>, AgentGraphState<TCustomState>>;
+
+export interface AgentMiddleware<TCustomState extends AgentData = EmptyAgentData> {
+  name: string;
+  handler: AgentMiddlewareHandler<TCustomState>;
+  hooks?: AgentMiddlewareHooks<TCustomState>;
+  outputKey?: keyof AgentGraphState<TCustomState>;
+}
+
+export interface AfterAgentRequest<TCustomState extends AgentData = EmptyAgentData> extends AgentRunRequest<TCustomState> {
+  result: AgentGraphState<TCustomState>;
+}
+
+export interface AgentMiddlewareHooks<TCustomState extends AgentData = EmptyAgentData> {
+  /**
+   * An optional hook that is called after the agent has executed, allowing for modification of the result or additional side effects.
+   *
+   * @param request - The request payload for the afterAgent hook, including the original request and the result of the agent's execution.
+   * @returns A partial update to the agent's state or other modifications to be applied to the final result, or a promise that resolves to such an update.
+   * @since 5.1
+   */
+  afterAgent?(request: AfterAgentRequest<TCustomState>): Partial<AgentGraphState<TCustomState>> | Promise<Partial<AgentGraphState<TCustomState>> | void> | void;
+  readonly afterModel?: ModelLifecycleHook;
+  readonly beforeModel?: ModelLifecycleHook;
+  /**
+   * An optional hook that is called before the agent executes, allowing for modification of the request or additional side effects.
+   *
+   * @param request - The request payload for the beforeAgent hook, including the original request.
+   * @returns A partial update to the agent's state or other modifications to be applied to the request, or a promise that resolves to such an update.
+   * @since 5.1
+   */
+  beforeAgent?(request: AgentRunRequest<TCustomState>): Partial<AgentGraphState<TCustomState>> | Promise<Partial<AgentGraphState<TCustomState>> | void> | void;
+  /**
+   * An optional hook that wraps the entire agent execution, allowing for complete control over the execution flow.
+   *
+   * @since 5.1
+   */
+  readonly wrapAgent?: AgentMiddlewareHandler<TCustomState>;
+  readonly wrapModelCall?: LangChainMiddlewareHooks["wrapModelCall"];
+  readonly wrapToolCall?: LangChainMiddlewareHooks["wrapToolCall"];
+}
+
+/** @since 5.1 */
+export interface ToolMiddlewareHooks<TInput extends AgentData = AgentData, TOutput = unknown> {
+  /**
+   * Hook that wraps a tool call, allowing you to intercept and modify the request and response of a tool execution. This can be used for logging, modifying inputs/outputs, or implementing custom behavior around tool calls.
+   *
+   * @since 5.1
+   */
+  readonly wrapToolCall?: FunctionToolMiddlewareHandler<TInput, TOutput>;
+}
+
+export type LangChainMiddlewareHooks = Pick<LangChainAgentMiddleware, "afterModel" | "beforeModel" | "wrapModelCall" | "wrapToolCall">;
+
+export type ModelLifecycleHook = NonNullable<LangChainMiddlewareHooks["beforeModel"]>;

package/dist/agent-utils/middlewares/types.js

@@ -0,0 +1,2 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+

package/dist/agent-utils/tools/FunctionTool.d.ts

@@ -0,0 +1,127 @@
+import type Accessor from "@arcgis/core/core/Accessor.js";
+import type z from "zod";
+import type { StructuredToolInterface } from "@langchain/core/tools";
+import type { Middleware } from "../middlewares/types.js";
+import type { AgentData, AgentExecutionConfig } from "../types.js";
+
+/**
+ * Execute function used by `FunctionTool`.
+ *
+ * @param input - Structured tool input.
+ * @param config - Optional execution configuration.
+ */
+export type FunctionToolExecute<TInput extends object, TOutput> = (input: TInput, config?: AgentExecutionConfig) => Promise<TOutput> | TOutput;
+
+export type FunctionToolResult<TOutput = unknown> = TOutput | string;
+
+export interface FunctionToolMiddlewareRequest<TInput extends AgentData = AgentData> {
+  config?: AgentExecutionConfig;
+  input: TInput;
+  tool: FunctionToolMiddlewareTool;
+  toolCallId?: string;
+}
+
+export type FunctionToolMiddlewareHandler<TInput extends AgentData = AgentData, TOutput = unknown> = Middleware<FunctionToolMiddlewareRequest<TInput>, FunctionToolResult<TOutput>>;
+
+export interface FunctionToolMiddleware<TInput extends AgentData = AgentData, TOutput = unknown> {
+  name: string;
+  handler: FunctionToolMiddlewareHandler<TInput, TOutput>;
+  outputKey?: keyof TInput;
+}
+
+export type ToolResultMode = "continue" | "terminal";
+
+export interface FunctionToolLike {
+  /**
+   * Name of the tool, used for invocation by agents. This should be unique among the tools available to an agent.
+   *
+   * @since 5.1
+   */
+  name?: string;
+  /**
+   * Result mode determines how the agent should treat the output of this tool. If set to "terminal", the agent will return the tool's output directly as its final response. If set to "continue", the agent will continue processing after invoking the tool, allowing for further reasoning or tool calls.
+   *
+   * @since 5.1
+   */
+  resultMode?: ToolResultMode;
+  getTool: () => StructuredToolInterface;
+}
+
+/**
+ * FunctionTool is a tool implementation that allows users to define custom logic through a provided execute function,
+ * along with input/output schemas for validation and optional middleware for extensibility.
+ *
+ * The FunctionTool is passed to LLMAgents as part of their tools array, and can be invoked by the agent during execution
+ * based on the agent's prompt and reasoning process. The resultMode property allows the tool to either return
+ * a final response directly or continue the agent's processing after execution, providing flexibility in how the tool's
+ * output is used within the agent's workflow.
+ *
+ * @since 5.1
+ */
+export class FunctionTool<TInput extends AgentData, TOutput = unknown> extends Accessor {
+  constructor(properties?: FunctionToolConstructProperties<TInput, TOutput>);
+  /**
+   * A concise, but clear description of the tool's functionality.
+   * This should provide enough information for the agent to understand when and why to use the tool.
+   * You can include examples of a user's input that would trigger the tool, the values to extract, and
+   * sample output to illustrate its purpose.
+   *
+   * @required
+   */
+  accessor description: string;
+  /**
+   * The execute function contains the custom logic that will be executed when the tool is invoked
+   * by an agent. It receives
+   * the input object and an optional execution configuration, and returns either a result directly
+   * or a promise that resolves to the result.
+   *
+   * The result is validated against the output schema, if provided.
+   *
+   * @required
+   * @since 5.1
+   */
+  accessor execute: FunctionToolExecute<TInput, TOutput>;
+  /**
+   * The input schema defines the expected structure of the input object when invoking the tool.
+   * This should be a Zod schema object.
+   * The agent will validate the input against this schema before execution.
+   */
+  accessor inputSchema: z.ZodType<TInput> | undefined;
+  /** Middleware that can wrap this tool's execution. */
+  accessor middlewares: FunctionToolMiddleware<TInput, TOutput>[];
+  /**
+   * The name of the tool, which will be used to invoke it. This should be unique among the tools
+   * available to an agent. It should also be descriptive of the tool's functionality to make it
+   * clear to the agent when to use it.
+   *
+   * @required
+   */
+  accessor name: string;
+  /**
+   * The output schema defines the expected structure of the result returned by the tool.
+   * This should be a Zod schema object.
+   * The agent will validate the output against this schema after execution.
+   */
+  accessor outputSchema: z.ZodType<TOutput> | undefined;
+  /**
+   * The result mode determines how the agent should treat the output of this tool.
+   * If set to `terminal`, the agent will
+   * return the tool's output directly as its final response. If set to `continue`,
+   * the agent will continue processing after
+   * invoking the tool, allowing for further reasoning or tool calls.
+   *
+   * @default "continue"
+   */
+  accessor resultMode: ToolResultMode;
+  /** Builds the LangChain tool adapter used by LLM agents. */
+  getTool(): StructuredToolInterface;
+}
+
+export interface FunctionToolMiddlewareTool {
+  description: string;
+  name: string;
+  resultMode: ToolResultMode;
+}
+
+export type FunctionToolConstructProperties<TInput extends AgentData, TOutput> = Partial<Pick<FunctionTool<TInput, TOutput>, "inputSchema" | "middlewares" | "outputSchema" | "resultMode">>
+  & Pick<FunctionTool<TInput, TOutput>, "description" | "execute" | "name">;

package/dist/agent-utils/tools/FunctionTool.js

@@ -0,0 +1,80 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
+import c from "@arcgis/core/core/Accessor.js";
+import { property as a, subclass as p } from "@arcgis/core/core/accessorSupport/decorators.js";
+import { tool as d } from "@langchain/core/tools";
+var h = Object.defineProperty, m = Object.getOwnPropertyDescriptor, s = (o, t, n, u) => {
+  for (var e = u > 1 ? void 0 : u ? m(t, n) : t, i = o.length - 1, l; i >= 0; i--)
+    (l = o[i]) && (e = (u ? l(t, n, e) : l(e)) || e);
+  return u && e && h(t, n, e), e;
+};
+let r = class extends c {
+  //#region Lifecycle
+  constructor(o) {
+    super(o), this.resultMode = "continue", this.middlewares = [];
+  }
+  //#endregion
+  //#region Public Methods
+  /**
+   * Builds the LangChain tool adapter used by LLM agents.
+   */
+  getTool() {
+    return d(this._executeWithMiddlewares.bind(this), {
+      name: this.name,
+      description: this.description,
+      returnDirect: this.resultMode === "terminal",
+      schema: this.inputSchema
+    });
+  }
+  //#endregion
+  //#region Private Methods
+  async _executeWithMiddlewares(o, t) {
+    const n = async (e) => {
+      const i = await this.execute(e.input, e.config);
+      return this._validateOutput(i);
+    };
+    return await this.middlewares.reduceRight(
+      (e, i) => async (l) => await i.handler(l, e),
+      n
+    )({ config: t, input: o, tool: this, toolCallId: f(t) });
+  }
+  _validateOutput(o) {
+    if (!this.outputSchema)
+      return o;
+    const t = this.outputSchema.safeParse(o);
+    if (!t.success)
+      throw new Error(`FunctionTool output schema validation failed: ${t.error.message}`);
+    return t.data;
+  }
+  //#endregion
+};
+s([
+  a()
+], r.prototype, "name", 2);
+s([
+  a()
+], r.prototype, "description", 2);
+s([
+  a()
+], r.prototype, "resultMode", 2);
+s([
+  a()
+], r.prototype, "inputSchema", 2);
+s([
+  a()
+], r.prototype, "outputSchema", 2);
+s([
+  a()
+], r.prototype, "middlewares", 2);
+s([
+  a()
+], r.prototype, "execute", 2);
+r = s([
+  p("FunctionTool")
+], r);
+function f(o) {
+  const t = o?.toolCall;
+  return typeof t?.id == "string" ? t.id : void 0;
+}
+export {
+  r as FunctionTool
+};

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

@@ -0,0 +1,181 @@
+import type z from "zod";
+import type { BaseChannel, BinaryOperatorAggregate } from "@langchain/langgraph/channels";
+import type { AnnotationRoot, StateDefinitionInit, StateGraph } from "@langchain/langgraph/web";
+import type { AgentExecutionContext, AgentRegistration, AgentStatus } from "../utils/index.js";
+
+export type AgentData = Record<string, unknown>;
+
+export type EmptyAgentData = Record<never, never>;
+
+/** @internal */
+export type ZodModule = {
+  z: typeof z;
+};
+
+export type SchemaPrimitiveFieldType = "boolean" | "number" | "string";
+
+export type SchemaArrayItemDefinition = SchemaFieldDefinition | SchemaPrimitiveFieldType;
+
+export type SchemaFieldDefinition = ({
+    type: "array";
+    itemType: SchemaArrayItemDefinition;
+} | { type: "boolean" | "number"; } | {
+    type: "object";
+    fields: SchemaDefinition;
+} | {
+    type: "string";
+    enum?: readonly string[];
+}) & {
+  description?: string;
+  required?: boolean;
+};
+
+export type SchemaDefinition = Record<string, SchemaFieldDefinition>;
+
+export type SchemaDefinitionData<TDefinition extends SchemaDefinition> = {
+    [K in keyof TDefinition as TDefinition[K] extends { required: true; } ? K : never]: SchemaFieldData<TDefinition[K]>;
+} &
+  {
+    [K in keyof TDefinition as TDefinition[K] extends { required: true; } ? never : K]?: SchemaFieldData<TDefinition[K]>;
+};
+
+/** @privateRemark All agents are orchestrator-driven, so these channels exist for every agent graph. */
+export type AgentRuntimeState = {
+  agentExecutionContext: AgentExecutionContext;
+  /** The outputMessage is a string representing the output of an agent execution. */
+  outputMessage: string;
+  /** The summary is a string providing a brief overview of the agent execution. */
+  summary: string;
+  /** The status field represents the current status of the agent execution, which can be used to indicate success, failure, or other relevant states. */
+  status?: AgentStatus;
+};
+
+export type AgentGraphState<TState extends AgentData = EmptyAgentData> = AgentRuntimeState
+  & Omit<TState, keyof AgentRuntimeState>;
+
+export interface BaseAgentLike<TCustomState extends AgentData = EmptyAgentData> {
+  /**
+   * Stable ID derived from the agent name and used for graph node and registration identity.
+   *
+   * @since 5.1
+   */
+  id: string;
+  /**
+   * Optional schema used to validate and shape agent input state.
+   *
+   * @since 5.1
+   */
+  inputSchema?: ZodObjectSchema<object>;
+  /**
+   * Human-readable name shown in registration metadata and tooling.
+   *
+   * @since 5.1
+   */
+  name: string;
+  /**
+   * Optional schema used to validate structured agent output.
+   *
+   * @since 5.1
+   */
+  outputSchema?: ZodObjectSchema<object>;
+  /**
+   * Registration payload consumed by the orchestrator.
+   *
+   * @since 5.1
+   */
+  registration: AgentRegistration;
+  /** Regenerates workspace and graph wiring for this agent. */
+  generate: () => void;
+  /** Returns all schemas the agent contributes to state/input/output validation. */
+  getSchemas: () => ZodObjectSchema<object>[];
+  /**
+   * Executes the compiled graph for this agent.
+   *
+   * @param state - Optional partial state used as graph input.
+   * @param config - Optional runtime execution configuration.
+   * @return The resulting graph state after execution.
+   * @since 5.1
+   */
+  run(state?: Partial<AgentGraphState<TCustomState>>, config?: AgentExecutionConfig): Promise<AgentGraphState<TCustomState>>;
+}
+
+/** AgentExecutionConfig defines the shape of the configuration object that can be passed to agent execution methods to influence their behavior at runtime. */
+export interface AgentExecutionConfig {
+  /**
+   * The configurable field allows passing arbitrary key-value pairs that can be used by agents during execution to modify their behavior or provide additional context.
+   * This can include flags, parameters, or any other relevant information that an agent might need to access at runtime.
+   *
+   * @since 5.1
+   */
+  configurable?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  recursionLimit?: number;
+  runName?: string;
+  /**
+   * The signal property is an optional AbortSignal that can be used to cancel the execution of an agent. Agents should listen for the abort signal and gracefully handle cancellation when it is triggered.
+   *
+   * @since 5.1
+   */
+  signal?: AbortSignal;
+  tags?: string[];
+}
+
+export type AgentCustomState<TInput extends AgentData = AgentData, TOutput extends AgentData = AgentData> = Omit<TInput, keyof AgentRuntimeState>
+  & Partial<Omit<TOutput, keyof AgentRuntimeState>>;
+
+export type AgentNodeState<TInput extends AgentData = AgentData, TOutput extends AgentData = AgentData> = AgentGraphState<AgentCustomState<TInput, TOutput>>;
+
+export type AgentNodeUpdate<TInput extends AgentData, TOutput extends AgentData> = Partial<AgentNodeState<TInput, TOutput>>;
+
+/**
+ * AgentStateAnnotation defines the shape of the agent state used in LangGraph nodes, including both the built-in runtime channels
+ * and any custom fields defined by the agent.
+ *
+ * @since 5.1
+ */
+export type AgentStateAnnotation<TState extends AgentData> = AnnotationRoot<{
+    [K in keyof TState]: BinaryOperatorAggregate<TState[K] | undefined, TState[K] | undefined>;
+} & {
+    agentExecutionContext: BaseChannel<AgentExecutionContext, unknown, unknown>;
+    outputMessage: BaseChannel<string, unknown, unknown>;
+    summary: BaseChannel<string, unknown, unknown>;
+    status: BaseChannel<AgentStatus | undefined, unknown, unknown>;
+}>;
+
+/**
+ * State update shape produced by graph nodes.
+ *
+ * @since 5.1
+ */
+export type RunnableUpdate<TState extends AgentData> = Partial<TState> extends object ? Partial<TState> & Record<string, any> : Partial<TState>;
+
+/**
+ * Internal type representing the compiled graph used for agent execution.
+ *
+ * @since 5.1
+ */
+export type TypedStateGraph<TState extends AgentData> = StateGraph<StateDefinitionInit, AgentGraphState<TState>, RunnableUpdate<AgentGraphState<TState>>, string>;
+
+/**
+ * The shape of the `createGraph` function used by agents to generate their internal graph representation.
+ * This function is responsible for defining the nodes and edges of the graph, as well as any associated state and middleware.
+ *
+ * @since 5.1
+ */
+export type AgentCreateGraph<TState extends AgentData> = () => TypedStateGraph<TState>;
+
+/** ZodObjectSchema is a simplified type representing Zod object schemas used for input and output validation in agents. */
+export type ZodObjectSchema<T extends object = AgentData> = Pick<z.ZodType<T>, "safeParse">
+  & z.ZodObject;
+
+export type GraphNodes<S extends AgentData> = Record<string, (state: S, config?: AgentExecutionConfig) => Partial<S> | Promise<Partial<S> | S> | S>;
+
+export type GraphEdge<S extends AgentData> = {
+    from: string;
+    decide: (state: S, config?: AgentExecutionConfig) => Promise<string | undefined> | string | undefined;
+} | {
+    from: string;
+    to: string;
+};
+
+export type SchemaFieldData<TField extends SchemaFieldDefinition> = TField extends { type: "string"; } ? TField["enum"] extends readonly (infer TValue extends string)[] ? TValue : string : TField extends { type: "array"; } ? (TField["itemType"] extends "string" ? string : TField["itemType"] extends "number" ? number : TField["itemType"] extends "boolean" ? boolean : TField["itemType"] extends SchemaFieldDefinition ? SchemaFieldData<TField["itemType"]> : never)[] : TField extends { type: "object"; } ? SchemaDefinitionData<TField["fields"]> : TField extends { type: "number"; } ? number : boolean;

package/dist/agent-utils/workflows/BaseWorkflow.d.ts

@@ -0,0 +1,87 @@
+import type Accessor from "@arcgis/core/core/Accessor.js";
+import type { AgentCreateGraph, AgentData, AgentGraphState, AgentStateAnnotation, BaseAgentLike, GraphEdge, GraphNodes } from "../types.js";
+
+/**
+ * Return payload from `BaseWorkflow.generate()`.
+ *
+ * @since 5.1
+ */
+export type WorkflowGenerateResult<TState extends AgentData = AgentData> = {
+  /**
+   * Shared workflow state annotation.
+   *
+   * @since 5.1
+   */
+  workspace: AgentStateAnnotation<TState>;
+  /**
+   * Factory that creates the workflow graph.
+   *
+   * @since 5.1
+   */
+  createGraph: AgentCreateGraph<TState>;
+};
+
+/**
+ * BaseWorkflow is the foundational class for defining workflows. A workflow defines a sequence of
+ * agents that work together to accomplish a task. This class provides the structure and common
+ * building blocks for constructing a workflow, including generating the shared workspace and
+ * creating the graph that defines how agents are connected and executed.
+ *
+ * Specific workflows extend this base class and implement the abstract methods to define
+ * their unique behavior and structure.
+ *
+ * The following workflow types are supported:
+ *
+ * - `SequentialWorkflow` - executes agents in a sequence, where the output of one agent can be passed as input to the next.
+ * - `ConditionalWorkflow` - allows for branching logic based on conditions evaluated at runtime, enabling different paths of execution depending on user input or LLM output.
+ * - `LoopWorkflow` - supports repeating a set of agents until a certain condition is met, useful for iterative processes.
+ * - `ParallelWorkflow` - enables concurrent execution of multiple agents, allowing for tasks that can be performed simultaneously.
+ * - `RouterWorkflow` - dynamically routes execution to different agents based on the input or state, providing flexibility in handling various scenarios.
+ * - `SwitchWorkflow` - similar to RouterWorkflow but designed for cases where there are multiple distinct paths based on discrete values in the input or state.
+ *
+ * @since 5.1
+ */
+export abstract class BaseWorkflow<TState extends AgentData = AgentData> extends Accessor {
+  /**
+   * Builds the workflow-specific edges.
+   *
+   * @param agents
+   */
+  protected abstract buildEdges(agents: BaseAgentLike<TState>[]): GraphEdge<AgentGraphState<TState>>[];
+  /**
+   * Builds the workflow's graph nodes.
+   *
+   * Node ids use the agent id plus its position (`agent.id_index`) instead of only the raw
+   * agent id. That prevents collisions when the same agent instance is used multiple times.
+   *
+   * @param agents
+   */
+  protected buildNodes(agents: BaseAgentLike<TState>[]): GraphNodes<AgentGraphState<TState>>;
+  /**
+   * Generates the workflow's graph and shared workspace based on the defined agents and their schemas. This method is
+   * called by the WorkflowAgent when it generates its graph, and it orchestrates the creation of the workflow's structure,
+   * including validating the agents, deriving shared state from their schemas, and building the nodes and edges of the graph.
+   */
+  generate(): WorkflowGenerateResult<TState>;
+  /** A list of agents that are part of this workflow. */
+  abstract getAgents(): BaseAgentLike<TState>[];
+  /**
+   * Returns the id of the first node in the workflow graph.
+   *
+   * @param agents
+   */
+  protected abstract getEntryNode(agents: BaseAgentLike<TState>[]): string | undefined;
+  /**
+   * Returns whether the agent at this position should expose terminal runtime fields.
+   *
+   * @param agents
+   * @param index
+   */
+  protected abstract isTerminalAgent(agents: BaseAgentLike<TState>[], index: number): boolean;
+  /**
+   * Validates the workflow configuration and throws if invalid.
+   *
+   * @param agents
+   */
+  protected validateAgents(agents: BaseAgentLike<TState>[]): void;
+}