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.
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
Set up your virtual environment
uv venv --python 3.12
source .venv/bin/activateInstall dependencies
uv pip install -U agno openaiExport your OpenAI API key
export OPENAI_API_KEY="your_openai_api_key_here"Run the example
Save the code as filesystem_context.py, then run:
python filesystem_context.pyConfiguration
| 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 | Discovery exclusions; None uses the toolkit defaults (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 | Positive deadline for the query tool (Python 3.11+); direct calls and raw tools are not bounded. |
stream_sub_agent_events | bool | True | Include sub-agent events in the parent stream. |
Exclusions hide matches from discovery, but a named excluded file can still be read by FileTools. Both filesystem and workspace providers use default exclusions for common secrets, dependency directories and build output; Workspace also rejects excluded paths when explicitly named.
Tools Exposed
| Tool | Description |
|---|---|
query_fs | Search files, read content, list directory structure. Read-only. |
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 |