AFS Local FS

This guide demonstrates how to build a chatbot capable of interacting with your local file system. By leveraging the AIGNE File System (AFS) and the SystemFS module, you can empower an AI agent to search, read, and manage files on your machine, turning it into a powerful local data expert.

Overview

The AIGNE File System (AFS) provides a virtual file system layer that gives AI agents a standardized way to access various storage systems. This example focuses on the SystemFS module, which bridges AFS to your local file system.

When a user asks a question, the agent intelligently performs the following actions:

1. Search:

   It uses the afs_search tool to find relevant files within the designated directory based on the user's query.

2. Read:

   It identifies the most promising file from the search results and uses the afs_read tool to access its content.

3. Synthesize:

   It processes the file's content to formulate a comprehensive and accurate answer.

This allows the agent to answer questions about your documents, code, or any other text-based files without manual guidance.

Prerequisites

Before you begin, ensure you have the following installed and configured:

Quick Start

You can run this example directly without a local installation using npx.

Example Interaction

Here is an example of the agent's process when asked, "What is AIGNE?":

👤 You: "What is AIGNE?"

🤖 Agent thinks: I need to find information about AIGNE in the provided files. I will start by searching.
   → Calls: afs_search(query: "AIGNE")

📁 Found 15 matching files:
   • docs/getting-started/what-is-aigne.md ⭐ (most relevant)
   • README.md
   • docs/core-concepts/overview.md
   ...

🤖 Agent thinks: The first result seems most relevant. I will read it to answer the user's question.
   → Calls: afs_read("docs/getting-started/what-is-aigne.md")

📄 File loaded (2.4 KB)

🤖 AI: "AIGNE is a framework and runtime engine for building LLM-powered
       applications and AI agents. It provides:

       • A unified Agentic File System (AFS) interface
       • Support for multiple LLM providers (OpenAI, Anthropic, etc.)
       • Tools for building autonomous agents
       • Integration with external services via MCP

       Would you like me to walk you through a quick-start tutorial, or
       would you prefer to see specific examples?"

The agent successfully found the correct file, read its contents, and provided a summarized, helpful response.

Connecting to an AI Model

The agent requires a connection to a Large Language Model (LLM) to function. If you run the example without providing an API key, you will be prompted to choose a connection method.

You have three options:

How It Works

The implementation can be broken down into three main steps, as illustrated in the diagram below:

1. Create a LocalFS Module

First, instantiate the LocalFS module, specifying the local path to the directory you want the agent to access and an optional description.

create-local-fs.ts

import { LocalFS } from "@aigne/afs-local-fs";

const localFS = new LocalFS({
  localPath: './aigne-framework',
  description: 'AIGNE framework documentation'
});

2. Mount the Module in AFS

Next, create an AFS instance and mount the localFS module. This makes the local directory available to any agent that has access to this AFS instance.

mount-module.ts

import { AFS } from "@aigne/afs";
import { AFSHistory } from "@aigne/afs-history";

const afs = new AFS()
  .mount(new AFSHistory({ storage: { url: ":memory:" } }))
  .mount(localFS);  // Mounted at the default path /modules/local-fs

3. Create and Configure the AI Agent

Finally, create an AIAgent and provide it with the afs instance. The agent automatically gains access to AFS tools for file system interaction.

create-agent.ts

import { AIAgent } from "@aigne/core";

const agent = AIAgent.from({
  instructions: "Help users find and read files from the local file system.",
  inputKey: "message",
  afs,  // The agent inherits afs_list, afs_read, afs_write, and afs_search
});

Available AFS Tools

By connecting the agent to AFS, it can use the following sandboxed tools to operate on the mounted directory:

Installation and Local Execution

If you prefer to run the example from the source code, follow these steps.

Use Cases

This example provides a foundation for several practical applications.

Documentation Chat

Mount your project's documentation folder to create a chatbot that can answer user questions about your project.

const afs = new AFS()
  .mount(new LocalFS({ localPath: './docs', description: 'Project documentation' }));

Codebase Analysis

Allow an AI agent to access your source code to help with analysis, refactoring, or explaining complex logic.

const afs = new AFS()
  .mount(new LocalFS({ localPath: './src', description: 'Source code' }));

File Organization

Build an agent that can help you sort and manage files in a directory, such as your "Downloads" folder.

const afs = new AFS()
  .mount(new LocalFS({ localPath: '~/Downloads', description: 'Downloads folder' }));

Multi-Directory Access

Mount several directories to give the agent a broader context, allowing it to search across your source code, documentation, and tests simultaneously.

const afs = new AFS()
  .mount("/docs", new LocalFS({ localPath: './docs' }))
  .mount("/src", new LocalFS({ localPath: './src' }))
  .mount("/tests", new LocalFS({ localPath: './tests' }));

Summary

You have learned how to use the AIGNE Framework to create a chatbot that can interact with a local file system. This powerful capability enables a wide range of applications, from intelligent documentation search to automated code analysis.

For further reading, explore the following related examples and packages: