Directory Read

Overview

Lists the files inside a folder. Useful when the agent needs to discover what's available before reading anything, or scan a whole project for specific filenames.

How it works

Lists the contents of a directory, optionally filtered by a glob pattern ('*.md', '**/*.java'). Setting 'recursive' to true walks the subtree as well. A 'maxResults' cap prevents oversized responses; the default is 500 entries.

Example

When a user asks:

List every Markdown file under the docs folder.

the agent calls the tool:

directory_read(path="docs", pattern="*.md", recursive=true)

and gets back: the list of matching file paths.

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# project-scan.yaml
name: project-scan-crew
process: SEQUENTIAL

agents:
  - id: scout
    role: Project Scout
    goal: Discover files the crew should ingest
    tools:
      - directory_read

tasks:
  - id: project-scan-task
    agent: scout
    description: List every Markdown file under the docs/ directory recursively.

Java

import ai.intelliswarm.swarmai.agent.Agent;
import ai.intelliswarm.swarmai.task.Task;
import ai.intelliswarm.swarmai.swarm.Swarm;
import ai.intelliswarm.swarmai.swarm.SwarmOutput;
import ai.intelliswarm.swarmai.process.ProcessType;
import ai.intelliswarm.swarmai.tool.common.DirectoryReadTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired DirectoryReadTool directoryReadTool;

Agent scout = Agent.builder()
    .role("Project Scout")
    .goal("Discover files the crew should ingest")
    .chatClient(chatClient)
    .tool(directoryReadTool)
    .build();

Task scoutTask = Task.builder()
    .description("List every Markdown file under the docs/ directory recursively.")
    .agent(scout)
    .build();

SwarmOutput result = Swarm.builder()
    .agent(scout)
    .task(scoutTask)
    .process(ProcessType.SEQUENTIAL)
    .build()
    .kickoff();

What it's good for

Real scenarios where agents put this tool to work.

Source

Implementation lives at swarmai-tools/src/main/java/ai/intelliswarm/swarmai/tool/common/DirectoryReadTool.java in the swarm-ai repository.

Open directory_read on GitHub →