diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index 5f356cfb094..a552412fd4c 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -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 diff --git a/python/packages/core/agent_framework/_harness/_agent.py b/python/packages/core/agent_framework/_harness/_agent.py index fbb9536b90f..530a72f81b1 100644 --- a/python/packages/core/agent_framework/_harness/_agent.py +++ b/python/packages/core/agent_framework/_harness/_agent.py @@ -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, @@ -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. @@ -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, diff --git a/python/packages/core/agent_framework/_harness/_agent.pyi b/python/packages/core/agent_framework/_harness/_agent.pyi index a56ee836ff0..ff777e77b31 100644 --- a/python/packages/core/agent_framework/_harness/_agent.pyi +++ b/python/packages/core/agent_framework/_harness/_agent.pyi @@ -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, diff --git a/python/packages/core/tests/core/test_harness_agent.py b/python/packages/core/tests/core/test_harness_agent.py index ae7ff32020b..1cc19eb65c0 100644 --- a/python/packages/core/tests/core/test_harness_agent.py +++ b/python/packages/core/tests/core/test_harness_agent.py @@ -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: @@ -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 @@ -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: @@ -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