Two Architecture Paths for Intelligent Coding Agents
Coding assistants are moving from autocomplete to end-to-end task completion. This article explains two common agent architectures—model-native loops versus framework-controlled orchestration—how to separate planning from execution, when to use fixed versus dynamic roles, and how to choose based on control, auditability, cost, flexibility, and reversibility.
Intelligent coding assistants are shifting from code completion toward autonomous task completion. Developers no longer want only a function snippet; they want an assistant that can read a repository, understand requirements, edit multiple files, run tests, and recover from failures. The core design question behind these capabilities is who decides the next step. Around that question, two main architecture approaches have emerged.
Two architecture paths
Model-native
This path leaves planning, tool use, and reflection as much as possible to the model. The system exposes a fixed set of tools—for example, read files, search code, run commands, and edit files. In each turn the model chooses which tool to call and when to stop. There is no separate scheduler; the execution loop is driven by model output.
The advantage is a short path and natural interaction. As the model improves, overall results tend to improve with it. The drawback is opaque decision-making, errors that are hard to isolate, and task boundaries that depend mainly on the model’s own judgment.
Framework-controlled
This path treats the model as a capability unit. An outer orchestration framework owns state, stage transitions, and permissions. The framework decides when to plan, when to execute, and when to feed failure information back to the model. The model produces results only within the stage it is assigned.
The advantage is predictable flow and constrained permissions; every step can be logged and audited. The drawback is higher engineering complexity, and poorly chosen stages can hurt efficiency.
Design points for separation of duties
In framework-controlled designs, a common pattern is to split thinking and execution into two roles.
- Planner: read-only. It reads code, maps dependencies, and produces a plan document. It cannot modify files, which prevents uncontrolled “think-and-edit” loops.
- Executor: write access. It applies the confirmed plan, edits code, and runs tests. It cannot change the plan on its own; if the plan is infeasible, it returns to the planner.
The two roles exchange structured artifacts through the filesystem—plan documents, change lists, and test reports. Using files as the handoff medium has several benefits: artifacts can be reviewed by humans, work can pause mid-task, and failures can be traced to a specific version.
The following sketch shows the flow only; a real implementation must match the model APIs and permission system in use:
class Planner:allowed_tools = ["read_file", "search_code"]class Executor:allowed_tools = ["read_file", "write_file", "run_tests"]def run_task(task):plan = planner.run(task) # produce plan documentsave("plan.md", plan)wait_for_human_review() # optional human checkpointresult = executor.run(read("plan.md"))report = run_tests()if not report.passed:return planner.revise(plan, report)return result
Dynamic orchestration versus fixed roles
Another difference is whether roles can be created at runtime.
With fixed roles, all sub-roles are defined at design time, with fixed duties and tool lists. Behavior is stable and easier to test; failures can be attributed to a specific role.
With dynamic orchestration, the model can create subtasks at runtime and choose how they collaborate—serial, parallel, or multi-agent voting. This is more flexible for unusual problems and can assemble a process for special cases. The cost is also clear: the process graph can become more complex than the task, spawn unnecessary subtasks, and consume extra context and compute.
A practical rule: if steps can be enumerated in advance, prefer a fixed flow. Introduce dynamic orchestration only when the task shape is highly uncertain, and cap it with a maximum number of subtasks, rounds, and budget.
Selection and rollout
Compare architectures along five dimensions:
- Controllability: whether each step’s permissions and outputs must be constrained
- Auditability: whether a full decision trail is required
- Cost: typical context size and number of calls per task
- Flexibility: how much task shape can vary
- Reversibility: how quickly mistaken actions can be rolled back
For production code, have the planning stage emit a reviewable plan, then let a human or test gate decide whether execution may proceed. For exploratory work, constraints can be looser, but still set budget and timeout limits.
Conclusion
Neither path is universally better. Model-native designs win on simplicity and adaptability; framework-controlled designs win on predictability and governance. Teams should weigh task risk, audit needs, and cost, rather than chasing a single architecture.
