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/activate

Install dependencies

uv pip install -U agno openai

Export 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.py

Configuration

ParameterTypeDefaultDescription
rootstr | PathrequiredDirectory to scope the provider to.
idstr"fs"Tool becomes query_<id>.
namestr"Filesystem"Display name used in provider instructions.
instructionsstr | NoneNoneInstructions for the read-only filesystem sub-agent.
exclude_patternslist[str] | NoneNoneDiscovery exclusions; None uses the toolkit defaults (e.g., ["*.pyc", "__pycache__"]).
modelModel | NoneNoneModel for the sub-agent.
modeContextModedefaultdefault or agent expose query_fs. tools exposes raw FileTools.
query_timeoutfloat | NoneNonePositive deadline for the query tool (Python 3.11+); direct calls and raw tools are not bounded.
stream_sub_agent_eventsboolTrueInclude 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

ToolDescription
query_fsSearch files, read content, list directory structure. Read-only.

FilesystemContextProvider is read-only. There is no update_fs tool.

Example queries

QueryWhat 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