[Mark Licata (marklicata)]

Motivation & Context

Agents running inside AgentLoopMiddleware have no standard way to say "I'm done" or "I need a human". Each team writes its own should_continue predicate. This adds a text-based signal protocol so the agent can communicate loop termination intent directly in its response text:

• TASK_COMPLETE: <summary>: agent signals it is done; loop stops
• NEED_INPUT: <question>: agent needs human input; loop stops

This is the Python half of the work previously proposed in #8993, split per language at the reviewers' request. The .NET counterpart is #9163.

Description & Review Guide

What are the major changes?

• SignalParser / signal_should_continue() (agent_framework._harness._signals): drop-in should_continue predicate for AgentLoopMiddleware. It scans assistant messages only, so user-role nudges injected between iterations are ignored.
• LoopExitReason: typed exit reason strings "completed", "iteration_cap_reached", "need_input", "cancelled"
• get_loop_exit_reason(response): reads the exit reason from assistant text first, then additional_properties; a signal always wins over the iteration cap
• AgentLoopMiddleware now stamps additional_properties["loop_exit_reason"] = "iteration_cap_reached" when the cap fires (streaming and non-streaming)
• New public symbols exported from agent_framework; __init__.pyi and packages/core/AGENTS.md updated

What is the impact of these changes?

Additive and marked experimental. Loops that don't use SignalParser see no behavior change beyond the new loop_exit_reason stamp when the cap fires.

What do you want reviewers to focus on?

• The two-source lookup order in get_loop_exit_reason: assistant text first, additional_properties second, so a signal on the final allowed iteration is reported as completed, not iteration_cap_reached
• Token strings are case-sensitive and must match the .NET implementation exactly

Related Issue

Part of #8860, together with #9163 for .NET. The issue is closed manually once both PRs have merged.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Exit metadata can remain stale, and the public API does not consistently match its documented experimental scope and exit-reason contract.

4 open findings

• Unconditionally assign non-streaming loop exit reason · New
• Unconditionally assign streaming loop exit reason · New
• Validate additional_properties before returning exit reason · New
• Missing experimental metadata on new public APIs · New

What changed in this PR

Adds a Python signal protocol for autonomous AgentLoopMiddleware termination and typed exit-reason reporting.

Changes:

• Adds task-complete and human-input signal parsing.
• Stamps iteration-cap metadata for streaming and non-streaming loops.
• Exports and tests the new public APIs.

File	Description
test_harness_loop.py	Tests signal parsing and loop exits.
AGENTS.md	Documents the signal protocol.
_signals.py	Implements signals and exit reasons.
_loop.py	Stamps iteration-cap metadata.
__init__.pyi	Exposes typed public imports.
__init__.py	Adds runtime public exports.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Jose Alvarez (jpalvarezl)]

This start-of-line rule still treats a token inside a fenced Markdown code block as a real signal. For example, an assistant explaining the protocol with a fenced TASK_COMPLETE: example line terminates the loop. Please exclude fenced-code regions, or otherwise require the signal to occur outside code, and add fenced TASK_COMPLETE: and NEED_INPUT: regressions.