Add signal-based completion detection and typed exit reasons to AgentLoopMiddleware #8860

Summary

AgentLoopMiddleware supports two completion detection mechanisms today: a developer-supplied should_continue predicate, and a judge-driven model that evaluates whether the original request was answered. Neither produces typed exit reasons — the caller cannot distinguish "agent finished the task" from "iteration cap fired" from "cancelled externally."

This issue proposes adding a third, lighter completion mechanism (text signal scanning) and typed exit reasons to the existing AgentLoopMiddleware in both the Python and .NET implementations.

We intend to take on implementation.

User need

When a user hands a task to an autonomous agent, they need a clear answer to whether it completed successfully. Today, every autonomous loop exit looks the same to the caller. Users also need a standard way for an agent to pause and surface a specific question — "I need your decision on X before I can continue" — without the loop terminating entirely.

Developer need

Teams building autonomous agents on MAF reimplement completion detection from scratch. The existing should_continue interface supports this, but there is no standard implementation. Building a signal-scanner predicate is simple; not having a canonical one means every team invents their own convention, and none of them are interoperable.

The default max_iterations=10 (Python) is appropriate for judge-driven quality refinement loops. For autonomous task-completion loops, this default silently terminates most real tasks before they complete. Guidance is needed.

What's already there

• Python: AgentLoopMiddleware (python/packages/core/agent_framework/_harness/_loop.py) — full loop middleware with should_continue predicate, max_iterations safety cap (default 10), judge-driven completion, feedback log, session snapshot/restore, and nudge injection.
• .NET: AgentLoopMiddleware equivalent in dotnet/src/Microsoft.Agents.AI/Harness/Loop/ and dotnet/src/Microsoft.Agents.AI.Harness/.
• Both: The loop already injects a nudge asking the agent to say when it is complete. There is no detection of that signal in either implementation.

Proposal

1. signal_should_continue helper — a ~50-line should_continue predicate implementation that scans the agent's last response text for two tokens:

TASK_COMPLETE: <summary>   →  returns False (stop), exit reason = "completed"
NEED_INPUT: <question>     →  pauses loop, surfaces question, waits for human resume()
(no signal, no tools)      →  returns True (continue), nudge injected

2. Typed loop exit reason — a LoopExitReason (enum or string literal union) surfaced on the response returned by the loop:

3. Documentation guidance on max_iterations — explicitly document that the default is calibrated for short quality-refinement loops. For autonomous task-completion loops, 50–150 is the appropriate range.

Scope

• Both Python and .NET implementations are in scope. The Python harness (python/packages/core/agent_framework/_harness/) and .NET harness (dotnet/src/Microsoft.Agents.AI/Harness/ and dotnet/src/Microsoft.Agents.AI.Harness/) maintain feature parity; changes to one require equivalent changes in the other.
• New signal_should_continue function and LoopExitReason type (experimental-flagged in both languages)
• No new packages, no new dependencies

Notes

The signal convention (TASK_COMPLETE: / NEED_INPUT:) is drawn from a production runtime where it ran at scale. The implementation is a should_continue predicate that slots into the existing loop interface — it does not require changes to the loop's core mechanics in either language.