types | References | ArcGIS Maps SDK for JavaScript

Types

import type { ChatHistory, AgentRegistration, VectorSearchFieldResults, DirectRoutingOptions, AutoRoutingOptions } from "@arcgis/ai-components/orchestrator/types.js";

Type definitions

ChatHistory

Type definition

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.

Type: BaseMessage[]

AgentRegistration

Type definition

beta

The registration object you create and provide to the arcgis-assistant-agent component when building a custom agent directly with LangGraph. Agent class instances created using agent-utils can be directly provided to the arcgis-assistant-agent component.

id

Property

Type: string

A unique identifier for the agent.

name

Property

Type: string

A human-readable name that describes the agent's purpose.

description

Property

Type: string

A description of what the agent does and when the assistant should invoke it. Include examples of user requests the agent can handle to help the assistant select it.

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 LangGraph state graph, which defines its execution flow.

See also

StateGraph documentation

workspace

Property

Type: AnnotationRoot<any>

The LangGraph annotation that defines the state fields available to the agent's graph.

See also

AnnotationRoot documentation

VectorSearchFieldResults

Type definition

Type: FieldVectors[]

DirectRoutingOptions

Type definition

Options for executing a registered agent directly.

routing

Property

Type: "direct"

Execute a registered agent directly without calling the intent LLM.

agentId

Property

Type: string

ID of the registered agent that will execute the request.

locale

Property

Type: string | undefined

Locale used for localized agent responses.

AutoRoutingOptions

Type definition

Options for routing a request through the intent LLM.

routing

Property

Type: "auto" | undefined

Route the request through the intent LLM.

agentIds

Property

Type: readonly string[] | undefined

Optional subset of registered agents available to the intent LLM.

locale

Property

Type: string | undefined

Locale used for localized agent responses.

AskOptions

Type definition

Agent selection and routing behavior for an orchestrator run.

Type: AutoRoutingOptions | DirectRoutingOptions

CustomConfigurableType

Type definition

Object used for getting and managing the context provided to an agent via its context property. This is used to access application state context, such as the map view or other relevant variables, that an agent may require to perform its tasks.

Supertypes: Record<string‚ unknown>

thread_id

Property

Type: string

locale

Property

Type: string

Locale used for localized agent responses.

hitlResponse

Property

Type: HITLResponse | null

Latest HITL response injected by the host application, or null before a response.

hitlResponses

Property

Type: readonly HITLResponse[] | undefined

HITL responses for the current request in submission order, including the latest response.

agentId

Property

Type: string | undefined

context

Property

Type: unknown | undefined

QueryEmbeddingCache

Type definition

Cache for query embeddings to avoid duplicate API calls within a request

Supertypes: Map<string‚ number[]>

AgentExecutionContext

Type definition

Type parameters: <TState extends SharedState = SharedState>

Since: ArcGIS Maps SDK for JavaScript 5.1

Runtime execution context available to agent graph nodes and tools.

Supertypes: Readonly<AgentExecutionContextShape>

PriorStep

Type definition

Summary of a previously executed agent step.

agentId

Property

Type: string

The agent that handled the step.

assignedTask

Property

Type: string

The task assigned to the agent for this step.

summary

Property

Type: string

A brief summary of the step's execution.

status

Property

Type: AgentStatus

The execution status of the step.

AgentStatus

Type definition

Execution status returned by an agent run.

Type: "failed" | "success" | "unknown"

UiInterrupt

Type definition

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.

showOtherOption

Property

Type: boolean | undefined

Shows the built-in Other option for singleSelection and multipleSelection prompts. Defaults to false. When false, the built-in option is not rendered. Explicit options named Other remain available.

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.