arcgis-assistant-agent | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/ai-components/components/arcgis-assistant-agent";

Inheritance:: ArcgisAssistantAgent→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 5.0

beta

The Assistant Agent component is a generic wrapper for registering custom agents to the arcgis-assistant component. To define a custom agent, you must be familiar with LangGraph. Custom agents must include a StateGraph that defines the agent's graph and subgraphs.

Building custom agents can only be done using modern JavaScript/TypeScript tooling and cannot be done directly in HTML using CDN imports. Therefore, you must use a package manager like npm or yarn to install the required dependencies. Please refer to the Custom Agents guide for more instructions on how to create a custom agent.

Use the utils module for helper functions and types related to building custom agents, including the AgentRegistration type and functions for making LLM calls, managing agent state, and setting up human-in-the-loop workflows.

We recommend that developers building custom agents have experience working with LLMs and generative AI, and have a good understanding of the limitations of these technologies when building applications for end users.

This is an unrendered component that must be added as a child of the arcgis-assistant component in either HTML or JavaScript.

<arcgis-assistant></arcgis-assistant>

const myCustomAgent = {
  id: "my-custom-agent",
  name: "My Custom Agent",
  description: "An agent that does custom things. Use this agent when users want to do custom things.",
  createGraph: {
   // StateGraph definition using LangGraph
  },
  workspace: {
    // AnnotationRoot definition using LangGraph
    // relevant variables and context required by the agent
  },
};

const assistant = document.querySelector("arcgis-assistant");
const assistantAgent = document.createElement("arcgis-assistant-agent");

assistantAgent.agent = myCustomAgent;
assistant.appendChild(assistantAgent);

See also

Properties

Property	Attribute	Type
`agent`		`AgentRegistration`
`context`		`TContext \| (() => Promise<TContext \| undefined> \| TContext \| undefined) \| undefined`

agent

Property

Type: AgentRegistration

The agent registration object that defines the AI agent's behavior and capabilities. This must include a StateGraph definition (defined using LangGraph).

This is an agent defined in the client and can be invoked by the assistant from the browser to perform specific tasks using functions defined in the client.

See the Custom Agents guide for more instructions and links to samples demonstrating how to create custom agents.

See also

Example

// An example graph that updates a component property and replies with a confirmation message
const myCustomGraph = () => {
  const graph = new StateGraph(myCustomState)
   .addNode("updateComponentProperty", updateComponentProperty)
   .addNode("replyComponentPropertyUpdate", replyComponentPropertyUpdate)
   .addEdge(START, "updateComponentProperty")
   .addEdge("updateComponentProperty", "replyComponentPropertyUpdate")
   .addEdge("replyComponentPropertyUpdate", END);

  return graph;
};

const myCustomAgentState = Annotation.Root({
  // This is required to keep track of chat messages between the user and the agent
  messages: Annotation<ChatHistory>({
    reducer: messagesStateReducer,
    default: () => [],
  }),
  // Accumulates user-visible output across graph nodes
  outputMessage: Annotation<string>({
    reducer: (current = "", update) =>
      typeof update === "string" && update.trim()
        ? current
          ? `${current}\n\n${update}`
          : update
        : current,
    default: () => "",
  }),
  // Result of the UI action performed by the agent
  // This is a custom type defined by the application
  result: Annotation<UIActionResult | null>({
    reducer: (_current, update) => update ?? null,
    default: () => null,
  }),
});

const myCustomAgent = {
  id: "my-custom-agent",
  name: "My Custom Agent",
  description: "An agent that does custom things. Use this agent when users want to do custom things.",
  createGraph: myCustomGraph,
  workspace: myCustomAgentState,
};

const assistant = document.querySelector("arcgis-assistant");
const assistantAgent = document.createElement("arcgis-assistant-agent");

assistantAgent.agent = myCustomAgent;
assistant.appendChild(assistantAgent);

context

Property

Type: TContext | (() => Promise<TContext | undefined> | TContext | undefined) | undefined

If the agent requires context provided by the application or user, it can be provided via this property and accessed in the agent's graph nodes.

Example

assistantAgent.context = {
  myData: {
   // data required for the custom agent
  },
};

Methods

Method	Signature
`componentOnReady` inherited	`componentOnReady(): Promise<this>`

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisAssistantAgent = document.querySelector("arcgis-assistant-agent");
document.body.append(arcgisAssistantAgent);
await arcgisAssistantAgent.componentOnReady();
console.log("arcgis-assistant-agent is ready to go!");