@aigne/example-afs-local-fs

AFS SystemFS Example

This example demonstrates how to create a chatbot that can interact with your local file system using the AIGNE Framework and AIGNE CLI. The example utilizes the SystemFS module to provide file system access to AI agents through the AIGNE File System (AFS) interface.

AIGNE File System (AFS) is a virtual file system abstraction that provides AI agents with unified access to various storage backends. For comprehensive documentation, see AFS Documentation.

What You'll See

User asks: "What is AIGNE?"

Behind the scenes:

• LLM calls afs_search → searches all files for "AIGNE"
• Finds /modules/local-fs/docs/getting-started/what-is-aigne.md
• LLM calls afs_read → reads the specific file
• LLM presents: "AIGNE is a framework and runtime engine for building LLM-powered applications..."

The power: AI agents intelligently search your file system and retrieve exactly what's needed - no manual navigation required!

Prerequisites

• Node.js (>=20.0) and npm installed on your machine
• An OpenAI API key for interacting with OpenAI's services
• Optional dependencies (if running the example from source code):
  • Pnpm for package management
  • Bun for running unit tests & examples

Quick Start (No Installation Required)

Run the Example

export OPENAI_API_KEY=YOUR_OPENAI_API_KEY

# Mount AIGNE framework docs (clone first)
git clone https://github.com/AIGNE-io/aigne-framework
npx -y @aigne/example-afs-local-fs --path ./aigne-framework --chat

# Or mount any directory
npx -y @aigne/example-afs-local-fs --path ~/Documents --description "My Documents" --chat

# Ask a specific question
npx -y @aigne/example-afs-local-fs --path . --input "What is AIGNE?"

See It In Action

Here's what happens when you ask "What is AIGNE?" with the framework docs mounted:

👤 You: "What is AIGNE?"

🤖 Agent thinks: I should search the docs for information about AIGNE...
   → 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: Let me read the most relevant file...
   → 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?"

Key insight: The agent intelligently searches, finds the right file, reads it, and synthesizes a helpful answer - all automatically!

Connect to an AI Model

As an example, running npx -y @aigne/example-afs-system-fs --path . --input "What files are in the current directory?" requires an AI model. If this is your first run, you need to connect one.

• Connect via the official AIGNE Hub

Choose the first option and your browser will open the official AIGNE Hub page. Follow the prompts to complete the connection. If you're a new user, the system automatically grants 400,000 tokens for you to use.

• Connect via a self-hosted AIGNE Hub

Choose the second option, enter the URL of your self-hosted AIGNE Hub, and follow the prompts to complete the connection. If you need to set up a self-hosted AIGNE Hub, visit the Blocklet Store to install and deploy it: Blocklet Store.

• Connect via a third-party model provider

Using OpenAI as an example, you can configure the provider's API key via environment variables. After configuration, run the example again:

export OPENAI_API_KEY="" # Set your OpenAI API key here

For more details on third-party model configuration (e.g., OpenAI, DeepSeek, Google Gemini), see .env.local.example.

After configuration, run the example again.

Debugging

The aigne observe command starts a local web server to monitor and analyze agent execution data. It provides a user-friendly interface to inspect traces, view detailed call information, and understand your agent’s behavior during runtime. This tool is essential for debugging, performance tuning, and gaining insight into how your agent processes information and interacts with tools and models.

Start the observation server.

View a list of recent executions.

Installation

Clone the Repository

git clone https://github.com/AIGNE-io/aigne-framework

Install Dependencies

cd aigne-framework/examples/afs-local-fs

pnpm install

Run the Example

# Run with your current directory
pnpm start --path .

# Run with a specific directory
pnpm start --path ~/Documents --description "My Documents"

# Run in interactive chat mode
pnpm start --path . --chat

How It Works: 3 Simple Steps

1. Create LocalFS Module

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

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

2. Mount It as an AFS Module

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 /modules/local-fs

3. Create an AI Agent

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

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

That's it! The agent can now intelligently search and retrieve files from your local directory.

What the Agent Can Do

• afs_list - List files and directories (with recursive depth control)
• afs_read - Read file contents and metadata
• afs_write - Create or update files
• afs_search - Fast full-text search using ripgrep (supports regex)

All operations are sandboxed to the mounted directory for safety.

Try These Examples

# Mount AIGNE docs and ask questions
git clone https://github.com/AIGNE-io/aigne-framework
npx -y @aigne/example-afs-local-fs --path ./aigne-framework --input "What is AIGNE?"

# Ask about specific features
npx -y @aigne/example-afs-local-fs --path ./aigne-framework --input "How does AFS work?"

# Search your codebase
npx -y @aigne/example-afs-local-fs --path . --input "Find all TypeScript files with TODO comments"

# Interactive mode - ask follow-up questions
npx -y @aigne/example-afs-local-fs --path ~/Documents --chat

In chat mode, try:

• "What files are in this directory?"
• "Show me the README"
• "Search for 'authentication' in all files"
• "Find all Python files"
• "What does the config.json file contain?"

Use Cases

Documentation Chat

Mount your project docs and let users ask questions:

const afs = new AFS()
  .mount(new LocalFS({ localPath: './docs', description: 'Project documentation' }));
// Users can now ask: "How do I configure authentication?"

Codebase Analysis

Give AI agents access to your codebase:

const afs = new AFS()
  .mount(new LocalFS({ localPath: './src', description: 'Source code' }));
// Agent can search, read, and explain code

File Organization

Let AI help organize your files:

const afs = new AFS()
  .mount(new LocalFS({ localPath: '~/Downloads', description: 'Downloads folder' }));
// Ask: "Find all PDFs from last week" or "Organize these files by type"

Multi-Directory Access

Mount multiple directories simultaneously:

const afs = new AFS()
  .mount("/docs", new LocalFS({ localPath: './docs' }))
  .mount("/src", new LocalFS({ localPath: './src' }))
  .mount("/tests", new LocalFS({ localPath: './tests' }));
// Agent can search across all mounted directories

Related Examples

• AFS Memory Example - Conversational memory with user profiles
• AFS MCP Server Example - Integration with MCP servers

Related Packages

• @aigne/afs - AFS core package
• @aigne/afs-local-fs - LocalFS module documentation

TypeScript Support

This package includes full TypeScript type definitions.

License

MIT