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.

Custom agents can be created using one of the following methods:

  • Agent utilities - Create skill agents and graph agents using agent utilities provided by the JS SDK, such as SkillAgent and WorkflowAgent, with consistent patterns and less boilerplate.
  • LangGraph - Bring an existing LangGraph agent or define its orchestration and state directly using the framework.

Agent utilities

The agent utilities provide reusable building blocks for creating skill agents and graph agents. Skill agents choose their next action at runtime using the request, available skills, and tool results, while graph agents follow an execution structure you define. Choose the approach that fits your workflow, and add tools, middleware, or human-in-the-loop behavior as needed, where supported. Human-in-the-loop behavior lets an agent pause to request approval, ask the user to choose from available options, or collect additional information before continuing.

Skills agents

Use SkillAgent when requests vary and the agent needs to choose its next action as the task unfolds. You provide task-specific skills, tools, and guidance. The agent selects relevant skills and uses their tools according to the user’s request and the information it discovers.

A skill packages task-specific instructions, domain knowledge, and declarations of the tools the agent may use; it is not a separate agent.

For example, an agent could answer different questions about a map by selecting the appropriate skills to find features, analyze spatial relationships, or summarize results.

See Skills agents for the building blocks and configuration options.

Graph agents

Use graph agents when you want to define the available steps and how they connect. The agent utilities provide reusable building blocks: FunctionAgent for developer-defined logic, LLMAgent for model reasoning and tool use, and WorkflowAgent to compose agents into a workflow. Models, tools, and conditions can influence what happens at runtime within the structure you define.

For example, a workflow could validate a user’s request, run a spatial analysis, then summarize the results, with conditions determining whether to proceed or ask the user for more information.

See Graph agents for the building blocks and configuration options.

LangGraph

Use LangGraph to bring an existing agent or define its orchestration and state directly, rather than using the higher-level building blocks provided by agent utilities.

Dependencies

Building custom agents with LangGraph uses the following third-party dependencies:

  • LangGraph (v1.4) for orchestration and workflow state.
  • LangChainJS (v1.5) for LLM and embedding calls.
  • Zod (v4) for schema definition and validation.

Install LangChainJS and LangGraph explicitly in your application. Do not rely on dependencies installed through @arcgis/ai-components.

Examples

The following samples demonstrate custom agents built with LangGraph:

Agent anatomy

Skill agents and graph agents differ in how they organize execution. Agents can use developer-defined logic, model reasoning, or a combination of both to carry out tasks.

In the context of the JavaScript Maps SDK, an agent’s core logic is defined within the browser, though it may call an LLM or other services to determine intent, define parameters, and summarize information.

The following diagram illustrates the main elements an agent can use to process a request and produce a response.

Agent anatomy

  • System prompt: Instructions that guide the agent’s behavior and responses.
  • Context: Information provided to the agent to help it interpret a request and carry out a task. This might include information about web map layers, selected features, or the current map extent, or information from a knowledge graph.
  • Tools: SDK-provided or custom functions the agent can execute to retrieve information or perform work, such as querying a layer, zooming to a location, or calling an external service.
  • Output: Results produced by the agent, such as a text response or structured data. These results can support subsequent workflow steps or a final response to the user.

See Key terms for definitions of agents, workflows, skills, and supporting concepts.