Skip to content
Open
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
1 change: 1 addition & 0 deletions docs/specs/004-python-function-calling-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -758,6 +758,7 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Opaque reasoning signature replay | Provider-specific opaque reasoning metadata is captured and restored on reconstructed calls. | `packages/gemini/tests/test_gemini_client.py::test_function_call_part_captures_thought_signature_as_reasoning_content`, `test_reconstructed_function_call_replays_thought_signature_from_reasoning_content` |
| Chat Completions approval wrappers | Framework approval wrappers are not sent as chat messages. | `packages/openai/tests/openai/test_openai_chat_completion_client.py` approval serialization tests |
| DevUI conversation-bound approval ownership | A pending function approval is bound to the conversation that originated it. A response from another conversation is rejected without consuming the pending approval, and identical request IDs in different conversations remain independent. | `packages/devui/tests/devui/test_approval_validation.py::test_approval_request_must_be_bound_to_originating_conversation`, `test_same_approval_request_id_is_scoped_per_conversation` |
| AG-UI durable approval opt-in | Trusted scoped private authority survives cold restore; claim-write failure prevents execution, interrupted/unsaved execution cannot regain a grant, and results keep original call identity. Single-writer storage is required; replay-only history cannot establish authority. | `packages/ag-ui/tests/ag_ui/test_cold_approval_resume.py`, `test_private_snapshot_preserves_expiration_across_downtime`, `test_private_snapshot_restore_respects_scope_capacity` |
| AG-UI approval result event | Approved result emits once with content and persists in snapshot. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approved_call_emits_one_live_result_under_original_identity`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_resume_persists_replayable_tool_results`, `test_endpoint_agent_approval_replayed_resume_entry_reprojects_retained_result` |
| AG-UI rejection/mixed decision | Transport emits only the events defined for approved and rejected calls without duplicates. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_rejected_call_does_not_execute_or_emit_live_result`, `test_mixed_batch_preserves_approved_result_identity_and_order`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_rejection_releases_already_approved_sibling` |
| AG-UI approval-time follow-up | The full grouped user-input pause remains in message history and emits no synthetic `TOOL_CALL_RESULT`. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_follow_up_group_remains_in_history_without_live_tool_result` |
Expand Down
4 changes: 4 additions & 0 deletions python/packages/ag-ui/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,10 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
ids alone; an older request generation for the same occurrence is still invalid.
- Approval responses for tools injected during `before_run` are deferred to the in-run approval middleware rather
than executed or rejected by the transport before those tools exist.
- `AgentFrameworkAgent(durable_approvals=True)` retains private lifecycle authority in the scoped Thread Snapshot.
Restore only that private record, never client Shared State, replay messages, or interrupt projections. Commit claims
before side effects and propagate claim-write failures; cold unfinished claims fail closed as indeterminate.
This requires application-owned atomic durable storage and single-writer serialization, not cross-replica coordination.
- `_approval_lifecycle.py` is the sole owner of approval occurrence registration, trusted aliases, authority
validation, claims, terminal outcomes, and retry deduplication. Runner code normalizes AG-UI protocol values and
projects lifecycle outcomes but must not maintain a parallel pending-approval registry.
Expand Down
35 changes: 35 additions & 0 deletions python/packages/ag-ui/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -433,6 +433,41 @@ For applications that need server-authoritative thread history, configure scoped
mode only accepts user turns and results for backend-issued tool calls when extending stored history. It complements
endpoint authentication and authorization; it does not replace them.

## Native approval recovery after restart

Approval authority is process-local by default. A replayable interrupt is not sufficient to authorize a tool after
restart. Opt in on the agent wrapper when the application provides a trusted, scoped durable snapshot store:

```python
from agent_framework.ag_ui import AgentFrameworkAgent, add_agent_framework_fastapi_endpoint

runner = AgentFrameworkAgent(agent, durable_approvals=True)
add_agent_framework_fastapi_endpoint(
app,
runner,
snapshot_store=durable_store,
authorization_scope_resolver=resolve_authenticated_scope,
)
```

The store must retain the complete snapshot, including private `session_state`, and atomically commit writes before
returning. Its scope must identify the same authorized owner after restart. Serialize all mutations for a thread
across its entire run; this option supports a single writer and does not implement locks or compare-and-swap across
replicas. `InMemoryAGUIThreadSnapshotStore` does not provide process-restart durability.

New snapshots retain private server-issued approval occurrences, their original function and provider call identities,
arguments, middleware continuation, and terminal results. This authority is never reconstructed from client messages,
Shared State, or the visible interrupt. Old snapshots without the private authority record remain non-resumable.
Native SDK-only histories use `AgentSession.to_dict()` / `AgentSession.from_dict()` separately; importing their visible
approval controls does not create AG-UI approval authority.

Before an approved side effect starts, the runner commits its claim. A failed claim write prevents execution. If a
process stops after the claim or the terminal result cannot be saved, cold recovery treats that claim as indeterminate
and refuses to execute it again. Applications must reconcile uncertain side effects outside this retry path; this is
not a guarantee of completing a tool exactly once across arbitrary crashes. Completed persisted approvals retain their
canonical result, and retries do not rerun the tool during the configured lifecycle retention window. Retention ages
include downtime. Default pending retention is 24 hours and terminal replay retention is 15 minutes.

## AG-UI Thread Snapshots

AG-UI Thread Snapshot persistence is opt-in and disabled by default. Existing endpoints keep their current behavior
Expand Down
10 changes: 10 additions & 0 deletions python/packages/ag-ui/agent_framework_ag_ui/_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ def __init__(
service_session_id_from_thread_id: bool = False,
emit_messages_snapshot: bool = True,
legacy_session_id_from_thread_id: bool = False,
durable_approvals: bool = False,
):
"""Initialize agent configuration.

Expand All @@ -51,6 +52,9 @@ def __init__(
emit_messages_snapshot: Whether to emit a terminal MessagesSnapshotEvent at the end of runs.
Defaults to True for backward compatibility. Set to False when using HistoryProvider
to prevent redundant full-transcript rewrites on the client.
durable_approvals: Persist private approval authority in a trusted scoped snapshot store.
Requires durable atomic writes and a single writer per thread. Incomplete claims after
restart fail closed; this does not coordinate concurrent replicas.
legacy_session_id_from_thread_id: Deprecated compatibility option that uses the client-owned
AG-UI Thread id directly as the internal Agent Session id.
"""
Expand All @@ -60,6 +64,7 @@ def __init__(
self.service_session_id_from_thread_id = service_session_id_from_thread_id
self.require_confirmation = require_confirmation
self.snapshot_store = snapshot_store
self.durable_approvals = durable_approvals
self.a2ui_config = a2ui_config
self.emit_messages_snapshot = emit_messages_snapshot
self.legacy_session_id_from_thread_id = legacy_session_id_from_thread_id
Expand Down Expand Up @@ -113,6 +118,7 @@ def __init__(
service_session_id_from_thread_id: bool = False,
emit_messages_snapshot: bool = True,
legacy_session_id_from_thread_id: bool = False,
durable_approvals: bool = False,
):
"""Initialize the AG-UI compatible agent wrapper.

Expand All @@ -134,6 +140,9 @@ def __init__(
a2ui_config: Optional backend A2UI config consumed by auto-injection.
emit_messages_snapshot: Whether to emit a terminal MessagesSnapshotEvent at the end of runs.
Defaults to True. Set to False when using HistoryProvider.
durable_approvals: Persist private approval authority in a trusted scoped snapshot store.
Requires durable atomic writes and a single writer per thread. Incomplete claims after
restart fail closed; this does not coordinate concurrent replicas.
legacy_session_id_from_thread_id: Deprecated compatibility option that uses the client-owned
AG-UI Thread id directly as the internal Agent Session id. This disables Snapshot Scope
isolation for context-provider state.
Expand Down Expand Up @@ -161,6 +170,7 @@ def __init__(
a2ui_config=a2ui_config,
emit_messages_snapshot=emit_messages_snapshot,
legacy_session_id_from_thread_id=legacy_session_id_from_thread_id,
durable_approvals=durable_approvals,
)

# Server-side Approval State. Populated when approval requests are emitted
Expand Down
47 changes: 34 additions & 13 deletions python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,12 @@
InRunApprovalExecution,
InRunPendingToolTransitionOwner,
)
from ._approval_state import _APPROVAL_SCOPE_INPUT_KEY, InMemoryAGUIApprovalStateStore, approval_state_thread_id
from ._approval_state import (
_APPROVAL_SCOPE_INPUT_KEY,
_APPROVAL_SNAPSHOT_STATE_KEY,
InMemoryAGUIApprovalStateStore,
approval_state_thread_id,
)
from ._message_adapters import _APPROVAL_DECISION_IS_BOOLEAN_KEY, normalize_agui_input_messages
from ._predictive_state import PredictiveStateHandler
from ._tooling import collect_server_tools, merge_tools
Expand Down Expand Up @@ -2575,6 +2580,7 @@ def _restore_session_continuation_state(
if snapshot is None or snapshot.session_state is None:
return
serialized_state = copy.deepcopy(snapshot.session_state)
serialized_state.pop(_APPROVAL_SNAPSHOT_STATE_KEY, None)
service_session_id = serialized_state.pop(_PROVIDER_SERVICE_SESSION_ID_STATE_KEY, None)
for key in excluded_state_keys:
serialized_state.pop(key, None)
Expand Down Expand Up @@ -2641,6 +2647,7 @@ def _request_state_protected_keys(agent: SupportsAgentRun) -> set[str]:
agent_middleware = categorize_middleware(getattr(agent, "middleware", None))["agent"]
return {
_TOOL_APPROVAL_STATE_KEY,
_APPROVAL_SNAPSHOT_STATE_KEY,
InMemoryHistoryProvider.DEFAULT_SOURCE_ID,
MESSAGE_INJECTION_PENDING_MESSAGES_STATE_KEY,
*(provider.source_id for provider in context_providers),
Expand Down Expand Up @@ -2730,6 +2737,7 @@ def _serialize_session_continuation_state(
excluded_keys = {
*shared_state_keys,
_TOOL_APPROVAL_STATE_KEY,
_APPROVAL_SNAPSHOT_STATE_KEY,
_PROVIDER_SERVICE_SESSION_ID_STATE_KEY,
*(provider.source_id for provider in context_providers if isinstance(provider, HistoryProvider)),
}
Expand Down Expand Up @@ -3004,6 +3012,12 @@ async def _run_agent_stream(
)

stored_snapshot = snapshot_session.stored
if config.durable_approvals and not snapshot_session.enabled:
raise ValueError("durable_approvals requires a scoped snapshot store.")
if config.durable_approvals and stored_snapshot is not None and stored_snapshot.session_state is not None:
authority = stored_snapshot.session_state.get(_APPROVAL_SNAPSHOT_STATE_KEY)
if authority is not None:
approval_state_store.restore_thread(approval_thread_id, authority)
stored_pending_approval_interrupt_ids: set[str] = set()
seeded_resume_from_snapshot = False
if stored_snapshot is not None:
Expand Down Expand Up @@ -3342,6 +3356,18 @@ async def _run_agent_stream(
_restore_tool_approval_state(session, approval_state_store, approval_thread_id)
approval_middleware_pipeline = _approval_observer_middleware_pipeline(agent, session)

def private_snapshot_state() -> dict[str, Any] | None:
continuation = _safe_serialize_session_continuation_state(
session,
agent,
shared_state_keys=set(flow.current_state).difference(protected_session_state_keys),
include_service_session_id=config.use_service_session,
)
if config.durable_approvals:
continuation = continuation or {}
continuation[_APPROVAL_SNAPSHOT_STATE_KEY] = approval_state_store.export_thread(approval_thread_id)
return continuation

async def save_thread_snapshot(
*,
persisted_messages: list[dict[str, Any]],
Expand All @@ -3353,12 +3379,7 @@ async def save_thread_snapshot(
messages=_bound_host_payload_history(_persistable_host_payload_history(persisted_messages)),
state=state,
interrupt=interrupt,
session_state=_safe_serialize_session_continuation_state(
session,
agent,
shared_state_keys=set(flow.current_state).difference(protected_session_state_keys),
include_service_session_id=config.use_service_session,
),
session_state=private_snapshot_state(),
)

authenticated_cancellations = [
Expand Down Expand Up @@ -3393,12 +3414,7 @@ async def save_thread_snapshot(
messages=stored_after_cancellation.messages,
state=stored_after_cancellation.state,
interrupt=stored_after_cancellation.interrupt,
session_state=_safe_serialize_session_continuation_state(
session,
agent,
shared_state_keys=set(flow.current_state).difference(protected_session_state_keys),
include_service_session_id=config.use_service_session,
),
session_state=private_snapshot_state(),
)
yield _build_run_finished_event(run_id=run_id, thread_id=thread_id)
return
Expand Down Expand Up @@ -3533,6 +3549,11 @@ async def save_thread_snapshot(
code="APPROVAL_INVOCATION_DISABLED",
)
return
if authorized_executions and config.durable_approvals:
# Commit the claim before any side effect. A crash or failed terminal save
# leaves an indeterminate claim on cold restore, never a fresh grant.
_save_tool_approval_state(session, approval_state_store, approval_thread_id)
await snapshot_session.save_approval_claim(session_state=private_snapshot_state() or {})
validated_approved_responses: list[Content] = []
replacement_approval_requests: list[Content] = []
newly_resolved_approval_results = await _resolve_approval_responses(
Expand Down
Loading
Loading