Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions python/packages/core/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -411,6 +411,10 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID
- **Approval escape hatch** - `_has_pending_approval_request(result)` checks whether an iteration's response carries a pending tool-approval request (any content with `type == "function_approval_request"`). Both the streaming and non-streaming loops stop and return that response to the caller *before* evaluating `should_continue`/`max_iterations` or injecting `next_message`, so the loop is HITL-safe even when wrapped outermost around a `ToolApprovalMiddleware` (mirrors the C# `LoopAgent`'s `HasPendingApprovalRequests`).
- **Harness integration** - `create_harness_agent` enables the loop when a `loop_should_continue` callable is passed; it prepends `AgentLoopMiddleware(loop_should_continue, max_iterations=loop_max_iterations, next_message=loop_next_message)` ahead of `ToolApprovalMiddleware` so the loop is the outermost middleware (each iteration is a full agent run including tool approval, and the escape hatch hands pending approvals back to the caller). `loop_next_message` and `loop_max_iterations` only take effect together with `loop_should_continue` (with no `loop_should_continue` there is no loop, so they are ignored); `loop_max_iterations` defaults to the loop's default cap (`None` → unbounded).

`loop_return_final_only=True` forwards to the loop's `return_final_only` setting so non-streaming callers receive
only the last iteration's response. It defaults to `False`, is ignored without `loop_should_continue`, and does
not change streamed updates or streaming finalization.

### Workflows (`_workflows/`)

- **`Workflow`** - Graph-based workflow definition. `cancel_pending_requests(request_ids)` cancels selected external
Expand Down
6 changes: 6 additions & 0 deletions python/packages/core/agent_framework/_harness/_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,7 @@ def create_harness_agent(
loop_should_continue: ShouldContinueCallable | None = None,
loop_next_message: NextMessageCallable | None = None,
loop_max_iterations: int | None = DEFAULT_MAX_ITERATIONS,
loop_return_final_only: bool = False,
otel_provider_name: str | None = None,
context_providers: Sequence[ContextProvider] | None = None,
middleware: Sequence[MiddlewareTypes] | None = None,
Expand Down Expand Up @@ -534,6 +535,10 @@ def create_harness_agent(
a positive integer caps the loop (defaults to the loop middleware's default cap). Only
takes effect when ``loop_should_continue`` is set (otherwise no loop is added and this
is ignored).
loop_return_final_only: When True, return only the final loop iteration's response for
non-streaming runs. When False (default), aggregate all iterations and injected loop
prompts. Streaming runs still yield every iteration's updates. Only takes effect when
``loop_should_continue`` is set; otherwise this is ignored.
otel_provider_name: Custom OpenTelemetry provider/source name for telemetry.
context_providers: Additional context providers to include after the built-in ones.
middleware: Additional middleware to include.
Expand Down Expand Up @@ -673,6 +678,7 @@ def create_harness_agent(
loop_should_continue,
max_iterations=loop_max_iterations,
next_message=loop_next_message,
return_final_only=loop_return_final_only,
),
)
# Message injection is always on. It is a no-op when no messages are queued for the session,
Expand Down
1 change: 1 addition & 0 deletions python/packages/core/agent_framework/_harness/_agent.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ def create_harness_agent(
loop_should_continue: ShouldContinueCallable | None = None,
loop_next_message: NextMessageCallable | None = None,
loop_max_iterations: int | None = DEFAULT_MAX_ITERATIONS,
loop_return_final_only: bool = False,
otel_provider_name: str | None = None,
context_providers: Sequence[ContextProvider] | None = None,
middleware: Sequence[MiddlewareTypes] | None = None,
Expand Down
42 changes: 41 additions & 1 deletion python/packages/core/tests/core/test_harness_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -1279,6 +1279,7 @@ def _should_continue(**kwargs: Any) -> bool:
assert agent.middleware is not None
assert isinstance(agent.middleware[0], AgentLoopMiddleware)
assert agent.middleware[0].should_continue is _should_continue
assert agent.middleware[0].return_final_only is False


def test_create_harness_agent_loop_outermost_of_tool_approval_and_user_middleware() -> None:
Expand Down Expand Up @@ -1328,6 +1329,44 @@ def _next_message(**kwargs: Any) -> Any:
assert loop.next_message is _next_message


@pytest.mark.parametrize("return_final_only", [False, True])
@pytest.mark.parametrize("streaming", [False, True])
async def test_create_harness_agent_loop_return_final_only(return_final_only: bool, streaming: bool) -> None:
"""Final-only results are opt-in for non-streaming; streaming preserves all updates."""
decisions = iter([True, False])

def should_continue(**kwargs: Any) -> bool:
return next(decisions)

agent = create_harness_agent(
client=_FakeChatClient(),
max_context_window_tokens=128_000,
max_output_tokens=16_384,
loop_should_continue=should_continue,
loop_next_message=lambda **kwargs: "Please continue.",
loop_return_final_only=return_final_only,
)

session = agent.create_session()
if streaming:
stream = agent.run("Hello", session=session, stream=True)
updates = [update async for update in stream]
result = await stream.get_final_response()
assert any(update.role == "user" and "Please continue." in update.text for update in updates)
assert sum(update.role == "assistant" and update.text == "Hello" for update in updates) == 2
else:
result = await agent.run("Hello", session=session)

loop = _find_loop_middleware(agent)
assert loop is not None
assert loop.return_final_only is return_final_only
final_only = return_final_only or streaming
assert sum(message.role == "assistant" for message in result.messages) == (1 if final_only else 2)
assert ("Please continue." in result.text) is not final_only
if final_only:
assert result.text == "Hello"


def test_create_harness_agent_uses_default_max_iterations_when_omitted() -> None:
"""When loop_max_iterations is omitted, the loop keeps the middleware's default cap."""
from agent_framework._harness._loop import DEFAULT_MAX_ITERATIONS
Expand Down Expand Up @@ -1375,7 +1414,7 @@ def _should_continue(**kwargs: Any) -> bool:
assert unbounded_loop.max_iterations is None


def test_create_harness_agent_next_message_and_max_iterations_ignored_without_should_continue() -> None:
def test_create_harness_agent_loop_options_ignored_without_should_continue() -> None:
"""Without loop_should_continue no loop is added, so loop params are simply ignored."""

def _next_message(**kwargs: Any) -> Any:
Expand All @@ -1387,6 +1426,7 @@ def _next_message(**kwargs: Any) -> Any:
max_output_tokens=16_384,
loop_next_message=_next_message,
loop_max_iterations=5,
loop_return_final_only=True,
)
assert _find_loop_middleware(agent) is None

Expand Down
Loading