Graph agents

Overview

Build custom graph agents with agent utilities provided by the JS SDK: FunctionAgent, LLMAgent, and WorkflowAgent. These utilities provide higher-level building blocks for defining agent behavior and composing workflows.

Agent classes

Supporting concepts and APIs

Workflows

Workflow classes define the order and conditions under which agents run. A WorkflowAgent wraps a workflow as a single agent that can run on its own or as a step in a larger workflow.

The current workflow API documentation describes these patterns:

• SequentialWorkflow runs agents in a fixed order, passing updated state from one step to the next.
• ConditionalWorkflow evaluates a true/false condition to choose between two branch agents.
• RouterWorkflow runs a routing agent first, then uses its selected route to dispatch to one downstream agent.
• SwitchWorkflow uses a resolver function to select a named branch, with an optional default agent.
• ParallelWorkflow runs independent agent branches from the same input snapshot, then merges their outputs.
• LoopWorkflow runs an inner workflow and repeats it while a continuation condition returns true.

Tools

An LLMAgent receives tools through its tools property. Developers can create custom tools with FunctionTool and configure their inputs, execution logic, and optional middleware.

Use a tool when the model should choose whether to invoke a capability, such as querying a layer or calculating a service area. Use a FunctionAgent when that logic should run as an explicitly scheduled agent step instead. Tools can also be reused with skills-based or compatible bring-your-own agents.

Middleware

Middleware can attach to agents or tools, depending on the utility. For example, human-in-the-loop (HIL/HITL) middleware can pause execution to request approval before proceeding.

Instructions

Set prompt on each LLMAgent to define the model’s instructions for that step. The prompt can include variables populated from graph state, combining behavioral guidance with information needed for the task. Each prompt applies to that LLMAgent, not automatically to other agents in the workflow.

State and runtime context

In a graph-based workflow, state carries the values produced and consumed by its steps—for example, ticket details extracted by one agent and passed to the next. A FunctionAgent receives the current state and optional execution configuration, allowing your code to read those values and return a result for subsequent steps. The state also contains runtime context through agentExecutionContext, including the user’s request, assigned task, conversation history, and shared information from other agents.

State passed between steps within a workflow is distinct from information shared between registered agents in a conversation. Registering agents with the same assistant does not automatically expose their internal workflow state to one another. Information intended for subsequent agents must be explicitly shared. See Shared state and Shared resource.

Schemas

Schemas define the structure of inputs and outputs for agents and tools. In a graph-based workflow, they help define the data passed between agents—for example, ticket details extracted by an LLMAgent and used by a FunctionAgent to save the ticket. You can define schemas directly with Zod or use the agent utility createSchema to create a Zod schema from a supported JSON Schema-style object definition.

Connect to the assistant

Once you have configured an agent, use its registration property to make it available to the arcgis-assistant component. Assign the registration to the agent property of an arcgis-assistant-agent element, then add that element as a child of the assistant. The utility assembles the AgentRegistration from the agent’s configuration.

For a composed workflow, register the WorkflowAgent representing the overall task. Its participating agents remain steps within that workflow; they do not need separate registration unless you also want the assistant to invoke them independently.

Give the registered agent a meaningful name and a description explaining its capabilities and when it should be used. The assistant uses the description to help select the agent for a request. Registration makes the agent available without changing its internal workflow behavior.

To control assistant-level routing, use allowedAgentIds to limit which registered agents are available for automatic selection, or alwaysUseAgentId to route user messages directly to your custom agent without automatic selection. These properties cannot be used together and do not control routing within the agent’s workflow. An explicitly targeted command can override alwaysUseAgentId.

Examples

The maintenance sample illustrates how different agent classes work together in a workflow:

WorkflowAgent wrapping a SequentialWorkflow
  LLMAgent              -> extract ticket details
  FunctionAgent (with HITL middleware) -> request and process approval
  FunctionAgent         -> save the approved ticket

The HITL approval interaction comes from middleware; the FunctionAgent processes the response without an LLM.

The service-area sample uses an LLMAgent with a FunctionTool to calculate service areas; no workflow wrapper is needed.