AI Agent Architecture: Model-Native vs. Framework-Orchestrated Agents
Choosing an architecture for an AI coding agent comes down to where decisions are made and how actions are controlled. This article compares model-native and framework-orchestrated agents, explains where dynamic subagents help, and outlines a hybrid design that adjusts autonomy, permissions, and approval requirements to the risk of each task.
Introduction: Agent Architecture Is About Who Has Control
As large language models move from answering questions to carrying out tasks, AI coding assistants can read code, analyze repositories, generate patches, run tests, and revise their work when tests fail. The engineering difference between these systems is not just how capable the model is. It is how the system organizes the model, its tools, the workflow, and the permissions needed to act.
Two questions help distinguish common agent architectures:
- Who decides what happens next? Does the model choose the next action, or does an external framework constrain each step?
- How does control pass from one step to the next? Does the model follow a natural-language goal, or do state transitions, roles, permissions, and approvals determine what can happen?
These questions point to two broad approaches:
- Model-native agents rely on the model to plan, reason, choose tools, evaluate results, and adjust its actions in pursuit of a goal.
- Framework-orchestrated agents use the model for reasoning and generation while an external framework manages roles, workflow constraints, permissions, and state.
Neither approach is inherently better. The right choice depends on task complexity, operational risk, and governance requirements.
1. Model-Native Agents: Let the Model Choose the Next Step
A model-native architecture keeps the workflow flexible. Rather than following a predefined sequence, the model interprets the goal, breaks it into steps, calls tools, checks the results, and adjusts its approach as it learns more.
A user might give the agent a goal such as:
Find the issue in this repository’s authentication logic, propose a fix, and add relevant unit tests.
The user specifies the outcome without prescribing which files to read or how to investigate.
1.1 The Model-Native Agent Loop
A typical loop covers five stages:
- Understand the task. Interpret the goal, identify its boundaries, and decide whether to inspect source code, documentation, logs, or test data.
- Plan the work. Break the task into steps, choose which files to read and which modules may need changes, and revise the plan as new findings emerge.
- Use tools. Search the repository, read files, generate patches, run tests, and inspect error output.
- Correct course. Revise the approach after a test failure, reconsider assumptions that do not hold, or return to the original constraints if the work drifts out of scope.
- Summarize the outcome. Explain the changes, identify remaining risks, and recommend follow-up checks.
1.2 Where Model-Native Agents Work Best
The main advantage is flexibility. If the agent discovers that an interface is now called differently, it can adjust its next step without waiting for the workflow to be reconfigured.
This is useful for:
- Exploratory work, where the user does not yet know where the problem lies.
- Cross-module diagnosis, where the agent must connect business logic, data structures, and call chains.
- Open-ended fixes, where several causes or repair paths are plausible.
- Complex refactoring, where changes must stay consistent across files and evolve in response to build or test results.
Model-native agents are a good fit when the goal is clear but the path is not.
1.3 The Trade-Off: Predictability, Permissions, and Cost
The same flexibility can make runs harder to predict. Two runs with the same goal may take different paths, which matters when an agent can touch production configuration, change a database, or merge critical code.
Greater autonomy also raises the stakes of tool access. If the model decides when to edit files or execute scripts, the system needs permission isolation, audit trails, and rollback. Cost can vary too: repeated searches, retries, and intermediate outputs can consume substantial context and compute.
Useful controls include step limits, tool allowlists, mandatory human confirmation for high-risk actions, execution logs and snapshots, and limits on context size and tool calls. A model-native workflow can be flexible without giving the model unrestricted access.
2. Framework-Orchestrated Agents: Put Workflow Rules Outside the Model
Framework orchestration prioritizes control over the process. The model still interprets, reasons, and generates, but the framework determines who can plan or execute, what each role can access, when approval is required, how errors are routed, and how results are handed off and accepted.
This is useful in enterprise software development, where generating correct code is only part of the job. Teams also need to enforce permissions, audit changes, satisfy compliance requirements, and repeat established workflows.
2.1 Separate Planning from Execution
A common design splits planning and execution into two roles:
- Planner agent: Has read-only access. It analyzes the repository, proposes changes, identifies the affected areas, and flags risks.
- Executor agent: Has scoped write access. It applies the plan, generates a patch, and runs tests. It cannot unilaterally redefine the task.
The planner can investigate without modifying the repository, while the executor is constrained by the plan. This reduces the chance that an agent will make changes during exploration and drift away from the original goal.
2.2 Pass Structured State Between Stages
Rather than relying on a single conversation context, an orchestrated system can pass structured state between roles. That state may include the task goal, files inspected, current hypotheses, candidate changes, commands awaiting execution, test results, error logs, and human review comments.
A typical workflow looks like this:
User submits a goal↓Planner analyzes the repository↓Planner produces a change plan↓Human or policy-based approval↓Executor generates a patch↓Tests run↓If tests fail, an error summary goes back to the planner↓Planner revises the plan↓Executor retries and the result is verified
Each handoff and state transition can be recorded in a log or event stream. That makes the workflow easier to observe, debug, and reuse.
2.3 Enforce Permissions by Role
Permission design starts with what each role should be allowed to do, not with everything the model is capable of doing:
- A read-only role can search, read, and summarize but cannot write.
- An analysis role can produce reports but cannot execute commands.
- An execution role can modify files when authorized.
- A test role can run tests but cannot edit source code.
- An audit role records changes and summarizes them.
A deny-by-default policy with explicit grants reduces risk in tasks involving code, configuration, database scripts, or infrastructure changes.
2.4 Where Orchestration Adds Friction
Roles, workflows, and state transitions have to be designed and maintained. A fixed process can struggle when a task is open-ended or the next step changes frequently. Handoffs can lose context, and multiple agents may repeat the same repository reads. As the state model grows more complex, maintenance and debugging get harder.
Orchestration fits best when the workflow is relatively stable and coordination, permissions, or auditability justify the overhead. For simple tasks, it can be more process than the work requires.
3. Dynamic Subagents: Create Roles as the Task Demands
Dynamic subagents offer an alternative to defining every role in advance. A lead agent can create a specialist when the task calls for code search, test analysis, documentation checks, performance review, or compatibility analysis. Each subagent works toward a local objective with its own context and a limited set of tools.
3.1 Why Split the Work?
A single agent handling a long task can accumulate irrelevant material in its context, making it harder to focus on the information that matters. Subagents let the system divide the work into smaller investigations:
Main task: Fix a cross-module defect├── Subagent A: Trace the call chain├── Subagent B: Analyze configuration differences├── Subagent C: Draft a candidate patch├── Subagent D: Run relevant tests└── Lead agent: Consolidate findings and make the final decision
Each specialist can focus on the relevant files and evidence, while the lead agent combines the results.
3.2 Common Coordination Patterns
- Sequential: One subagent’s output becomes the next subagent’s input. This works when steps have clear dependencies.
- Parallel: Several subagents analyze different areas at the same time. This works when the work can be divided and verified independently.
- Voting or selection: Multiple subagents propose solutions, and the lead agent or a reviewer chooses among them. This is useful when no solution is clearly preferable at the outset.
- Adversarial review: One subagent proposes a change, while another looks for counterexamples, risks, or omissions. This provides a cross-check before a high-risk change.
3.3 Bound the Overhead
Dynamic subagents are not automatically better than fixed roles. Poor task decomposition can split up information that belongs together. Excessive context isolation can lead to duplicate work. A changing set of agents can also make runs harder to reproduce and debug, while unnecessary coordination increases token use.
Set budgets, concurrency limits, and stopping conditions. An illustrative policy might look like this:
Maximum subagents: 5Maximum concurrent subagents: 3Maximum total steps: 20Total context budget: Set an explicit limitHigh-risk actions: Require human confirmation
4. Model-Native vs. Framework-Orchestrated Agents
| Dimension | Model-native architecture | Framework-orchestrated architecture |
|---|---|---|
| Who controls the next step | Primarily the model | Primarily the external framework |
| How work progresses | Guided by the goal | Guided by workflows and roles |
| Flexibility | High | Lower when workflows are fixed |
| Predictability | Lower because paths can vary | Higher when transitions are predefined |
| Permission governance | Relies on model and tool constraints | Can enforce restrictions by role and workflow stage |
| Auditability | Requires explicit logging and tracing | State changes and approvals are easier to capture |
| Debugging | Variable paths can be hard to reproduce | Defined stages make failures easier to trace |
| Best fit | Exploration, open-ended work, and complex diagnosis | High-risk work, strict compliance, and stable processes |
| Cost | Flexible but can vary significantly between runs | Easier to bound, though orchestration adds overhead |
Model-native designs give the model room to adapt. Framework orchestration makes the process easier to govern. Those strengths are complementary.
5. Putting a Hybrid Architecture into Practice
A practical approach is to choose the level of orchestration based on the risk of the task rather than use one architecture for everything.
5.1 Match Autonomy to Risk
- Low risk: Reading code, drafting comments, explaining functions, or organizing documentation can generally use a model-native workflow.
- Medium risk: Adding tests, changing local logic, or refactoring a small module benefits from orchestration that separates planning, execution, and verification.
- High risk: Changes to authentication logic, data migration scripts, infrastructure configuration, or production releases call for stricter orchestration, human approval, a rollback plan, and an audit trail.
5.2 Let the Model Reason and the Framework Enforce Policy
A hybrid coding assistant can route work by risk before granting permissions or taking action:
User goal↓Identify and classify risk↓Low risk: Model-native workflowMedium or high risk: Framework-orchestrated workflow↓Validate permissions↓Execute and log actions↓Test and verify↓Summarize results and retain the audit record
The model still handles interpretation, reasoning, and generation. The framework ensures that critical actions stay within the applicable rules.
5.3 Apply Least Privilege
Regardless of architecture, default to read-only access. Authorize writes separately, restrict network access independently, and allow only approved commands. Require approval for high-risk paths and retain snapshots of changes.
agent_policy:planner:permissions:- read_repository- search_documents- summarize_findingsexecutor:permissions:- write_patch- run_testsapproval_required: trueauditor:permissions:- read_logs- read_diff- generate_report
The point is to enforce permissions at the system level rather than rely on prompt instructions alone.
5.4 Make Changes Reversible
Agent tasks often take several attempts. Capture a snapshot before execution, record each change, and make it possible to compare diffs, roll back failures, override changes manually, and restore the test baseline. An agent that cannot undo its changes should not modify a production environment.
5.5 Design for Observability
Operators should be able to tell which stage a task is in, which role owns it, what files were read, and which tools were called. The record should also show which options were proposed, why an option was selected, whether approval was required, where a failure occurred, and whether the system rolled back. This information supports both debugging and operational governance.
5.6 Measure More Than Code Generation
Generating a patch does not tell you whether the agent solved the right problem or stayed within scope. Track metrics such as:
- Task completion rate: Did the agent achieve the user’s actual goal?
- Human interventions: How often did someone need to correct or redirect it?
- Change accuracy: Were the changes necessary and limited to the task?
- Test pass rate: Did the patch pass existing and newly added tests?
- Unintended action rate: Did the agent touch files or configuration it should have left alone?
- Resource usage: How much context, how many tool calls, and how much inference time did the task require?
- Reproducibility: Can the same input produce a comparable result under similar conditions?
6. Hybrid Workflow Pseudocode
The following product-neutral pseudocode illustrates how risk classification can determine the execution path.
def handle_task(task):risk = classify_risk(task)if risk == "low":result = native_agent_loop(goal=task.goal,max_steps=10,tools=["search", "read", "explain"])return summarize(result)if risk == "medium":plan = planner_agent.read_only(goal=task.goal,tools=["search", "read", "analyze"])patch = executor_agent.apply(plan=plan,tools=["write_patch", "run_tests"],approval_required=True)return verify_and_report(patch)if risk == "high":plan = planner_agent.read_only(goal=task.goal,tools=["search", "read", "analyze"])approved = human_approval(plan)if not approved:return reject_with_reason(plan)patch = executor_agent.apply(plan=plan,tools=["write_patch", "run_tests"],rollback_enabled=True)audit_log = auditor_agent.record(plan=plan,patch=patch,test_result=patch.test_result)return summarize_with_audit(patch, audit_log)
Risk classification happens before execution. Low-risk tasks retain more autonomy within a restricted tool set. Medium- and high-risk paths separate planning from execution, and the high-risk path explicitly includes human approval, rollback support, and auditing.
7. Conclusion: Choose the Architecture That Fits the Task
Model-native agents work well for exploration and complex diagnosis because the model can change course as it learns. Framework orchestration is a better fit when changes must be controlled, releases must satisfy compliance requirements, or teams need an auditable record of what happened.
In practice, a layered architecture can use both: let the model interpret goals, reason, and generate; let the framework enforce permissions, workflows, and audit requirements; and let task risk determine how much autonomy the agent gets. Tests provide evidence that the work succeeded, while logs show how it was carried out.
The measure of a coding agent is not whether it can generate a patch. It is whether it can complete real engineering work reliably, safely, and within the controls the task requires.
