Building production AI agents usually starts with a simple loop. You hand a large language model a system prompt, a few function signatures, and a user query. As business requirements grow, engineering teams inevitably attach more capabilities to that same prompt. What began as five clean JSON schemas quickly expands into thirty complex function definitions. This creates severe context window bloat, inflates input token overhead, and sharply degrades model performance. The language model spends an enormous fraction of its attention budget evaluating tool descriptions it will never use for the immediate task, leading to tool-selection hallucination and higher inference latency. Resolving this bottleneck requires an architectural shift from monolithic prompt construction toward tool-scoped subagents, a design pattern demonstrated by Pizza Bot, an open-source local-first workspace for long-running agentic workflows.
When you dump dozens of tool definitions into a single model context, two concrete failure modes emerge. First, token overhead stacks linearly with every added tool definition. A full tool schema suite can easily consume 4,000 to 8,000 tokens before a single line of user prompt or conversation history enters the window. Second, tool selection accuracy drops off significantly when a model faces too many broad choices simultaneously. Models frequently confuse parameters, hallucinate non-existent arguments, or choose slightly off-target tools. By isolating tool capabilities inside dedicated subagents, the primary orchestration loop only needs to see top-level skill routing descriptions rather than granular function payloads.
The architecture underlying Pizza Bot demonstrates how this isolation pattern functions in practice. Developed at Amazon and released under the Apache 2.0 license, the platform uses a stateful runtime built on DeepAgents and LangGraph. Instead of giving a central agent direct access to terminal commands, file systems, and API clients simultaneously, capabilities are encapsulated into modular skills that execute as self-contained, tool-scoped subagents.
When the main agent identifies a specialized task, it delegates execution to a skill-focused subagent. This subagent receives a pristine context window containing only the specific tools necessary for its narrow domain. The context footprint remains compact. The subagent works through its plan independently, performing iterative function calls, evaluating intermediate outputs, and returning only the final structured result to the parent coordinator.
A major challenge with subagent patterns is UI clutter and context degradation in the main conversation thread. If every subagent tool call, scratchpad thought, and intermediate payload gets appended back into the primary chat thread, you defeat the purpose of subagent isolation. The primary prompt context bloats anyway. Pizza Bot handles this by streaming intermediate progress and telemetry directly into a dedicated Activity panel in the interface. Raw tool invocations and subagent execution logs bypass the primary conversation state, preserving a clean context history for the main coordinator while giving human operators full visibility into background work.
Decoupling agent runtimes from user interface sessions is equally critical for long-running background tasks. Traditional desktop or web interfaces couple execution lifetimes to the frontend client session. If a user closes their browser or navigates away from an active run, background executions fail or freeze. In the Pizza Bot architecture, execution state lives entirely within a supervised api-server backend process using LangGraph state serialization and checkpointing.
The user interface layer, whether running as an Electron desktop shell, a browser application, or a terminal CLI, acts strictly as a presentation client communicating over an HTTP and Server-Sent Events (SSE) interface. When a user kicks off a complex background run and closes the desktop application, the api-server continues managing the DeepAgents state machine. Checkpointed runs persist across client disconnects. Completed tasks automatically surface in an Unread queue, while execution paths that require human intervention drop into a durable Action queue for manual approval.
Model provider portability and strict security boundaries are mandatory requirements when running local-first agent runtimes. Agent execution platforms cannot afford vendor lock-in, as latency and cost trade-offs vary across tasks. Pizza Bot’s runtime abstraction permits hot-swapping between hosted cloud models like Amazon Bedrock, Anthropic, Google Gemini, OpenAI, and OpenRouter, alongside local models powered by Ollama.
Security at the local boundary requires explicit isolation. Allowing an autonomous subagent unrestricted file system access poses obvious operational risks. The runtime strictly enforces directory permissions at the system boundary. By default, the system receives zero access to the user home directory. Operators must explicitly grant read-only or writable access to specific individual folders through Settings > Files. When a subagent executes file manipulations, the runtime rejects any access outside these explicitly approved directories, preventing runaway file modifications.
While tool-scoped subagent architectures solve prompt context bloat, they introduce distinct engineering trade-offs that teams must plan for. Spawning distinct subagents adds IPC and HTTP orchestration latency, as state must be serialized across graph boundaries. If a subagent gets stuck in a retry loop or fails to synthesize its final payload correctly, the parent agent may re-trigger the subagent, accumulating unnecessary API costs. Furthermore, running stateful checkpointing systems demands robust storage cleanup policies to prevent local SQLite or vector state stores from bloating over time.
Building modular subagents shifts the complexity from prompt engineering to runtime orchestration. To inspect how this stateful runtime is constructed or to evaluate its client-server separation using Node.js 24 and LangGraph, explore the source code directly on the Pizza Bot repository on GitHub.