Filesystem access

Filesystem Tools give agents a dedicated filesystem to save plans and take notes. Agents read, write, search, and manage files with configurable isolation across users and conversations. Use filesystem tools for agents that:

Store and retrieve user-specific data.
Process documents and files.
Maintain conversation-specific context.
Generate reports or code files.

Available Tools

When you add FilesystemTools() to an agent, these tools become available:

Tool	Description
`list_directory`	List files and directories at a path
`read_file`	Read file contents, optionally by line range
`write_file`	Create or overwrite a file
`edit_file`	Replace text in a file using exact string matching
`find_files`	Find files matching a glob pattern
`search_in_files`	Search for a regex pattern in files
`remove_file`	Delete a file
`remove_directory`	Delete a directory

See Available Operations for detailed parameter documentation.

Quick Start

Add filesystem tools to your agent with default (conversation-level) isolation:

images/main/main.py

from autonomy import Agent, FilesystemTools, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="assistant",
    instructions="You are a helpful assistant with file access",
    model=Model("claude-sonnet-4-v1"),
    tools=[FilesystemTools()]  # Default: conversation-level isolation
  )


Node.start(main)

The agent can now use filesystem operations:

curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Create a file called notes.txt with the content: Hello World", "conversation":"chat-1"}' \
  "http://localhost:8000/agents/assistant"

Files isolate per conversation by default:

Conversation chat-1: /tmp/agent-files/assistant/default/chat-1/notes.txt
Conversation chat-2: /tmp/agent-files/assistant/default/chat-2/notes.txt

Visibility Levels

Visibility controls file isolation between users and conversations. Choose the level that matches your security and sharing requirements.

Conversation (Default)

Maximum isolation - Each conversation has its own isolated filesystem:

tools=[FilesystemTools(visibility="conversation")]

Path structure:

/tmp/agent-files/{agent_name}/{scope}/{conversation}/

Example paths:

User Alice, Chat 1: /tmp/agent-files/assistant/user-alice/chat-1/notes.txt
User Alice, Chat 2: /tmp/agent-files/assistant/user-alice/chat-2/notes.txt
User Bob, Chat 1:   /tmp/agent-files/assistant/user-bob/chat-1/notes.txt

Use when:

Users must not see each other’s files
Different conversations must be completely isolated
Maximum security is required
Building chat applications with ephemeral workspaces

Scope

Per-user/tenant isolation - Files shared across conversations for the same user:

tools=[FilesystemTools(visibility="scope")]

Path structure:

/tmp/agent-files/{agent_name}/{scope}/

Example paths:

User Alice, Chat 1: /tmp/agent-files/assistant/user-alice/notes.txt
User Alice, Chat 2: /tmp/agent-files/assistant/user-alice/notes.txt  # Same file!
User Bob, Chat 1:   /tmp/agent-files/assistant/user-bob/notes.txt

Use when:

Users need persistent storage across conversations
Building document management or note-taking apps
Implementing user workspaces
Multi-tenant applications with user isolation

Agent

Per-agent isolation - Files shared across all users but separate per agent:

tools=[FilesystemTools(visibility="agent")]

Path structure:

/tmp/agent-files/{agent_name}/

Example paths:

All users, all conversations: /tmp/agent-files/assistant/notes.txt

Use when:

Agent accesses shared configuration or templates
All users see the same reference files
Building knowledge base or documentation assistants
Single-tenant applications

All

No isolation - Files shared across all agents and users:

tools=[FilesystemTools(visibility="all")]

Path structure:

/tmp/agent-files/

Use when:

Building single-user development tools
Prototyping and testing
Files genuinely need to be shared globally

Available Operations

Filesystem tools provide eight operations for file management:

List Directory

List files and directories:

# Agent can call: list_directory(path=".")
# Returns: List of files and directories with metadata

Read File

Read file contents:

# Agent can call: read_file(path="notes.txt")
# Agent can call: read_file(path="log.txt", start_line=10, end_line=20)
# Returns: File contents as text

Write File

Create or overwrite files:

# Agent can call: write_file(path="report.txt", content="...")
# Creates: report.txt with specified content

Edit File

Modify existing files with search/replace:

# Agent can call: edit_file(
#   path="config.json",
#   old_string="\"debug\": false",
#   new_string="\"debug\": true"
# )

Find Files

Search for files by name pattern:

# Agent can call: find_files(pattern="*.txt")
# Agent can call: find_files(pattern="**/*.md")
# Returns: List of matching file paths

Search in Files

Search file contents with regex:

# Agent can call: search_in_files(pattern="TODO", path=".")
# Agent can call: search_in_files(pattern="def main", path=".", context_lines=2)
# Returns: Files containing the search term with context

Remove File

Delete a file:

# Agent can call: remove_file(path="temp.txt")

Remove Directory

Delete a directory:

# Agent can call: remove_directory(path="temp")
# Agent can call: remove_directory(path="old_project", recursive=True)

Factory Mode vs Direct Mode

Factory Mode (Recommended)

In factory mode, pass FilesystemTools() to the agent. The framework automatically creates the right instance with proper isolation:

```python images/main/main.py
from autonomy import Agent, FilesystemTools, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="assistant",
    instructions="You are a helpful assistant",
    model=Model("claude-sonnet-4-v1"),
    tools=[FilesystemTools(visibility="conversation")]
  )


Node.start(main)

The framework automatically:

Extracts scope and conversation from each request
Creates an isolated FilesystemTools instance for that context
All file operations stay within the visibility boundary

This is the recommended approach for multi-user applications.

Direct Mode

Direct mode specifies the full context upfront:

from autonomy import FilesystemTools, Tool

# Create instance with specific context
fs = FilesystemTools(
  visibility="scope",
  agent_name="assistant",
  scope="user-alice",
  base_dir="/data/files"
)

# Use directly
tools = [
  Tool(fs.read_file),
  Tool(fs.write_file),
  Tool(fs.list_directory)
]

Use direct mode when:

Building single-user applications
Running agents outside the HTTP API
You need explicit control over file paths
Testing and development

Configuration

Custom Base Directory

Change where files are stored:

tools=[FilesystemTools(
  visibility="conversation",
  base_dir="/data/agent-files"  # Custom location
)]

Multiple Filesystem Instances

Provide different filesystem access with different visibility levels:

from autonomy import FilesystemTools

# Shared templates (all users can read)
templates_fs = FilesystemTools(visibility="agent")

# User-specific workspace
workspace_fs = FilesystemTools(visibility="scope")

await Agent.start(
  node=node,
  name="assistant",
  instructions="""
  You access two filesystems:
  - Shared templates in the agent filesystem
  - Your personal workspace in the scope filesystem
  """,
  model=Model("claude-sonnet-4-v1"),
  tools=[templates_fs, workspace_fs]
)

Complete Example

Build a document assistant with user-specific workspaces:

images/main/main.py

from autonomy import Agent, FilesystemTools, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="document_assistant",
    instructions="""
    You are a document assistant that helps users manage their files.
    
    Capabilities:
    - List files in their workspace
    - Read and write documents
    - Search for content across files
    - Organize files into directories
    
    Each user has their own isolated workspace. Files are persistent
    across conversations for the same user.
    """,
    model=Model("claude-sonnet-4-v1"),
    tools=[FilesystemTools(visibility="scope")]
  )


Node.start(main)

images/main/Dockerfile

FROM ghcr.io/build-trust/autonomy-python
COPY . .
ENTRYPOINT ["python", "main.py"]

autonomy.yaml

name: docu
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main

Usage examples:

# User Alice creates a document
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Create a file called project-notes.md with my project ideas", "scope":"user-alice"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/document_assistant"

# Later, in a different conversation, Alice can still access it
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"Read my project-notes.md file", "scope":"user-alice", "conversation":"new-chat"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/document_assistant"

# User Bob has a completely separate workspace
curl --request POST \
  --header "Content-Type: application/json" \
  --data '{"message":"List my files", "scope":"user-bob"}' \
  "https://CLUSTER-ZONE.cluster.autonomy.computer/agents/document_assistant"

GET STARTED

APPLICATIONS

AGENTS

TOOLS

GUIDES

Filesystem access

Available Tools

Quick Start

Visibility Levels

Conversation (Default)

Scope

Agent

All

Available Operations

List Directory

Read File

Write File

Edit File

Find Files

Search in Files

Remove File

Remove Directory

Factory Mode vs Direct Mode

Factory Mode (Recommended)

Direct Mode

Configuration

Custom Base Directory

Multiple Filesystem Instances

Complete Example

GET STARTED

APPLICATIONS

AGENTS

TOOLS

GUIDES

Documentation Index

​Available Tools

​Quick Start

​Visibility Levels

​Conversation (Default)

​Scope

​Agent

​All

​Available Operations

​List Directory

​Read File

​Write File

​Edit File

​Find Files

​Search in Files

​Remove File

​Remove Directory

​Factory Mode vs Direct Mode

​Factory Mode (Recommended)

​Direct Mode

​Configuration

​Custom Base Directory

​Multiple Filesystem Instances

​Complete Example

Available Tools

Quick Start

Visibility Levels

Conversation (Default)

Scope

Agent

All

Available Operations

List Directory

Read File

Write File

Edit File

Find Files

Search in Files

Remove File

Remove Directory

Factory Mode vs Direct Mode

Factory Mode (Recommended)

Direct Mode

Configuration

Custom Base Directory

Multiple Filesystem Instances

Complete Example