Python: [BREAKING]: Canonicalize AG-UI interrupt and resume handling

python/packages/ag-ui/AGENTS.md

@@ -16,7 +16,7 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
 
 - **`AGUIRequest`** / **`AGUIChatOptions`** - Request types
 - **`AGUIThreadSnapshot`** / **`AGUIThreadSnapshotStore`** - Replayable thread snapshot model and scoped async store protocol
-- **`availableInterrupts` / `resume`** - Optional interrupt configuration and continuation payloads
+- **`availableInterrupts` / `resume`** - Optional canonical AG-UI `Interrupt` and `ResumeEntry` protocol data
 - **`AgentState`** / **`RunMetadata`** - State management types
 - **`PredictStateConfig`** - Configuration for state prediction
 
@@ -26,7 +26,8 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
 - Usage metadata from `Content(type="usage")` is surfaced as `CUSTOM` events with `name="usage"`.
 - Inbound custom event aliases are accepted: `CUSTOM`, `CUSTOM_EVENT`, and `custom_event`.
 - Multimodal user inputs support both legacy (`text`, `binary`) and draft-style (`image`, `audio`, `video`, `document`) shapes.
-- `RUN_FINISHED.interrupt` can be emitted for pause/request-info flows, and interruption metadata is preserved in converters.
+- Interrupted runs complete with `RUN_FINISHED.outcome.type == "interrupt"` and canonical `outcome.interrupts`; do not document or add new flows that depend on the legacy top-level `RUN_FINISHED.interrupt` field.
+- `Interrupt` and `ResumeEntry` come from the `ag-ui-protocol` package (`ag_ui.core`), not from an Agent Framework-specific interrupt model.
 
 ## Usage
 

python/packages/ag-ui/README.md

@@ -97,7 +97,7 @@ The `AGUIChatClient` supports:
 - Hybrid tool execution (client-side + server-side tools)
 - Automatic thread management for conversation continuity
 - Integration with `Agent` for client-side history management
-- Interrupt metadata passthrough (`availableInterrupts` and `resume`)
+- Canonical interrupt/resume passthrough (`availableInterrupts` and `resume`)
 
 ## Tool Return Helpers
 
@@ -132,6 +132,87 @@ async def get_weather(city: str) -> Content:
   - Thread management and conversation continuity
 - **[Examples](agent_framework_ag_ui_examples/)** - Complete examples for AG-UI features
 
+## Interrupts and Resume
+
+Agent Framework AG-UI uses the canonical AG-UI interrupt protocol. Paused agent approval and workflow
+`request_info` runs finish with `RUN_FINISHED.outcome.type == "interrupt"` and a non-empty
+`RUN_FINISHED.outcome.interrupts` array. Agent Framework does not define a separate interrupt model; use
+`ag_ui.core.Interrupt` and `ag_ui.core.ResumeEntry` when constructing typed request data in Python.
+
+Tool approval interrupts use `reason: "tool_call"` and include `toolCallId` when the pause is bound to a tool call.
+Workflow `request_info` interrupts use `reason: "input_required"`. Framework-specific details needed for resume
+validation live in each interrupt's `metadata`, while generic clients can render the human-readable `message` and
+`responseSchema`.
+
+Interrupted terminal event shape:
+
+```json
+{
+  "type": "RUN_FINISHED",
+  "outcome": {
+    "type": "interrupt",
+    "interrupts": [
+      {
+        "id": "approval_1",
+        "reason": "tool_call",
+        "message": "Approve tool call get_weather?",
+        "toolCallId": "tool_call_1",
+        "responseSchema": {
+          "type": "object",
+          "properties": {
+            "approved": { "type": "boolean" },
+            "arguments": { "type": "object" }
+          },
+          "required": ["approved"]
+        },
+        "metadata": {
+          "agentFramework": {
+            "kind": "function_approval"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+Resume the paused thread with a canonical `resume` array. Each entry addresses exactly one open interrupt by
+`interruptId`; `status` is `resolved` or `cancelled`; resolved entries carry the approval or workflow response payload.
+
+```json
+{
+  "threadId": "thread-1",
+  "messages": [],
+  "resume": [
+    {
+      "interruptId": "approval_1",
+      "status": "resolved",
+      "payload": {
+        "approved": true
+      }
+    }
+  ]
+}
+```
+
+This is a clean release-candidate breaking change before `1.0.0`: new interrupted runs use
+`RUN_FINISHED.outcome.interrupts` and do not emit a stable top-level `RUN_FINISHED.interrupt` field. Normal
+non-interrupted runs continue to finish with valid `RUN_FINISHED` terminal events.
+
+## Public API Review Notes
+
+The Python package is currently in release candidate stage and is targeting the released `1.0.0` API surface. The preferred application import path is `agent_framework.ag_ui`; direct package imports from `agent_framework_ag_ui` are also supported.
+
+Review focus: whether these names are the right stable contract for Python users, and whether the protocol interrupt fields below match AG-UI's expected pause/resume shape.
+
+| Surface | Public exports |
+| --- | --- |
+| `agent_framework.ag_ui` facade | `AgentFrameworkAgent`, `AgentFrameworkWorkflow`, `AGUIChatClient`, `AGUIEventConverter`, `AGUIHttpService`, `AGUIThreadSnapshot`, `AGUIThreadSnapshotStore`, `InMemoryAGUIThreadSnapshotStore`, `SnapshotScopeResolver`, `add_agent_framework_fastapi_endpoint`, `state_update`, `__version__` |
+| Direct `agent_framework_ag_ui` package | Facade exports plus `AGUIChatOptions`, `AGUIRequest`, `AGUIThreadID`, `AgentState`, `DEFAULT_MAX_THREAD_SNAPSHOTS`, `DEFAULT_TAGS`, `PredictStateConfig`, `RunMetadata`, `SnapshotScope`, `WorkflowFactory` |
+| AG-UI protocol package (`ag_ui.core`) | `Interrupt`, `ResumeEntry`, `RunFinishedInterruptOutcome`, and related run outcome models |
+
+Interrupt support is protocol data rather than a separate Agent Framework Python class. Requests accept canonical `availableInterrupts`/`available_interrupts` and `resume` values; `AGUIChatClient` and `AGUIHttpService.post_run(...)` forward those fields with AG-UI wire aliases; agent approval and workflow `request_info` pauses emit `RUN_FINISHED.outcome.interrupts`; `AGUIEventConverter` preserves canonical interrupt outcome metadata on the final `ChatResponseUpdate`; and thread snapshot hydration replays the canonical interrupt outcome when a scoped snapshot stores an unresolved pause.
+
 ## Features
 
 This integration supports all 7 AG-UI features:
@@ -149,7 +230,7 @@ Additional compatibility and draft support:
 - Workflow-to-AG-UI event mapping (run/step/activity/tool/custom events)
 - Custom event compatibility for inbound `CUSTOM`, `CUSTOM_EVENT`, and `custom_event`
 - Pragmatic multimodal input parsing for both legacy (`binary`) and draft media-part shapes
-- Pragmatic interrupt/resume handling (`availableInterrupts`, `resume`, and `RUN_FINISHED.interrupt`)
+- Canonical interrupt/resume handling (`availableInterrupts`, `resume`, and `RUN_FINISHED.outcome.interrupts`)
 
 ## Security: Authentication & Authorization
 
@@ -206,7 +287,7 @@ unless you provide a `snapshot_store`.
 Thread snapshots let an AG-UI frontend recover replayable UI state after a refresh. When snapshot persistence is
 enabled, the endpoint stores the latest replayable snapshot for an AG-UI Thread within an application-defined
 Snapshot Scope. A Hydrate Request is an AG-UI request with a known `threadId`, `messages: []`, and no `resume`
-payload. Hydration replays the stored Shared State, message snapshot, and interruption metadata when available,
+payload. Hydration replays the stored Shared State, message snapshot, and canonical interrupt outcome when available,
 then finishes without invoking the wrapped agent or workflow.
 
 Use the built-in in-memory store for local development, demos, and tests:
@@ -255,7 +336,7 @@ and choose a Snapshot Scope that represents the app's real access boundary, such
 or workspace. Do not rely on untrusted client-provided fields by themselves to choose that boundary.
 
 Stored snapshots are untrusted application data with confidentiality impact. They may contain sensitive user text,
-model output, tool results, function arguments, UI payloads, Shared State, and interruption data. The built-in
+model output, tool results, function arguments, UI payloads, Shared State, and interrupt data. The built-in
 `InMemoryAGUIThreadSnapshotStore` is in-memory only, process-local, bounded, latest-only, and not durable production
 storage. It is cleared on process restart and is not shared across workers.
 

python/packages/ag-ui/agent_framework_ag_ui/_agent.py

@@ -9,7 +9,7 @@
 from ag_ui.core import BaseEvent
 from agent_framework import SupportsAgentRun
 
-from ._agent_run import PendingApprovalEntry, run_agent_stream
+from ._agent_run import PendingApprovalEntry, PendingApprovalKey, run_agent_stream
 from ._snapshots import AGUIThreadSnapshotStore
 
 
@@ -112,11 +112,11 @@ def __init__(
         )
 
         # Server-side registry of pending approval requests.
-        # Keys are "{thread_id}:{request_id}", values are the function name.
+        # Keys are (thread_id, request_id), values are the function name.
         # Populated when approval requests are emitted; consumed when responses arrive.
         # Prevents bypass, function name spoofing, and replay attacks.
         # Bounded to prevent unbounded growth from abandoned approval requests.
-        self._pending_approvals: OrderedDict[str, PendingApprovalEntry] = OrderedDict()
+        self._pending_approvals: OrderedDict[PendingApprovalKey, PendingApprovalEntry] = OrderedDict()
         self._pending_approvals_max_size: int = 10_000
 
     @property