Python: expose final-only loop responses in create_harness_agent - #10214

Motivation & Context

Looping harness agents currently return an aggregated non-streaming response containing earlier answers and injected loop prompts. Applications that only need the final answer cannot select the existing AgentLoopMiddleware.return_final_only behavior through create_harness_agent().

This change exposes that option without changing the default behavior.

Description & Review Guide

• What are the major changes?
  Add the optional, keyword-only loop_return_final_only: bool = False parameter to create_harness_agent() and its type stub. Forward it to AgentLoopMiddleware, document its behavior, and add regression coverage.

  from agent_framework import create_harness_agent, todos_remaining
  from agent_framework.openai import OpenAIChatClient
  
  client = OpenAIChatClient(model="gpt-4.1")
  
  # Existing behavior: aggregate iterations and injected prompts.
  aggregated = create_harness_agent(
      client=client,
      loop_should_continue=todos_remaining(),
  )
  
  # New opt-in behavior: return the final iteration's response.
  final_only = create_harness_agent(
      client=client,
      loop_should_continue=todos_remaining(),
      loop_return_final_only=True,
  )

• What is the impact of these changes?
  Non-streaming callers can opt into final-only responses. The default remains False, preserving existing aggregation. Streaming updates and streaming finalization remain unchanged. The option is ignored when loop_should_continue is not configured. Middleware ordering and approval handling are unchanged.

  All 186 tests in the harness factory and loop modules passed, along with focused Ruff, Pyright, and mypy checks. The full core suite has not been run for this change.

• What do you want reviewers to focus on?
  Runtime/stub signature consistency, unchanged defaults, forwarding to the existing middleware, and streaming parity. This follows the narrowly scoped factory-option proposal in Python: [Feature]: Option in create_harness_agent to return only the agent's answer from a looping run (result.text currently includes the loop's prompts) #10209; it does not change AgentResponse.text globally.

Related Issue

Fixes #10209

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Copilot assisted with implementation, tests, documentation, focused validation, and this PR description.

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 links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after a language prefix) — a workflow keeps the label and title prefix in sync automatically.