@arcgis/ai-components 5.1.0-next.13 → 5.1.0-next.131

package/dist/utils/index.d.ts

@@ -1,101 +1,312 @@
-import type z from "zod";
-import type { ChatHistory } from "@arcgis/ai-orchestrator";
-import type { AIMessage } from "@langchain/core/messages";
+import type MapView from "@arcgis/core/views/MapView.js";
+import type KnowledgeGraph from "@arcgis/core/rest/knowledgeGraph/KnowledgeGraph.js";
+import type LinkChartView from "@arcgis/core/views/LinkChartView.js";
+import type { AIMessage, BaseMessage } from "@langchain/core/messages";
 import type { RunnableConfig } from "@langchain/core/runnables";
 import type { StructuredToolInterface } from "@langchain/core/tools";
+import type { AnnotationRoot, BaseChannel, StateGraph } from "@langchain/langgraph/web";
+import type { ChatOpenAI } from "@langchain/openai";
+import type { ZodType } from "zod";
+import type { AgentRegistration as AgentRegistration2 } from "../orchestrator/registry/agentRegistry.js";
 
-export { type ChatHistory } from "@arcgis/ai-orchestrator";
-export { type CustomConfigurableType } from "@arcgis/ai-orchestrator";
+export { type CustomConfigurableType } from "../orchestrator";
+export { Orchestrator } from "../orchestrator";
+
+/** @internal */
+export type ChatModelTier = "advanced" | "default" | "fast";
+
+/**
+ * Represents the chat message history between the user and the assistant, including all messages sent and received during the conversation.
+ * This structure is used to provide context for the assistant's responses and can be utilized when invoking prompts to ensure the model
+ * has access to the full conversation history.
+ *
+ * @since 5.0
+ */
+export type ChatHistory = BaseMessage[];
 
 /**
  * Represents a user-facing interruption emitted by an agent that requires
- * input before execution can continue.
+ * input before execution can continue. This is used to implement human-in-the-loop workflows where
+ * the agent needs to ask the user for clarification, confirmation, or additional information
+ * before proceeding with its tasks.
  *
  * Used to pause an agent flow and request clarification, confirmation,
  * or additional information from the user.
+ *
+ * @since 5.0
  */
 export interface UiInterrupt {
-  /** Unique identifier for this interrupt instance */
+  /**
+   * Unique identifier for this interrupt instance. This is used to associate the interrupt with a
+   * specific message or action in the agent's workflow, allowing the system to track and manage the
+   * interrupt effectively.
+   */
   id: string;
-  /** Identifier of the agent requesting input (e.g. "navigation", "layerFilter") */
+  /**
+   * Identifier of the agent requesting input (e.g. "navigation", "myCustomAgent", etc.).
+   * This is used to associate the interrupt with the specific agent that emitted it, which
+   * can be helpful for debugging, logging, and providing context to the user about which agent
+   * is requesting input.
+   */
   agentId: string;
-  /** Type of input being requested */
+  /**
+   * The type of input being requested. See the list below for the currently supported input types. This is used
+   * to determine how to render the interrupt in the user interface and what kind of input to expect from the user.
+   *
+   * - `booleanChoice` - Presents the user with a yes or no option. This is typically used for confirmation
+   * prompts where the agent needs to confirm an action with the user before proceeding. For example, some actions
+   * may have a high risk of being destructive, such as applying an edit, submitting a form, or deleting data.
+   * In these cases, the agent might ask for confirmation before proceeding.
+   * - `multipleSelection` - Presents the user with multiple options that the user may choose from in a checkbox
+   * interface.
+   * - `singleSelection` - Presents the user with a list of options in a radio button interface, prompting the user
+   * to select a single option from a list.
+   * - `textInput` - Prompts the user to enter free-form text before proceeding. This is a flexible input
+   * type that can be used for a wide variety of purposes, such as asking the user for more details about
+   * a request, requesting specific information needed to complete a task, or allowing the user to
+   * provide feedback or additional context.
+   */
   kind: "booleanChoice" | "multipleSelection" | "singleSelection" | "textInput";
-  /** Optional message shown to the user */
+  /**
+   * The message shown 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.
+   */
   message?: string;
-  /** Additional data required to render or handle the interrupt */
+  /**
+   * Additional data required to render or handle the interrupt. This is typically an array of strings
+   * representing options for selection when the `kind` is `multipleSelection` or `singleSelection`.
+   * For `booleanChoice`, the options are implicitly "Yes" and "No" and do not need to be provided.
+   * For `textInput`, options are not applicable and should be omitted.
+   */
   metadata?: unknown;
 }
 
+/**
+ * Definition of a client-side agent to register to the [arcgis-assistant-agent](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant-agent/) component.
+ * To construct an agent, you must build a state graph using LangGraph that defines the agent's
+ * nodes, edges, workspace variables, and tools.
+ *
+ * @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/)
+ * @beta
+ * @since 5.0
+ */
+export interface AgentRegistration {
+  /** A unique identifier for the agent. */
+  id: string;
+  /** A human-readable name for the agent. This must be unique, but also be semantically meaningful. */
+  name: string;
+  /**
+   * A brief description of the agent's purpose and functionality. This is required for the agent to be
+   * discoverable in the orchestration of the [arcgis-assistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/). It should provide enough information
+   * for the Assistant component and users to understand when to use this agent and what it can do.
+   * This description should provide examples of user prompts that would indicate this agent should be used.
+   *
+   * @example
+   * ```js
+   * agentRegistration.description = "This agent calculates service areas for a given location.
+   * Use this agent when users ask questions about drive or walk times from a specific location, or when they
+   * ask for areas reachable within a certain time frame from a location.";
+   * ```
+   */
+  description: string;
+  /**
+   * A function that creates and returns the agent's state graph. This graph defines the agent's behavior,
+   * including how it processes inputs, makes decisions, and produces outputs. The graph consists of nodes and edges
+   * that represent the agent's deterministic logic and flow. This is a structure defined using LangGraph's StateGraph.
+   *
+   * @see [LangGraph documentation](https://docs.langchain.com/oss/javascript/langgraph/overview)
+   * @see [StateGraph documentation](https://langchain-ai.github.io/langgraphjs/reference/classes/langgraph.StateGraph.html)
+   * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+   */
+  createGraph: () => StateGraph<unknown>;
+  /**
+   * The workspace variables or context required by the agent's graph. This includes messages, results,
+   * and any other relevant data required by the LLM to make decisions and determine parameters for function calls.
+   * This is a structure defined using LangGraph's AnnotationRoot.
+   *
+   * @see [LangGraph documentation](https://docs.langchain.com/oss/javascript/langgraph/overview)
+   * @see [AnnotationRoot documentation](https://langchain-ai.github.io/langgraphjs/reference/modules/langgraph.Annotation.html)
+   * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+   */
+  workspace: AnnotationRoot<any>;
+}
+
+/**
+ * Options for sending a prompt to an LLM.
+ *
+ * @since 5.0
+ */
 export type ArcgisPromptOptions = {
-  /** The prompt text to send to the model. */
+  /** The input prompt text to send to the model. */
   promptText: string;
-  /** The model tier to use. */
-  modelTier?: "advanced" | "default";
-  /** The temperature to use for the model. */
+  /**
+   * The model tier to use. See the following options:
+   *
+   * - `default` - The default model tier, which provides a balance of performance and cost.
+   *   This is suitable for most general-purpose use cases. At JS SDK v5.0, this model
+   *   tier corresponds to GPT-5 mini model.
+   * - `advanced` - An advanced model tier that may provide improved accuracy or capabilities compared to
+   *   the default tier. However, it may also come with increased cost and slower performance. At
+   *   JS SDK v5.0, this model tier corresponds to GPT-5.2 model.
+   * - `fast` - A lower cost model suitable for tasks like classification and summarization. This tier may have limitations in terms of response length and complexity.
+   *   New at JS SDK v5.1, this model tier corresponds to GPT-5.4-nano model.
+   *
+   * The specific models available in each tier may evolve over time as new models are released and existing
+   * models are retired. The dates models are retired depends on the model provider and therefore may not
+   * align with the semantic versioning rules of the JS SDK. Therefore, the user experience of apps may break
+   * in a minor version update of the JS SDK. It is important to keep your implementation flexible and test your prompts
+   * regularly to ensure they continue to perform as expected, especially when updating the JS SDK version or
+   *  when new models are released.
+   *
+   * Note that the same prompt will not necessarily produce the same results across different
+   * models. As models are updated, you will need to re-evaluate the prompts you send to the LLM, including
+   * agent descriptions and tool node descriptions to
+   * ensure they still return the expected responses. You should adjust your implementation as needed.
+   */
+  modelTier?: ChatModelTier;
+  /**
+   * The temperature to use for the model (a number between 0 and 1). Higher values will result in more
+   * creative and varied responses, while lower values will produce more focused and deterministic responses.
+   */
   temperature?: number;
-  /** The chat history to use for the prompt. */
+  /**
+   * The chat history used to provide context for the prompt. This should include the recent messages
+   * exchanged between the user and the assistant that are necessary for the model to generate an
+   * informed response. Providing chat history can help the model understand the conversation context
+   * and produce more accurate and relevant responses.
+   */
   messages?: ChatHistory;
-  /** Input variables for the prompt. */
+  /** Optional runnable configuration used to derive runtime values (for example, conversation id and abort signal). */
+  config?: RunnableConfig;
+  /**
+   * Input variables for the prompt. This can include any relevant variables related to the context
+   * provided to the agent. This may be necessary for determining tool parameters or for providing additional
+   * context to the model when generating a response.
+   */
   inputVariables?: Record<string, unknown>;
 };
 
+/**
+ * Options when sending a prompt to an LLM that expects a structured response validated against a Zod schema.
+ *
+ * @since 5.0
+ */
 export type ArcgisStructuredPromptOptions<T> = ArcgisPromptOptions
   & {
-  /** A Zod schema that defines the expected structure of the model's response. */
-  schema: z.ZodType<T>;
+  /**
+   * A Zod schema that defines the expected structure of the model's response. For example, if the expected
+   * result from a prompt sent to an LLM is parameters for a tool function that executes specific JS SDK core
+   * API calls, the schema should define the structure of those parameters. This allows the response from the model
+   * to be validated and parsed according to the defined schema, ensuring type safety and consistency.
+   *
+   * @see [Zod documentation](https://zod.dev/api)
+   */
+  schema: ZodType<T>;
 };
 
+/**
+ * Options when sending a prompt to an LLM when the node is expected to invoke tools (e.g. functions defined
+ * in the client). This includes the array of tools that the model can choose to invoke in response to the prompt.
+ *
+ * @since 5.0
+ */
 export type ArcgisToolPromptOptions = ArcgisPromptOptions
   & {
-  /** An array of tools that the model can choose to invoke in response to the prompt. */
+  /**
+   * An array of tools that the model can choose to invoke in response to the prompt.
+   *
+   * @see [StructuredToolInterface documentation](https://reference.langchain.com/javascript/interfaces/_langchain_core.tools.StructuredToolInterface.html)
+   */
   tools: StructuredToolInterface[];
 };
 
+/**
+ * Data structure for trace messages emitted by agents during graph execution.
+ * This is used to send trace messages to the log in the chat interface, allowing users to see the
+ * intermediate steps and thought processes of the agent as it executes its graph.
+ * This log will only be visible if the [ArcGISAssistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#logEnabled) property is set to `true`.
+ *
+ * @since 5.0
+ * @see [ArcGISAssistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#logEnabled)
+ */
 export interface TraceEventData {
-  /** The text content of the trace message. */
+  /**
+   * The text content of the trace message. This should provide information about the agent's current state,
+   * the actions it is taking, the decisions it is making, or any other relevant details that can help users
+   * understand the agent's behavior and thought process.
+   */
   text: string;
-  /** Optional name of the agent associated with this trace message, if applicable. */
+  /**
+   * The name of the agent associated with this trace message. This can help provide
+   * additional context to users about which agent is emitting the trace message, especially in scenarios
+   * where multiple agents are involved in a conversation or workflow.
+   */
   agentName?: string;
-  /** Optional name of the tool associated with this trace message, if applicable. */
+  /**
+   * The name of the tool associated with the trace message. This can help provide
+   * additional context to users about which tool (e.g. function defined in the client) is being invoked or
+   * referenced in the trace message, especially when the agent is using multiple tools in its workflow.
+   */
   toolName?: string;
 }
 
 /**
- * Invokes a prompt and returns a plain text response.
+ * Sends a prompt to an LLM and returns a plain text response. This function should be used when you expect
+ * a simple text response from the model without the need for structured parsing or tool invocation.
  *
- * @param options - Prompt options.
- * @returns The model response as a string
+ * @param options - Options for the prompt, including the prompt text, model tier,
+ *   temperature, chat history, and input variables.
+ * @returns The model response.
+ * @since 5.0
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
  */
 export function invokeTextPrompt(options: ArcgisPromptOptions): Promise<string>;
 
 /**
- * Invokes a prompt and returns a structured response validated against a Zod schema.
+ * Sends a prompt to an LLM and returns a structured response validated against a Zod schema.
  *
  * @param options - Prompt options, including a Zod schema for response validation.
  * @returns The model response parsed into the structure defined by the provided Zod schema.
+ * @see [Zod documentation](https://zod.dev/api)
+ * @since 5.0
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
  */
 export function invokeStructuredPrompt<T>(options: ArcgisStructuredPromptOptions<T>): Promise<T>;
 
 /**
- * Invokes a prompt with tools enabled and returns the model’s tool call response.
+ * Invokes a prompt with tools enabled and returns the model's tool call response.
  *
  * @param options - Prompt options, including an array of tools the model can invoke.
- * @returns The model's response as an AIMessage.
+ * @returns Resolves to the model's response as an AIMessage as defined in LangChain.
+ * @since 5.0
+ * @see [AIMessage documentation](https://reference.langchain.com/javascript/classes/_langchain_core.messages.AIMessage.html)
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
  */
 export function invokeToolPrompt(options: ArcgisToolPromptOptions): Promise<AIMessage>;
 
 /**
- * Dispatches a graph trace message to the browser event bridge.
+ * Dispatches a graph trace message to the log in the chat interface. This allows agents to emit trace
+ * messages during graph execution, providing users with insights into the intermediate steps, decisions,
+ * and actions taken by the agent. These trace messages can help users understand the agent's thought
+ * process and behavior as it executes its graph. It can also be useful for debugging and
+ * transparency purposes.
  *
- * @param data - Trace event data.
- * @param config - Optional runnable configuration.
+ * @param data - Trace event data to display in the chat log, including the message, agent, and tool if applicable.
+ * @param config - Optional runnable configuration
+ *   [as defined in LangChain](https://reference.langchain.com/javascript/interfaces/_langchain_core.runnables.RunnableConfig.html),
+ *   which can include additional context or variables to associate with the trace message.
  * @returns A promise that resolves once the event has been dispatched.
+ * @since 5.0
+ * @see [ArcGISAssistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#logEnabled)
+ * @see [RunnableConfig documentation](https://reference.langchain.com/javascript/interfaces/_langchain_core.runnables.RunnableConfig.html)
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
  */
 export function sendTraceMessage(data: TraceEventData, config?: RunnableConfig): Promise<void>;
 
 /**
- * Generates vector embeddings for a given array of strings.
+ * Generates vector embeddings for an array of strings.
  *
  * @param inputs - An array of text strings to be embedded.
  * @returns A promise that resolves to an array of embedding vectors.
@@ -103,10 +314,230 @@ export function sendTraceMessage(data: TraceEventData, config?: RunnableConfig):
 export function getEmbeddings(inputs: string[]): Promise<number[][]>;
 
 /**
- * Calculates the cosine similarity between two numeric vectors.
+ * Calculates the cosine similarity between two numeric vectors. This is used to measure the similarity
+ * between two embedding vectors, where a score of 1 indicates identical vectors, 0 indicates orthogonal
+ * vectors, and -1 indicates opposite vectors.
  *
  * @param vectorA - The first vector array.
  * @param vectorB - The second vector array.
  * @returns A similarity score from -1 (opposite) to 1 (identical).
  */
-export function cosineSimilarity(vectorA: number[], vectorB: number[]): number;
+export function cosineSimilarity(vectorA: number[], vectorB: number[]): number;
+
+/**
+ * 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>;
+};
+
+/**
+ * Execution status returned by an agent run.
+ *
+ * @since 5.1
+ */
+export type AgentStatus = "failed" | "success" | "unknown";
+
+/**
+ * Summary of a previously executed agent step.
+ *
+ * @since 5.1
+ */
+export interface PriorStep {
+  /** The agent that handled the step. */
+  agentId: string;
+  /** The task assigned to the agent for this step. */
+  assignedTask: string;
+  /** A brief summary of the step's execution. */
+  summary: string;
+  /** The execution status of the step. */
+  status: AgentStatus;
+}
+
+/**
+ * Runtime execution context available to agent graph nodes and tools.
+ *
+ * @since 5.1
+ */
+export interface AgentExecutionContext<TState extends Record<string, unknown> = Record<string, unknown>> {
+  /** The user's original request. */
+  userRequest: string;
+  /** The task assigned to the agent. */
+  assignedTask: string;
+  /** The message history for the run */
+  messages: ChatHistory;
+  /** Previous steps */
+  priorSteps: PriorStep[];
+  /** Shared state available to the agent. */
+  sharedState: SharedState<TState>;
+}
+
+/** @internal */
+export const NavigationAgent: AgentRegistration;
+
+/** @internal */
+export type NavigationContext = {
+  mapView: MapView;
+};
+
+/** @internal */
+export const LayerStylingAgent: AgentRegistration;
+
+/** @internal */
+export type LayerStylingContext = {
+  mapView: MapView;
+};
+
+/** @internal */
+export const DataExplorationAgent: AgentRegistration;
+
+/** @internal */
+export type DataExplorationContext = {
+  mapView: MapView;
+};
+
+/** @internal */
+export const HelpAgent: AgentRegistration;
+
+/** @internal */
+export const ArcgisKnowledgeAgent: AgentRegistration2;
+
+/** @internal */
+export type ArcgisKnowledgeContext = {
+    knowledgeGraph: KnowledgeGraph;
+    view?: never;
+} | {
+    view: LinkChartView | MapView;
+    knowledgeGraph?: never;
+};
+
+/** @internal */
+export const createWebmapEmbeddings: (mapView: MapView) => Promise<{
+    schemaVersion: "0.1";
+    modified: number;
+    embeddings: {
+        modelProvider: "openai";
+        model: string;
+        dimensions: 1536;
+        templates: {
+            layer: string;
+            field: string;
+        };
+    };
+    layers: Array<{
+        id: string;
+        name: string;
+        title: string;
+        description: string;
+        vector: Array<number>;
+        fields: Array<{
+            name: string;
+            alias: string;
+            description: string;
+            vector: Array<number>;
+        }>;
+    }>;
+}>;
+
+/** @internal */
+export type GetContext<TContext extends Record<string, unknown>> = () => Promise<TContext> | TContext;
+
+/** @internal */
+export interface AgentWithContext<TContext extends Record<string, unknown> = Record<string, unknown>> {
+  agent: AgentRegistration;
+  /**
+   * Lazily resolves runtime context.
+   * Can be sync or async, and may perform lifecycle checks (e.g. await view.when()).
+   */
+  getContext?: GetContext<TContext>;
+}
+
+/** @internal */
+export type AgentExecutionContextWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>> = AgentExecutionContext<TState>;
+
+/** @internal */
+export type StatelessAgentBaseState<TState extends Record<string, unknown> = Record<string, unknown>> = {
+  agentExecutionContext: BaseChannel<AgentExecutionContextWithSharedState<TState>, unknown, unknown>;
+  outputMessage: BaseChannel<string, unknown, unknown>;
+  summary: BaseChannel<string, unknown, unknown>;
+  status: BaseChannel<AgentStatus | undefined, unknown, unknown>;
+};
+
+/** @internal */
+export type StatefulAgentBaseState<TState extends Record<string, unknown> = Record<string, unknown>> = StatelessAgentBaseState<TState>
+  & {
+  sharedStatePatch: BaseChannel<SharedStatePatch<TState> | undefined, unknown, unknown>;
+};
+
+/**
+ * Creates the standard runtime state for a custom agent graph.
+ * Includes common fields used by the assistant flow (request context, output message, summary, and status), so you only add your agent-specific state.
+ *
+ * @since 5.1
+ */
+export function createAgentRuntimeState<TState extends Record<string, unknown> = Record<string, unknown>>(): StatelessAgentBaseState<TState>;
+
+/**
+ * Creates the standard runtime state for a custom agent graph, plus support for shared state updates.
+ * Use this when your agent needs to write values that other agents can read later in the same orchestration flow.
+ *
+ * @since 5.1
+ */
+export function createAgentRuntimeStateWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>>(): StatefulAgentBaseState<TState>;
+
+/**
+ * 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>;
+
+/** @internal */
+export type SharedStateEntry<T = unknown> = {
+  value: T;
+  meta: {
+      updatedByAgentId: string;
+      updatedAt: number;
+  };
+};
+
+/** @internal */
+export type SharedStatePatchEntry<T = unknown> = {
+  value: T;
+};
+
+/**
+ * Shared state that can be read and updated during agent execution.
+ *
+ * @since 5.1
+ */
+export type SharedState<T extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof T]?: SharedStateEntry<T[K]>;
+};
+
+/**
+ * Partial shared state returned by an agent for merging into the current run state.
+ *
+ * @since 5.1
+ */
+export type SharedStatePatch<T extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof T]?: SharedStatePatchEntry<T[K]>;
+};
+
+/**
+ * @param parameter0
+ * @internal
+ */
+export function createChatModel(parameter0?: {
+    modelTier?: ChatModelTier;
+    temperature?: number;
+    config?: RunnableConfig;
+}): Promise<ChatOpenAI>;