Single-File Agent Architecture

Embracing the Single-File Approach

Over time, I discovered that packing an entire agent—its logic, prompt handling, and dependencies—into a single script can be surprisingly powerful. Having everything in one place makes it easier to see exactly what's happening at each step. It also means I can drop the file into a fresh environment, run it, and get immediate results without fussing over separate config files or environment mismatches.

To pull this off, I rely on an approach that embeds dependencies right in the file and organizes each tool through a simple interface. The tools themselves are just small functions or classes with clear parameters. Each loop of the agent is straightforward too: parse arguments, pick a tool, return the result, and repeat. It's a no-frills way to stay transparent about what's being called and why.

Going single-file helped me move faster because I could quickly clone or tweak agents for different tasks: swap out one database library for another, or replace a single prompt step without tearing apart a big codebase. It feels modular despite being self-contained. The key is to keep tools minimal, keep prompts well-scoped, and treat your main loop like a conversation with bite-sized steps. The end result is a system that's easy to grasp, fast to iterate on, and surprisingly robust.

As Big Tech continues to scale up their AI tooling, every developer focusing on agentic systems faces the threat of their custom code being crushed overnight. By keeping systems modular and - more crucially - composable, we can reduce our exposure to technical risk. The uber models will provide an ever more capable orchestration layer that we can use to play our single file systems like a well-tuned orchestra.

Credit to Anthropic's "Building Effective Agents" for one of the clearest sources of guidance on this devilishly difficult topic.

Many of these reflections are built upon the contributions of IndyDevDan; a source of true signal (and sanity) in a world of hype, FUD and noise. One of the first movers in this space, he has been building with agents for years and has a wealth of knowledge to share. Rather than jumping on every new tool or framework, Dan is focused on the fundamentals of building effective agents and distilling them into a set of principles that is language, toolchain and framework agnostic. I would strongly recommend you check out his course Principled AI Coding.

It's a game changer.