Skip to main content

File Tools

Prebuilt tools for reading, writing, and searching files within a configured workspace root.

Import path: agentflow.prebuilt.tools

All three tools are workspace-scoped: every path is resolved relative to a configured root directory and paths that escape the root are rejected. The root is read from config["file_tool_root"] or config["workspace_root"]; if neither is set, the current directory (.) is used.

file_read​

Reads a UTF-8 text file and returns its content.

What it does​

  • Resolves the path under the workspace root (rejects path traversal)
  • Detects binary files and refuses to read them
  • Supports optional line-range selection (start_line / end_line, 1-based)
  • Truncates content to max_chars and reports truncated: true if cut

Parameters​

ParameterTypeDefaultDescription
pathstrrequiredRelative (or absolute within root) file path
start_lineint1First line to include (1-based)
end_lineint0Last line to include; 0 means end of file
max_charsint20000Maximum characters returned
configdictNoneRuntime config; supports file_tool_root / workspace_root

Example response​

{
  "path": "src/main.py",
  "start_line": 1,
  "end_line": 30,
  "content": "import asyncio\n...",
  "truncated": false
}

Usage​

from agentflow.prebuilt.tools import file_read
from agentflow.core.graph import Agent, ToolNode

agent = Agent(
    model="gpt-4o-mini",
    tool_node=ToolNode([file_read]),
)

To set the workspace root at runtime, pass it through the agent config:

result = await app.ainvoke(
    {"message": "Show me the first 20 lines of README.md"},
    config={"thread_id": "t1", "file_tool_root": "/home/user/project"},
)

file_write​

Writes UTF-8 text to a file under the workspace root.

What it does​

  • Three modes: create (fails if the file exists), overwrite (replaces), append
  • Optionally creates parent directories with create_dirs=True
  • Content is capped at 200 000 characters
  • Returns the written path, byte count, and mode used

Parameters​

ParameterTypeDefaultDescription
pathstrrequiredTarget file path (relative to workspace root)
contentstrrequiredUTF-8 text to write
modestr"create""create", "overwrite", or "append"
create_dirsboolFalseCreate missing parent directories
configdictNoneRuntime config; supports file_tool_root / workspace_root

Example response​

{
  "status": "written",
  "path": "output/report.md",
  "bytes": 1024,
  "mode": "create"
}

Usage​

from agentflow.prebuilt.tools import file_read, file_write
from agentflow.core.graph import Agent, ToolNode

agent = Agent(
    model="gpt-4o-mini",
    tool_node=ToolNode([file_read, file_write]),
    system_prompt=[{
        "role": "system",
        "content": "You are a coding assistant. Read files to understand context, "
                   "write files to save your output.",
    }],
)

Searches text files under the workspace root by filename and content.

What it does​

  • Matches file names and file content against a case-insensitive query
  • Supports a glob pattern to restrict the file set (default **/*)
  • Skips common non-source directories: .git, node_modules, __pycache__, dist, etc.
  • Skips binary files and files larger than 1 MB
  • Returns relative paths, line numbers, match types (filename or content), and short previews

Parameters​

ParameterTypeDefaultDescription
querystrrequiredSearch term (case-insensitive)
pathstr""Sub-directory to search within (relative to root)
globstr"**/*"Filename glob pattern, e.g. "*.py"
max_resultsint20Maximum matches to return (capped at 100)
configdictNoneRuntime config; supports file_tool_root / workspace_root

Example response​

{
  "query": "asyncio",
  "root": ".",
  "results": [
    {"path": "src/server.py", "match_type": "content", "line": 3, "preview": "import asyncio"},
    {"path": "tests/test_async.py", "match_type": "filename", "line": null, "preview": "test_async.py"}
  ]
}

Usage​

from agentflow.prebuilt.tools import file_read, file_search
from agentflow.core.graph import Agent, ToolNode

agent = Agent(
    model="gpt-4o-mini",
    tool_node=ToolNode([file_read, file_search]),
    system_prompt=[{
        "role": "system",
        "content": "You are a codebase assistant. Use file_search to locate relevant files, "
                   "then file_read to inspect them.",
    }],
)

Using all three file tools together​

from agentflow.prebuilt.tools import file_read, file_write, file_search
from agentflow.prebuilt.agent import ReactAgent

agent = ReactAgent(
    model="gpt-4o-mini",
    tools=[file_read, file_write, file_search],
    system_prompt=[{
        "role": "system",
        "content": (
            "You are a code-editing assistant. "
            "Search for files with file_search, read them with file_read, "
            "and write changes with file_write."
        ),
    }],
)
app = agent.compile()

result = await app.ainvoke(
    {"message": "Find all Python files that import asyncio and list them."},
    config={"thread_id": "t1", "file_tool_root": "/home/user/project"},
)
Last updated on