This sample builds a custom SkillAgent that calculates a service area reachable by walking, driving, or trucking. The application combines the custom agent with the SDK’s navigation, data-exploration, and help agents. Use the suggested prompts in the UI to see how the agent calculates and displays service areas.

A skill agent allows you to define agent logic using natural language in a markdown file.

Set up the agent

The custom agent in this sample is called Network Analysis. It is created using the SkillAgent class from the AI components SDK. State the name of the agent, the model to use and provide a description.

const networkAnalysisAgent = new SkillAgent({
  id: "networkAnalysis",
  name: "Network Analysis",
  modelTier: "fast",
  description: "Calculate and display walking, driving, or trucking service areas from shared locations.",
  systemPrompt: "You are an ArcGIS network analysis agent.",
  skillLoaders: [
    // Load the network-analysis skill here
  ],
  toolLoaders: {
    // Load the relevant tools here
  },
});

Write the skill

A skill must include the agent name, description, and the tools it uses to perform specific tasks in its front matter. The file also describes steps the agent should follow to complete its tasks.

The Network Analysis agent in this sample specifies a single skill called network-analysis. You can add more skills to a SkillAgent by including them in the skillLoaders array of the agent. Each skill is progressively loaded and disclosed to the underlying model as needed by the agent. The network-analysis skill lists three tools:

• findServiceAreas - calculates a service area given a point location and parameters as specified by the end user. This is defined in the application.
• addServiceAreaFeatures - adds service area features to the map and zooms to them. This is defined in the application.
• listSharedResources lists all shared resources published by other agents, allowing the network-analysis skill to select the appropriate facility point for the service area calculation. This is provided by the SDK directly.

The full skill file is shown below:

---
name: network-analysis
description: Calculate and display service areas from locations produced by earlier agents.
allowed-tools: listSharedResources findServiceAreas addServiceAreaFeatures
---

# Network Analysis

- Call `listSharedResources` with kinds: ["point"] before calculating a service area.
- Use only points whose descriptions clearly match the user's intended location. Never invent coordinates or IDs.
- If a point is missing or ambiguous, ask the user to navigate to it or clarify the location.
- Use Walking, Driving, or Trucking travel modes as requested. Prefer Time unless distance is explicitly requested.

## Service Areas

- Use `findServiceAreas` for requests about areas reachable within time or distance from or to a location.
- Pass the selected point's exact ID as `sharedResourceId`.
- After calculation succeeds, pass the returned `calculationId` to `addServiceAreaFeatures` to add the polygons and facility to the map.
- Complete both calculation and display steps. Do not claim features were added until `addServiceAreaFeatures` succeeds.

Define custom tools

Use FunctionTool to define custom tools that the agent can call. A function tool must include a name and description so the LLM can know in what scenarios to call the tool. It must also include an inputSchema, which defines the expected input structure, and the parameters for the LLM to provide when calling the tool. And finally, it must include an execute function, which defines the logic to execute.

const findServiceAreas = new FunctionTool({
  name: "findServiceAreas",
  description:
    "Calculates service areas from a point shared resource without changing the map. Returns a calculationId for addServiceAreaFeatures and publishes the resulting polygons as shared resources.",
  inputSchema: await createSchema({
    type: "object",
    properties: {
      // the input schema for the tool used by the LLM to determine the parameter values
    },
    // Lists the properties the LLM must provide when calling this tool
    required: ["sharedResourceId", "driveTimeCutoffs", "travelModeName", "travelDirection"],
  }),
  // include artifacts in the response for further processing in follow up questions
  responseFormat: "content-and-artifact",
  execute: calculateServiceArea,
  resultMode: "continue",
});

Custom tools must be added to the toolLoaders property of the agent.

Note the responseFormat property is set to content-and-artifact. This allows the agent to include both a message and additional artifacts (such as shared resource additions) in its response.

Shared Resources

Once a service area is calculated, the resulting polygons are published as shared resources. The kind and description properties describe the type and purpose of the shared resource so the LLM can determine when to use the resource in future workflows. The payload is used by the agent to access the actual data contained within the shared resource.

return ["Agent message", {
  value: { calculationId },
  sharedResourceAdditions: polygons.map((graphic) => ({
    kind: "polygon",
    description: "Calculated service area",
    payload: graphic.geometry.toJSON(),
  })),
}];

See the Custom agents guide for more information.