index | References | ArcGIS Maps SDK for JavaScript

ESM

import { invokeTextPrompt, invokeStructuredPrompt, invokeToolPrompt, sendTraceMessage, getEmbeddings } from "@arcgis/ai-components/utils/index.js";

Type definitions

UiInterrupt

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

Represents a user-facing interruption emitted by an agent that requires 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.

id

Property

Type: string

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.

agentId

Property

Type: string

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.

kind

Property

Type: "booleanChoice" | "multipleSelection" | "singleSelection" | "textInput"

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.

message

Property

Type: string | undefined

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.

metadata

Property

Type: unknown | undefined

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.

AgentRegistration

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

beta

Definition of a client-side agent to register to the 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 also

id

Property

Type: string

A unique identifier for the agent.

name

Property

Type: string

A human-readable name for the agent. This must be unique, but also be semantically meaningful.

description

Property

Type: 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. 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

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.";

createGraph

Property

Type: () => StateGraph<unknown>

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 also

workspace

Property

Type: AnnotationRoot<any>

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 also

ArcgisPromptOptions

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

Options for sending a prompt to an LLM.

promptText

Property

Type: string

The input prompt text to send to the model.

modelTier

Property

Type: "advanced" | "default" | undefined

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.

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.

temperature

Property

Type: number | undefined

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.

messages

Property

Type: ChatHistory | undefined

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.

inputVariables

Property

Type: Record<string, unknown> | undefined

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.

ArcgisStructuredPromptOptions

Type definition

Type parameters: <T>

Since: ArcGIS Maps SDK for JavaScript 5.0

Options when sending a prompt to an LLM that expects a structured response validated against a Zod schema.

Supertypes: ArcgisPromptOptions

schema

Property

Type: z.ZodType

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 also

Zod documentation

ArcgisToolPromptOptions

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

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.

Supertypes: ArcgisPromptOptions

tools

Property

Type: StructuredToolInterface[]

An array of tools that the model can choose to invoke in response to the prompt.

See also

StructuredToolInterface documentation

TraceEventData

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

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 property is set to true.

See also

ArcGISAssistant

text

Property

Type: string

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.

agentName

Property

Type: string | undefined

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.

toolName

Property

Type: string | undefined

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.

Functions

Name	Return Type	Object
`UiInterrupt`
`AgentRegistration`
`ArcgisPromptOptions`
`ArcgisStructuredPromptOptions`
`ArcgisToolPromptOptions`
`TraceEventData`
`invokeTextPrompt`	`Promise<string>`
`invokeStructuredPrompt`	`Promise`
`invokeToolPrompt`	`Promise`
`sendTraceMessage`	`Promise<void>`
`getEmbeddings`	`Promise<number[][]>`
`cosineSimilarity`	`number`

invokeTextPrompt

Function

Since: ArcGIS Maps SDK for JavaScript 5.0

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.

See also

Custom agents guide

Signature: invokeTextPrompt (options: ArcgisPromptOptions): Promise<string>

Parameters

Parameter	Type	Description	Required
options	`ArcgisPromptOptions`	Options for the prompt, including the prompt text, model tier, temperature, chat history, and input variables.

Returns: Promise<string>
The model response.

invokeStructuredPrompt

Function

Type parameters: <T>

Since: ArcGIS Maps SDK for JavaScript 5.0

Sends a prompt to an LLM and returns a structured response validated against a Zod schema.

See also

Signature: invokeStructuredPrompt <T>(options: ArcgisStructuredPromptOptions<T>): Promise<T>

Parameters

Parameter	Type	Description	Required
options	`ArcgisStructuredPromptOptions`	Prompt options, including a Zod schema for response validation.

Returns: Promise
The model response parsed into the structure defined by the provided Zod schema.

invokeToolPrompt

Function

Since: ArcGIS Maps SDK for JavaScript 5.0

Invokes a prompt with tools enabled and returns the model's tool call response.

See also

Signature: invokeToolPrompt (options: ArcgisToolPromptOptions): Promise<AIMessage>

Parameters

Parameter	Type	Description	Required
options	`ArcgisToolPromptOptions`	Prompt options, including an array of tools the model can invoke.

Returns: Promise
Resolves to the model's response as an AIMessage as defined in LangChain.

sendTraceMessage

Function

Since: ArcGIS Maps SDK for JavaScript 5.0

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.

See also

Signature: sendTraceMessage (data: TraceEventData, config?: RunnableConfig): Promise<void>

Parameters

Parameter	Type	Description	Required
data	`TraceEventData`	Trace event data to display in the chat log, including the message, agent, and tool if applicable.
config	`RunnableConfig`	Optional runnable configuration as defined in LangChain, which can include additional context or variables to associate with the trace message.

Returns: Promise<void>
A promise that resolves once the event has been dispatched.

getEmbeddings

Function

Generates vector embeddings for an array of strings.

Signature: getEmbeddings (inputs: string[]): Promise<number[][]>

Parameters

Parameter	Type	Description	Required
inputs	`string[]`	An array of text strings to be embedded.

Returns: Promise<number[][]>
A promise that resolves to an array of embedding vectors.

cosineSimilarity

Function

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.

Signature: cosineSimilarity (vectorA: number[], vectorB: number[]): number

Parameters

Parameter	Type	Description	Required
vectorA	`number[]`	The first vector array.
vectorB	`number[]`	The second vector array.

Returns: number
A similarity score from -1 (opposite) to 1 (identical).