@arcgis/ai-components 5.2.0-next.99 → 6.0.0-next.1

package/dist/utils/index.d.ts

@@ -7,10 +7,11 @@ 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/types.js";
 
-export { type CustomConfigurableType } from "../orchestrator.js";
-export { Orchestrator } from "../orchestrator.js";
-export { type AskOptions } from "../orchestrator.js";
+export { type CustomConfigurableType } from "../orchestrator/types.js";
+export { Orchestrator } from "../orchestrator/orchestrator/orchestrator.js";
+export { type AskOptions } from "../orchestrator/types.js";
 
 /** @internal */
 export type ChatModelTier = "advanced" | "default" | "fast";
@@ -20,7 +21,8 @@ export type ChatModelTier = "advanced" | "default" | "fast";
  * 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
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  */
 export type ChatHistory = BaseMessage[];
 
@@ -33,13 +35,16 @@ export type ChatHistory = BaseMessage[];
  * Used to pause an agent flow and request clarification, confirmation,
  * or additional information from the user.
  *
- * @since 5.0
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  */
 export interface UiInterrupt {
   /**
    * 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.
+   *
+   * @internal
    */
   id: string;
   /**
@@ -47,6 +52,8 @@ export interface UiInterrupt {
    * 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.
+   *
+   * @internal
    */
   agentId: string;
   /**
@@ -65,12 +72,16 @@ export interface UiInterrupt {
    * 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.
+   *
+   * @internal
    */
   kind: "booleanChoice" | "multipleSelection" | "singleSelection" | "textInput";
   /**
    * 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.
+   *
+   * @internal
    */
   message?: string;
   /**
@@ -78,6 +89,8 @@ export interface UiInterrupt {
    * 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.
+   *
+   * @internal
    */
   metadata?: unknown;
 }
@@ -87,15 +100,23 @@ export interface UiInterrupt {
  * To construct an agent, you must build a state graph using LangGraph that defines the agent's
  * nodes, edges, workspace variables, and tools.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @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
+ * @internal
  */
 export interface AgentRegistration {
-  /** A unique identifier for the agent. */
+  /**
+   * A unique identifier for the agent.
+   *
+   * @internal
+   */
   id: string;
-  /** A human-readable name for the agent. This must be unique, but also be semantically meaningful. */
+  /**
+   * A human-readable name for the agent. This must be unique, but also be semantically meaningful.
+   *
+   * @internal
+   */
   name: string;
   /**
    * A brief description of the agent's purpose and functionality. This is required for the agent to be
@@ -103,6 +124,7 @@ export interface AgentRegistration {
    * 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.
    *
+   * @internal
    * @example
    * ```js
    * agentRegistration.description = "This agent calculates service areas for a given location.
@@ -116,6 +138,7 @@ export interface AgentRegistration {
    * 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.
    *
+   * @internal
    * @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/)
@@ -126,6 +149,7 @@ export interface AgentRegistration {
    * 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.
    *
+   * @internal
    * @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/)
@@ -136,33 +160,41 @@ export interface AgentRegistration {
 /**
  * Options for sending a prompt to an LLM.
  *
- * @since 5.0
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  */
 export type ArcgisPromptOptions = {
-  /** The input prompt text to send to the model. */
+  /**
+   * The input prompt text to send to the model.
+   *
+   * @internal
+   */
   promptText: string;
   /**
    * The model tier to use. See the following options:
    *
    * - `default` - The default model tier, suitable for most general-purpose use cases.
-   *   At v5.2, this tier uses the `gpt-5.6-terra` model.
+   *   At v5.2, this tier uses the `gpt-6-sol` model.
    * - `advanced` - A model tier for tasks that benefit from more advanced capabilities.
-   *   At v5.2, this tier uses the `gpt-5.6-sol` model.
+   *   At v5.2, this tier uses the `gpt-6-astra` model.
    * - `fast` - A model tier for tasks such as classification and summarization, where
    *   faster responses are preferred.
-   *   At v5.2, this tier uses the `gpt-5.6-luna` model.
+   *   At v5.2, this tier uses the `gpt-6-luna` model.
    *
    * The models available for each tier may change as models are released and retired by
    * the model provider and may not align with the semantic versioning rules of the JS SDK.
    * The same prompt may produce different results when a tier's model changes.
    * Re-evaluate and adjust prompts, agent descriptions, and tool descriptions
    * when updating the ArcGIS Maps SDK for JavaScript or when model updates occur.
+   *
+   * @internal
    */
   modelTier?: ChatModelTier;
   /**
    * This option is ignored. The model provider's default temperature is always used.
    *
    * @deprecated This option is no longer supported and will be removed in a future release.
+   * @internal
    */
   temperature?: number;
   /**
@@ -170,6 +202,8 @@ export type ArcgisPromptOptions = {
    * 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.
+   *
+   * @internal
    */
   messages?: ChatHistory;
   /** Optional runnable configuration used to derive runtime values (for example, conversation id and abort signal). */
@@ -178,6 +212,8 @@ export type ArcgisPromptOptions = {
    * 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.
+   *
+   * @internal
    */
   inputVariables?: Record<string, unknown>;
 };
@@ -185,6 +221,8 @@ export type ArcgisPromptOptions = {
 /**
  * Options when sending a prompt to an LLM that expects a structured response validated against a Zod schema.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.0
  */
 export type ArcgisStructuredPromptOptions<T> = ArcgisPromptOptions
@@ -195,6 +233,7 @@ export type ArcgisStructuredPromptOptions<T> = ArcgisPromptOptions
    * 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.
    *
+   * @internal
    * @see [Zod documentation](https://zod.dev/api)
    */
   schema: ZodType<T>;
@@ -204,13 +243,15 @@ export type ArcgisStructuredPromptOptions<T> = ArcgisPromptOptions
  * 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
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  */
 export type ArcgisToolPromptOptions = ArcgisPromptOptions
   & {
   /**
    * An array of tools that the model can choose to invoke in response to the prompt.
    *
+   * @internal
    * @see [StructuredToolInterface documentation](https://reference.langchain.com/javascript/interfaces/_langchain_core.tools.StructuredToolInterface.html)
    */
   tools: StructuredToolInterface[];
@@ -222,7 +263,8 @@ export type ArcgisToolPromptOptions = ArcgisPromptOptions
  * 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
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @see [ArcGISAssistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#logEnabled)
  */
 export interface TraceEventData {
@@ -230,18 +272,24 @@ export interface TraceEventData {
    * 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.
+   *
+   * @internal
    */
   text: string;
   /**
    * 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.
+   *
+   * @internal
    */
   agentName?: string;
   /**
    * 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.
+   *
+   * @internal
    */
   toolName?: string;
 }
@@ -250,9 +298,10 @@ export interface TraceEventData {
  * 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.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @param options - Options for the prompt, including the prompt text, model tier, chat history, and input variables.
  * @returns The model response.
- * @since 5.0
+ * @internal
  * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
  */
 export function invokeTextPrompt(options: ArcgisPromptOptions): Promise<string>;
@@ -260,10 +309,11 @@ export function invokeTextPrompt(options: ArcgisPromptOptions): Promise<string>;
 /**
  * Sends a prompt to an LLM and returns a structured response validated against a Zod schema.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @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.
+ * @internal
  * @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>;
@@ -271,9 +321,10 @@ export function invokeStructuredPrompt<T>(options: ArcgisStructuredPromptOptions
 /**
  * Invokes a prompt with tools enabled and returns the model's tool call response.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @param options - Prompt options, including an array of tools the model can invoke.
  * @returns Resolves to the model's response as an AIMessage as defined in LangChain.
- * @since 5.0
+ * @internal
  * @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/)
  */
@@ -286,12 +337,13 @@ export function invokeToolPrompt(options: ArcgisToolPromptOptions): Promise<AIMe
  * process and behavior as it executes its graph. It can also be useful for debugging and
  * transparency purposes.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @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
+ * @internal
  * @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/)
@@ -301,8 +353,10 @@ export function sendTraceMessage(data: TraceEventData, config?: RunnableConfig):
 /**
  * Generates vector embeddings for an array of strings.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @param inputs - An array of text strings to be embedded.
  * @returns A promise that resolves to an array of embedding vectors.
+ * @internal
  */
 export function getEmbeddings(inputs: string[]): Promise<number[][]>;
 
@@ -311,16 +365,19 @@ export function getEmbeddings(inputs: string[]): Promise<number[][]>;
  * between two embedding vectors, where a score of 1 indicates identical vectors, 0 indicates orthogonal
  * vectors, and -1 indicates opposite vectors.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @param vectorA - The first vector array.
  * @param vectorB - The second vector array.
  * @returns A similarity score from -1 (opposite) to 1 (identical).
+ * @internal
  */
 export function cosineSimilarity(vectorA: number[], vectorB: number[]): number;
 
 /**
  * The suggestions emitted by the agent to the user interface.
  *
- * @since 5.1
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  */
 export type UXSuggestion = {
   /** The type of suggestion being made. */
@@ -332,6 +389,8 @@ export type UXSuggestion = {
 /**
  * Execution status returned by an agent run.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.1
  */
 export type AgentStatus = "failed" | "success" | "unknown";
@@ -339,6 +398,8 @@ export type AgentStatus = "failed" | "success" | "unknown";
 /**
  * Summary of a previously executed agent step.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.1
  */
 export interface PriorStep {
@@ -355,6 +416,8 @@ export interface PriorStep {
 /**
  * Runtime execution context available to agent graph nodes and tools.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.1
  */
 export interface AgentExecutionContext<TState extends Record<string, unknown> = Record<string, unknown>> {
@@ -372,37 +435,82 @@ export interface AgentExecutionContext<TState extends Record<string, unknown> =
   sharedResources: readonly SharedResource[];
 }
 
-/** @internal */
-export const NavigationAgent: AgentRegistration;
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const NavigationAgent: AgentRegistration2;
 
-/** @internal */
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const NavigationGraphAgent: AgentRegistration2;
+
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
 export type NavigationContext = {
   mapView: MapView;
 };
 
-/** @internal */
-export const LayerStylingAgent: AgentRegistration;
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const LayerStylingAgent: AgentRegistration2;
 
-/** @internal */
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
 export type LayerStylingContext = {
   mapView: MapView;
 };
 
-/** @internal */
-export const DataExplorationAgent: AgentRegistration;
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const DataExplorationAgent: AgentRegistration2;
 
-/** @internal */
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const DataExplorationGraphAgent: AgentRegistration2;
+
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
 export type DataExplorationContext = {
   mapView: MapView;
 };
 
-/** @internal */
-export const HelpAgent: AgentRegistration;
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const HelpAgent: AgentRegistration2;
 
-/** @internal */
-export const ArcgisKnowledgeAgent: AgentRegistration;
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const HelpGraphAgent: AgentRegistration2;
 
-/** @internal */
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
+export const ArcgisKnowledgeAgent: AgentRegistration2;
+
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
 export type ArcgisKnowledgeContext = {
     knowledgeGraph: KnowledgeGraph;
     view?: never;
@@ -411,7 +519,10 @@ export type ArcgisKnowledgeContext = {
     knowledgeGraph?: never;
 };
 
-/** @internal */
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
 export const createWebmapEmbeddings: (mapView: MapView) => Promise<{
     schemaVersion: "0.1";
     modified: number;
@@ -442,7 +553,10 @@ export const createWebmapEmbeddings: (mapView: MapView) => Promise<{
 /** @internal */
 export type GetContext<TContext extends Record<string, unknown>> = () => Promise<TContext> | TContext;
 
-/** @internal */
+/**
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
+ */
 export interface AgentWithContext<TContext extends Record<string, unknown> = Record<string, unknown>> {
   agent: AgentRegistration;
   /**
@@ -469,6 +583,8 @@ export type AgentBaseState<TState extends Record<string, unknown> = Record<strin
  * Creates the standard runtime state for a custom agent graph.
  * Includes common fields used by the assistant flow and channels for shared state and shared resource updates, so you only add your agent-specific state.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.1
  */
 export function createAgentRuntimeState<TState extends Record<string, unknown> = Record<string, unknown>>(): AgentBaseState<TState>;
@@ -477,6 +593,7 @@ export function createAgentRuntimeState<TState extends Record<string, unknown> =
  * Use `createAgentRuntimeState` instead.
  *
  * @deprecated Use `createAgentRuntimeState` instead.
+ * @internal
  * @since 5.1
  */
 export function createAgentRuntimeStateWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>>(): AgentBaseState<TState>;
@@ -485,8 +602,10 @@ export function createAgentRuntimeStateWithSharedState<TState extends Record<str
  * 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.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @param suggestion
  * @param config
+ * @internal
  * @since 5.1
  */
 export function sendUXSuggestion(suggestion: UXSuggestion, config?: RunnableConfig): Promise<void>;
@@ -508,6 +627,8 @@ export type SharedStatePatchEntry<T = unknown> = {
 /**
  * Shared state that can be read and updated during agent execution.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.1
  */
 export type SharedState<T extends Record<string, unknown> = Record<string, unknown>> = {
@@ -517,6 +638,8 @@ export type SharedState<T extends Record<string, unknown> = Record<string, unkno
 /**
  * Partial shared state returned by an agent for merging into the current run state.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.1
  */
 export type SharedStatePatch<T extends Record<string, unknown> = Record<string, unknown>> = {
@@ -526,6 +649,8 @@ export type SharedStatePatch<T extends Record<string, unknown> = Record<string,
 /**
  * Kinds of resources an agent can share with subsequent agents.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
+ * @internal
  * @since 5.2
  */
 export type SharedResourceKind = "custom" | "extent" | "point" | "polygon" | "polyline";
@@ -533,7 +658,9 @@ export type SharedResourceKind = "custom" | "extent" | "point" | "polygon" | "po
 /**
  * Resource available to agents during a conversation.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @remarks Descriptions are limited to 256 characters. Payloads must be compatible with the structured clone algorithm.
+ * @internal
  * @since 5.2
  */
 export type SharedResource = Readonly<{
@@ -550,7 +677,9 @@ export type SharedResource = Readonly<{
 /**
  * Resource supplied by an agent before the orchestrator adds identity and metadata.
  *
+ * @deprecated Use the corresponding export from its owning module instead.
  * @remarks Description values longer than 256 characters are truncated. Payloads are cloned using the structured clone algorithm.
+ * @internal
  * @since 5.2
  */
 export type SharedResourceInput = Readonly<{
@@ -560,6 +689,7 @@ export type SharedResourceInput = Readonly<{
 }>;
 
 /**
+ * @deprecated Use the corresponding export from its owning module instead.
  * @param parameter0
  * @internal
  */