FileAgent

A tool-calling AI agent built from scratch in Python — no agent frameworks. Answers natural-language questions about any folder of files.

How it works

The core is a single loop:

1. The LLM receives the conversation + descriptions of 3 tools (list_files, read_file, search_text)
2. It replies with either a final answer, or a request to call a tool
3. The code executes the requested tool and feeds the result back
4. Repeat until the model answers (max 8 iterations)

The LLM never executes anything — it only decides. The code is the hands; the model is the brain.

Run it

pip install -r requirements.txt
echo "GROQ_API_KEY=your_key_here" > .env
python3 agent.py ./your_folder

Then ask things like: "which file mentions the deadline?"

Design decisions

• No frameworks — the agent loop is ~30 lines; owning it beats importing it
• Path sandboxing — tool arguments are treated as untrusted input; safe_path() blocks escapes like ../../etc/passwd
• Errors return to the model — failed tool calls become tool results, so the agent can read the error and self-correct
• Malformed-generation retry — the model occasionally garbles tool-call syntax; the loop catches this and retries within the iteration cap
• Max-iteration cap — hard guarantee against runaway loops