▾
Overview
A skills agent uses an agent loop to choose its next action at runtime, guided by the request, available skills, and tool results. You supply task-specific skills, the tools they can use, and guidance for the agent, rather than authoring the sequence of skill and tool calls in advance. SkillAgent, one of the agent utilities provided by the JS SDK, manages the agent loop, while skill instructions and tool availability guide how the agent handles each task.
Agent classes
| Concept / purpose | API reference | When to consider it / example | What the developer configures |
|---|---|---|---|
| Skill-guided execution | SkillAgent | Requests vary and the agent needs to choose actions using task-specific guidance. Example: answer map questions using relevant layer-inspection or analysis skills, rather than a fixed sequence of steps. | An ID, name, description, system prompt, and one or more skill loaders; optionally named tool loaders, a model tier, additional instructions, and a runtime context loader. |
Supporting concepts and APIs
Skills
A skill is Markdown content with a name, description, task instructions, and an optional declaration of allowed tools. Write instructions in the skill’s Markdown to tell the model how to perform that capability—for example, which navigation tool to use, when to use it, or how to handle missing information. Include domain knowledge where useful. A skill is not a separate registered agent.
skillLoaders supply the skill content to the agent. With one skill, its instructions are active from the start. With multiple skills, the agent initially sees their names and descriptions, then can activate a skill using load_skill; only the active skill’s tools are available.
Tools
List the SDK-provided or custom tools a skill can use by name in its Markdown allowed-tools metadata. See the SkillAgent tools reference for available SDK-provided tools and their names.
To build custom tools, use FunctionTool to define their execution logic and optional input/output schemas. Supply each tool through SkillAgent.toolLoaders, using the same tool name listed in the skill. You can also configure a FunctionTool to request user approval, a selection, or additional information before it runs, using SDK-provided human-in-the-loop middleware.
Instructions
Set systemPrompt on your SkillAgent to define its overall role and behavior, regardless of which skill is active. The optional instructions property appends additional guidance to that prompt. The model uses this guidance alongside the active skill’s instructions.
Runtime context
Runtime context supplies information the model needs to interpret a request using the current application state. Set runtimeContextLoader on your SkillAgent to a function that reads relevant application information and returns it as text. SkillAgent calls this function at the start of each run and provides the text to the model as reference data, alongside its instructions.
Application information supplied through runtimeContextLoader is distinct from information shared between agents in a conversation. Agents can build on earlier work through explicitly shared state and resources. Registering agents with the same assistant does not automatically expose their internal state to one another. See Shared state and Shared resource.
Connect to the assistant
Once you have configured a SkillAgent, 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.
Give the 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. Individual skills guide execution within the agent; they are not separately registered with the assistant. Registration makes the agent available without changing its internal skill 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 skill selection within the agent. An explicitly targeted command can override alwaysUseAgentId.
Examples
The following are examples of apps with custom skill agents:
- Custom agent - Define a network-analysis skill and custom tools to calculate and display service areas.
- Custom agent with human-in-the-loop - Collect user input and approval before exporting a map.
- Custom human-in-the-loop form - Let users review and edit AI-generated maintenance reports before submitting them.
- Custom agent with slottable UI - Display interactive directions inside the assistant’s chat.