Bound planning loops with explicit outcomes

Learning objective

Specify architecture-level planning and reflection loops, completion criteria, escalation paths, and termination conditions.

Core idea

For an architect, a planning loop is useful only when it can finish with an accountable outcome. The planner chooses a course of action; execution produces evidence; reflection assesses progress and decides whether to continue, revise, complete, or escalate. Every pass consumes time and resources, so the architecture needs enforceable stopping boundaries.

Microsoft Agent Framework’s Magentic orchestration supplies a concrete manager-led loop. The manager plans, selects specialists, assesses progress, detects stalls, and replans. Its progress ledger tracks request satisfaction, looping, and progress. This is coordination evidence, not independent proof that the business objective has been achieved.

The Magentic documentation marks the C# Magentic types as experimental through warning MAAIW001. Treat that implementation status as part of the technology decision. The logical requirements for budgets, acceptance, and escalation apply whether you use Magentic or implement a bounded workflow yourself.

How it works

Separate planning from completion

A plan states intended work, dependencies, and expected evidence. Completion criteria state what must be true of the result. Define the criteria before running the planner so the system cannot quietly redefine success after an inconvenient finding.

For an incident investigation, completion might require a supported hypothesis, identified evidence gaps, and an accepted recommendation. “The manager produced a final answer” is a framework outcome, not a business acceptance criterion. Validate required evidence and fields after synthesis.

The Azure Architecture Center describes Magentic as dynamic orchestration for complex problems without a predetermined approach. Its manager maintains a task ledger with goals and subgoals. Use that pattern where planning itself needs reasoning. If the sequence is already known, a simpler fixed workflow avoids paying for repeated coordination.

Design reflection around observable progress

Reflection should compare evidence and results with the plan and acceptance contract. Ask whether the request is satisfied, whether another action could resolve a specific gap, and whether the team is repeating unproductive work. Do not make “the agent feels confident” the only continue-or-stop signal.

In Agent Framework Magentic, consecutive non-progressing rounds increment a stall counter. Exceeding the configured maximum triggers a reset and replan. Planning and reflection therefore need different budgets: a stalled plan can be revised, but repeated revisions must not create unlimited execution. Reflection closes every pass by continuing, replanning after repeated stalls, completing, or escalating.

The Python MagenticBuilder exposes max_round_count, max_stall_count, and max_reset_count. The .NET builder exposes WithMaxRounds(), WithMaxStalls(), and WithMaxResets(). These are coordination-round, consecutive-stall, and plan-reset limits, not interchangeable measures.

For example, the documented Python configuration uses 10 rounds, 3 stalls, and 2 resets. Those are example values, not service quotas or universal defaults. Select and record values appropriate to the task, and add an application deadline because a round count does not measure elapsed time.

Handoff orchestration supplies a different stopping mechanism: Python’s HandoffBuilder(..., termination_condition=lambda conversation: ...) and .NET’s WithTerminationCondition(conversation => ...) evaluate conversation state. Combine a task-specific completion predicate with bounded continuation instead of relying only on counts; see 1.1.4 for handoff autonomy controls and the Python experimental status. A predicate can detect an accepted completion signal, while a turn limit bounds work when that signal never arrives. Neither substitutes for validating the business result.

Define terminal outcomes and escalation paths

Separate completed, rejected, unresolved, budget-exhausted, and failed outcomes in the application contract. These are application-defined statuses, not Magentic enum values. Associate each with evidence and a responsible consumer.

An unresolved factual conflict can go to a domain reviewer. An unavailable required tool can go to an operator. An exhausted investigation budget can produce an incomplete report for the requesting team. State which decision the recipient must make and what evidence the system includes, rather than escalating with a bare “needs help.”

Framework limits constrain the coordination loop. They do not automatically assign a business reviewer or establish how the caller presents an incomplete outcome. The application must interpret terminal results and route review or failure cases without launching an unlimited replacement loop.

A pause for external input uses workflow request/response handling; a pending request is a waiting state, not completion — see 1.1.6.

Review plans without authorizing every action

Magentic plan review uses MagenticPlanReviewRequest and MagenticPlanReviewResponse. Python enables it with enable_plan_review=True; .NET uses RequirePlanSignoff(true). The documentation says Python plan review defaults to off, while .NET defaults to on. Configure it explicitly rather than inferring one language’s behavior from the other.

The Python request supports approve() and revise(...). Review can appear for the initial plan and for stall-triggered replans, with progress information on replans. This makes a changed approach reviewable instead of silently broadening the investigation.

Plan approval does not replace approval for a consequential tool invocation. It accepts the approach, not every eventual argument produced during execution. Keep action gates at the write boundary; see 1.1.6. Preserve the overall deadline and outcome contract across replanning and human review.

Key distinctions and trade-offs

Reflection versus retry: Reflection changes or assesses the approach using evidence. A retry repeats an operation after a failure. Neither should erase the other’s budget or restart the entire job implicitly.

Satisfied ledger versus accepted outcome: The manager’s progress assessment guides coordination. Application validation establishes whether the result meets the business contract. A final synthesis can still be incomplete.

Stall limit versus reset limit: Stall detection decides when to replan. Reset limits bound how many replans can occur. Round limits bound coordination work, while deadlines bound elapsed time.

Adaptive planning versus predictable execution: Magentic can discover useful work as evidence develops. Fixed workflows offer clearer order and easier cost prediction. Choose adaptive planning only when that discovery contributes to the task.

Architecture / decision scenario

A manufacturing team investigates an intermittent production defect. The evidence sources and useful investigation order vary by incident, so you select a manager-led Magentic workflow with log-analysis and process-history specialists. The C# experimental status would require a separate implementation decision; this design uses the documented Python surface.

The application defines completion as a supported hypothesis, cited incident evidence, and a recommendation with unresolved risks. It configures max_round_count=10, max_stall_count=3, and max_reset_count=2 as chosen example budgets, plus an application deadline. The manager reviews progress after specialist work rather than treating every response as advancement.

If repeated log analysis produces no additional evidence, stall detection triggers replanning. With enable_plan_review=True, a reviewer receives MagenticPlanReviewRequest and can approve the revised approach or return feedback through revise(...). If a required record is missing, the workflow requests external input rather than guessing it.

A final synthesis passes through application validation. Missing evidence yields an unresolved report for the incident lead. Budget exhaustion yields an incomplete outcome with work performed and remaining gaps. The system does not restart a fresh planner to bypass its limits, and a proposed equipment change still requires a separate action approval.

Common exam traps

• Using a final manager answer as the only completion criterion.
• Treating stall, round, reset, and deadline limits as equivalent.
• Restarting budgets after every replan or escalation.
• Assuming Python and .NET have identical plan-review defaults.
• Treating plan signoff as authorization for all later tool calls.
• Presenting experimental C# Magentic types as generally available.

What to remember

Plan toward explicit acceptance evidence, reflect on observable progress, and enforce separate round, stall, reset, and time budgets. Define terminal business outcomes and their escalation owners. A reviewable plan and a synthesized answer still need action authorization and result validation.

Knowledge check

References

• Microsoft, Workflows orchestrations — Magentic
• Microsoft, AI agent orchestration patterns
• Microsoft, Workflows — Human-in-the-loop
• Microsoft, Workflows orchestrations — Handoff