Main Loop and Progressive Disclosure: Building Controllable, Evolvable Agent Architectures

    This article examines why monolithic single-prompt agent architectures break down as tasks grow more complex, and presents a controllable, evolvable alternative built on three ideas: a single main loop, two layers of progressive disclosure, and a controlled set of sub-agents. It walks through a minimal implementation skeleton with structured decisions and explicit exit conditions, layered context engineering (summarization, rolling compression, and external memory), guidelines for when to delegate to sub-agents, tool and skill design standards, and metrics for evaluation, observability, and cost governance. It closes with common anti-patterns and a four-phase adoption roadmap for teams moving from ad hoc prompting toward software-engineering-grade agent systems.

    1. Where the Problems Come From: Three Failure Curves of the Monolithic Prompt

    The most common way to build an agent early on is a “one prompt to rule them all” approach: you write every role definition, piece of domain knowledge, operating rule, exception-handling strategy, and example dialogue into a single system prompt, attach a batch of tools, and then rely on the model to find its own answers within that large prompt. This works when task boundaries are clear and steps are fixed. But once tasks become multi-step, span domains, and require repeated verification, three problems surface at the same time.

    The first is attention dilution. The longer the context, the more the model’s adherence to early instructions and key constraints tends to decay. This is not the model getting “dumber”; it is the result of information competing inside a limited context window. A formatting rule written on line 37 of a 5,000-word prompt often carries far less binding force than the same rule written in the final sentence. When a team keeps fixing bugs by “adding one more rule,” the prompt only keeps expanding, and the marginal return quickly approaches zero.

    The second is error accumulation. In a multi-step task, small deviations at each step are inherited and amplified by the steps that follow. Without explicit validation and rollback mechanisms, errors spread exponentially: if the previous step picked the wrong data source, no amount of rigor in the next step’s analysis will matter.

    The third is cost and latency spiraling out of control. Under a monolithic architecture, every round carries the full context regardless of whether the task is simple or complex. Even a simple information-extraction task pays the full price of long-context reasoning. Token consumption is not proportional to task complexity, and the cost structure deteriorates rapidly at scale.

    Piling on sub-agents does not make the problem disappear; it changes its shape. The number of sub-agents is not positively correlated with system quality. Each additional sub-agent forces the main scheduler to make one more intent judgment, maintain one more result contract, and absorb one more context round-trip. When sub-agents lack clear boundaries, they issue contradictory recommendations, and the main loop is forced to arbitrate amid the noise, becoming more error-prone than a single agent would be. The conclusion is clear: what you need is not more agents, but a better control structure and a more precise supply of capabilities.

    2. Architecture Backbone: One Main Loop, Two Layers of Progressive Disclosure

    The recommended overall structure can be summarized as “1 + 2 + N”:

    • 1 main loop: the single decision and scheduling hub. It holds the task state, termination conditions, and budget constraints, and is responsible for planning, dispatch, validation, and convergence.
    • 2 layers of progressive disclosure: the first layer is the capability catalog (which skills/tools are available and their metadata); the second layer is the full instructions, parameter schema, and execution logic, loaded only when needed.
    • N controlled sub-agents: enabled only when a task can be cleanly partitioned, requires independent context isolation, or requires parallel fan-out. The number is determined by the task structure, not fixed in advance.

    Progressive Disclosure is the most important and most easily underestimated design in this architecture. Its core idea is this: at startup, expose only the “index” of capabilities, and defer the “manuals” until they are actually needed. A catalog containing only a name, a one-line purpose, and applicability boundaries consumes on the order of a few hundred tokens; an expanded skill specification with parameter schemas, error-code tables, and example calls can consume thousands of tokens. Expanding all of the latter at startup is a classic waste of context.

    A recommended form for the skill and tool catalog (illustrative; fields can be adjusted to your team’s conventions):

    1. # Lightweight catalog injected at startup (example structure)
    2. skills:
    3. - name: data_quality_check
    4. summary: Validates structured datasets for completeness, uniqueness, and value ranges
    5. when_to_use: After receiving the data, before any statistical analysis
    6. load_cost: medium # Estimated context cost after expansion
    7. - name: report_formatter
    8. summary: Renders analysis results into a standard report structure
    9. when_to_use: Once conclusions are confirmed and a deliverable is needed
    10. load_cost: low

    Only when the main agent decides in a given round that it needs data_quality_check does it request the full definition, including the parameter schema, return structure, recommended handling on failure, and typical examples. As a result, the path for a simple request is very short: decide, call directly, return. Only complex requests trigger progressive loading, so the context always stays aligned with the task’s actual needs.

    3. Implementation Skeleton of the Main Loop

    The main loop is not about “letting the model do whatever it wants.” It is a controlled loop with an explicit state machine and exit conditions. A minimal viable skeleton has five phases: observe, decide, act, validate, and compress.

    1. def main_loop(task, budget, max_steps):
    2. state = init_state(task) # structured task state, not plain text
    3. manifest = load_manifest() # load only the capability catalog
    4. loaded = set()
    5. for step in range(max_steps):
    6. # 1) Observe: assemble this round's context (state summary + completed steps + latest tool result)
    7. obs = build_observation(state, compact=True)
    8. # 2) Decide: the main agent outputs a structured decision object, not free text
    9. decision = model.decide(obs, catalog=manifest, loaded=loaded)
    10. if decision.type == "load_skill":
    11. manifest_detail = fetch_skill_detail(decision.skill) # progressive expansion
    12. loaded.add(decision.skill)
    13. state.append(observation=manifest_detail)
    14. continue
    15. if decision.type == "call_tool":
    16. result = call_tool(decision.tool, decision.args) # args validated against the schema
    17. state.append(action=decision, result=result)
    18. continue
    19. if decision.type == "answer":
    20. if verify(state, decision.answer) is False:
    21. state.append(observation="Verification failed: " + verify.reason)
    22. continue # move to the next correction round
    23. return decision.answer
    24. if decision.type == "delegate":
    25. # Dispatch a sub-agent only when the task can be split and needs context isolation
    26. sub_result = run_sub_agent(
    27. goal=decision.goal,
    28. context_slice=state.slice_for(decision.scope), # provide only the necessary slice
    29. allowed_tools=decision.tool_whitelist,
    30. budget=decision.sub_budget,
    31. )
    32. state.append(result=sub_result)
    33. continue
    34. raise BudgetExceeded(max_steps, budget)

    A few implementation details are easy to overlook but decide success or failure:

    Decisions must be structured objects, not free text. Have the main loop output a decision in JSON (or an equivalent structure) that includes the intent type, goal, parameters, and expected result. On one hand, this lets you intercept illegal calls with schema validation; on the other, it naturally produces a replayable, evaluable decision trace. Parsing free text and then extracting with regex is the source of most “unstable agent” problems.

    Exit conditions must be explicit and multi-dimensional. At minimum you need all of the following: an answer has been generated and passed validation; a step limit; a token or time budget limit; and “no progress for N consecutive rounds” stall detection. Without stall detection, the most common failure mode is an agent repeatedly calling the same tool until the budget runs out.

    State must be structured, not held entirely in the conversation history. Break the task state into explicit fields (evidence collected, hypotheses ruled out, items to confirm, tools used and summaries of their results). Each round, the main loop reads and writes this structured state, with the conversation history serving only as a supplement. This design tradeoff pays off enormously: it makes context compression safe, and it makes interruption recovery and human takeover possible.

    4. Context Engineering: Compression, Retrieval, and Layered Memory

    Once the main loop runs for a dozen or more rounds, context management stops being an optimization and becomes a requirement. In practice it is usually handled in three layers:

    The first layer is result summarization. Raw tool returns are often verbose (large logs, full pages of structured data). The principle is: send the full raw data to external storage, and keep only a structured summary plus an addressable reference in the context. When details are needed, the main loop actively issues a targeted query rather than stuffing tens of thousands of words into the context at once.

    The second layer is rolling compression. As the context approaches a threshold, fold earlier steps into “fact cards”: what was done, what conclusions were reached, and which hypotheses were refuted. Folding rules should be tailored to the task type; analysis tasks keep conclusions and counterexamples, while operational tasks keep state and records of side effects.

    The third layer is external memory and retrieval. Stable domain knowledge, historical decisions, and common questions should not occupy the context for long. They should be externalized into a searchable document collection or key-value memory and recalled on demand. One important engineering discipline here: recalled content must carry source and freshness markers, otherwise stale information gets used as current fact and produces errors that are hard to locate.

    When deployed on the cloud, this layering usually maps to a few general capabilities: files and datasets stored in object storage, summaries and state in a key-value or document database, recall handled by a retrieval service, run traces and call chains handled by logging and monitoring/alerting services, and inference services running on a container platform so they can scale elastically with load. When choosing specific implementations, focus on whether they support structured filtering, whether they make access auditing easy, and whether they integrate with the observability stack, rather than on how long the feature list is.

    5. Sub-Agents: When to Use Them and When Not To

    Sub-agents are valuable, but that value comes from context isolation and parallel fan-out, not from “looking smarter.”

    There are three typical scenarios that call for dispatching a sub-agent. First, the task is naturally parallelizable; for example, running the same kind of analysis across dozens of data sources, where fan-out followed by aggregation significantly compresses the total time. Second, the subtask has a large context but the main loop does not need the details, such as deep retrieval or large-scale codebase exploration, where only the conclusion needs to be returned. Third, the subtask requires a role constraint that differs from, or is even mutually exclusive with, the main agent’s (for example, a review role dedicated to strict fault-finding); a separate prompt and separate context avoid mutual interference.

    Conversely, restraint is warranted in the following cases: the task is strongly sequential and later steps must depend on the full details of earlier ones; the subtask boundary is blurry and requires repeated negotiation with the main agent over inputs and outputs; or the system’s stability is not yet solid and you are still tuning the main loop itself. A practical rule of thumb: if you cannot state in one sentence what the sub-agent’s input is, what its output is, and what it is not allowed to do, then it should not be split out yet.

    When dispatching a sub-agent, the contract must be tightened to something close to the strictness of a function call:

    1. {
    2. "goal": "Find the channels with abnormal order-volume fluctuations within the specified time window",
    3. "context_slice": ["time_range", "channel_list"],
    4. "allowed_tools": ["query_metrics"],
    5. "output_schema": {
    6. "type": "object",
    7. "properties": {
    8. "anomalies": {"type": "array", "items": {"type": "object"}},
    9. "confidence": {"type": "number"}
    10. },
    11. "required": ["anomalies"]
    12. },
    13. "budget": {"steps": 8, "tokens": 30000}
    14. }

    Also hold to three disciplines: sub-agents are read-only by default, and any write operation with side effects must return to the main loop for execution, so that operations remain auditable and rollbackable; the sub-agent’s tool whitelist is granted minimally, per need; and the sub-agent’s return must pass schema validation. A validation failure counts as a failed dispatch and triggers a retry or a downgrade, rather than merging a chunk of free text directly into the main context.

    6. Tool and Skill Design Guidelines

    Tools are the agent’s “hands and feet,” and the quality of their descriptions directly determines call accuracy. A few guidelines that have been validated repeatedly:

    • Write descriptions for the caller, not for the documentation reader. Explain what problem the tool solves, when it should not be used, and how it differs from neighboring tools. As the number of tools grows, “which tool should I use” is often harder than “how do I call the tool,” so boundary descriptions matter more than parameter descriptions.
    • Use strong types and enums for parameters. Prefer an enum over a free-form string; provide a default whenever possible; and replace a single free-text field with two required fields where you can. The more structured the parameters, the lower the misuse rate.
    • Write error messages as instructions. Instead of returning “invalid parameter,” return “missing start_time; please provide an ISO8601 start time, for example 2026-08-01T00:00:00Z.” A good error message is itself a prompt correction and can turn a single failure into a self-healing step.
    • Require idempotency or an idempotency key for writes. Agents retry naturally, and a non-idempotent write interface will inevitably produce duplicate side effects across multiple retries.
    • Return results in two tiers. A summary (which enters the context) plus the full result (addressable on demand). This aligns directly with the context-layering strategy.

    7. Evaluation, Observability, and Cost Governance

    The benefits of an architecture upgrade must be measurable; otherwise you cannot tell whether you are improving or regressing. Establish a baseline around four categories of metrics and run a regression after every prompt or tool change:

    Dimension Key Metrics Notes
    Effectiveness Task success rate, human takeover rate Must be tiered by task difficulty; an overall average hides long-tail problems
    Efficiency Average steps, average rounds, peak context usage Reflects whether the loop is spinning in place
    Quality Tool misuse rate, parameter validation failure rate, hallucinated citation rate Pinpoints whether the problem is in the prompt, the tool description, or the data layer
    Cost Per-task token consumption, cache hit rate Tie it to business value for quota management

    Building the evaluation set is the most labor-intensive but most rewarding part of this work. The approach is to sample from real requests and manually annotate “expected result + acceptable range + disallowed errors,” forming a layered regression set on the order of a few hundred cases and folding it into continuous integration. The effect of progressive disclosure in particular needs this kind of evaluation to prove out: load order, catalog granularity, and summary length all affect results, and tuning by intuition almost inevitably leads to repeated back-and-forth.

    On observability, one complete agent execution should form a replayable call chain: each round’s decision object, which skills were loaded, which tools were called and with what parameters, return summaries, changes in context usage, and time and cost should all be recorded and linkable by an identifier. The chain also needs alerts on anomalous patterns, such as a sudden spike in one tool’s failure rate, a certain task type repeatedly hitting the budget limit, or a rising ratio of failed sub-agent return validations. These are often early signals of changes in upstream prompts or data quality.

    Cost governance should be designed alongside the architecture: push deterministic sub-flows (format conversion, field mapping, fixed-rule validation) down into traditional code, and do not hand deterministic work to reasoning; add result caching for repeatable calls; and tier token and step budgets by task value, routing low-value requests to a lightweight model and a short path. In practice, a single structural downshift-and-cache refactor usually yields far greater cost improvement than repeatedly tuning prompts.

    8. Common Anti-Patterns at a Glance

    • Perpetual prompt growth: every production issue is solved by “adding one more rule,” until no one dares touch the prompt. Rules should be converged into testable skills and tool contracts.
    • Indiscriminate sub-agent-ification: splitting one big prompt into ten sub-agents that know nothing of each other, so that scheduling overhead and conflict cost exceed the benefit.
    • Free-text decisions: the main loop outputs natural language and then parses it with regex, which is fragile and non-evaluable.
    • Missing stall and budget protection: the agent spins in a failure loop until it times out.
    • Context that only grows and never shrinks: without summarization and compression, long tasks inevitably break at the context boundary.
    • Tool descriptions written for developers: only a parameter table, no applicability boundaries, leading to the wrong tool being selected.
    • No regression evaluation set: every change is validated by hand on a few cases, so you cannot clearly tell an improvement from a regression.

    9. Adoption Roadmap

    In the first phase, refactor the main loop first: change decisions to structured output, add the three protections (steps, budget, stall), and separate the task state from the conversation history into an explicit structure. This step requires no new components, yet it immediately turns “occasional runaway behavior” into “diagnosable failures.”

    In the second phase, implement progressive disclosure: organize the capability catalog so that only three metadata items, name, purpose, and applicability boundary, remain in the startup context; write the full expanded description, parameter schema, and failure-handling guidance for each skill; then use the regression evaluation set to compare the effect and cost differences across load granularities.

    In the third phase, introduce controlled sub-agents: start from the clearest parallel scenarios (batch processing of same-type tasks, and deep retrieval that needs context isolation), first stabilizing the input/output contracts and the read-only constraint, then gradually expanding the scope.

    In the fourth phase, complete the engineering loop: call-chain tracing, anomaly alerting, layered evaluation, budget quotas, and cost attribution, giving the architecture the ability to evolve over the long term rather than stalling at the demo stage once again.

    The value of this method lies not in the cleverness of any single component, but in turning agent construction from a “prompt art” back into “software engineering”: use the main loop to control the control flow, use progressive disclosure to control context cost, use contractual sub-agents to control complexity growth, and use evaluation and observability to control change risk. When deploying on the cloud, connect these capabilities respectively to the elastic scheduling of a container platform, to logging and monitoring/alerting services, and to object storage and retrieval services and other general-purpose infrastructure, and you get an agent system that both iterates quickly and runs stably at scale. Baidu AI Cloud provides general-purpose capability support in this direction for this kind of architecture engineering practice, though specific selection should still be weighed against your own task structure, cost constraints, and compliance requirements.