Custom agents

Developers can create custom agents to extend the capabilities of the arcgis-assistant component. Custom agents can be designed to handle specific tasks or workflows that are unique to the application’s requirements or an organization’s data. A custom agent could be created to provide specialized data analysis, integrate with external services, or support domain-specific queries.

For example, given a web map with zoning and planning data for a city, you could create an agent that looks up information from documents or an external service that provides additional details about the rules and regulations for a parcel selected by a user.

Get started

To build applications that use custom agents, you must use modern tooling and a package manager like npm or yarn to install the AI components package.

Third party dependencies

Building custom agents requires installing the following third party dependencies:

• LangGraph (v1.1) is used to define the orchestration graph agents and tools, manages global state and LLM calls, and defines multi-step workflows
• LangChainJS (v1.1) manages LLM and embeddings calls
• Zod (v4.3) enforces structured outputs, schemas, and typing

The AI components package directly relies on these dependencies, so they will be automatically installed when you install @arcgis/ai-components.

Install the AI components package

Run the following command to install the package:

  npm install @arcgis/ai-components

  yarn add @arcgis/ai-components @arcgis/core @esri/calcite-components

Afterward, you’ll need to individually import each component you use.

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

Create a custom agent

Custom agents are created by defining an AgentRegistration object. This object includes properties such as id, name, description, createGraph, and workspace. The createGraph property defines the agent’s orchestration graph using LangGraph, while the workspace property defines the agent’s context and relevant variables using an AnnotationRoot type from LangGraph.

The description is important as it helps the orchestrator behind the assistant component determine which agent to use for a given user input. Be sure to write a clear and descriptive description that outlines the intended purpose and capabilities of the agent along with example user prompts that should trigger the agent.

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
  },
};

Once the agent object is defined, it can be registered to the arcgis-assistant component by creating an arcgis-assistant-agent element and setting its agent property to the custom agent object. The arcgis-assistant-agent element should then be appended as a child of the arcgis-assistant component.

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

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

Custom agent examples

See the following samples for examples of how to build custom agents:

• AI Components - custom agent with tools (React) - This sample shows how to create a custom agent that may call tools in behalf of the user. The agent defined in this example includes one tool that calculates a service area from natural language input. Download this code to experiment with adding additional tools to the agent.
• AI Components - custom agent using HIL (React) - This sample shows how to create a custom agent with a human-in-the-loop (HIL) workflow that asks the user for confirmation before creating a maintenance request. Human-in-the-loop provides an interrupt in an agentic workflow that prompts the human/user for additional information prior to proceeding with the workflow. This is often used to safeguard against LLMs making decisions that lead to destructive actions. For example, you may use an interrupt to prompt the user to confirm whether to proceed with given parameters before executing a tool. The LLM may also not have confidence in a user’s intent and could prompt them to provide more information in freeform text. You can also present deterministic options as a menu to the user before proceeding with a workflow.