> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem

> Read files from a scoped local directory.

Read files from a scoped local directory. The provider exposes one tool: `query_fs` for searching and reading files.

```python theme={null}
import asyncio
from pathlib import Path

from agno.agent import Agent
from agno.context.fs import FilesystemContextProvider
from agno.models.openai import OpenAIResponses

fs = FilesystemContextProvider(
    root=Path(__file__).resolve().parent,
    model=OpenAIResponses(id="gpt-5.6-luna"),
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.4"),
    tools=fs.get_tools(),
    instructions=fs.instructions(),
)

if __name__ == "__main__":
    asyncio.run(
        agent.aprint_response("Summarize the files in this directory.")
    )
```

The agent can call `query_fs` with a filesystem question. A sub-agent handles file listing, searching, and reading.

## Run

<Snippet file="create-venv-step.mdx" />

**1. Install dependencies**

```bash theme={null}
uv pip install -U agno openai
```

**2. Export your OpenAI API key**

```bash Mac/Linux theme={null}
export OPENAI_API_KEY="your_openai_api_key_here"
```

```powershell Windows theme={null}
$Env:OPENAI_API_KEY="your_openai_api_key_here"
```

**3. Run the example**

Save the code as `filesystem_context.py`, then run:

```bash theme={null}
python filesystem_context.py
```

## Configuration

| Parameter | Type | Default | Description |
| - | - | - | - |
| `root` | `str \| Path` | required | Directory to scope the provider to. |
| `id` | `str` | `"fs"` | Tool becomes `query_<id>`. |
| `name` | `str` | `"Filesystem"` | Display name used in provider instructions. |
| `instructions` | `str \| None` | `None` | Instructions for the read-only filesystem sub-agent. |
| `exclude_patterns` | `list[str] \| None` | `None` | Glob patterns to exclude (e.g., `["*.pyc", "__pycache__"]`). |
| `model` | `Model \| None` | `None` | Model for the sub-agent. |
| `mode` | `ContextMode` | `default` | `default` or `agent` expose `query_fs`. `tools` exposes raw FileTools. |
| `query_timeout` | `float \| None` | `None` | Timeout in seconds for a sub-agent query. |
| `stream_sub_agent_events` | `bool` | `True` | Include sub-agent events in the parent stream. |

## Tools Exposed

| Tool | Description |
| - | - |
| `query_fs` | Search files, read content, list directory structure. Read-only. |

> [!NOTE]
>
> FilesystemContextProvider is read-only. There is no `update_fs` tool.

## Example queries

| Query | What happens |
| - | - |
| "What files are in this project?" | Lists directory structure |
| "Find all Python files that import requests" | Searches file content |
| "Read the README" | Returns file content |

## Resources

> **[FileTools Reference](https://agno-v2.mintlify.site/tools/toolkits/local/file.md)**
>
> Underlying toolkit methods

> **[Cookbook Example](https://github.com/agno-agi/agno/blob/v3.0.4/cookbook/12_context/00_filesystem.py)**
>
> Working example


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.