Python: [Bug]: `AgentFrameworkAgent(require_confirmation=...)` docstring is misleading — it also gates the `confirm_changes` HITL tool-call emission, not just "predictive updates"

[antsok]

Description

In agent-framework-ag-ui, the require_confirmation parameter on AgentFrameworkAgent (and AgentConfig) is documented as:

require_confirmation: Whether predictive updates require user confirmation before applying

However, the actual implementation uses this flag as the master switch that controls whether a synthetic confirm_changes tool call is emitted for function-approval requests (tools with approval_mode="always_require"). This is the mechanism a human-in-the-loop (HITL) frontend (e.g. CopilotKit's useHumanInTheLoop({ name: "confirm_changes" })) relies on to render an approval card.

The docstring makes no mention of tool-approval / HITL, so users reasonably conclude the flag only affects predict_state_config-style predictive state updates. Setting require_confirmation=False silently disables the entire approval UI for gated tools, even though the tool is still gated server-side.

Where the behavior diverges from the docs

AgentConfig.__init__ / AgentFrameworkAgent.__init__ docstring (_agent.py):

require_confirmation: Whether predictive updates require user confirmation before applying

But in _run_common.py, _emit_approval_request(...) uses the same flag to decide whether to emit the confirm_changes tool call:

def _emit_approval_request(content, flow, predictive_handler=None, require_confirmation=True):
    ...
    # Always emitted: ToolCallEnd for the gated call + CustomEvent("function_approval_request") + RUN_FINISHED interrupt
    ...
    if require_confirmation:
        confirm_id = generate_event_id()
        events.append(ToolCallStartEvent(tool_call_id=confirm_id, tool_call_name="confirm_changes", ...))
        events.append(ToolCallArgsEvent(tool_call_id=confirm_id, delta=args_json))
        events.append(ToolCallEndEvent(tool_call_id=confirm_id))
        ...

And it is threaded through _emit_content(...):

if content_type == "function_approval_request":
    return events + _emit_approval_request(content, flow, predictive_handler, require_confirmation)

So for a tool marked approval_mode="always_require":

• require_confirmation=True → the confirm_changes tool call is emitted → the HITL frontend renders an approval card.
• require_confirmation=False → no confirm_changes tool call → the frontend never sees an approval prompt; the tool chip is stuck "Running" (only the non-standard CustomEvent / RUN_FINISHED.interrupt are emitted).

Impact

Users who want to disable predictive-state confirmation (per the docstring) but keep tool-approval HITL will inadvertently break their approval UI. Conversely, users troubleshooting a missing approval card have no way to discover from the docs that this flag is the cause.

Code Sample

Error Messages / Stack Traces

Package Versions

agent-framework-ag-ui: 1.0.0rc6

Python Version

Python 3.12

Additional Context

Suggested fix

Update the docstring for require_confirmation in both AgentConfig.__init__ and AgentFrameworkAgent.__init__ to reflect what it actually controls, e.g.:

require_confirmation: When True, function-approval requests (tools with approval_mode="always_require") are surfaced as a synthetic confirm_changes tool call so a human-in-the-loop frontend can render an approval prompt before the tool runs. Also gates confirmation for predictive state updates. When False, no confirm_changes tool call is emitted (only a function_approval_request custom event and a RUN_FINISHED interrupt).

Optionally, consider decoupling the two concerns into separate flags (e.g. require_tool_approval vs. require_predictive_confirmation) since they serve distinct purposes.

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

Repro: _emit_approval_request() in python/packages/ag-ui/agent_framework_ag_ui/_run_common.py (line 460) uses the require_confirmation flag to gate confirm_changes tool call emission for function_approval_request content, but the docstring in _agent.py (lines 33, 97) only documents it as controlling "predictive updates". Minimal repro: call _emit_approval_request(approval_content, flow, require_confirmation=False) and observe no TOOL_CALL_START for confirm_changes is emitted. Fix requires updating the docstring to reflect dual purpose and/or decoupling into separate flags (e.g. require_tool_approval vs require_predictive_confirmation).

• Failing test: none
• Files examined: python/packages/ag-ui/agent_framework_ag_ui/_agent.py, python/packages/ag-ui/agent_framework_ag_ui/_run_common.py, python/packages/ag-ui/tests/ag_ui/test_run.py, python/packages/ag-ui/tests/ag_ui/golden/test_scenario_hitl.py, python/packages/ag-ui/pyproject.toml
• Tests run: tests/ag_ui/test_issue_6881_require_confirmation_gates_approval.py (3 tests, all pass confirming the documented behavior mismatch)
• Reported version: 1.0.0rc6
• Current version: 1.0.0rc7

[Tuttotorna]

This is a configuration-surface boundary issue.

The key distinction is:

predictive-state confirmation
!=
function-approval surfacing

From the issue, require_confirmation is documented as controlling:

whether predictive updates require user confirmation before applying

But at runtime it also controls whether a synthetic confirm_changes tool call is emitted for function-approval requests.

So the same flag currently gates two different transitions:

1. predictive update confirmation
   → should the user confirm predicted state changes?

2. tool approval surfacing
   → should an approval-required tool emit the UI-visible confirm_changes call needed by HITL clients?

Those are not the same boundary.

The failure mode is:

tool has approval_mode="always_require"
require_confirmation=False
server-side tool remains gated
synthetic confirm_changes call is not emitted
frontend receives no approval card
tool chip remains running / unresolvable

So the runtime has two incompatible states:

server state:
this tool requires approval before execution

client-visible state:
no approval prompt was emitted

That makes the approval requirement non-operational at the UI boundary.

A minimal conformance fixture could be:

case_1:
tool_approval_mode: always_require
require_confirmation: false
synthetic_confirm_changes_emitted: false
function_approval_custom_event_emitted: true
frontend_can_render_standard_approval_prompt: false
expected: NON_CONFORMANT
reason: server-side approval requirement is not surfaced through the standard HITL tool-call channel

case_2:
predictive_state_updates_enabled: true
predictive_confirmation_required: false
tool_approval_mode: always_require
tool_approval_surface_enabled: true
synthetic_confirm_changes_emitted: true
expected: CONFORMANT
reason: predictive confirmation and tool approval surfacing are independent concerns

case_3:
tool_approval_mode: always_require
tool_approval_surface_enabled: false
explicit_custom_client_handles_function_approval_event: true
expected: CONFORMANT_IF_DOCUMENTED
reason: disabling synthetic confirm_changes is valid only if a documented alternate approval surface exists

case_4:
require_confirmation: false
tool_approval_mode: never_require
synthetic_confirm_changes_emitted: false
expected: CONFORMANT

The invariant I would preserve is:

a server-side approval requirement must either be surfaced through a documented client-actionable channel,
or explicitly declared as requiring a custom client handler.

It should not be silently hidden behind a flag documented only for predictive-state confirmation.

So the minimal documentation fix is useful, but the cleaner runtime/API boundary would be to split the flag:

require_predictive_confirmation
controls predicted state update confirmation

surface_tool_approval
controls whether approval-required tools emit a synthetic confirm_changes tool call for HITL UIs

Then the combined behavior becomes explicit:

approval_mode="always_require"

• surface_tool_approval=True
  → emit standard confirm_changes approval prompt

approval_mode="always_require"

• surface_tool_approval=False
  → do not emit confirm_changes, but require custom function_approval_request handling

predictive updates
→ governed separately

The important failure mode is not only a misleading docstring.

It is that a hidden coupling between two unrelated confirmation surfaces can make an approval-required tool non-resumable from the client side.

This is a transition-sufficiency issue:

the approval-gated tool transition is treated as valid,
but the support required for the client to observe, approve, and resume that transition
is disabled by a flag whose documented boundary does not mention tool approval.

Technical signature:
Result produced by the PHI-OMEGA algorithm — transition-sufficiency analysis:
Required(τ) ⊆ Supported(τ)