File System Tools

AG-Kit’s file system tools provide a comprehensive and reliable way for your agents to interact with files. With support for transactions, different backends, and a unified toolkit, it’s designed for building robust agents that perform file-based tasks.

​

What You Can Do

Use this toolkit to give your agent the ability to:

• Perform Atomic Operations: Safely modify multiple files at once with automatic rollback on failure.
• Manage Files & Directories: Create, read, update, delete, and list files and directories.
• Search the Filesystem: Find files by name (glob) or content (grep).
• Run in Secure Environments: Choose between local, in-memory, and sandboxed backends to match your security needs.

​

Core Concepts

1. FilesystemToolkit: This is the main entry point. It bundles a collection of file-related tools (read_file, write_file, etc.) that are ready to be used by an agent.
2. FileOperator (Backend): This is the engine that performs the actual file operations. You can choose from three backends:
   • LocalFileOperator: For high-performance access to the local filesystem.
   • InMemoryFileOperator: For fast, isolated testing in a virtual filesystem.
   • SandboxFileOperator: For secure execution in an isolated container, ideal for handling untrusted code.

​

Quick Start

​

Key Feature: Atomic Transactions

For complex tasks like code generation, you often need to modify multiple files. If one step fails, you risk leaving the project in a broken state. Transactions solve this by ensuring that all file operations succeed or none of them do. If any operation inside withTransaction fails, all changes are automatically rolled back. For more advanced transaction control, see the API Reference.

​

Core Operations

Here are the most common operations you can perform with the toolkit.

​

Writing and Creating Files

The write_file tool creates a new file or overwrites an existing one. It automatically creates parent directories if they don’t exist.

​

Reading Files

The read_file tool reads the entire content of a specified file.

​

Editing Files

The edit_file tool performs a search-and-replace on a file’s content. It’s useful for making targeted changes.

​

Listing Directory Contents

The ls tool lists the files and subdirectories within a given path.

​

Finding Files by Pattern (Glob)

The glob tool finds all files and directories matching a specific pattern, which is useful for discovering files before processing them.

​

Searching File Content (Grep)

The grep tool searches for a specific text pattern (including regex) within files in a given directory. It’s perfect for finding where a function is called or locating specific comments. For detailed input/output schemas of all tools, see the API Reference.

​

Workflow Example: Agent Integration

Integrate the FilesystemToolkit directly into your agent to give it powerful file manipulation capabilities.

​

Next Steps