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

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   
2. Install dependencies

   uv pip install -U agno openai
   
3. Export your OpenAI API key

   Mac/Linux

   export OPENAI_API_KEY="your_openai_api_key_here"
   
4. Run the example

   Save the code as filesystem_context.py, then run:

   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.

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

Underlying toolkit methods

Cookbook Example

Working example