agent-framework-ag-ui 1.2.2__tar.gz → 1.3.0__tar.gz

{agent_framework_ag_ui-1.2.2 → agent_framework_ag_ui-1.3.0}/AGENTS.md

@@ -8,6 +8,8 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
 - **`AgentFrameworkWorkflow`** - Wraps native `Workflow` objects, or accepts `workflow_factory(thread_id)` for thread-scoped workflow instances without subclassing
 - **`AGUIChatClient`** - Chat client that speaks AG-UI protocol
 - **`AGUIHttpService`** - HTTP service for AG-UI endpoints
+- **`agent_framework_messages_to_agui_host_history()`** - Converts persisted Agent Framework messages to bounded
+  AG-UI Host history while retaining MCP widget payloads and model replay metadata
 - **`AGUIEventConverter`** - Converts between Agent Framework and AG-UI events
 - **`add_agent_framework_fastapi_endpoint()`** - Add AG-UI endpoint to FastAPI app (`SupportsAgentRun` or `Workflow`)
 - **`InMemoryAGUIThreadSnapshotStore`** - Memory-only latest AG-UI Thread Snapshot store for local development, demos, and tests
@@ -50,6 +52,13 @@ AG-UI protocol integration for building agent UIs with the AG-UI standard.
 - AG-UI Thread and Run ids are client-owned protocol correlation ids. Service-session mode stores provider conversation
   or response ids privately in the thread snapshot. Set `service_session_id_from_thread_id=True` only for compatibility
   when the application intentionally uses a provider continuation id as its AG-UI Thread id.
+- A configured Snapshot Scope and the client-owned Thread id are combined into a deterministic internal
+  `AgentSession.session_id`. Keep the raw Thread id for protocol events and snapshot addressing so equal Thread ids
+  in different trusted scopes cannot collide in context-provider state. The deprecated
+  `legacy_session_id_from_thread_id=True` compatibility option preserves raw provider keys only for explicit
+  migrations and must warn because it disables that isolation; it is unsafe for shared multi-tenant deployments.
+  A configured endpoint resolver must return a non-empty string. Reject invalid results before accessing state or
+  invoking the runner; absence of a resolver, not an invalid result, selects intentionally unscoped operation.
 - `confirm_changes` snapshot cleanup resolves the synthetic confirmation back to its original `function_call_id`;
   it must never concatenate unrelated tool results or record accepted changes without a matching real result.
 - SSE keepalive is endpoint-owned transport behavior configured through

{agent_framework_ag_ui-1.2.2 → agent_framework_ag_ui-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-framework-ag-ui
-Version: 1.2.2
+Version: 1.3.0
 Summary: AG-UI protocol integration for Agent Framework
 Project-URL: homepage, https://aka.ms/agent-framework
 Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
@@ -19,8 +19,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: ag-ui-protocol<0.2,>=0.1.19
-Requires-Dist: agent-framework-core<2,>=1.17.0
-Requires-Dist: fastapi<0.140.0,>=0.121.0
+Requires-Dist: agent-framework-core<2,>=1.18.0
+Requires-Dist: fastapi<0.142.0,>=0.121.0
 Requires-Dist: httpx<1,>=0.28.1
 Requires-Dist: sse-starlette<4,>=3.4.5
 Requires-Dist: uvicorn[standard]<1,>=0.30.0
@@ -271,12 +271,14 @@ Review focus: whether these names are the right stable contract for Python users
 
 | 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__` |
+| `agent_framework.ag_ui` facade | `AgentFrameworkAgent`, `AgentFrameworkWorkflow`, `AGUIChatClient`, `AGUIEventConverter`, `AGUIHttpService`, `AGUIThreadSnapshot`, `AGUIThreadSnapshotStore`, `InMemoryAGUIThreadSnapshotStore`, `SnapshotScopeResolver`, `add_agent_framework_fastapi_endpoint`, `state_carrier`, `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.
 
+Use `state_carrier(...)` to mark JSON content that should be sent in the AG-UI request's `state` field rather than as a model-visible document. The client removes explicitly marked carriers from all client-controlled history and uses the most recent carrier. Ordinary `application/json` content remains a document. For migration, pass `allow_legacy_state_carrier=True` in `AGUIChatOptions` to recognize the deprecated final single-content base64 JSON convention; mixed text and document messages remain model-visible. This client-only option emits a `DeprecationWarning` when the legacy convention is used and is not sent to the remote server.
+
 ## Features
 
 This integration supports all 7 AG-UI features:
@@ -410,10 +412,27 @@ A frontend can then hydrate the latest stored snapshot for the scoped thread:
 
 Endpoint configuration requires `snapshot_scope_resolver` whenever a snapshot store is configured, including when
 the store is already set on a pre-wrapped `AgentFrameworkAgent` or `AgentFrameworkWorkflow`. The resolver returns
-the application-defined Snapshot Scope used with the AG-UI Thread id as the storage key. When using
-`AgentFrameworkWorkflow(workflow_factory=...)`, the same resolver also scopes the in-memory workflow cache even
-without a snapshot store; provide it in multi-user deployments so two users who submit the same `threadId` do not
-share a live `Workflow` instance.
+the application-defined Snapshot Scope used with the AG-UI Thread id as the storage key. The endpoint also derives
+the internal `AgentSession.session_id` from this trusted scope and the client-owned Thread id, so context providers
+cannot merge server-side state for equal Thread ids in different scopes. The raw Thread id remains unchanged in
+AG-UI events and snapshot operations. When using `AgentFrameworkWorkflow(workflow_factory=...)`, the same resolver
+also scopes the in-memory workflow cache even without a snapshot store; provide it in multi-user deployments so two
+users who submit the same `threadId` do not share a live `Workflow` instance.
+
+Authenticate and authorize the current scope on every request, including hydration and approval resume, rather than
+trusting a scope supplied through Shared State or forwarded properties. A configured resolver must return a non-empty
+string. Returning `None`, an empty string, or another type fails the request with a generic HTTP 500 configuration
+error before accessing snapshots, approval state, or context providers. Resolver failures never fall back to unscoped
+operation. Valid scope strings are used exactly as returned, without trimming or normalization. An endpoint without a
+resolver remains intentionally unscoped; it must not share session-keyed storage across distinct authorization scopes.
+Use endpoint authentication dependencies to reject unauthorized requests before scope resolution.
+
+Existing applications that need time to migrate provider records from raw Thread-id keys can temporarily wrap the
+agent with `AgentFrameworkAgent(..., legacy_session_id_from_thread_id=True)`. This deprecated compatibility option
+emits a `DeprecationWarning` and disables Snapshot Scope isolation for context-provider state. It is not safe for a
+shared multi-tenant deployment, even with a trusted resolver. Keep it disabled when establishing scope isolation.
+
+### Request state and snapshot authority
 
 For hosted agents, request Shared State is also available through `AgentSession.state` during that run, whether or
 not snapshot persistence is configured. Request values are untrusted per-run context: they overlay ordinary restored

{agent_framework_ag_ui-1.2.2 → agent_framework_ag_ui-1.3.0}/README.md

@@ -239,12 +239,14 @@ Review focus: whether these names are the right stable contract for Python users
 
 | 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__` |
+| `agent_framework.ag_ui` facade | `AgentFrameworkAgent`, `AgentFrameworkWorkflow`, `AGUIChatClient`, `AGUIEventConverter`, `AGUIHttpService`, `AGUIThreadSnapshot`, `AGUIThreadSnapshotStore`, `InMemoryAGUIThreadSnapshotStore`, `SnapshotScopeResolver`, `add_agent_framework_fastapi_endpoint`, `state_carrier`, `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.
 
+Use `state_carrier(...)` to mark JSON content that should be sent in the AG-UI request's `state` field rather than as a model-visible document. The client removes explicitly marked carriers from all client-controlled history and uses the most recent carrier. Ordinary `application/json` content remains a document. For migration, pass `allow_legacy_state_carrier=True` in `AGUIChatOptions` to recognize the deprecated final single-content base64 JSON convention; mixed text and document messages remain model-visible. This client-only option emits a `DeprecationWarning` when the legacy convention is used and is not sent to the remote server.
+
 ## Features
 
 This integration supports all 7 AG-UI features:
@@ -378,10 +380,27 @@ A frontend can then hydrate the latest stored snapshot for the scoped thread:
 
 Endpoint configuration requires `snapshot_scope_resolver` whenever a snapshot store is configured, including when
 the store is already set on a pre-wrapped `AgentFrameworkAgent` or `AgentFrameworkWorkflow`. The resolver returns
-the application-defined Snapshot Scope used with the AG-UI Thread id as the storage key. When using
-`AgentFrameworkWorkflow(workflow_factory=...)`, the same resolver also scopes the in-memory workflow cache even
-without a snapshot store; provide it in multi-user deployments so two users who submit the same `threadId` do not
-share a live `Workflow` instance.
+the application-defined Snapshot Scope used with the AG-UI Thread id as the storage key. The endpoint also derives
+the internal `AgentSession.session_id` from this trusted scope and the client-owned Thread id, so context providers
+cannot merge server-side state for equal Thread ids in different scopes. The raw Thread id remains unchanged in
+AG-UI events and snapshot operations. When using `AgentFrameworkWorkflow(workflow_factory=...)`, the same resolver
+also scopes the in-memory workflow cache even without a snapshot store; provide it in multi-user deployments so two
+users who submit the same `threadId` do not share a live `Workflow` instance.
+
+Authenticate and authorize the current scope on every request, including hydration and approval resume, rather than
+trusting a scope supplied through Shared State or forwarded properties. A configured resolver must return a non-empty
+string. Returning `None`, an empty string, or another type fails the request with a generic HTTP 500 configuration
+error before accessing snapshots, approval state, or context providers. Resolver failures never fall back to unscoped
+operation. Valid scope strings are used exactly as returned, without trimming or normalization. An endpoint without a
+resolver remains intentionally unscoped; it must not share session-keyed storage across distinct authorization scopes.
+Use endpoint authentication dependencies to reject unauthorized requests before scope resolution.
+
+Existing applications that need time to migrate provider records from raw Thread-id keys can temporarily wrap the
+agent with `AgentFrameworkAgent(..., legacy_session_id_from_thread_id=True)`. This deprecated compatibility option
+emits a `DeprecationWarning` and disables Snapshot Scope isolation for context-provider state. It is not safe for a
+shared multi-tenant deployment, even with a trusted resolver. Keep it disabled when establishing scope isolation.
+
+### Request state and snapshot authority
 
 For hosted agents, request Shared State is also available through `AgentSession.state` during that run, whether or
 not snapshot persistence is configured. Request values are untrusted per-run context: they overlay ordinary restored

{agent_framework_ag_ui-1.2.2 → agent_framework_ag_ui-1.3.0}/agent_framework_ag_ui/__init__.py

@@ -10,6 +10,7 @@ from ._client import AGUIChatClient
 from ._endpoint import add_agent_framework_fastapi_endpoint
 from ._event_converters import AGUIEventConverter
 from ._http_service import AGUIHttpService
+from ._message_adapters import agent_framework_messages_to_agui_host_history
 from ._snapshots import (
     DEFAULT_MAX_THREAD_SNAPSHOTS,
     AGUIThreadID,
@@ -19,7 +20,7 @@ from ._snapshots import (
     SnapshotScope,
     SnapshotScopeResolver,
 )
-from ._state import state_update
+from ._state import state_carrier, state_update
 from ._types import AgentState, AGUIChatOptions, AGUIRequest, PredictStateConfig, RunMetadata
 from ._workflow import AgentFrameworkWorkflow, WorkflowFactory
 
@@ -39,6 +40,7 @@ __all__ = [
     "AgentFrameworkWorkflow",
     "WorkflowFactory",
     "add_agent_framework_fastapi_endpoint",
+    "agent_framework_messages_to_agui_host_history",
     "AGUIChatClient",
     "AGUIChatOptions",
     "AGUIEventConverter",
@@ -55,6 +57,7 @@ __all__ = [
     "SnapshotScopeResolver",
     "DEFAULT_MAX_THREAD_SNAPSHOTS",
     "DEFAULT_TAGS",
+    "state_carrier",
     "state_update",
     "__version__",
     # A2UI (lazy — require ag-ui-a2ui-toolkit)

{agent_framework_ag_ui-1.2.2 → agent_framework_ag_ui-1.3.0}/agent_framework_ag_ui/_agent.py

@@ -2,6 +2,7 @@
 
 """AgentFrameworkAgent wrapper for AG-UI protocol."""
 
+import warnings
 from collections.abc import AsyncGenerator
 from typing import Any, cast
 
@@ -27,6 +28,8 @@ class AgentConfig:
         snapshot_store: AGUIThreadSnapshotStore | None = None,
         a2ui_config: dict[str, Any] | None = None,
         service_session_id_from_thread_id: bool = False,
+        emit_messages_snapshot: bool = True,
+        legacy_session_id_from_thread_id: bool = False,
     ):
         """Initialize agent configuration.
 
@@ -45,6 +48,11 @@ class AgentConfig:
             require_confirmation: Whether predictive updates require user confirmation before applying
             a2ui_config: Optional backend A2UI config consumed by auto-injection
                 (``forwardedProps.injectA2UITool``). See ``plan_a2ui_injection``.
+            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.
+            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.
         """
         self.state_schema = self._normalize_state_schema(state_schema)
         self.predict_state_config = predict_state_config or {}
@@ -53,6 +61,8 @@ class AgentConfig:
         self.require_confirmation = require_confirmation
         self.snapshot_store = snapshot_store
         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
 
     @staticmethod
     def _normalize_state_schema(state_schema: Any | None) -> dict[str, Any]:
@@ -101,6 +111,8 @@ class AgentFrameworkAgent:
         snapshot_store: AGUIThreadSnapshotStore | None = None,
         a2ui_config: dict[str, Any] | None = None,
         service_session_id_from_thread_id: bool = False,
+        emit_messages_snapshot: bool = True,
+        legacy_session_id_from_thread_id: bool = False,
     ):
         """Initialize the AG-UI compatible agent wrapper.
 
@@ -120,7 +132,21 @@ class AgentFrameworkAgent:
             snapshot_store: Optional AG-UI Thread Snapshot store. Snapshot persistence remains inactive unless
                 endpoint setup also provides an explicit Snapshot Scope resolver.
             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.
+            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.
         """
+        if legacy_session_id_from_thread_id:
+            warnings.warn(
+                "legacy_session_id_from_thread_id=True is deprecated because client-owned AG-UI Thread ids "
+                "do not isolate server-side state. Migrate provider state to scoped session ids and remove "
+                "this option.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         self.agent = agent
         self.name = name or getattr(agent, "name", "agent")
         self.description = description or getattr(agent, "description", "")
@@ -133,6 +159,8 @@ class AgentFrameworkAgent:
             require_confirmation=require_confirmation,
             snapshot_store=snapshot_store,
             a2ui_config=a2ui_config,
+            emit_messages_snapshot=emit_messages_snapshot,
+            legacy_session_id_from_thread_id=legacy_session_id_from_thread_id,
         )
 
         # Server-side Approval State. Populated when approval requests are emitted