Deep agents — long-horizon AI agents that plan, dispatch sub-agents, and act over many steps instead of answering in one shot. Architecture patterns, LangGraph implementation notes, and hard-won lessons from running them in CodeBuddy.
Most AI coding tools autocomplete a line and stop. CodeBuddy is a deep agent: it plans the task, delegates isolated sub-jobs to eight specialist subagents, runs ~30 tools against your real files, verifies the result, and retries (failing over to another provider) when a step breaks. Open source, runs in your editor, uses your own keys. Here’s what that means and why we built it.
A single LLM loop can’t reliably run a multi-step coding task. CodeBuddy is a deep agent instead: one createDeepAgent call composed from five seams (model, tools, file system, subagents, middleware) returning a compiled LangGraph graph, with four layers of self-healing. This is the whole architecture from the inside, grounded in the real code and file paths.
Open the harness and the system prompt is 40 lines you could read over coffee. Print what the model actually receives on the same turn and it’s 4,000 tokens: a persona block, a skills catalog, a summarized history, tool schemas, spotlighted retrieval. None of it is in the prompt file. That gap is context engineering, and if you let it be ad-hoc string concatenation it rots. Here’s how we made it an ordered middleware stack instead, and why the order is load-bearing.
Ask an agent to review 300 files and somewhere around turn 40 it starts losing the plot. The fix isn’t a smarter model; it’s a different architecture. Here’s how recursive dispatch works, why we wired it into CodeBuddy, and everything that surprised us along the way.
