Merge branch 'main' into feature/python-foundry-hosted-agent-vnext

python/.env.example

@@ -38,6 +38,9 @@ COPILOTSTUDIOAGENT__AGENTAPPID=""
 # Anthropic
 ANTHROPIC_API_KEY=""
 ANTHROPIC_MODEL=""
+# Google Gemini
+GEMINI_API_KEY=""
+GEMINI_MODEL=""
 # Ollama
 OLLAMA_ENDPOINT=""
 OLLAMA_MODEL=""

python/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **agent-framework-azure-cosmos**: [BREAKING] `CosmosCheckpointStorage` now uses restricted pickle deserialization by default, matching `FileCheckpointStorage` behavior. If your checkpoints contain application-defined types, pass them via `allowed_checkpoint_types=["my_app.models:MyState"]`. ([#5200](https://github.com/microsoft/agent-framework/issues/5200))
+
 ## [1.0.1] - 2026-04-09
 
 ### Added

python/PACKAGE_STATUS.md

@@ -31,6 +31,7 @@ Status is grouped into these buckets:
 | `agent-framework-durabletask` | `python/packages/durabletask` | `beta` |
 | `agent-framework-foundry` | `python/packages/foundry` | `released` |
 | `agent-framework-foundry-local` | `python/packages/foundry_local` | `beta` |
+| `agent-framework-gemini` | `python/packages/gemini` | `alpha` |
 | `agent-framework-github-copilot` | `python/packages/github_copilot` | `beta` |
 | `agent-framework-lab` | `python/packages/lab` | `beta` |
 | `agent-framework-mem0` | `python/packages/mem0` | `beta` |

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

@@ -9,6 +9,7 @@ from ._client import AGUIChatClient
 from ._endpoint import add_agent_framework_fastapi_endpoint
 from ._event_converters import AGUIEventConverter
 from ._http_service import AGUIHttpService
+from ._state import state_update
 from ._types import AgentState, AGUIChatOptions, AGUIRequest, PredictStateConfig, RunMetadata
 from ._workflow import AgentFrameworkWorkflow, WorkflowFactory
 
@@ -34,5 +35,6 @@ __all__ = [
     "PredictStateConfig",
     "RunMetadata",
     "DEFAULT_TAGS",
+    "state_update",
     "__version__",
 ]

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

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import json
 import logging
+from collections.abc import Mapping
 from dataclasses import dataclass, field
 from typing import Any, cast
 
@@ -31,6 +32,7 @@ from ag_ui.core import (
 from agent_framework import Content
 
 from ._orchestration._predictive_state import PredictiveStateHandler
+from ._state import TOOL_RESULT_STATE_KEY
 from ._utils import generate_event_id, make_json_safe
 
 logger = logging.getLogger(__name__)
@@ -233,16 +235,66 @@ def _emit_tool_call(
     return events
 
 
+def _extract_tool_result_state(content: Content) -> dict[str, Any] | None:
+    """Extract a deterministic AG-UI state update from a tool-result ``Content``.
+
+    Tools using :func:`agent_framework_ag_ui.state_update` carry the state
+    payload in ``additional_properties[TOOL_RESULT_STATE_KEY]`` on the inner
+    text item produced by ``parse_result``. We also check the outer
+    function_result content's ``additional_properties`` for robustness.
+
+    If multiple items carry state, they are merged in order so later items
+    override earlier ones (plain ``dict.update`` semantics).
+
+    Returns:
+        The merged state dict to apply, or ``None`` if no state update is
+        present.
+    """
+    merged: dict[str, Any] | None = None
+
+    outer_ap = getattr(content, "additional_properties", None) or {}
+    outer_state = outer_ap.get(TOOL_RESULT_STATE_KEY)
+    if isinstance(outer_state, dict):
+        merged = dict(outer_state)
+
+    for item in content.items or ():
+        item_ap = getattr(item, "additional_properties", None) or {}
+        item_state = item_ap.get(TOOL_RESULT_STATE_KEY)
+        if isinstance(item_state, dict):
+            if merged is None:
+                merged = dict(item_state)
+            else:
+                merged.update(item_state)
+
+    return merged
+
+
 def _emit_tool_result_common(
     call_id: str,
     raw_result: Any,
     flow: FlowState,
     predictive_handler: PredictiveStateHandler | None = None,
+    *,
+    state_update: Mapping[str, Any] | None = None,
 ) -> list[BaseEvent]:
     """Shared helper for emitting ToolCallEnd + ToolCallResult events and performing FlowState cleanup.
 
     Both ``_emit_tool_result`` (standard function results) and ``_emit_mcp_tool_result``
     (MCP server tool results) delegate to this function.
+
+    Args:
+        call_id: Tool call identifier.
+        raw_result: The stringified tool result content sent back to the LLM.
+        flow: Current ``FlowState``.
+        predictive_handler: Optional predictive state handler driven by
+            ``predict_state_config``.
+        state_update: Optional deterministic state snapshot produced by a tool
+            returning :func:`agent_framework_ag_ui.state_update`. When present,
+            it is merged into ``flow.current_state`` and a ``StateSnapshotEvent``
+            is emitted after the ``ToolCallResult`` event. When both
+            ``predictive_handler`` and ``state_update`` are active, predictive
+            updates are applied first, then the deterministic merge, and a
+            single coalesced ``StateSnapshotEvent`` is emitted.
     """
     events: list[BaseEvent] = []
 
@@ -271,8 +323,18 @@ def _emit_tool_result_common(
 
     if predictive_handler:
         predictive_handler.apply_pending_updates()
-        if flow.current_state:
-            events.append(StateSnapshotEvent(snapshot=flow.current_state))
+
+    if state_update:
+        flow.current_state.update(state_update)
+        logger.debug(
+            "Emitted deterministic tool-result StateSnapshotEvent for call_id=%s (keys=%s)",
+            call_id,
+            list(state_update.keys()),
+        )
+
+    # Emit a single coalesced snapshot when either mechanism updated state.
+    if (predictive_handler or state_update) and flow.current_state:
+        events.append(StateSnapshotEvent(snapshot=flow.current_state))
 
     flow.tool_call_id = None
     flow.tool_call_name = None
@@ -295,7 +357,14 @@ def _emit_tool_result(
     if not content.call_id:
         return []
     raw_result = content.result if content.result is not None else ""
-    return _emit_tool_result_common(content.call_id, raw_result, flow, predictive_handler)
+    state_update = _extract_tool_result_state(content)
+    return _emit_tool_result_common(
+        content.call_id,
+        raw_result,
+        flow,
+        predictive_handler,
+        state_update=state_update,
+    )
 
 
 def _emit_approval_request(
@@ -460,7 +529,14 @@ def _emit_mcp_tool_result(
         logger.warning("MCP tool result content missing call_id, skipping")
         return []
     raw_output = content.output if content.output is not None else ""
-    return _emit_tool_result_common(content.call_id, raw_output, flow, predictive_handler)
+    state_update = _extract_tool_result_state(content)
+    return _emit_tool_result_common(
+        content.call_id,
+        raw_output,
+        flow,
+        predictive_handler,
+        state_update=state_update,
+    )
 
 
 def _close_reasoning_block(flow: FlowState) -> list[BaseEvent]:

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

@@ -0,0 +1,84 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Deterministic tool-driven AG-UI state updates.
+
+Tools wired into the :mod:`agent_framework_ag_ui` endpoint can push a
+deterministic state update by returning :func:`state_update`. Unlike
+``predict_state_config`` — which emits ``StateDeltaEvent``s optimistically from
+LLM-predicted tool call arguments — ``state_update`` runs *after* the tool
+executes, so the AG-UI state always reflects the tool's actual return value.
+
+See issue https://github.com/microsoft/agent-framework/issues/3167 for the
+motivating discussion.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from agent_framework import Content
+
+__all__ = ["TOOL_RESULT_STATE_KEY", "state_update"]
+
+
+TOOL_RESULT_STATE_KEY = "__ag_ui_tool_result_state__"
+"""Reserved ``Content.additional_properties`` key used to carry a tool-driven
+state snapshot from a tool return value through to the AG-UI emitter."""
+
+
+def state_update(
+    text: str = "",
+    *,
+    state: Mapping[str, Any],
+) -> Content:
+    """Build a tool return value that deterministically updates AG-UI shared state.
+
+    Return the result of this helper from an agent tool to push a state update
+    to AG-UI clients using the actual tool output, rather than LLM-predicted
+    tool arguments.
+
+    When the AG-UI endpoint emits the tool result, it will:
+
+    * Forward ``text`` to the LLM as the normal ``function_result`` content.
+    * Merge ``state`` into ``FlowState.current_state``.
+    * Emit a deterministic ``StateSnapshotEvent`` after the ``ToolCallResult``
+      event so frontends observe the updated state deterministically. If
+      predictive state is enabled, a predictive snapshot may be emitted first.
+
+    Example:
+        .. code-block:: python
+
+            from agent_framework import tool
+            from agent_framework_ag_ui import state_update
+
+
+            @tool
+            async def get_weather(city: str) -> Content:
+                data = await _fetch_weather(city)
+                return state_update(
+                    text=f"Weather in {city}: {data['temp']}°C {data['conditions']}",
+                    state={"weather": {"city": city, **data}},
+                )
+
+    Args:
+        text: Text passed back to the LLM as the ``function_result`` content.
+            Defaults to an empty string for tools whose only output is a state
+            update.
+        state: A mapping merged into the AG-UI shared state via JSON-compatible
+            ``dict.update`` semantics. Nested dicts are replaced, not deep-merged.
+
+    Returns:
+        A ``Content`` object with ``type="text"``. The state payload rides in
+        ``additional_properties`` under :data:`TOOL_RESULT_STATE_KEY` and is
+        extracted by the AG-UI emitter.
+
+    Raises:
+        TypeError: If ``state`` is not a ``Mapping``.
+    """
+    if not isinstance(state, Mapping):
+        raise TypeError(f"state_update() 'state' must be a Mapping, got {type(state).__name__}")
+    return Content.from_text(
+        text,
+        additional_properties={TOOL_RESULT_STATE_KEY: dict(state)},
+    )

python/packages/ag-ui/agent_framework_ag_ui_examples/agents/weather_state_agent.py

@@ -0,0 +1,92 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Deterministic tool-driven AG-UI state example.
+
+This sample demonstrates how a tool can push a *deterministic* state update
+to the AG-UI frontend based on its actual return value — in contrast to
+``predict_state_config`` which fires optimistically from LLM-predicted tool
+call arguments. See issue https://github.com/microsoft/agent-framework/issues/3167.
+
+The :func:`agent_framework_ag_ui.state_update` helper wraps a text result
+together with a state snapshot. When a tool returns one of these, the AG-UI
+endpoint merges the snapshot into the shared state and emits a
+``StateSnapshotEvent`` after the tool result.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_framework import Agent, Content, SupportsChatGetResponse, tool
+from agent_framework.ag_ui import AgentFrameworkAgent
+
+from agent_framework_ag_ui import state_update
+
+# Simulated weather database — in the issue's motivating example the tool
+# would instead call a real weather API.
+_WEATHER_DB: dict[str, dict[str, Any]] = {
+    "seattle": {"temperature": 11, "conditions": "rainy", "humidity": 75},
+    "san francisco": {"temperature": 14, "conditions": "foggy", "humidity": 85},
+    "new york city": {"temperature": 18, "conditions": "sunny", "humidity": 60},
+    "miami": {"temperature": 29, "conditions": "hot and humid", "humidity": 90},
+    "chicago": {"temperature": 9, "conditions": "windy", "humidity": 65},
+}
+
+
+@tool
+async def get_weather(location: str) -> Content:
+    """Fetch current weather for a location and push it into AG-UI shared state.
+
+    Unlike ``predict_state_config`` — which derives state optimistically from
+    LLM-predicted tool call arguments — this tool uses ``state_update`` to
+    forward the *actual* fetched weather to the frontend. The ``text`` goes
+    back to the LLM as the normal tool result, and the ``state`` dict is merged
+    into the AG-UI shared state.
+
+    Args:
+        location: City name to look up.
+
+    Returns:
+        A :class:`Content` carrying both the LLM-visible text result and a
+        deterministic state snapshot.
+    """
+    key = location.lower()
+    data = _WEATHER_DB.get(
+        key,
+        {"temperature": 21, "conditions": "partly cloudy", "humidity": 50},
+    )
+    weather_record = {"location": location, **data}
+    return state_update(
+        text=(
+            f"The weather in {location} is {data['conditions']} at "
+            f"{data['temperature']}°C with {data['humidity']}% humidity."
+        ),
+        state={"weather": weather_record},
+    )
+
+
+def weather_state_agent(client: SupportsChatGetResponse[Any]) -> AgentFrameworkAgent:
+    """Create an AG-UI agent with a deterministic tool-driven state tool."""
+    agent = Agent[Any](
+        name="weather_state_agent",
+        instructions=(
+            "You are a weather assistant. When a user asks about the weather "
+            "in a city, call the get_weather tool and use its output to give a "
+            "friendly, concise reply. The tool also updates the shared UI state "
+            "so the frontend can render a weather card from the `weather` key."
+        ),
+        client=client,
+        tools=[get_weather],
+    )
+
+    return AgentFrameworkAgent(
+        agent=agent,
+        name="WeatherStateAgent",
+        description="Weather agent that deterministically updates shared state from tool results.",
+        state_schema={
+            "weather": {
+                "type": "object",
+                "description": "Last fetched weather record",
+            },
+        },
+    )

python/packages/ag-ui/agent_framework_ag_ui_examples/server/main.py

@@ -24,6 +24,7 @@ from ..agents.subgraphs_agent import subgraphs_agent
 from ..agents.task_steps_agent import task_steps_agent_wrapped
 from ..agents.ui_generator_agent import ui_generator_agent
 from ..agents.weather_agent import weather_agent
+from ..agents.weather_state_agent import weather_state_agent
 
 AnthropicClient: type[Any] | None
 try:
@@ -141,6 +142,14 @@ add_agent_framework_fastapi_endpoint(
     path="/subgraphs",
 )
 
+# Deterministic Tool-Driven State - tool returns state_update() to push snapshot
+# from actual tool output (see issue #3167).
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=weather_state_agent(client),
+    path="/deterministic_state",
+)
+
 
 def main():
     """Run the server."""

python/packages/ag-ui/tests/ag_ui/golden/test_scenario_deterministic_state.py

@@ -0,0 +1,267 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Golden event-stream tests for the deterministic tool-driven state scenario.
+
+Covers issue https://github.com/microsoft/agent-framework/issues/3167 — a tool
+returning :func:`agent_framework_ag_ui.state_update` must push a deterministic
+``StateSnapshotEvent`` derived from its actual return value, orthogonal to the
+optimistic ``predict_state_config`` path. These golden tests pin the user-visible
+event stream so additive changes cannot silently regress it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_framework import AgentResponseUpdate, Content
+from conftest import StubAgent
+from event_stream import EventStream
+
+from agent_framework_ag_ui import AgentFrameworkAgent, state_update
+
+STATE_SCHEMA = {
+    "weather": {"type": "object", "description": "Last fetched weather"},
+}
+
+
+def _build_agent(updates: list[AgentResponseUpdate], **kwargs: Any) -> AgentFrameworkAgent:
+    stub = StubAgent(updates=updates)
+    kwargs.setdefault("state_schema", STATE_SCHEMA)
+    return AgentFrameworkAgent(agent=stub, **kwargs)
+
+
+async def _run(agent: AgentFrameworkAgent, payload: dict[str, Any]) -> EventStream:
+    return EventStream([event async for event in agent.run(payload)])
+
+
+PAYLOAD: dict[str, Any] = {
+    "thread_id": "thread-det-state",
+    "run_id": "run-det-state",
+    "messages": [{"role": "user", "content": "What's the weather in SF?"}],
+    "state": {"weather": {}},
+}
+
+
+def _tool_call(call_id: str, name: str, arguments: str) -> AgentResponseUpdate:
+    return AgentResponseUpdate(
+        contents=[Content.from_function_call(name=name, call_id=call_id, arguments=arguments)],
+        role="assistant",
+    )
+
+
+def _tool_result_with_state(call_id: str, text: str, state: dict[str, Any]) -> AgentResponseUpdate:
+    """Build a function_result update whose inner item carries a state marker.
+
+    This mirrors what the core framework produces when a real ``@tool`` returns
+    :func:`state_update`: ``parse_result`` keeps the ``Content`` as-is, and
+    ``Content.from_function_result`` preserves its ``additional_properties``
+    inside ``items``.
+    """
+    return AgentResponseUpdate(
+        contents=[
+            Content.from_function_result(
+                call_id=call_id,
+                result=[state_update(text=text, state=state)],
+            )
+        ],
+        role="assistant",
+    )
+
+
+# ── Golden stream tests ──
+
+
+async def test_deterministic_state_emits_snapshot_after_tool_result() -> None:
+    """The happy path: STATE_SNAPSHOT follows TOOL_CALL_RESULT in order."""
+    updates = [
+        _tool_call("call-1", "get_weather", '{"city": "SF"}'),
+        _tool_result_with_state(
+            "call-1",
+            text="Weather in SF: 14°C foggy",
+            state={"weather": {"city": "SF", "temp": 14, "conditions": "foggy"}},
+        ),
+        AgentResponseUpdate(
+            contents=[Content.from_text(text="It's 14°C and foggy in SF.")],
+            role="assistant",
+        ),
+    ]
+    agent = _build_agent(updates)
+    stream = await _run(agent, PAYLOAD)
+
+    stream.assert_bookends()
+    stream.assert_no_run_error()
+    stream.assert_tool_calls_balanced()
+    stream.assert_text_messages_balanced()
+
+    # Ordered subsequence: the deterministic STATE_SNAPSHOT must follow the
+    # TOOL_CALL_RESULT. This is the central contract for #3167.
+    stream.assert_ordered_types(
+        [
+            "RUN_STARTED",
+            "TOOL_CALL_START",
+            "TOOL_CALL_ARGS",
+            "TOOL_CALL_END",
+            "TOOL_CALL_RESULT",
+            "STATE_SNAPSHOT",
+            "RUN_FINISHED",
+        ]
+    )
+
+    # The final STATE_SNAPSHOT must carry the tool-driven state.
+    snapshot = stream.snapshot()
+    assert snapshot["weather"] == {"city": "SF", "temp": 14, "conditions": "foggy"}
+
+
+async def test_deterministic_state_does_not_fire_for_plain_tool_result() -> None:
+    """Regression guard: tools returning plain strings must NOT emit a new STATE_SNAPSHOT.
+
+    The initial STATE_SNAPSHOT fires once from the schema + initial payload
+    state. A plain (non-state_update) tool result must not add another one.
+    """
+    updates = [
+        _tool_call("call-1", "get_weather", '{"city": "SF"}'),
+        AgentResponseUpdate(
+            contents=[Content.from_function_result(call_id="call-1", result="14°C foggy")],
+            role="assistant",
+        ),
+        AgentResponseUpdate(
+            contents=[Content.from_text(text="It's 14°C and foggy.")],
+            role="assistant",
+        ),
+    ]
+    agent = _build_agent(updates)
+    stream = await _run(agent, PAYLOAD)
+
+    stream.assert_bookends()
+    stream.assert_no_run_error()
+
+    snapshots = stream.get("STATE_SNAPSHOT")
+    # Only the initial snapshot (from state_schema + payload state) should exist.
+    # No deterministic snapshot should have been added by the plain tool result.
+    assert len(snapshots) == 1, (
+        f"Expected exactly 1 STATE_SNAPSHOT (initial only) for plain tool result; "
+        f"got {len(snapshots)}. Snapshots: {[s.snapshot for s in snapshots]}"
+    )
+
+
+async def test_deterministic_state_merges_into_initial_state() -> None:
+    """The tool-driven snapshot must merge into, not replace, pre-existing state keys."""
+    payload = dict(PAYLOAD)
+    payload["state"] = {"weather": {}, "user_preferences": {"unit": "C"}}
+
+    updates = [
+        _tool_call("call-1", "get_weather", '{"city": "SF"}'),
+        _tool_result_with_state(
+            "call-1",
+            text="Weather: 14°C",
+            state={"weather": {"city": "SF", "temp": 14}},
+        ),
+    ]
+    agent = _build_agent(updates, state_schema={**STATE_SCHEMA, "user_preferences": {"type": "object"}})
+    stream = await _run(agent, payload)
+
+    stream.assert_bookends()
+    stream.assert_no_run_error()
+
+    final_snapshot = stream.snapshot()
+    assert final_snapshot["weather"] == {"city": "SF", "temp": 14}
+    assert final_snapshot["user_preferences"] == {"unit": "C"}, (
+        "Pre-existing state keys must survive the deterministic merge"
+    )
+
+
+async def test_deterministic_state_llm_visible_text_is_clean() -> None:
+    """The LLM-visible TOOL_CALL_RESULT content must not leak the state marker key."""
+    updates = [
+        _tool_call("call-1", "get_weather", '{"city": "SF"}'),
+        _tool_result_with_state(
+            "call-1",
+            text="Weather in SF: 14°C foggy",
+            state={"weather": {"city": "SF", "temp": 14}},
+        ),
+    ]
+    agent = _build_agent(updates)
+    stream = await _run(agent, PAYLOAD)
+
+    result = stream.first("TOOL_CALL_RESULT")
+    assert result.content == "Weather in SF: 14°C foggy"
+    # The marker key must never appear in the content sent back to the LLM.
+    assert "__ag_ui_tool_result_state__" not in result.content
+    assert "weather" not in result.content  # not as a raw state dump
+
+
+async def test_deterministic_state_multiple_tools_merge_in_order() -> None:
+    """Two state-updating tools in one run merge in order; later wins on key collisions."""
+    updates = [
+        _tool_call("call-a", "get_weather", '{"city": "SF"}'),
+        _tool_result_with_state(
+            "call-a",
+            text="First result",
+            state={"weather": {"city": "SF", "temp": 14}, "source": "primary"},
+        ),
+        _tool_call("call-b", "get_weather_refined", '{"city": "SF"}'),
+        _tool_result_with_state(
+            "call-b",
+            text="Refined result",
+            state={"source": "refined"},
+        ),
+        AgentResponseUpdate(
+            contents=[Content.from_text(text="Here you go.")],
+            role="assistant",
+        ),
+    ]
+    agent = _build_agent(
+        updates,
+        state_schema={**STATE_SCHEMA, "source": {"type": "string"}},
+    )
+    stream = await _run(agent, PAYLOAD)
+
+    stream.assert_bookends()
+    stream.assert_tool_calls_balanced()
+    stream.assert_no_run_error()
+
+    # Two tool-driven snapshots emitted (one per tool) plus the initial snapshot.
+    snapshots = stream.get("STATE_SNAPSHOT")
+    assert len(snapshots) >= 2, f"Expected at least 2 STATE_SNAPSHOTs; got {len(snapshots)}"
+
+    final = stream.snapshot()
+    assert final["weather"] == {"city": "SF", "temp": 14}
+    # Later tool must override earlier tool on the shared key.
+    assert final["source"] == "refined"
+
+
+async def test_deterministic_state_coexists_with_predict_state_config() -> None:
+    """Predictive state and deterministic state must coexist without clobbering each other."""
+    predict_config = {
+        "draft": {
+            "tool": "write_draft",
+            "tool_argument": "body",
+        }
+    }
+    updates = [
+        # Predictive tool: its argument "body" populates state.draft optimistically.
+        _tool_call("call-1", "write_draft", '{"body": "Hello world"}'),
+        # Then a deterministic tool result landing a different key.
+        _tool_result_with_state(
+            "call-1",
+            text="Draft saved",
+            state={"weather": {"city": "SF", "temp": 14}},
+        ),
+    ]
+    agent = _build_agent(
+        updates,
+        state_schema={**STATE_SCHEMA, "draft": {"type": "string"}},
+        predict_state_config=predict_config,
+        require_confirmation=False,
+    )
+    payload = dict(PAYLOAD)
+    payload["state"] = {"weather": {}, "draft": ""}
+    stream = await _run(agent, payload)
+
+    stream.assert_bookends()
+    stream.assert_no_run_error()
+    stream.assert_tool_calls_balanced()
+
+    # The final observed state must contain both the deterministic and predictive contributions.
+    final = stream.snapshot()
+    assert final["weather"] == {"city": "SF", "temp": 14}, f"Deterministic state missing from final snapshot: {final}"

python/packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py

@@ -1405,3 +1405,95 @@ async def test_fabricated_rejection_without_pending_approval_is_blocked(streamin
         for content in msg.contents:
             if content.type == "function_result" and content.call_id == "fake_reject_001":
                 assert False, "Fabricated rejection response leaked as function_result into LLM messages"
+
+
+async def test_state_update_end_to_end_via_real_tool_invocation(streaming_chat_client_stub):
+    """End-to-end coverage for issue #3167: a real ``@tool`` returning ``state_update`` must
+    emit a deterministic STATE_SNAPSHOT through the full pipeline.
+
+    This test exercises the entire chain that a user would hit in production:
+    ``FunctionInvocationLayer`` executes the tool, ``FunctionTool.parse_result``
+    preserves the returned ``Content`` with its ``additional_properties`` marker,
+    ``Content.from_function_result`` carries the marker through in ``items``,
+    and the AG-UI emitter extracts it via ``_extract_tool_result_state`` and
+    emits the snapshot. A regression anywhere in that chain will fail this test.
+    """
+    from agent_framework import tool
+    from agent_framework.ag_ui import AgentFrameworkAgent
+
+    from agent_framework_ag_ui import state_update
+
+    @tool(name="get_weather", description="Get current weather for a city.")
+    async def get_weather(city: str) -> Content:
+        return state_update(
+            text=f"Weather in {city}: 14°C foggy",
+            state={"weather": {"city": city, "temperature": 14, "conditions": "foggy"}},
+        )
+
+    call_count = {"n": 0}
+
+    async def stream_fn(
+        messages: MutableSequence[Message], options: ChatOptions, **kwargs: Any
+    ) -> AsyncIterator[ChatResponseUpdate]:
+        """First turn proposes a tool call; second turn (after tool execution) returns text."""
+        call_count["n"] += 1
+        if call_count["n"] == 1:
+            yield ChatResponseUpdate(
+                contents=[
+                    Content.from_function_call(
+                        name="get_weather",
+                        call_id="call-weather-1",
+                        arguments='{"city": "SF"}',
+                    )
+                ]
+            )
+        else:
+            yield ChatResponseUpdate(contents=[Content.from_text(text="It's 14°C and foggy in SF.")])
+
+    agent = Agent(
+        client=streaming_chat_client_stub(stream_fn),
+        name="weather_agent",
+        instructions="Answer weather questions.",
+        tools=[get_weather],
+    )
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"weather": {"type": "object"}},
+    )
+
+    events: list[Any] = []
+    async for event in wrapper.run(
+        {
+            "thread_id": "thread-weather",
+            "run_id": "run-weather",
+            "messages": [{"role": "user", "content": "What's the weather in SF?"}],
+            "state": {"weather": {}},
+        }
+    ):
+        events.append(event)
+
+    types = [e.type for e in events]
+
+    # The tool call must be visible in the stream.
+    assert "TOOL_CALL_START" in types, f"Missing TOOL_CALL_START in: {types}"
+    assert "TOOL_CALL_RESULT" in types, f"Missing TOOL_CALL_RESULT in: {types}"
+
+    # A STATE_SNAPSHOT must be emitted after the tool result.
+    tool_result_idx = types.index("TOOL_CALL_RESULT")
+    snapshot_indices_after_result = [i for i, t in enumerate(types) if t == "STATE_SNAPSHOT" and i > tool_result_idx]
+    assert snapshot_indices_after_result, (
+        f"Expected a STATE_SNAPSHOT after TOOL_CALL_RESULT (index {tool_result_idx}); got types: {types}"
+    )
+
+    # The tool's deterministic snapshot carries the actual fetched weather data.
+    final_snapshot = events[snapshot_indices_after_result[-1]].snapshot
+    assert final_snapshot["weather"] == {
+        "city": "SF",
+        "temperature": 14,
+        "conditions": "foggy",
+    }
+
+    # The LLM-visible tool result must carry the plain text, not the marker key.
+    tool_result_event = next(e for e in events if e.type == "TOOL_CALL_RESULT")
+    assert tool_result_event.content == "Weather in SF: 14°C foggy"
+    assert "__ag_ui_tool_result_state__" not in tool_result_event.content

python/packages/ag-ui/tests/ag_ui/test_public_exports.py

@@ -18,7 +18,24 @@ def test_core_ag_ui_lazy_exports_include_only_stable_api() -> None:
     assert hasattr(ag_ui, "AgentFrameworkAgent")
     assert hasattr(ag_ui, "AGUIChatClient")
     assert hasattr(ag_ui, "add_agent_framework_fastapi_endpoint")
+    assert hasattr(ag_ui, "state_update")
 
     assert not hasattr(ag_ui, "WorkflowFactory")
     assert not hasattr(ag_ui, "AGUIRequest")
     assert not hasattr(ag_ui, "RunMetadata")
+
+
+def test_agent_framework_ag_ui_exports_state_update() -> None:
+    """Runtime package should export the ``state_update`` helper."""
+    from agent_framework_ag_ui import state_update
+
+    assert callable(state_update)
+
+
+def test_core_ag_ui_lazy_exports_include_event_converter_and_http_service() -> None:
+    """Core facade must expose AGUIEventConverter, AGUIHttpService, and __version__."""
+    from agent_framework import ag_ui
+
+    assert hasattr(ag_ui, "AGUIEventConverter")
+    assert hasattr(ag_ui, "AGUIHttpService")
+    assert hasattr(ag_ui, "__version__")

python/packages/ag-ui/tests/ag_ui/test_run_common.py

@@ -2,14 +2,20 @@
 
 """Tests for _run_common.py edge cases."""
 
+from ag_ui.core import EventType
 from agent_framework import Content
 
+from agent_framework_ag_ui import state_update
+from agent_framework_ag_ui._orchestration._predictive_state import PredictiveStateHandler
 from agent_framework_ag_ui._run_common import (
     FlowState,
+    _emit_mcp_tool_result,
     _emit_tool_result,
     _extract_resume_payload,
+    _extract_tool_result_state,
     _normalize_resume_interrupts,
 )
+from agent_framework_ag_ui._state import TOOL_RESULT_STATE_KEY
 
 
 class TestNormalizeResumeInterrupts:
@@ -120,3 +126,223 @@ class TestEmitToolResult:
         assert "TEXT_MESSAGE_END" in event_types
         assert flow.message_id is None
         assert flow.accumulated_text == ""
+
+
+class TestStateUpdateHelper:
+    """Tests for the public ``state_update`` helper."""
+
+    def test_builds_text_content_with_state_marker(self):
+        """state_update returns a text Content carrying state in additional_properties."""
+        c = state_update(text="done", state={"weather": {"temp": 14}})
+        assert c.type == "text"
+        assert c.text == "done"
+        assert c.additional_properties == {
+            TOOL_RESULT_STATE_KEY: {"weather": {"temp": 14}},
+        }
+
+    def test_empty_text_is_allowed(self):
+        """State-only tools can omit the text argument."""
+        c = state_update(state={"steps": ["a", "b"]})
+        assert c.text == ""
+        assert c.additional_properties[TOOL_RESULT_STATE_KEY] == {"steps": ["a", "b"]}
+
+    def test_non_mapping_state_raises(self):
+        """Passing a non-mapping value for state raises TypeError."""
+        import pytest
+
+        with pytest.raises(TypeError):
+            state_update(text="t", state=["not", "a", "mapping"])  # type: ignore[arg-type]
+
+    def test_state_is_copied_defensively(self):
+        """Mutating the caller's dict after ``state_update`` must not mutate the content."""
+        caller_state = {"weather": {"temp": 14}}
+        c = state_update(text="ok", state=caller_state)
+        caller_state["weather"]["temp"] = 99
+        # The top-level dict was copied, so replacing the key in caller_state
+        # would not affect the Content, but nested dicts share references — document
+        # this by asserting only the top-level copy semantics.
+        assert TOOL_RESULT_STATE_KEY in c.additional_properties
+        inner = c.additional_properties[TOOL_RESULT_STATE_KEY]
+        assert inner is not caller_state
+
+
+class TestExtractToolResultState:
+    """Tests for ``_extract_tool_result_state``."""
+
+    def test_returns_none_for_plain_string_result(self):
+        content = Content.from_function_result(call_id="c1", result="plain")
+        assert _extract_tool_result_state(content) is None
+
+    def test_extracts_state_from_inner_item(self):
+        tool_return = state_update(text="hi", state={"k": 1})
+        content = Content.from_function_result(call_id="c1", result=[tool_return])
+        assert _extract_tool_result_state(content) == {"k": 1}
+
+    def test_extracts_state_from_outer_additional_properties(self):
+        """Outer function_result content can also carry state (legacy/advanced use)."""
+        content = Content.from_function_result(
+            call_id="c1",
+            result="hi",
+            additional_properties={TOOL_RESULT_STATE_KEY: {"k": 1}},
+        )
+        assert _extract_tool_result_state(content) == {"k": 1}
+
+    def test_merges_multiple_items(self):
+        a = state_update(text="a", state={"k": 1, "shared": "from_a"})
+        b = state_update(text="b", state={"shared": "from_b", "extra": True})
+        content = Content.from_function_result(call_id="c1", result=[a, b])
+        merged = _extract_tool_result_state(content)
+        assert merged == {"k": 1, "shared": "from_b", "extra": True}
+
+    def test_ignores_non_dict_marker_value(self):
+        """A garbled marker value must not break extraction (defensive guard)."""
+        bad = Content.from_text(
+            "hi",
+            additional_properties={TOOL_RESULT_STATE_KEY: "not-a-dict"},
+        )
+        content = Content.from_function_result(call_id="c1", result=[bad])
+        assert _extract_tool_result_state(content) is None
+
+
+class TestEmitToolResultWithState:
+    """Tests for the deterministic state emission in ``_emit_tool_result``."""
+
+    def test_emits_state_snapshot_after_tool_call_result(self):
+        """Tool returning state_update produces a StateSnapshotEvent right after the result."""
+        tool_return = state_update(
+            text="Weather: 14°C",
+            state={"weather": {"temp": 14, "conditions": "foggy"}},
+        )
+        content = Content.from_function_result(call_id="call_1", result=[tool_return])
+        flow = FlowState()
+
+        events = _emit_tool_result(content, flow)
+        event_types = [e.type for e in events]
+
+        # Expect TOOL_CALL_END, TOOL_CALL_RESULT, STATE_SNAPSHOT in that order.
+        assert event_types[0] == EventType.TOOL_CALL_END
+        assert event_types[1] == EventType.TOOL_CALL_RESULT
+        state_idx = event_types.index(EventType.STATE_SNAPSHOT)
+        assert state_idx == 2
+        assert events[state_idx].snapshot == {"weather": {"temp": 14, "conditions": "foggy"}}
+
+    def test_updates_flow_current_state(self):
+        tool_return = state_update(text="", state={"a": 1})
+        content = Content.from_function_result(call_id="c1", result=[tool_return])
+        flow = FlowState(current_state={"existing": "value"})
+
+        _emit_tool_result(content, flow)
+
+        # Existing keys must survive (merge semantics), new keys must be added.
+        assert flow.current_state == {"existing": "value", "a": 1}
+
+    def test_merge_overrides_existing_key(self):
+        tool_return = state_update(text="", state={"existing": "new"})
+        content = Content.from_function_result(call_id="c1", result=[tool_return])
+        flow = FlowState(current_state={"existing": "old", "other": 1})
+
+        _emit_tool_result(content, flow)
+
+        assert flow.current_state == {"existing": "new", "other": 1}
+
+    def test_no_state_snapshot_when_result_has_no_state(self):
+        """Plain tool results must not emit a StateSnapshotEvent."""
+        content = Content.from_function_result(call_id="c1", result="plain")
+        flow = FlowState()
+
+        events = _emit_tool_result(content, flow)
+        assert all(e.type != EventType.STATE_SNAPSHOT for e in events)
+
+    def test_tool_result_content_text_unchanged(self):
+        """The text sent to the LLM must not leak the state marker."""
+        tool_return = state_update(text="Weather: 14°C", state={"weather": {"temp": 14}})
+        content = Content.from_function_result(call_id="c1", result=[tool_return])
+        flow = FlowState()
+
+        events = _emit_tool_result(content, flow)
+        result_events = [e for e in events if e.type == EventType.TOOL_CALL_RESULT]
+        assert len(result_events) == 1
+        assert result_events[0].content == "Weather: 14°C"
+        assert TOOL_RESULT_STATE_KEY not in result_events[0].content
+
+    def test_coexists_with_active_predictive_state_handler(self):
+        """Both predictive and deterministic state produce a single coalesced snapshot.
+
+        Predictive state (``predict_state_config``) and deterministic state
+        (``state_update``) are two independent mechanisms. When both are active,
+        a single coalesced ``StateSnapshotEvent`` is emitted containing the
+        merged result of both contributions.
+        """
+        flow = FlowState(current_state={"preexisting": "value"})
+        handler = PredictiveStateHandler(
+            predict_state_config={"draft": {"tool": "write_draft", "tool_argument": "body"}},
+            current_state=flow.current_state,
+        )
+
+        tool_return = state_update(text="Draft written", state={"draft_final": True})
+        content = Content.from_function_result(call_id="c1", result=[tool_return])
+
+        events = _emit_tool_result(content, flow, predictive_handler=handler)
+
+        # Exactly one coalesced snapshot must be emitted containing all merged keys.
+        snapshots = [e for e in events if e.type == EventType.STATE_SNAPSHOT]
+        assert len(snapshots) == 1
+        assert snapshots[0].snapshot["draft_final"] is True
+        assert snapshots[0].snapshot["preexisting"] == "value"
+        assert flow.current_state["draft_final"] is True
+        assert flow.current_state["preexisting"] == "value"
+
+    def test_predictive_and_deterministic_emit_single_snapshot(self):
+        """When both predictive_handler and state_update are active, only one snapshot is emitted."""
+        flow = FlowState(current_state={"existing": "yes"})
+        handler = PredictiveStateHandler(
+            predict_state_config={"draft": {"tool": "write_draft", "tool_argument": "body"}},
+            current_state=flow.current_state,
+        )
+
+        tool_return = state_update(text="ok", state={"new_key": 42})
+        content = Content.from_function_result(call_id="c1", result=[tool_return])
+
+        events = _emit_tool_result(content, flow, predictive_handler=handler)
+
+        snapshots = [e for e in events if e.type == EventType.STATE_SNAPSHOT]
+        assert len(snapshots) == 1, f"Expected 1 coalesced snapshot, got {len(snapshots)}"
+        assert snapshots[0].snapshot == {"existing": "yes", "new_key": 42}
+
+
+class TestEmitMcpToolResultWithState:
+    """MCP tool results should honour the same state_update marker.
+
+    MCP results come from an external MCP server rather than a locally
+    executed ``@tool`` function, so they do not flow through ``parse_result``
+    and ``content.items`` is typically empty. State is instead carried on the
+    outer content's ``additional_properties`` (e.g. by middleware that
+    inspects the MCP output and attaches a marker). ``_extract_tool_result_state``
+    supports both locations so this path remains usable.
+    """
+
+    def test_mcp_tool_result_emits_state_snapshot_from_additional_properties(self):
+        content = Content.from_mcp_server_tool_result(
+            call_id="mcp_1",
+            output="server result",
+            additional_properties={TOOL_RESULT_STATE_KEY: {"mcp_ok": True}},
+        )
+        flow = FlowState()
+
+        events = _emit_mcp_tool_result(content, flow)
+        event_types = [e.type for e in events]
+
+        assert EventType.TOOL_CALL_END in event_types
+        assert EventType.TOOL_CALL_RESULT in event_types
+        assert EventType.STATE_SNAPSHOT in event_types
+        assert flow.current_state == {"mcp_ok": True}
+
+    def test_mcp_tool_result_without_state_emits_no_snapshot(self):
+        content = Content.from_mcp_server_tool_result(
+            call_id="mcp_1",
+            output="server result",
+        )
+        flow = FlowState()
+
+        events = _emit_mcp_tool_result(content, flow)
+        assert all(e.type != EventType.STATE_SNAPSHOT for e in events)

python/packages/azure-cosmos/agent_framework_azure_cosmos/_checkpoint_storage.py

@@ -43,9 +43,34 @@ class CosmosCheckpointStorage:
     ``FileCheckpointStorage``, allowing full Python object fidelity for
     complex workflow state while keeping the document structure human-readable.
 
-    SECURITY WARNING: Checkpoints use pickle for data serialization. Only load
-    checkpoints from trusted sources. Loading a malicious checkpoint can execute
-    arbitrary code.
+    Security warning: checkpoints use pickle for non-JSON-native values. Loading
+    checkpoints from untrusted sources is unsafe and can execute arbitrary code
+    during deserialization. The built-in deserialization restrictions reduce risk,
+    but they do not make untrusted checkpoints safe to load. Extending
+    ``allowed_checkpoint_types`` may further increase risk and should only be done
+    for trusted application types.
+
+    By default, checkpoint deserialization is restricted to a built-in set of safe
+    Python types (primitives, datetime, uuid, ...) and all ``agent_framework``
+    internal types.  To allow additional application-specific types, pass them via
+    the ``allowed_checkpoint_types`` parameter using ``"module:qualname"`` format.
+
+    Example:
+
+    .. code-block:: python
+
+        from azure.identity.aio import DefaultAzureCredential
+        from agent_framework_azure_cosmos import CosmosCheckpointStorage
+
+        storage = CosmosCheckpointStorage(
+            endpoint="https://my-account.documents.azure.com:443/",
+            credential=DefaultAzureCredential(),
+            database_name="agent-db",
+            container_name="checkpoints",
+            allowed_checkpoint_types=[
+                "my_app.models:MyState",
+            ],
+        )
 
     The database and container are created automatically on first use
     if they do not already exist. The container uses partition key
@@ -97,6 +122,7 @@ class CosmosCheckpointStorage:
         container_client: ContainerProxy | None = None,
         env_file_path: str | None = None,
         env_file_encoding: str | None = None,
+        allowed_checkpoint_types: list[str] | None = None,
     ) -> None:
         """Initialize the Azure Cosmos DB checkpoint storage.
 
@@ -129,10 +155,15 @@ class CosmosCheckpointStorage:
             container_client: Pre-created Cosmos container client.
             env_file_path: Path to environment file for loading settings.
             env_file_encoding: Encoding of the environment file.
+            allowed_checkpoint_types: Additional types (beyond the built-in safe set
+                and framework types) that are permitted during checkpoint
+                deserialization.  Each entry should be a ``"module:qualname"``
+                string (e.g., ``"my_app.models:MyState"``).
         """
         self._cosmos_client: CosmosClient | None = cosmos_client
         self._container_proxy: ContainerProxy | None = container_client
         self._owns_client = False
+        self._allowed_types: frozenset[str] = frozenset(allowed_checkpoint_types or [])
 
         if self._container_proxy is not None:
             self.database_name: str = database_name or ""
@@ -401,8 +432,7 @@ class CosmosCheckpointStorage:
             partition_key=PartitionKey(path="/workflow_name"),
         )
 
-    @staticmethod
-    def _document_to_checkpoint(document: dict[str, Any]) -> WorkflowCheckpoint:
+    def _document_to_checkpoint(self, document: dict[str, Any]) -> WorkflowCheckpoint:
         """Convert a Cosmos DB document back to a WorkflowCheckpoint.
 
         Strips Cosmos DB system properties (``_rid``, ``_self``, ``_etag``,
@@ -413,7 +443,7 @@ class CosmosCheckpointStorage:
         cosmos_keys = {"id", "_rid", "_self", "_etag", "_attachments", "_ts"}
         cleaned = {k: v for k, v in document.items() if k not in cosmos_keys}
 
-        decoded = decode_checkpoint_value(cleaned)
+        decoded = decode_checkpoint_value(cleaned, allowed_types=self._allowed_types)
         return WorkflowCheckpoint.from_dict(decoded)
 
     @staticmethod

python/packages/azure-cosmos/tests/test_cosmos_checkpoint_storage.py

@@ -6,6 +6,7 @@ import os
 import uuid
 from collections.abc import AsyncIterator
 from contextlib import suppress
+from dataclasses import dataclass
 from typing import Any
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -595,3 +596,142 @@ async def test_cosmos_checkpoint_storage_roundtrip_with_emulator() -> None:
         finally:
             with suppress(Exception):
                 await cosmos_client.delete_database(database_name)
+
+
+# --- Tests for allowed_checkpoint_types ---
+
+
+@dataclass
+class _AppState:
+    """Application-defined state type used to test allowed_checkpoint_types."""
+
+    label: str
+    count: int
+
+
+_APP_STATE_TYPE_KEY = f"{_AppState.__module__}:{_AppState.__qualname__}"
+
+
+def _make_checkpoint_with_state(state: dict[str, Any]) -> WorkflowCheckpoint:
+    """Create a checkpoint with custom state for serialization tests."""
+    return WorkflowCheckpoint(
+        workflow_name="test-workflow",
+        graph_signature_hash="abc123",
+        timestamp="2025-01-01T00:00:00+00:00",
+        state=state,
+        iteration_count=1,
+    )
+
+
+async def test_init_accepts_allowed_checkpoint_types(mock_container: MagicMock) -> None:
+    """CosmosCheckpointStorage.__init__ accepts allowed_checkpoint_types."""
+    storage = CosmosCheckpointStorage(
+        container_client=mock_container,
+        allowed_checkpoint_types=["some.module:SomeType"],
+    )
+    assert storage is not None
+
+
+async def test_load_allows_builtin_safe_types(mock_container: MagicMock) -> None:
+    """Built-in safe types load without opt-in via allowed_checkpoint_types."""
+    from datetime import datetime, timezone
+
+    checkpoint = _make_checkpoint_with_state({
+        "ts": datetime(2025, 1, 1, tzinfo=timezone.utc),
+        "tags": {1, 2, 3},
+    })
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    loaded = await storage.load(checkpoint.checkpoint_id)
+
+    assert loaded.state["ts"] == datetime(2025, 1, 1, tzinfo=timezone.utc)
+    assert loaded.state["tags"] == {1, 2, 3}
+
+
+async def test_load_blocks_unlisted_app_type(mock_container: MagicMock) -> None:
+    """Application types are blocked when not listed in allowed_checkpoint_types."""
+    checkpoint = _make_checkpoint_with_state({"data": _AppState(label="x", count=1)})
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+
+    with pytest.raises(WorkflowCheckpointException, match="deserialization blocked"):
+        await storage.load(checkpoint.checkpoint_id)
+
+
+async def test_load_allows_listed_app_type(mock_container: MagicMock) -> None:
+    """Application types are allowed when listed in allowed_checkpoint_types."""
+    checkpoint = _make_checkpoint_with_state({"data": _AppState(label="ok", count=7)})
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(
+        container_client=mock_container,
+        allowed_checkpoint_types=[_APP_STATE_TYPE_KEY],
+    )
+    loaded = await storage.load(checkpoint.checkpoint_id)
+
+    assert isinstance(loaded.state["data"], _AppState)
+    assert loaded.state["data"].label == "ok"
+    assert loaded.state["data"].count == 7
+
+
+async def test_list_checkpoints_blocks_unlisted_app_type(mock_container: MagicMock) -> None:
+    """list_checkpoints skips documents with unlisted application types."""
+    checkpoint = _make_checkpoint_with_state({"data": _AppState(label="x", count=1)})
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+    results = await storage.list_checkpoints(workflow_name="test-workflow")
+
+    # The document is skipped (logged as warning) because the type is blocked
+    assert len(results) == 0
+
+
+async def test_list_checkpoints_allows_listed_app_type(mock_container: MagicMock) -> None:
+    """list_checkpoints decodes documents with listed application types."""
+    checkpoint = _make_checkpoint_with_state({"data": _AppState(label="ok", count=3)})
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(
+        container_client=mock_container,
+        allowed_checkpoint_types=[_APP_STATE_TYPE_KEY],
+    )
+    results = await storage.list_checkpoints(workflow_name="test-workflow")
+
+    assert len(results) == 1
+    assert isinstance(results[0].state["data"], _AppState)
+
+
+async def test_get_latest_blocks_unlisted_app_type(mock_container: MagicMock) -> None:
+    """get_latest raises when the checkpoint contains an unlisted application type."""
+    checkpoint = _make_checkpoint_with_state({"data": _AppState(label="x", count=1)})
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(container_client=mock_container)
+
+    with pytest.raises(WorkflowCheckpointException, match="deserialization blocked"):
+        await storage.get_latest(workflow_name="test-workflow")
+
+
+async def test_get_latest_allows_listed_app_type(mock_container: MagicMock) -> None:
+    """get_latest decodes checkpoints with listed application types."""
+    checkpoint = _make_checkpoint_with_state({"data": _AppState(label="latest", count=9)})
+    doc = _checkpoint_to_cosmos_document(checkpoint)
+    mock_container.query_items.return_value = _to_async_iter([doc])
+
+    storage = CosmosCheckpointStorage(
+        container_client=mock_container,
+        allowed_checkpoint_types=[_APP_STATE_TYPE_KEY],
+    )
+    result = await storage.get_latest(workflow_name="test-workflow")
+
+    assert result is not None
+    assert isinstance(result.state["data"], _AppState)
+    assert result.state["data"].label == "latest"

python/packages/core/agent_framework/_skills.py

@@ -486,8 +486,8 @@ YAML_KV_RE = re.compile(
 )
 
 # Validates skill names: lowercase letters, numbers, hyphens only;
-# must not start or end with a hyphen.
-VALID_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$")
+# must not start or end with a hyphen, and must not contain consecutive hyphens.
+VALID_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9]*-[a-z0-9])*[a-z0-9]*$")
 
 # Default system prompt template for advertising available skills to the model.
 # Use {skills} as the placeholder for the generated skills XML list.
@@ -1156,7 +1156,8 @@ def _validate_skill_metadata(
     if len(name) > MAX_NAME_LENGTH or not VALID_NAME_RE.match(name):
         return (
             f"Skill from '{source}' has an invalid name '{name}': Must be {MAX_NAME_LENGTH} characters or fewer, "
-            "using only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen."
+            "using only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen "
+            "or contain consecutive hyphens."
         )
 
     if not description or not description.strip():
@@ -1241,6 +1242,17 @@ def _read_and_parse_skill_file(
         return None
 
     name, description = result
+
+    dir_name = Path(skill_dir_path).name
+    if name != dir_name:
+        logger.error(
+            "SKILL.md at '%s' has frontmatter name '%s' that does not match the directory name '%s'; skipping.",
+            skill_file,
+            name,
+            dir_name,
+        )
+        return None
+
     return name, description, content
 
 

python/packages/core/agent_framework/_types.py

@@ -2816,6 +2816,7 @@ class ResponseStream(AsyncIterable[UpdateT], Generic[UpdateT, FinalT]):
             cleanup_hooks if cleanup_hooks is not None else []
         )
         self._cleanup_run: bool = False
+        self._stream_error: Exception | None = None
         self._inner_stream: ResponseStream[Any, Any] | None = None
         self._inner_stream_source: ResponseStream[Any, Any] | Awaitable[ResponseStream[Any, Any]] | None = None
         self._wrap_inner: bool = False
@@ -2948,8 +2949,12 @@ class ResponseStream(AsyncIterable[UpdateT], Generic[UpdateT, FinalT]):
             await self._run_cleanup_hooks()
             await self.get_final_response()
             raise
-        except Exception:
-            await self._run_cleanup_hooks()
+        except Exception as exc:
+            self._stream_error = exc
+            try:
+                await self._run_cleanup_hooks()
+            finally:
+                self._stream_error = None
             raise
         if self._map_update is not None:
             update = self._map_update(update)  # type: ignore[assignment]

python/packages/core/agent_framework/_workflows/_agent.py

@@ -119,15 +119,11 @@ class WorkflowAgent(BaseAgent):
         if not any(is_type_compatible(list[Message], input_type) for input_type in start_executor.input_types):
             raise ValueError("Workflow's start executor cannot handle list[Message]")
 
-        resolved_context_providers = list(context_providers) if context_providers is not None else []
-        if not resolved_context_providers:
-            resolved_context_providers.append(InMemoryHistoryProvider())
-
         super().__init__(
             id=id,
             name=name,
             description=description,
-            context_providers=resolved_context_providers,
+            context_providers=context_providers,
             **kwargs,
         )
         self._workflow: Workflow = workflow
@@ -261,6 +257,15 @@ class WorkflowAgent(BaseAgent):
             An AgentResponse representing the workflow execution results.
         """
         input_messages = normalize_messages_input(messages)
+
+        if (
+            not any(
+                provider.load_messages for provider in self.context_providers if isinstance(provider, HistoryProvider)
+            )
+            and session is not None
+        ):
+            self.context_providers.append(InMemoryHistoryProvider())
+
         provider_session = session
         if provider_session is None and self.context_providers:
             provider_session = AgentSession()
@@ -332,6 +337,15 @@ class WorkflowAgent(BaseAgent):
             AgentResponseUpdate objects representing the workflow execution progress.
         """
         input_messages = normalize_messages_input(messages)
+
+        if (
+            not any(
+                provider.load_messages for provider in self.context_providers if isinstance(provider, HistoryProvider)
+            )
+            and session is not None
+        ):
+            self.context_providers.append(InMemoryHistoryProvider())
+
         provider_session = session
         if provider_session is None and self.context_providers:
             provider_session = AgentSession()

python/packages/core/agent_framework/ag_ui/__init__.py

@@ -7,10 +7,13 @@ This module lazily re-exports objects from:
 
 Supported classes and functions:
 - AgentFrameworkAgent
+- AgentFrameworkWorkflow
 - AGUIChatClient
 - AGUIEventConverter
 - AGUIHttpService
 - add_agent_framework_fastapi_endpoint
+- state_update
+- __version__
 """
 
 import importlib
@@ -23,6 +26,10 @@ _IMPORTS = [
     "AgentFrameworkWorkflow",
     "add_agent_framework_fastapi_endpoint",
     "AGUIChatClient",
+    "AGUIEventConverter",
+    "AGUIHttpService",
+    "state_update",
+    "__version__",
 ]
 
 

python/packages/core/agent_framework/ag_ui/__init__.pyi

@@ -8,6 +8,7 @@ from agent_framework_ag_ui import (
     AGUIHttpService,
     __version__,
     add_agent_framework_fastapi_endpoint,
+    state_update,
 )
 
 __all__ = [
@@ -18,4 +19,5 @@ __all__ = [
     "AgentFrameworkWorkflow",
     "__version__",
     "add_agent_framework_fastapi_endpoint",
+    "state_update",
 ]

python/packages/core/agent_framework/observability.py

@@ -1323,6 +1323,12 @@ class ChatTelemetryLayer(Generic[OptionsCoT]):
                 from ._types import ChatResponse
 
                 try:
+                    if result_stream._stream_error is not None:  # pyright: ignore[reportPrivateUsage]
+                        # Stream errored; skip get_final_response() to avoid firing
+                        # result hooks such as after_run context providers on error
+                        # paths. Capture the error on the span before returning.
+                        capture_exception(span=span, exception=result_stream._stream_error, timestamp=time_ns())  # pyright: ignore[reportPrivateUsage]
+                        return
                     response: ChatResponse[Any] = await result_stream.get_final_response()
                     duration = duration_state.get("duration")
                     response_attributes = _get_response_attributes(attributes, response)
@@ -1579,6 +1585,12 @@ class AgentTelemetryLayer:
                 from ._types import AgentResponse
 
                 try:
+                    if result_stream._stream_error is not None:  # pyright: ignore[reportPrivateUsage]
+                        # Stream errored; skip get_final_response() to avoid firing
+                        # result hooks such as after_run context providers on error
+                        # paths. Capture the error on the span before returning.
+                        capture_exception(span=span, exception=result_stream._stream_error, timestamp=time_ns())  # pyright: ignore[reportPrivateUsage]
+                        return
                     response: AgentResponse[Any] = await result_stream.get_final_response()
                     duration = duration_state.get("duration")
                     response_attributes = _get_response_attributes(

python/packages/core/pyproject.toml

@@ -34,14 +34,13 @@ all = [
     "mcp>=1.24.0,<2",
     "agent-framework-a2a",
     "agent-framework-ag-ui",
+    "agent-framework-anthropic",
     "agent-framework-azure-ai-search",
     "agent-framework-azure-cosmos",
-    "agent-framework-anthropic",
-    "agent-framework-openai",
-    "agent-framework-claude",
     "agent-framework-azurefunctions",
     "agent-framework-bedrock",
     "agent-framework-chatkit",
+    "agent-framework-claude",
     "agent-framework-copilotstudio",
     "agent-framework-declarative",
     "agent-framework-devui",
@@ -52,6 +51,7 @@ all = [
     "agent-framework-lab",
     "agent-framework-mem0",
     "agent-framework-ollama",
+    "agent-framework-openai",
     "agent-framework-orchestrations",
     "agent-framework-purview",
     "agent-framework-redis",

python/packages/core/tests/core/test_skills.py

@@ -296,6 +296,15 @@ class TestDiscoverAndLoadSkills:
         skills = _discover_file_skills([str(tmp_path)])
         assert len(skills) == 0
 
+    def test_skips_skill_with_name_directory_mismatch(self, tmp_path: Path) -> None:
+        skill_dir = tmp_path / "wrong-dir-name"
+        skill_dir.mkdir()
+        (skill_dir / "SKILL.md").write_text(
+            "---\nname: actual-skill-name\ndescription: A skill.\n---\nBody.", encoding="utf-8"
+        )
+        skills = _discover_file_skills([str(tmp_path)])
+        assert len(skills) == 0
+
     def test_deduplicates_skill_names(self, tmp_path: Path) -> None:
         dir1 = tmp_path / "dir1"
         dir2 = tmp_path / "dir2"
@@ -904,6 +913,11 @@ class TestSkill:
         provider = SkillsProvider(skills=[invalid_skill])
         assert len(provider._skills) == 0
 
+    def test_name_with_consecutive_hyphens_skipped(self) -> None:
+        invalid_skill = Skill(name="consecutive--hyphens", description="A skill.", content="Body")
+        provider = SkillsProvider(skills=[invalid_skill])
+        assert len(provider._skills) == 0
+
     def test_name_too_long_skipped(self) -> None:
         invalid_skill = Skill(name="a" * 65, description="A skill.", content="Body")
         provider = SkillsProvider(skills=[invalid_skill])
@@ -1421,6 +1435,11 @@ class TestValidateSkillMetadata:
         assert result is not None
         assert "invalid name" in result
 
+    def test_name_with_consecutive_hyphens(self) -> None:
+        result = _validate_skill_metadata("consecutive--hyphens", "desc", "source")
+        assert result is not None
+        assert "invalid name" in result
+
     def test_single_char_name(self) -> None:
         assert _validate_skill_metadata("a", "desc", "source") is None
 
@@ -1526,6 +1545,15 @@ class TestReadAndParseSkillFile:
         result = _read_and_parse_skill_file(str(skill_dir))
         assert result is None
 
+    def test_name_directory_mismatch_returns_none(self, tmp_path: Path) -> None:
+        skill_dir = tmp_path / "wrong-dir-name"
+        skill_dir.mkdir()
+        (skill_dir / "SKILL.md").write_text(
+            "---\nname: actual-skill-name\ndescription: A skill.\n---\nBody.", encoding="utf-8"
+        )
+        result = _read_and_parse_skill_file(str(skill_dir))
+        assert result is None
+
 
 # ---------------------------------------------------------------------------
 # Tests: _create_resource_element

python/packages/core/tests/workflow/test_workflow_agent.py

@@ -14,6 +14,7 @@ from agent_framework import (
     AgentSession,
     Content,
     Executor,
+    HistoryProvider,
     InMemoryHistoryProvider,
     Message,
     ResponseStream,
@@ -678,6 +679,110 @@ class TestWorkflowAgent:
 
         assert agent.context_providers == [explicit_provider]
 
+    async def test_no_history_provider_injected_when_session_is_none(self) -> None:
+        """Test that InMemoryHistoryProvider is NOT injected when session is None."""
+        capturing_executor = ConversationHistoryCapturingExecutor(id="no_session_test")
+        workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="No Session Agent")
+
+        await agent.run("hello")
+
+        assert not any(isinstance(p, InMemoryHistoryProvider) for p in agent.context_providers)
+
+    async def test_no_history_provider_injected_when_session_is_none_streaming(self) -> None:
+        """Test that InMemoryHistoryProvider is NOT injected when session is None (streaming)."""
+        capturing_executor = ConversationHistoryCapturingExecutor(id="no_session_stream_test")
+        workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="No Session Stream Agent")
+
+        async for _ in agent.run("hello", stream=True):
+            pass
+
+        assert not any(isinstance(p, InMemoryHistoryProvider) for p in agent.context_providers)
+
+    async def test_no_injection_when_history_provider_with_load_messages_exists(self) -> None:
+        """Test that no InMemoryHistoryProvider is injected when an existing HistoryProvider has load_messages=True."""
+        capturing_executor = ConversationHistoryCapturingExecutor(id="existing_provider_test")
+        workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+        existing_provider = InMemoryHistoryProvider("custom", load_messages=True)
+        agent = WorkflowAgent(
+            workflow=workflow,
+            name="Existing Provider Agent",
+            context_providers=[existing_provider],
+        )
+        session = AgentSession()
+
+        await agent.run("hello", session=session)
+
+        # Should still have only the original provider
+        history_providers = [p for p in agent.context_providers if isinstance(p, HistoryProvider)]
+        assert len(history_providers) == 1
+        assert history_providers[0] is existing_provider
+
+    async def test_injection_when_history_provider_with_load_messages_false(self) -> None:
+        """Test that InMemoryHistoryProvider IS injected when existing HistoryProvider has load_messages=False."""
+        capturing_executor = ConversationHistoryCapturingExecutor(id="no_load_provider_test")
+        workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+        audit_provider = InMemoryHistoryProvider("audit", load_messages=False)
+        agent = WorkflowAgent(
+            workflow=workflow,
+            name="Audit Provider Agent",
+            context_providers=[audit_provider],
+        )
+        session = AgentSession()
+
+        await agent.run("hello", session=session)
+
+        # Should have injected an additional InMemoryHistoryProvider with load_messages=True
+        history_providers = [p for p in agent.context_providers if isinstance(p, HistoryProvider)]
+        assert len(history_providers) == 2
+        loading_providers = [p for p in history_providers if p.load_messages]
+        assert len(loading_providers) == 1
+        assert isinstance(loading_providers[0], InMemoryHistoryProvider)
+
+    async def test_no_duplicate_injection_on_multiple_runs(self) -> None:
+        """Test that calling run() multiple times does not keep adding InMemoryHistoryProvider."""
+        capturing_executor = ConversationHistoryCapturingExecutor(id="no_dup_test")
+        workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="No Dup Agent")
+        session = AgentSession()
+
+        await agent.run("first", session=session)
+        await agent.run("second", session=session)
+        await agent.run("third", session=session)
+
+        history_providers = [p for p in agent.context_providers if isinstance(p, InMemoryHistoryProvider)]
+        assert len(history_providers) == 1
+
+    async def test_no_duplicate_injection_on_multiple_runs_streaming(self) -> None:
+        """Test that calling run(stream=True) multiple times does not keep adding InMemoryHistoryProvider."""
+        capturing_executor = ConversationHistoryCapturingExecutor(id="no_dup_stream_test")
+        workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="No Dup Stream Agent")
+        session = AgentSession()
+
+        async for _ in agent.run("first", stream=True, session=session):
+            pass
+        async for _ in agent.run("second", stream=True, session=session):
+            pass
+        async for _ in agent.run("third", stream=True, session=session):
+            pass
+
+        history_providers = [p for p in agent.context_providers if isinstance(p, InMemoryHistoryProvider)]
+        assert len(history_providers) == 1
+
+    async def test_injection_with_session_in_streaming_mode(self) -> None:
+        """Test that InMemoryHistoryProvider is injected when session is provided in streaming mode."""
+        capturing_executor = ConversationHistoryCapturingExecutor(id="stream_inject_test")
+        workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+        agent = WorkflowAgent(workflow=workflow, name="Stream Inject Agent")
+        session = AgentSession()
+
+        async for _ in agent.run("hello", stream=True, session=session):
+            pass
+
+        assert any(isinstance(p, InMemoryHistoryProvider) for p in agent.context_providers)
+
     async def test_checkpoint_storage_passed_to_workflow(self) -> None:
         """Test that checkpoint_storage parameter is passed through to the workflow."""
         from agent_framework import InMemoryCheckpointStorage

python/packages/devui/frontend/src/App.tsx

@@ -3,7 +3,7 @@
  * Features: Entity selection, layout management, debug coordination
  */
 
-import { useEffect, useCallback, useState } from "react";
+import { useEffect, useCallback, useRef, useState } from "react";
 import { AppHeader, DebugPanel, SettingsModal, DeploymentModal } from "@/components/layout";
 import { GalleryView } from "@/components/features/gallery";
 import { AgentView } from "@/components/features/agent";
@@ -15,17 +15,22 @@ import type {
   AgentInfo,
   WorkflowInfo,
   ExtendedResponseStreamEvent,
+  ResponseTextDeltaEvent,
 } from "@/types";
 import { Button } from "./components/ui/button";
 import { Input } from "./components/ui/input";
 import { useDevUIStore } from "@/stores";
 
+const DEBUG_TEXT_EVENT_FLUSH_INTERVAL_MS = 50;
+
 export default function App() {
   // Local state for auth handling
   const [authRequired, setAuthRequired] = useState(false);
   const [authToken, setAuthToken] = useState("");
   const [isTestingToken, setIsTestingToken] = useState(false);
   const [authError, setAuthError] = useState("");
+  const bufferedDebugTextRef = useRef<ResponseTextDeltaEvent | null>(null);
+  const lastBufferedDebugFlushAtRef = useRef(0);
 
   // Entity state from Zustand
   const agents = useDevUIStore((state) => state.agents);
@@ -303,16 +308,63 @@ export default function App() {
     [selectEntity, updateAgent, updateWorkflow, addToast]
   );
 
+  const flushBufferedDebugText = useCallback(() => {
+    const bufferedEvent = bufferedDebugTextRef.current;
+    if (!bufferedEvent) {
+      return;
+    }
+
+    bufferedDebugTextRef.current = null;
+    lastBufferedDebugFlushAtRef.current = performance.now();
+    addDebugEvent(bufferedEvent);
+  }, [addDebugEvent]);
+
   // Handle debug events from active view
   const handleDebugEvent = useCallback(
     (event: ExtendedResponseStreamEvent | "clear") => {
       if (event === "clear") {
+        bufferedDebugTextRef.current = null;
         clearDebugEvents();
-      } else {
-        addDebugEvent(event);
+        return;
       }
+
+      if (
+        event.type === "response.output_text.delta" &&
+        "delta" in event &&
+        typeof event.delta === "string" &&
+        event.delta.length > 0
+      ) {
+        const bufferedEvent = bufferedDebugTextRef.current;
+        const isSameOutput =
+          bufferedEvent !== null &&
+          bufferedEvent.item_id === event.item_id &&
+          bufferedEvent.output_index === event.output_index &&
+          bufferedEvent.content_index === event.content_index;
+
+        if (isSameOutput && bufferedEvent) {
+          bufferedDebugTextRef.current = {
+            ...bufferedEvent,
+            delta: bufferedEvent.delta + event.delta,
+            sequence_number: event.sequence_number ?? bufferedEvent.sequence_number,
+          };
+        } else {
+          flushBufferedDebugText();
+          bufferedDebugTextRef.current = { ...event } as ResponseTextDeltaEvent;
+        }
+
+        if (
+          performance.now() - lastBufferedDebugFlushAtRef.current >=
+          DEBUG_TEXT_EVENT_FLUSH_INTERVAL_MS
+        ) {
+          flushBufferedDebugText();
+        }
+        return;
+      }
+
+      flushBufferedDebugText();
+      addDebugEvent(event);
     },
-    [addDebugEvent, clearDebugEvents]
+    [addDebugEvent, clearDebugEvents, flushBufferedDebugText]
   );
 
   // Show loading state while initializing

python/packages/devui/frontend/src/components/features/agent/agent-view.tsx

@@ -44,6 +44,8 @@ import { loadStreamingState } from "@/services/streaming-state";
 
 type DebugEventHandler = (event: ExtendedResponseStreamEvent | "clear") => void;
 
+const ASSISTANT_TEXT_RENDER_INTERVAL_MS = 50;
+
 interface AgentViewProps {
   selectedAgent: AgentInfo;
   onDebugEvent: DebugEventHandler;
@@ -309,6 +311,71 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
   } | null>(null);
   const userJustSentMessage = useRef<boolean>(false);
   const accumulatedTextRef = useRef<string>("");
+  const lastAssistantTextRenderAt = useRef(0);
+
+  const renderAssistantStreamingText = useCallback(
+    (
+      assistantMessageId: string,
+      status: "in_progress" | "completed" | "incomplete" = "in_progress",
+      force: boolean = false
+    ) => {
+      const now = performance.now();
+      if (
+        !force &&
+        now - lastAssistantTextRenderAt.current < ASSISTANT_TEXT_RENDER_INTERVAL_MS
+      ) {
+        return;
+      }
+
+      const currentItems = useDevUIStore.getState().chatItems;
+      let changed = false;
+      const nextItems = currentItems.map((item) => {
+        if (item.id !== assistantMessageId || item.type !== "message") {
+          return item;
+        }
+
+        const nextText = accumulatedTextRef.current;
+        const existingTextContent = item.content.find(
+          (content) => content.type === "text" || content.type === "output_text"
+        );
+        const currentText =
+          existingTextContent && "text" in existingTextContent
+            ? existingTextContent.text
+            : "";
+
+        if (currentText === nextText && item.status === status) {
+          return item;
+        }
+
+        changed = true;
+        const existingNonTextContent = item.content.filter(
+          (content) => content.type !== "text" && content.type !== "output_text"
+        );
+
+        return {
+          ...item,
+          content: nextText
+            ? [
+                ...existingNonTextContent,
+                {
+                  type: "text",
+                  text: nextText,
+                } as import("@/types/openai").MessageTextContent,
+              ]
+            : existingNonTextContent,
+          status,
+        };
+      });
+
+      if (changed) {
+        lastAssistantTextRenderAt.current = now;
+        setChatItems(nextItems);
+      } else if (force) {
+        lastAssistantTextRenderAt.current = now;
+      }
+    },
+    [setChatItems]
+  );
 
   // Auto-scroll to bottom when new items arrive
   useEffect(() => {
@@ -382,6 +449,7 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
           undefined,  // No abort signal for resume
           storedState.responseId  // Pass response ID for resume
         );
+        lastAssistantTextRenderAt.current = 0;
 
         for await (const openAIEvent of streamGenerator) {
           // Pass all events to debug panel
@@ -412,6 +480,12 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
                 : JSON.stringify(error)
               : "Request failed";
 
+            if (accumulatedTextRef.current) {
+              renderAssistantStreamingText(assistantMessage.id, "incomplete", true);
+              setIsStreaming(false);
+              return;
+            }
+
             const currentItems = useDevUIStore.getState().chatItems;
             setChatItems(currentItems.map((item) =>
               item.id === assistantMessage.id && item.type === "message"
@@ -434,6 +508,7 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
           // Handle function approval request events
           if (openAIEvent.type === "response.function_approval.requested") {
             const approvalEvent = openAIEvent as import("@/types/openai").ResponseFunctionApprovalRequestedEvent;
+            renderAssistantStreamingText(assistantMessage.id, "in_progress", true);
             setPendingApprovals([
               ...useDevUIStore.getState().pendingApprovals,
               {
@@ -458,6 +533,12 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
             const errorEvent = openAIEvent as ExtendedResponseStreamEvent & { message?: string };
             const errorMessage = errorEvent.message || "An error occurred";
 
+            if (accumulatedTextRef.current) {
+              renderAssistantStreamingText(assistantMessage.id, "incomplete", true);
+              setIsStreaming(false);
+              return;
+            }
+
             const currentItems = useDevUIStore.getState().chatItems;
             setChatItems(currentItems.map((item) =>
               item.id === assistantMessage.id && item.type === "message"
@@ -484,27 +565,13 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
             openAIEvent.delta
           ) {
             accumulatedTextRef.current += openAIEvent.delta;
-
-            const currentItems = useDevUIStore.getState().chatItems;
-            setChatItems(currentItems.map((item) =>
-              item.id === assistantMessage.id && item.type === "message"
-                ? {
-                    ...item,
-                    content: [
-                      {
-                        type: "text",
-                        text: accumulatedTextRef.current,
-                      } as import("@/types/openai").MessageTextContent,
-                    ],
-                    status: "in_progress" as const,
-                  }
-                : item
-            ));
+            renderAssistantStreamingText(assistantMessage.id);
           }
         }
 
         // Stream ended - mark as complete
         const finalUsage = currentMessageUsage.current;
+        renderAssistantStreamingText(assistantMessage.id, "in_progress", true);
 
         const currentItems = useDevUIStore.getState().chatItems;
         setChatItems(currentItems.map((item) =>
@@ -721,11 +788,12 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
     setIsStreaming(false);
     setCurrentConversation(undefined);
     accumulatedTextRef.current = "";
+    lastAssistantTextRenderAt.current = 0;
 
     loadConversations();
     // currentConversation is intentionally excluded - this effect should only run when agent changes
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [selectedAgent, onDebugEvent, setChatItems, setIsStreaming, setLoadingConversations, setAvailableConversations, setCurrentConversation, setPendingApprovals, updateConversationUsage]);
+  }, [selectedAgent, onDebugEvent, renderAssistantStreamingText, setChatItems, setIsStreaming, setLoadingConversations, setAvailableConversations, setCurrentConversation, setPendingApprovals, updateConversationUsage]);
 
   // Removed old input handling functions - now handled by ChatMessageInput component
 
@@ -1118,6 +1186,7 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
 
         // Clear text accumulator for new response
         accumulatedTextRef.current = "";
+        lastAssistantTextRenderAt.current = 0;
 
         // Create new AbortController for this request
         const signal = createAbortSignal();
@@ -1167,6 +1236,12 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
             }
 
             // Update assistant message with error
+            if (accumulatedTextRef.current) {
+              renderAssistantStreamingText(assistantMessage.id, "incomplete", true);
+              setIsStreaming(false);
+              return; // Exit stream processing on failure
+            }
+
             const currentItems = useDevUIStore.getState().chatItems;
             setChatItems(currentItems.map((item) =>
               item.id === assistantMessage.id && item.type === "message"
@@ -1189,6 +1264,7 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
           // Handle function approval request events
           if (openAIEvent.type === "response.function_approval.requested") {
             const approvalEvent = openAIEvent as import("@/types/openai").ResponseFunctionApprovalRequestedEvent;
+            renderAssistantStreamingText(assistantMessage.id, "in_progress", true);
 
             // Add to pending approvals (for popup)
             setPendingApprovals([
@@ -1267,6 +1343,12 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
             const errorMessage = errorEvent.message || "An error occurred";
 
             // Update assistant message with error and stop streaming
+            if (accumulatedTextRef.current) {
+              renderAssistantStreamingText(assistantMessage.id, "incomplete", true);
+              setIsStreaming(false);
+              return; // Exit stream processing early on error
+            }
+
             const currentItems = useDevUIStore.getState().chatItems;
             setChatItems(currentItems.map((item) =>
               item.id === assistantMessage.id && item.type === "message"
@@ -1290,6 +1372,7 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
           if (openAIEvent.type === "response.output_item.added") {
             const outputItemEvent = openAIEvent as import("@/types/openai").ResponseOutputItemAddedEvent;
             const item = outputItemEvent.item;
+            renderAssistantStreamingText(assistantMessage.id, "in_progress", true);
 
             // Handle function calls as separate conversation items
             if (item.type === "function_call") {
@@ -1363,28 +1446,7 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
             openAIEvent.delta
           ) {
             accumulatedTextRef.current += openAIEvent.delta;
-
-            // Update assistant message with accumulated content
-            // Preserve any existing non-text content (images, files, data)
-            const currentItems = useDevUIStore.getState().chatItems;
-            setChatItems(currentItems.map((item) => {
-              if (item.id === assistantMessage.id && item.type === "message") {
-                // Keep existing non-text content, update text content
-                const existingNonTextContent = item.content.filter(c => c.type !== "text");
-                return {
-                  ...item,
-                  content: [
-                    ...existingNonTextContent,
-                    {
-                      type: "text",
-                      text: accumulatedTextRef.current,
-                    } as import("@/types/openai").MessageTextContent,
-                  ],
-                  status: "in_progress" as const,
-                };
-              }
-              return item;
-            }));
+            renderAssistantStreamingText(assistantMessage.id);
           }
 
           // Handle completion/error by detecting when streaming stops
@@ -1394,6 +1456,7 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
         // Stream ended - mark as complete
         // Usage is provided via response.completed event (OpenAI standard)
         const finalUsage = currentMessageUsage.current;
+        renderAssistantStreamingText(assistantMessage.id, "in_progress", true);
 
         const currentItems = useDevUIStore.getState().chatItems;
         setChatItems(currentItems.map((item) =>
@@ -1419,45 +1482,42 @@ export function AgentView({ selectedAgent, onDebugEvent }: AgentViewProps) {
         if (isAbortError(error)) {
           // User cancelled - mark as cancelled for UI feedback
           setWasCancelled(true);
-          // Mark the message as completed with what we have
-          const currentItems = useDevUIStore.getState().chatItems;
-          setChatItems(currentItems.map((item) =>
-            item.id === assistantMessage.id && item.type === "message"
-              ? {
-                  ...item,
-                  status: accumulatedTextRef.current ? "completed" as const : "incomplete" as const,
-                  // Keep whatever text we have accumulated
-                  content: item.content,
-                }
-              : item
-          ));
+          renderAssistantStreamingText(
+            assistantMessage.id,
+            accumulatedTextRef.current ? "completed" : "incomplete",
+            true
+          );
         } else {
           // Other errors - show error message
-          const currentItems = useDevUIStore.getState().chatItems;
-          setChatItems(currentItems.map((item) =>
-            item.id === assistantMessage.id && item.type === "message"
-              ? {
-                  ...item,
-                  content: [
-                    {
-                      type: "text",
-                      text: `Error: ${
-                        error instanceof Error
-                          ? error.message
-                          : "Failed to get response"
-                      }`,
-                    } as import("@/types/openai").MessageTextContent,
-                  ],
-                  status: "incomplete" as const,
-                }
-              : item
-          ));
+          if (accumulatedTextRef.current) {
+            renderAssistantStreamingText(assistantMessage.id, "incomplete", true);
+          } else {
+            const currentItems = useDevUIStore.getState().chatItems;
+            setChatItems(currentItems.map((item) =>
+              item.id === assistantMessage.id && item.type === "message"
+                ? {
+                    ...item,
+                    content: [
+                      {
+                        type: "text",
+                        text: `Error: ${
+                          error instanceof Error
+                            ? error.message
+                            : "Failed to get response"
+                        }`,
+                      } as import("@/types/openai").MessageTextContent,
+                    ],
+                    status: "incomplete" as const,
+                  }
+                : item
+            ));
+          }
         }
         setIsStreaming(false);
         resetCancelling();
       }
     },
-    [selectedAgent, currentConversation, onDebugEvent, setChatItems, setIsStreaming, setCurrentConversation, setAvailableConversations, setPendingApprovals, updateConversationUsage, createAbortSignal, resetCancelling]
+    [selectedAgent, currentConversation, onDebugEvent, renderAssistantStreamingText, setChatItems, setIsStreaming, setCurrentConversation, setAvailableConversations, setPendingApprovals, updateConversationUsage, createAbortSignal, resetCancelling]
   );
 
   // Handle non-streaming message sending

python/packages/devui/frontend/src/services/api.ts

@@ -16,9 +16,10 @@ import type {
 import type { AgentFrameworkRequest } from "@/types/agent-framework";
 import type { ExtendedResponseStreamEvent } from "@/types/openai";
 import {
+  applyStreamingEventToState,
+  createStreamingState,
   loadStreamingState,
-  updateStreamingState,
-  markStreamingCompleted,
+  saveStreamingState,
   clearStreamingState,
 } from "./streaming-state";
 import { isAbortError } from "@/hooks";
@@ -72,6 +73,7 @@ const DEFAULT_API_BASE_URL =
 // Retry configuration for streaming
 const RETRY_INTERVAL_MS = 1000; // Base retry interval (will use exponential backoff)
 const MAX_RETRY_ATTEMPTS = 10; // Max 10 retries (~30 seconds with exponential backoff)
+const STREAMING_STATE_SAVE_INTERVAL_MS = 250;
 
 // Get backend URL from localStorage or default
 function getBackendUrl(): string {
@@ -223,7 +225,7 @@ class ApiClient {
           chat_client_type: entity.chat_client_type,
           context_provider: entity.context_provider,
           middleware: entity.middleware,
-        };
+        } as AgentInfo;
       } else {
         // Workflow - prefer executors field, fall back to tools for backward compatibility
         const executorList = entity.executors || entity.tools || [];
@@ -263,7 +265,7 @@ class ApiClient {
           input_type_name: entity.input_type_name || "Input",
           start_executor_id: startExecutorId,
           tools: [],
-        };
+        } as WorkflowInfo;
       }
     });
 
@@ -484,31 +486,65 @@ class ApiClient {
     let hasYieldedAnyEvent = false;
     let currentResponseId: string | undefined = resumeResponseId;
     let lastMessageId: string | undefined = undefined;
+    let lastStreamingStateSaveAt = 0;
+    let storedState = conversationId ? loadStreamingState(conversationId) : null;
+    let streamingState = storedState ? { ...storedState } : null;
+
+    const persistStreamingState = (force: boolean = false): void => {
+      if (!conversationId || !streamingState) {
+        return;
+      }
+
+      const now = Date.now();
+      if (!force && now - lastStreamingStateSaveAt < STREAMING_STATE_SAVE_INTERVAL_MS) {
+        return;
+      }
+
+      lastStreamingStateSaveAt = now;
+      saveStreamingState({
+        ...streamingState,
+        timestamp: now,
+      });
+    };
+
+    const recordStreamingEvent = (event: ExtendedResponseStreamEvent): void => {
+      if (!conversationId || !currentResponseId) {
+        return;
+      }
+
+      streamingState = applyStreamingEventToState(
+        streamingState ?? createStreamingState({
+          conversationId,
+          responseId: currentResponseId,
+          lastMessageId,
+          lastSequenceNumber,
+          accumulatedText: storedState?.accumulatedText,
+        }),
+        event,
+        currentResponseId,
+        lastMessageId
+      );
+
+      const isTextDelta =
+        event.type === "response.output_text.delta" &&
+        "delta" in event &&
+        typeof event.delta === "string" &&
+        event.delta.length > 0;
+      persistStreamingState(!isTextDelta);
+    };
 
     // Try to resume from stored state if conversation ID is provided
-    if (conversationId) {
-      const storedState = loadStreamingState(conversationId);
-      if (storedState) {
-        // Use stored response ID if no explicit one provided
-        if (!resumeResponseId) {
-          currentResponseId = storedState.responseId;
-        }
-
-        lastSequenceNumber = storedState.lastSequenceNumber;
-        lastMessageId = storedState.lastMessageId;
-
-        // Replay stored events only if we're not explicitly resuming
-        // (explicit resume means the caller already has the events)
-        if (!resumeResponseId) {
-          for (const event of storedState.events) {
-            hasYieldedAnyEvent = true;
-            yield event;
-          }
-        } else {
-          // Mark that we've already seen events up to this sequence number
-          hasYieldedAnyEvent = storedState.events.length > 0;
-        }
+    if (storedState) {
+      // Use stored response ID if no explicit one provided
+      if (!resumeResponseId) {
+        currentResponseId = storedState.responseId;
       }
+
+      lastSequenceNumber = storedState.lastSequenceNumber;
+      lastMessageId = storedState.lastMessageId;
+      hasYieldedAnyEvent =
+        storedState.lastSequenceNumber >= 0 ||
+        Boolean(storedState.accumulatedText);
     }
 
     while (retryCount <= MAX_RETRY_ATTEMPTS) {
@@ -621,7 +657,8 @@ class ApiClient {
             if (done) {
               // Stream completed successfully
               if (conversationId) {
-                markStreamingCompleted(conversationId);
+                clearStreamingState(conversationId);
+                streamingState = null;
               }
               return;
             }
@@ -640,7 +677,8 @@ class ApiClient {
                 // Handle [DONE] signal
                 if (dataStr === "[DONE]") {
                   if (conversationId) {
-                    markStreamingCompleted(conversationId);
+                    clearStreamingState(conversationId);
+                    streamingState = null;
                   }
                   return;
                 }
@@ -676,6 +714,9 @@ class ApiClient {
                       if (conversationId) {
                         clearStreamingState(conversationId);
                       }
+                      storedState = null;
+                      streamingState = null;
+                      lastStreamingStateSaveAt = 0;
                       yield {
                         type: "error",
                         message: "Connection lost - previous response failed. Starting new response.",
@@ -684,9 +725,7 @@ class ApiClient {
                       hasYieldedAnyEvent = true;
 
                       // Save new event to storage
-                      if (conversationId && currentResponseId) {
-                        updateStreamingState(conversationId, openAIEvent, currentResponseId, lastMessageId);
-                      }
+                      recordStreamingEvent(openAIEvent);
 
                       yield openAIEvent;
                     }
@@ -698,9 +737,7 @@ class ApiClient {
                       hasYieldedAnyEvent = true;
 
                       // Save event to storage before yielding
-                      if (conversationId && currentResponseId) {
-                        updateStreamingState(conversationId, openAIEvent, currentResponseId, lastMessageId);
-                      }
+                      recordStreamingEvent(openAIEvent);
 
                       yield openAIEvent;
                     }
@@ -709,9 +746,7 @@ class ApiClient {
                     hasYieldedAnyEvent = true;
 
                     // Still save to storage if we have conversation context
-                    if (conversationId && currentResponseId) {
-                      updateStreamingState(conversationId, openAIEvent, currentResponseId, lastMessageId);
-                    }
+                    recordStreamingEvent(openAIEvent);
 
                     yield openAIEvent;
                   }
@@ -730,7 +765,8 @@ class ApiClient {
         // Don't retry on abort
         if (isAbortError(error)) {
           if (conversationId) {
-            markStreamingCompleted(conversationId); // Clean up state
+            clearStreamingState(conversationId);
+            streamingState = null;
           }
           throw error; // Re-throw abort error without retrying
         }

python/packages/devui/frontend/src/services/streaming-state.ts

@@ -3,7 +3,6 @@
  *
  * Manages browser storage of streaming response state to enable:
  * - Resume interrupted streams after page refresh
- * - Replay cached events before fetching new ones
  * - Graceful recovery from network disconnections
  */
 
@@ -14,7 +13,6 @@ export interface StreamingState {
   responseId: string;
   lastMessageId?: string;
   lastSequenceNumber: number;
-  events: ExtendedResponseStreamEvent[];
   timestamp: number; // When this state was last updated
   completed: boolean; // Whether the stream completed successfully
   accumulatedText?: string; // Accumulated text content for quick restoration
@@ -23,6 +21,14 @@ export interface StreamingState {
 const STORAGE_KEY_PREFIX = "devui_streaming_state_";
 const STATE_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24 hours
 
+interface CreateStreamingStateOptions {
+  conversationId: string;
+  responseId: string;
+  lastMessageId?: string;
+  lastSequenceNumber?: number;
+  accumulatedText?: string;
+}
+
 /**
  * Storage key for a specific conversation
  */
@@ -31,16 +37,81 @@ function getStorageKey(conversationId: string): string {
 }
 
 /**
- * Extract accumulated text from events (for quick restoration)
+ * Read raw streaming state from storage, including completed entries.
  */
-function extractAccumulatedText(events: ExtendedResponseStreamEvent[]): string {
-  let text = "";
-  for (const event of events) {
-    if (event.type === "response.output_text.delta" && "delta" in event) {
-      text += event.delta;
-    }
+function readStreamingState(conversationId: string): StreamingState | null {
+  const key = getStorageKey(conversationId);
+  const data = localStorage.getItem(key);
+
+  if (!data) {
+    return null;
   }
-  return text;
+
+  const state: StreamingState = JSON.parse(data);
+
+  // Check if state has expired
+  const age = Date.now() - state.timestamp;
+  if (age > STATE_EXPIRY_MS) {
+    clearStreamingState(conversationId);
+    return null;
+  }
+
+  return state;
+}
+
+/**
+ * Create an initial streaming state snapshot.
+ */
+export function createStreamingState({
+  conversationId,
+  responseId,
+  lastMessageId,
+  lastSequenceNumber = -1,
+  accumulatedText,
+}: CreateStreamingStateOptions): StreamingState {
+  return {
+    conversationId,
+    responseId,
+    lastMessageId,
+    lastSequenceNumber,
+    timestamp: Date.now(),
+    completed: false,
+    accumulatedText,
+  };
+}
+
+/**
+ * Apply an incoming stream event to an in-memory streaming state snapshot.
+ */
+export function applyStreamingEventToState(
+  state: StreamingState,
+  event: ExtendedResponseStreamEvent,
+  responseId: string,
+  lastMessageId?: string
+): StreamingState {
+  const sequenceNumber = "sequence_number" in event ? event.sequence_number : undefined;
+  const nextState: StreamingState = {
+    ...state,
+    responseId,
+    lastMessageId,
+    timestamp: Date.now(),
+    completed: event.type === "response.completed" || event.type === "response.failed",
+  };
+
+  if (sequenceNumber !== undefined) {
+    nextState.lastSequenceNumber = sequenceNumber;
+  }
+
+  if (
+    event.type === "response.output_text.delta" &&
+    "delta" in event &&
+    typeof event.delta === "string" &&
+    event.delta.length > 0
+  ) {
+    nextState.accumulatedText = `${state.accumulatedText ?? ""}${event.delta}`;
+  }
+
+  return nextState;
 }
 
 /**
@@ -71,19 +142,8 @@ export function saveStreamingState(state: StreamingState): void {
  */
 export function loadStreamingState(conversationId: string): StreamingState | null {
   try {
-    const key = getStorageKey(conversationId);
-    const data = localStorage.getItem(key);
-
-    if (!data) {
-      return null;
-    }
-
-    const state: StreamingState = JSON.parse(data);
-
-    // Check if state has expired
-    const age = Date.now() - state.timestamp;
-    if (age > STATE_EXPIRY_MS) {
-      clearStreamingState(conversationId);
+    const state = readStreamingState(conversationId);
+    if (!state) {
       return null;
     }
 
@@ -99,54 +159,6 @@ export function loadStreamingState(conversationId: string): StreamingState | nul
   }
 }
 
-/**
- * Update streaming state with a new event
- */
-export function updateStreamingState(
-  conversationId: string,
-  event: ExtendedResponseStreamEvent,
-  responseId: string,
-  lastMessageId?: string
-): void {
-  try {
-    const existing = loadStreamingState(conversationId);
-    const sequenceNumber = "sequence_number" in event ? event.sequence_number : undefined;
-
-    const newEvents = existing ? [...existing.events, event] : [event];
-
-    const state: StreamingState = {
-      conversationId,
-      responseId,
-      lastMessageId,
-      lastSequenceNumber: sequenceNumber ?? (existing?.lastSequenceNumber ?? -1),
-      events: newEvents,
-      timestamp: Date.now(),
-      completed: event.type === "response.completed" || event.type === "response.failed",
-      accumulatedText: extractAccumulatedText(newEvents),
-    };
-
-    saveStreamingState(state);
-  } catch (error) {
-    console.error("Failed to update streaming state:", error);
-  }
-}
-
-/**
- * Mark streaming state as completed
- */
-export function markStreamingCompleted(conversationId: string): void {
-  try {
-    const existing = loadStreamingState(conversationId);
-    if (existing) {
-      existing.completed = true;
-      existing.timestamp = Date.now();
-      saveStreamingState(existing);
-    }
-  } catch (error) {
-    console.error("Failed to mark streaming as completed:", error);
-  }
-}
-
 /**
  * Clear streaming state for a conversation
  */

python/packages/devui/tests/devui/test_ui_memory_regression.py

@@ -0,0 +1,750 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Browser-based regression test for DevUI streaming memory growth."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import http.client
+import json
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from collections.abc import AsyncIterable, Awaitable, Generator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import pytest
+import uvicorn
+from agent_framework import (
+    AgentResponse,
+    AgentResponseUpdate,
+    AgentSession,
+    BaseAgent,
+    Content,
+    Message,
+    ResponseStream,
+)
+from websockets.asyncio.client import connect as websocket_connect
+
+from agent_framework_devui import DevServer
+
+_BROWSER_COMMANDS = (
+    "chrome",
+    "chrome.exe",
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+    "microsoft-edge",
+    "msedge",
+    "msedge.exe",
+)
+_BROWSER_ENV_VARS = ("DEVUI_TEST_BROWSER", "CHROME_BIN", "BROWSER_BIN")
+_WINDOWS_PROCESS_QUERY = """
+$rows = @(
+    Get-CimInstance Win32_Process | ForEach-Object {
+        if (-not $_.CommandLine) {
+            return
+        }
+
+        try {
+            $process = Get-Process -Id $_.ProcessId -ErrorAction Stop
+            [PSCustomObject]@{
+                pid = [int]$_.ProcessId
+                parent_pid = [int]$_.ParentProcessId
+                rss_kb = [int][Math]::Round($process.WorkingSet64 / 1KB)
+                command = [string]$_.CommandLine
+            }
+        }
+        catch {
+        }
+    }
+)
+
+$rows | ConvertTo-Json -Compress
+""".strip()
+
+_STREAM_CHUNK_COUNT = 12_000
+_STREAM_CHUNK_SIZE = 128
+_POST_SEND_DELAY_S = 1.0
+_SAMPLE_INTERVAL_S = 0.5
+_SAMPLE_WINDOW_S = 12.0
+_MAX_RENDERER_GROWTH_MB = 500.0
+
+
+@dataclass(frozen=True)
+class _BrowserProcessRow:
+    pid: int
+    parent_pid: int
+    rss_kb: int
+    command: str
+
+
+class MemoryStressAgent(BaseAgent):
+    """Agent that emits many small streaming chunks."""
+
+    def __init__(self, *, chunk_count: int, chunk_size: int, delay_ms: float, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._chunk_count = chunk_count
+        self._chunk_size = max(chunk_size, 24)
+        self._delay_s = max(delay_ms, 0.0) / 1000.0
+
+    def run(
+        self,
+        messages: str | Message | list[str] | list[Message] | None = None,
+        *,
+        stream: bool = False,
+        session: AgentSession | None = None,
+        **kwargs: Any,
+    ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
+        del messages, session, kwargs
+        if stream:
+            return self._run_stream()
+        return self._run()
+
+    async def _run(self) -> AgentResponse:
+        text = "".join(self._make_chunk(index) for index in range(self._chunk_count))
+        return AgentResponse(messages=[Message("assistant", [Content.from_text(text=text)])])
+
+    def _run_stream(self) -> ResponseStream[AgentResponseUpdate, AgentResponse]:
+        async def _iter() -> AsyncIterable[AgentResponseUpdate]:
+            for index in range(self._chunk_count):
+                yield AgentResponseUpdate(
+                    contents=[Content.from_text(text=self._make_chunk(index))],
+                    role="assistant",
+                )
+                if self._delay_s:
+                    await asyncio.sleep(self._delay_s)
+
+        return ResponseStream(_iter(), finalizer=AgentResponse.from_updates)
+
+    def _make_chunk(self, index: int) -> str:
+        prefix = f"[{index:06d}] "
+        payload_size = max(self._chunk_size - len(prefix), 1)
+        payload = ("x" * (payload_size - 1)) + ("\n" if index % 8 == 7 else " ")
+        return prefix + payload
+
+
+class _CDPClient:
+    """Minimal Chrome DevTools Protocol client for a single attached page."""
+
+    def __init__(self, websocket: Any) -> None:
+        self._websocket = websocket
+        self._next_id = 0
+
+    async def send(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        session_id: str | None = None,
+    ) -> dict[str, Any]:
+        self._next_id += 1
+        command_id = self._next_id
+        payload: dict[str, Any] = {"id": command_id, "method": method}
+        if params is not None:
+            payload["params"] = params
+        if session_id is not None:
+            payload["sessionId"] = session_id
+
+        await self._websocket.send(json.dumps(payload))
+
+        while True:
+            raw_message = await self._websocket.recv()
+            if isinstance(raw_message, bytes):
+                raw_message = raw_message.decode("utf-8")
+
+            message = json.loads(raw_message)
+            if message.get("id") != command_id:
+                continue
+
+            error = message.get("error")
+            if isinstance(error, dict):
+                raise RuntimeError(f"CDP command {method} failed: {error}")
+
+            result = message.get("result")
+            return result if isinstance(result, dict) else {}
+
+    async def evaluate(self, expression: str, *, session_id: str) -> Any:
+        result = await self.send(
+            "Runtime.evaluate",
+            {
+                "expression": expression,
+                "awaitPromise": True,
+                "returnByValue": True,
+            },
+            session_id=session_id,
+        )
+        remote_result = result.get("result")
+        if isinstance(remote_result, dict):
+            return remote_result.get("value")
+        return None
+
+
+def _get_browser_candidates() -> tuple[Path, ...]:
+    if sys.platform == "darwin":
+        return (
+            Path("/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),
+            Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+            Path("/Applications/Chromium.app/Contents/MacOS/Chromium"),
+        )
+
+    if sys.platform == "win32":
+        windows_bases: list[Path] = []
+        for env_var in ("PROGRAMFILES", "PROGRAMFILES(X86)", "LOCALAPPDATA"):
+            raw_value = os.environ.get(env_var)
+            if raw_value:
+                windows_bases.append(Path(raw_value))
+
+        return tuple(
+            dict.fromkeys(
+                [base / "Microsoft/Edge/Application/msedge.exe" for base in windows_bases]
+                + [base / "Google/Chrome/Application/chrome.exe" for base in windows_bases]
+                + [base / "Chromium/Application/chrome.exe" for base in windows_bases]
+            )
+        )
+
+    return (
+        Path("/usr/bin/google-chrome"),
+        Path("/usr/bin/google-chrome-stable"),
+        Path("/usr/bin/chromium"),
+        Path("/usr/bin/chromium-browser"),
+        Path("/usr/bin/microsoft-edge"),
+        Path("/opt/google/chrome/chrome"),
+        Path("/opt/microsoft/msedge/msedge"),
+        Path("/snap/bin/chromium"),
+    )
+
+
+def _find_browser_executable() -> Path | None:
+    for env_var in _BROWSER_ENV_VARS:
+        configured_path = os.environ.get(env_var)
+        if not configured_path:
+            continue
+
+        candidate = Path(configured_path).expanduser()
+        if candidate.exists():
+            return candidate
+
+    for candidate in _get_browser_candidates():
+        if candidate.exists():
+            return candidate
+
+    for command in _BROWSER_COMMANDS:
+        resolved = shutil.which(command)
+        if resolved is not None:
+            return Path(resolved)
+
+    return None
+
+
+def _find_available_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        sock.listen(1)
+        return int(sock.getsockname()[1])
+
+
+def _get_json_response(*, host: str, port: int, path: str) -> dict[str, Any]:
+    connection = http.client.HTTPConnection(host, port, timeout=5)
+    try:
+        connection.request("GET", path)
+        response = connection.getresponse()
+        if response.status != 200:
+            raise RuntimeError(f"Request to {path} failed with status {response.status}")
+        payload = response.read().decode("utf-8")
+    finally:
+        connection.close()
+
+    data = json.loads(payload)
+    if isinstance(data, dict):
+        return data
+    raise RuntimeError(f"Expected JSON object from {path}, got: {type(data).__name__}")
+
+
+async def _get_devtools_websocket_url(port: int) -> str:
+    deadline = time.monotonic() + 10.0
+    while time.monotonic() < deadline:
+        with contextlib.suppress(Exception):
+            version_data = _get_json_response(host="127.0.0.1", port=port, path="/json/version")
+            websocket_url = version_data.get("webSocketDebuggerUrl")
+            if isinstance(websocket_url, str) and websocket_url:
+                return websocket_url
+        await asyncio.sleep(0.1)
+
+    raise RuntimeError(f"Timed out waiting for DevTools on port {port}")
+
+
+def _wait_for_server_details(server_instance: uvicorn.Server) -> tuple[int, str]:
+    deadline = time.monotonic() + 10.0
+    actual_port: int | None = None
+
+    while time.monotonic() < deadline:
+        if hasattr(server_instance, "servers") and server_instance.servers:
+            for uvicorn_server in server_instance.servers:
+                sockets = getattr(uvicorn_server, "sockets", None)
+                if not sockets:
+                    continue
+                actual_port = int(sockets[0].getsockname()[1])
+                break
+
+        if actual_port is not None:
+            with contextlib.suppress(Exception):
+                health = _get_json_response(host="127.0.0.1", port=actual_port, path="/health")
+                if health.get("status") == "healthy":
+                    entities = _get_json_response(host="127.0.0.1", port=actual_port, path="/v1/entities")
+                    entity_list = entities.get("entities")
+                    if isinstance(entity_list, list) and entity_list:
+                        entity = entity_list[0]
+                        if isinstance(entity, dict) and isinstance(entity.get("id"), str):
+                            return actual_port, entity["id"]
+        time.sleep(0.1)
+
+    raise RuntimeError("Timed out waiting for DevUI server startup")
+
+
+def _parse_posix_process_rows(output: str) -> list[_BrowserProcessRow]:
+    rows: list[_BrowserProcessRow] = []
+    for line in output.splitlines():
+        parts = line.strip().split(None, 3)
+        if len(parts) != 4:
+            continue
+
+        pid_text, parent_pid_text, rss_text, command = parts
+        with contextlib.suppress(ValueError):
+            rows.append(
+                _BrowserProcessRow(
+                    pid=int(pid_text),
+                    parent_pid=int(parent_pid_text),
+                    rss_kb=int(rss_text),
+                    command=command,
+                )
+            )
+
+    return rows
+
+
+def _parse_windows_process_rows(output: str) -> list[_BrowserProcessRow]:
+    text = output.strip()
+    if not text:
+        return []
+
+    payload = json.loads(text)
+    items = payload if isinstance(payload, list) else [payload]
+
+    rows: list[_BrowserProcessRow] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+
+        pid = item.get("pid")
+        parent_pid = item.get("parent_pid")
+        rss_kb = item.get("rss_kb")
+        command = item.get("command")
+        if not all(isinstance(value, int) for value in (pid, parent_pid, rss_kb)):
+            continue
+        if not isinstance(command, str):
+            continue
+
+        rows.append(
+            _BrowserProcessRow(
+                pid=pid,
+                parent_pid=parent_pid,
+                rss_kb=rss_kb,
+                command=command,
+            )
+        )
+
+    return rows
+
+
+def _read_process_rows() -> list[_BrowserProcessRow]:
+    if sys.platform == "win32":
+        result = subprocess.run(
+            ["powershell", "-NoProfile", "-Command", _WINDOWS_PROCESS_QUERY],
+            capture_output=True,
+            text=True,
+            check=True,
+            encoding="utf-8",
+        )
+        return _parse_windows_process_rows(result.stdout)
+
+    result = subprocess.run(
+        ["ps", "-axo", "pid=,ppid=,rss=,command="],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return _parse_posix_process_rows(result.stdout)
+
+
+def _collect_process_tree(root_pids: set[int], process_rows: list[_BrowserProcessRow]) -> list[_BrowserProcessRow]:
+    process_by_pid = {row.pid: row for row in process_rows}
+    child_pids_by_parent: dict[int, list[int]] = {}
+    for row in process_rows:
+        child_pids_by_parent.setdefault(row.parent_pid, []).append(row.pid)
+
+    collected_rows: list[_BrowserProcessRow] = []
+    seen_pids: set[int] = set()
+    pending_pids = list(root_pids)
+
+    while pending_pids:
+        pid = pending_pids.pop()
+        if pid in seen_pids:
+            continue
+
+        seen_pids.add(pid)
+        process_row = process_by_pid.get(pid)
+        if process_row is None:
+            continue
+
+        collected_rows.append(process_row)
+        pending_pids.extend(child_pids_by_parent.get(pid, []))
+
+    return collected_rows
+
+
+def _collect_browser_process_rows(root_pid: int, profile_dir: str) -> list[_BrowserProcessRow]:
+    process_rows = _read_process_rows()
+    normalized_profile_dir = profile_dir.casefold()
+    matched_root_pids = {row.pid for row in process_rows if normalized_profile_dir in row.command.casefold()}
+    matched_root_pids.add(root_pid)
+    return _collect_process_tree(matched_root_pids, process_rows)
+
+
+def _sample_peak_renderer_rss_mb(root_pid: int, profile_dir: str) -> float:
+    renderer_rss_kb = [
+        row.rss_kb
+        for row in _collect_browser_process_rows(root_pid, profile_dir)
+        if "--type=renderer" in row.command.casefold()
+    ]
+    return round((max(renderer_rss_kb, default=0)) / 1024, 2)
+
+
+def _terminate_browser_processes(root_pid: int, profile_dir: str) -> None:
+    browser_rows = _collect_browser_process_rows(root_pid, profile_dir)
+    browser_pids = sorted({row.pid for row in browser_rows} | {root_pid}, reverse=True)
+
+    if sys.platform == "win32":
+        for pid in browser_pids:
+            with contextlib.suppress(subprocess.CalledProcessError):
+                subprocess.run(
+                    ["taskkill", "/PID", str(pid), "/T", "/F"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    check=True,
+                )
+        return
+
+    for pid in browser_pids:
+        with contextlib.suppress(ProcessLookupError):
+            os.kill(pid, signal.SIGTERM)
+
+
+def _launch_browser_process(*, browser_path: Path, debug_port: int, profile_dir: str) -> subprocess.Popen[str]:
+    return subprocess.Popen(
+        [
+            str(browser_path),
+            "--headless=new",
+            f"--remote-debugging-port={debug_port}",
+            "--remote-debugging-address=127.0.0.1",
+            f"--user-data-dir={profile_dir}",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-background-networking",
+            "--disable-sync",
+            "--disable-renderer-backgrounding",
+            "--hide-scrollbars",
+            "--mute-audio",
+            "--enable-precise-memory-info",
+            "--no-sandbox",
+            "about:blank",
+        ],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        text=True,
+    )
+
+
+def _shutdown_browser_process(browser_process: subprocess.Popen[str], *, profile_dir: str) -> None:
+    with contextlib.suppress(Exception):
+        browser_process.terminate()
+        browser_process.wait(timeout=5)
+    _terminate_browser_processes(browser_process.pid, profile_dir)
+
+
+def test_parse_posix_process_rows() -> None:
+    output = """
+      101 1 2048 /usr/bin/google-chrome --user-data-dir=/tmp/devui-memory
+      202 101 4096 /usr/bin/google-chrome --type=renderer --lang=en-US
+    """.strip()
+
+    assert _parse_posix_process_rows(output) == [
+        _BrowserProcessRow(
+            pid=101,
+            parent_pid=1,
+            rss_kb=2048,
+            command="/usr/bin/google-chrome --user-data-dir=/tmp/devui-memory",
+        ),
+        _BrowserProcessRow(
+            pid=202,
+            parent_pid=101,
+            rss_kb=4096,
+            command="/usr/bin/google-chrome --type=renderer --lang=en-US",
+        ),
+    ]
+
+
+def test_parse_windows_process_rows() -> None:
+    output = json.dumps([
+        {
+            "pid": 301,
+            "parent_pid": 1,
+            "rss_kb": 2048,
+            "command": r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+        },
+        {
+            "pid": 302,
+            "parent_pid": 301,
+            "rss_kb": 6144,
+            "command": r"C:\Program Files\Google\Chrome\Application\chrome.exe --type=renderer",
+        },
+    ])
+
+    assert _parse_windows_process_rows(output) == [
+        _BrowserProcessRow(
+            pid=301,
+            parent_pid=1,
+            rss_kb=2048,
+            command=r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+        ),
+        _BrowserProcessRow(
+            pid=302,
+            parent_pid=301,
+            rss_kb=6144,
+            command=r"C:\Program Files\Google\Chrome\Application\chrome.exe --type=renderer",
+        ),
+    ]
+
+
+def test_sample_peak_renderer_rss_mb_uses_browser_process_tree(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    profile_dir = "/tmp/devui-memory-browser"
+    process_rows = [
+        _BrowserProcessRow(
+            pid=101,
+            parent_pid=1,
+            rss_kb=1024,
+            command="/usr/bin/google-chrome",
+        ),
+        _BrowserProcessRow(
+            pid=102,
+            parent_pid=101,
+            rss_kb=4096,
+            command="/usr/bin/google-chrome --type=renderer",
+        ),
+        _BrowserProcessRow(
+            pid=201,
+            parent_pid=1,
+            rss_kb=2048,
+            command=f"/usr/bin/google-chrome --user-data-dir={profile_dir}",
+        ),
+        _BrowserProcessRow(
+            pid=202,
+            parent_pid=201,
+            rss_kb=8192,
+            command="/usr/bin/google-chrome --type=renderer",
+        ),
+        _BrowserProcessRow(
+            pid=999,
+            parent_pid=1,
+            rss_kb=32768,
+            command="/usr/bin/google-chrome --type=renderer",
+        ),
+    ]
+
+    monkeypatch.setattr(sys.modules[__name__], "_read_process_rows", lambda: process_rows)
+
+    assert _sample_peak_renderer_rss_mb(101, profile_dir) == 8.0
+
+
+@pytest.fixture
+def memory_regression_server() -> Generator[tuple[str, str]]:
+    """Start DevUI with a synthetic streaming agent and yield the base URL plus entity ID."""
+
+    server = DevServer(host="127.0.0.1", port=0)
+    server.register_entities([
+        MemoryStressAgent(
+            id="memory-stream-agent",
+            name="MemoryStreamAgent",
+            description="Streams many small chunks for UI memory profiling.",
+            chunk_count=_STREAM_CHUNK_COUNT,
+            chunk_size=_STREAM_CHUNK_SIZE,
+            delay_ms=1.0,
+        )
+    ])
+
+    app = server.get_app()
+    server_config = uvicorn.Config(
+        app=app,
+        host="127.0.0.1",
+        port=0,
+        log_level="error",
+        ws="none",
+    )
+    server_instance = uvicorn.Server(server_config)
+
+    def run_server() -> None:
+        asyncio.run(server_instance.serve())
+
+    server_thread = threading.Thread(target=run_server, daemon=True)
+    server_thread.start()
+
+    actual_port, entity_id = _wait_for_server_details(server_instance)
+    yield f"http://127.0.0.1:{actual_port}", entity_id
+
+    with contextlib.suppress(Exception):
+        server_instance.should_exit = True
+    server_thread.join(timeout=5)
+
+
+async def _wait_for_expression(
+    client: _CDPClient,
+    *,
+    session_id: str,
+    expression: str,
+    timeout_s: float,
+) -> Any:
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        value = await client.evaluate(expression, session_id=session_id)
+        if value:
+            return value
+        await asyncio.sleep(0.1)
+
+    raise AssertionError(f"Timed out waiting for expression: {expression}")
+
+
+async def test_devui_streaming_renderer_memory_is_bounded(
+    memory_regression_server: tuple[str, str],
+) -> None:
+    """Fail when frontend renderer memory grows unbounded during streaming."""
+
+    browser_path = _find_browser_executable()
+    if browser_path is None:
+        pytest.skip("No Chromium-based browser found for DevUI memory regression test")
+
+    base_url, entity_id = memory_regression_server
+    debug_port = _find_available_port()
+
+    with tempfile.TemporaryDirectory(prefix="devui-memory-browser-") as profile_dir:
+        browser_process = _launch_browser_process(
+            browser_path=browser_path,
+            debug_port=debug_port,
+            profile_dir=profile_dir,
+        )
+
+        try:
+            websocket_url = await _get_devtools_websocket_url(debug_port)
+
+            async with websocket_connect(websocket_url, max_size=None) as websocket:
+                client = _CDPClient(websocket)
+
+                target = await client.send("Target.createTarget", {"url": "about:blank"})
+                target_id = target["targetId"]
+                attached = await client.send(
+                    "Target.attachToTarget",
+                    {"targetId": target_id, "flatten": True},
+                )
+                session_id = attached["sessionId"]
+
+                await client.send("Page.enable", session_id=session_id)
+                await client.send("Runtime.enable", session_id=session_id)
+                await client.send(
+                    "Page.navigate",
+                    {"url": f"{base_url}/?entity_id={entity_id}"},
+                    session_id=session_id,
+                )
+
+                await _wait_for_expression(
+                    client,
+                    session_id=session_id,
+                    expression=(
+                        "Boolean("
+                        "document.querySelector('textarea') && "
+                        "document.querySelector('button[aria-label=\"Send message\"]')"
+                        ")"
+                    ),
+                    timeout_s=30.0,
+                )
+
+                start_renderer_rss_mb = _sample_peak_renderer_rss_mb(
+                    browser_process.pid,
+                    profile_dir,
+                )
+
+                await client.evaluate(
+                    """
+                    (() => {
+                      const textarea = document.querySelector("textarea");
+                      const valueSetter = Object.getOwnPropertyDescriptor(
+                        HTMLTextAreaElement.prototype,
+                        "value"
+                      ).set;
+                      valueSetter.call(textarea, "Stream a very long answer.");
+                      textarea.dispatchEvent(new Event("input", { bubbles: true }));
+                      document.querySelector('button[aria-label="Send message"]').click();
+                      return true;
+                    })()
+                    """,
+                    session_id=session_id,
+                )
+
+                await _wait_for_expression(
+                    client,
+                    session_id=session_id,
+                    expression="Boolean(document.querySelector('button[aria-label=\"Stop generating response\"]'))",
+                    timeout_s=10.0,
+                )
+
+                await asyncio.sleep(_POST_SEND_DELAY_S)
+
+                peak_renderer_rss_mb = start_renderer_rss_mb
+                samples: list[tuple[float, float]] = [(0.0, start_renderer_rss_mb)]
+                start_time = time.monotonic()
+
+                while time.monotonic() - start_time < _SAMPLE_WINDOW_S:
+                    current_sample = _sample_peak_renderer_rss_mb(
+                        browser_process.pid,
+                        profile_dir,
+                    )
+                    elapsed_s = round(time.monotonic() - start_time, 2)
+                    samples.append((elapsed_s, current_sample))
+                    peak_renderer_rss_mb = max(peak_renderer_rss_mb, current_sample)
+
+                    if peak_renderer_rss_mb - start_renderer_rss_mb > _MAX_RENDERER_GROWTH_MB:
+                        break
+
+                    await asyncio.sleep(_SAMPLE_INTERVAL_S)
+
+                renderer_growth_mb = round(peak_renderer_rss_mb - start_renderer_rss_mb, 2)
+                assert renderer_growth_mb <= _MAX_RENDERER_GROWTH_MB, (
+                    "DevUI renderer memory grew too much during a ~1.5 MB streaming response. "
+                    f"start={start_renderer_rss_mb:.2f}MB "
+                    f"peak={peak_renderer_rss_mb:.2f}MB "
+                    f"growth={renderer_growth_mb:.2f}MB "
+                    f"budget={_MAX_RENDERER_GROWTH_MB:.2f}MB "
+                    f"samples={samples}"
+                )
+        finally:
+            _shutdown_browser_process(browser_process, profile_dir=profile_dir)

python/packages/gemini/AGENTS.md

@@ -0,0 +1,35 @@
+# Gemini Package (agent-framework-gemini)
+
+Integration with Google's Gemini API via the `google-genai` SDK.
+
+## Core Classes
+
+- **`RawGeminiChatClient`** - Lightweight chat client without any layers, for custom pipeline composition
+- **`GeminiChatClient`** - Full-featured chat client with function invocation, middleware, and telemetry
+- **`GeminiChatOptions`** - Options TypedDict for Gemini-specific parameters
+- **`GeminiSettings`** - Settings loaded from environment variables
+- **`ThinkingConfig`** - Configuration for extended thinking
+
+## Gemini-specific Options
+
+- **`thinking_config`** - Enable extended thinking via `ThinkingConfig`
+- **`response_schema`** - Raw JSON schema dict for structured output (alternative to `response_format`)
+- **`top_k`** - Top-K sampling parameter
+
+## Built-in Tool Factory Methods
+
+- **`get_web_search_tool()`** - Google Search grounding for up-to-date web answers
+- **`get_code_interpreter_tool()`** - Sandboxed code execution
+- **`get_maps_grounding_tool()`** - Google Maps grounding for location and mapping
+- **`get_file_search_tool()`** - Retrieval from Gemini file search stores
+- **`get_mcp_tool()`** - Model Context Protocol server integration
+
+## Usage
+
+```python
+from agent_framework import Content, Message
+from agent_framework_gemini import GeminiChatClient
+
+client = GeminiChatClient(model="gemini-2.5-flash")
+response = await client.get_response([Message(role="user", contents=[Content.from_text("Hello")])])
+```

python/packages/gemini/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/gemini/README.md

@@ -0,0 +1,30 @@
+# Get Started with Microsoft Agent Framework Gemini
+
+Install the provider package:
+
+```bash
+pip install agent-framework-gemini --pre
+```
+
+## Gemini Integration
+
+The Gemini integration enables Microsoft Agent Framework applications to call Google Gemini models with familiar chat abstractions, including streaming, tool/function calling, and structured output.
+
+## Authentication
+
+Obtain an API key from [Google AI Studio](https://aistudio.google.com/apikey) and set it via environment variable:
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+export GEMINI_MODEL="gemini-2.5-flash"
+```
+
+## Examples
+
+See the [Google Gemini samples](samples/) for runnable end-to-end scripts covering:
+
+- Basic agent with tool calling and streaming
+- Extended thinking with `ThinkingConfig`
+- Google Search grounding
+- Google Maps grounding
+- Built-in code execution

python/packages/gemini/agent_framework_gemini/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+from ._chat_client import GeminiChatClient, GeminiChatOptions, GeminiSettings, RawGeminiChatClient, ThinkingConfig
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "GeminiChatClient",
+    "GeminiChatOptions",
+    "GeminiSettings",
+    "RawGeminiChatClient",
+    "ThinkingConfig",
+    "__version__",
+]

python/packages/gemini/agent_framework_gemini/_chat_client.py

@@ -0,0 +1,939 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from collections.abc import AsyncIterable, Awaitable, Mapping, Sequence
+from typing import Any, ClassVar, Generic, cast
+from uuid import uuid4
+
+from agent_framework import (
+    AGENT_FRAMEWORK_USER_AGENT,
+    BaseChatClient,
+    ChatAndFunctionMiddlewareTypes,
+    ChatMiddlewareLayer,
+    ChatOptions,
+    ChatResponse,
+    ChatResponseUpdate,
+    Content,
+    FinishReasonLiteral,
+    FunctionInvocationConfiguration,
+    FunctionInvocationLayer,
+    FunctionTool,
+    Message,
+    ResponseStream,
+    UsageDetails,
+    validate_tool_mode,
+)
+from agent_framework._settings import SecretString, load_settings
+from agent_framework.observability import ChatTelemetryLayer
+from google import genai
+from google.genai import types
+from pydantic import BaseModel
+
+if sys.version_info >= (3, 13):
+    from typing import TypeVar  # type: ignore # pragma: no cover
+else:
+    from typing_extensions import TypeVar  # type: ignore # pragma: no cover
+
+if sys.version_info >= (3, 12):
+    from typing import override  # type: ignore # pragma: no cover
+else:
+    from typing_extensions import override  # type: ignore # pragma: no cover
+
+if sys.version_info >= (3, 11):
+    from typing import TypedDict  # type: ignore # pragma: no cover
+else:
+    from typing_extensions import TypedDict  # type: ignore # pragma: no cover
+
+logger = logging.getLogger("agent_framework.gemini")
+
+__all__ = [
+    "GeminiChatClient",
+    "GeminiChatOptions",
+    "GeminiSettings",
+    "RawGeminiChatClient",
+    "ThinkingConfig",
+]
+
+ResponseModelT = TypeVar("ResponseModelT", bound=BaseModel | None, default=None)
+
+
+# region Options & Settings
+
+
+class ThinkingConfig(TypedDict, total=False):
+    """Extended thinking configuration for Gemini models.
+
+    Attributes:
+        include_thoughts: Whether to include thought summaries in the response. Thought summaries
+            are condensed representations of the model's internal reasoning and appear as response
+            parts where ``part.thought`` is ``True``. Note: the framework currently excludes
+            thought parts from ``ChatResponse.contents`` and does not surface them as output.
+        thinking_budget: Token budget for Gemini 2.5 models. Set to ``0`` to disable
+            thinking or ``-1`` to enable a dynamic budget.
+        thinking_level: Thinking level for Gemini 2.5 models and later. One of
+            ``ThinkingLevel.THINKING_LEVEL_UNSPECIFIED`` (default), ``ThinkingLevel.MINIMAL``,
+            ``ThinkingLevel.LOW``, ``ThinkingLevel.MEDIUM``, or ``ThinkingLevel.HIGH``.
+    """
+
+    include_thoughts: bool
+    thinking_budget: int
+    thinking_level: types.ThinkingLevel
+
+
+class GeminiChatOptions(ChatOptions[ResponseModelT], Generic[ResponseModelT], total=False):
+    """Google Gemini API-specific chat options.
+
+    Extends ``ChatOptions`` with Gemini-specific fields. Standard options are mapped to their
+    ``GenerateContentConfig`` equivalents; Gemini-specific fields are declared below.
+
+    Only text output is supported for now. Other modalities may be added later.
+
+    See: https://ai.google.dev/api/generate-content#generationconfig
+
+    Inherited fields from ``ChatOptions``:
+        model: Model to use for this call (e.g. ``"gemini-2.5-flash"``).
+        temperature: Controls randomness. Higher values produce more varied output.
+        max_tokens: Maximum number of tokens to generate (``maxOutputTokens``).
+        top_p: Nucleus sampling cutoff. Only tokens within the top-p probability mass are considered.
+        stop: One or more sequences that stop generation when encountered (``stopSequences``).
+        seed: Fixed seed for reproducible outputs.
+        frequency_penalty: Reduces repetition by penalising tokens that appear frequently.
+        presence_penalty: Reduces repetition by penalising tokens that have already appeared.
+        tools: Function tools the model may call. Accepts ``FunctionTool`` instances, plain callables,
+            or ``types.Tool`` objects returned by ``get_code_interpreter_tool``, ``get_web_search_tool``,
+            ``get_mcp_tool``, ``get_file_search_tool``, or ``get_maps_grounding_tool``.
+        tool_choice: How the model picks a tool. One of ``'auto'``, ``'none'``, or ``'required'``.
+        response_format: Pydantic model type for structured JSON output. The response text is
+            parsed into the model and exposed via ``ChatResponse.value``.
+        instructions: Extra system-level instructions prepended to the system message.
+
+    Not supported, and passing these raises a type error:
+        - ``logit_bias``
+        - ``allow_multiple_tool_calls``
+        - ``store``
+        - ``user``
+        - ``metadata``
+        - ``conversation_id``
+    """
+
+    # Gemini's GenerationConfig options
+    response_schema: dict[str, Any]
+    """Raw JSON schema dict for structured output (alternative to ``response_format``).
+    Sets ``response_mime_type`` to ``'application/json'`` and passes the schema directly."""
+
+    top_k: int
+    """Top-K sampling: limits token selection to the K most probable tokens."""
+
+    thinking_config: ThinkingConfig
+    """Extended thinking configuration. See ``ThinkingConfig`` for available fields."""
+
+    # Unsupported base options. Override with None to indicate not supported
+    logit_bias: None  # type: ignore[misc]
+    """Not supported in the Gemini API."""
+
+    allow_multiple_tool_calls: None  # type: ignore[misc]
+    """Not supported. Gemini handles parallel tool calls automatically."""
+
+    store: None  # type: ignore[misc]
+    """Not supported in the Gemini API."""
+
+    user: None  # type: ignore[misc]
+    """Not supported in the Gemini API."""
+
+    metadata: None  # type: ignore[misc]
+    """Not supported in the Gemini API."""
+
+    conversation_id: None  # type: ignore[misc]
+    """Not supported in the Gemini API."""
+
+
+GeminiChatOptionsT = TypeVar("GeminiChatOptionsT", bound=TypedDict, default="GeminiChatOptions", covariant=True)  # type: ignore[valid-type]
+
+
+class GeminiSettings(TypedDict, total=False):
+    """Gemini configuration settings loaded from environment or .env files."""
+
+    api_key: SecretString | None
+    model: str | None
+
+
+# endregion
+
+
+_GEMINI_SERVICE_URL = "https://generativelanguage.googleapis.com"
+
+# Keys mapping to a different GenerateContentConfig field name
+_OPTION_TRANSLATIONS: dict[str, str] = {
+    "max_tokens": "max_output_tokens",
+    "stop": "stop_sequences",
+}
+
+# Keys handled with dedicated logic, not via the generic passthrough
+_OPTION_EXPLICIT_KEYS: frozenset[str] = frozenset({
+    "tools",
+    "tool_choice",
+    "response_format",
+    "response_schema",
+    "thinking_config",
+})
+
+# Keys consumed upstream and not forwarded to GenerateContentConfig
+_OPTION_CONSUMED_KEYS: frozenset[str] = frozenset({
+    "model",
+    "instructions",
+})
+
+_OPTION_EXCLUDE_KEYS: frozenset[str] = _OPTION_EXPLICIT_KEYS | _OPTION_CONSUMED_KEYS
+
+_FINISH_REASON_MAP: dict[str, FinishReasonLiteral] = {
+    "STOP": "stop",
+    "MAX_TOKENS": "length",
+    "SAFETY": "content_filter",
+    "RECITATION": "content_filter",
+    "LANGUAGE": "content_filter",
+    "BLOCKLIST": "content_filter",
+    "PROHIBITED_CONTENT": "content_filter",
+    "SPII": "content_filter",
+    "IMAGE_SAFETY": "content_filter",
+    "IMAGE_PROHIBITED_CONTENT": "content_filter",
+    "IMAGE_RECITATION": "content_filter",
+    "MALFORMED_FUNCTION_CALL": "tool_calls",
+    "UNEXPECTED_TOOL_CALL": "tool_calls",
+}
+
+
+class RawGeminiChatClient(
+    BaseChatClient[GeminiChatOptionsT],
+    Generic[GeminiChatOptionsT],
+):
+    """A raw Gemini chat client for the Google Gemini API without function invocation, middleware or telemetry.
+
+    Use this when you want full control over the request pipeline. For instance, to opt out of
+    telemetry, use custom middleware, or compose your own layers. If you want the full-featured
+    client with batteries included, use `GeminiChatClient` instead.
+    """
+
+    OTEL_PROVIDER_NAME: ClassVar[str] = "gcp.gemini"  # type: ignore[reportIncompatibleVariableOverride, misc]
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        model: str | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        client: genai.Client | None = None,
+        additional_properties: dict[str, Any] | None = None,
+    ) -> None:
+        """Create a raw Gemini chat client.
+
+        Args:
+            api_key: Google AI Studio API key. Falls back to ``GEMINI_API_KEY`` environment variable.
+            model: Default model identifier. Falls back to ``GEMINI_MODEL`` environment variable.
+            env_file_path: Path to a ``.env`` file for credential loading.
+            env_file_encoding: Encoding for the ``.env`` file.
+            client: Pre-built ``genai.Client`` instance. When provided, ``api_key`` is not required.
+            additional_properties: Extra properties stored on the client instance.
+        """
+        settings = load_settings(
+            GeminiSettings,
+            env_prefix="GEMINI_",
+            api_key=api_key,
+            model=model,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
+
+        if client:
+            self._genai_client = client
+        else:
+            resolved_key = settings.get("api_key")
+            if not resolved_key:
+                raise ValueError(
+                    "Gemini API key is required. Set via api_key parameter or GEMINI_API_KEY environment variable."
+                )
+            self._genai_client = genai.Client(
+                api_key=resolved_key.get_secret_value(),
+                http_options={"headers": {"x-goog-api-client": AGENT_FRAMEWORK_USER_AGENT}},
+            )
+
+        self.model = settings.get("model")
+
+        super().__init__(additional_properties=additional_properties)
+
+    @staticmethod
+    def get_code_interpreter_tool() -> types.Tool:
+        """Create a code execution tool.
+
+        Pass the returned tool to the ``tools`` list of an agent or ``ChatOptions``.
+
+        Returns:
+            A ``types.Tool`` configured for sandboxed code execution.
+        """
+        return types.Tool(code_execution=types.ToolCodeExecution())
+
+    @staticmethod
+    def get_web_search_tool(
+        *,
+        search_types: types.SearchTypes | None = None,
+        blocking_confidence: types.PhishBlockThreshold | None = None,
+        exclude_domains: list[str] | None = None,
+        time_range_filter: types.Interval | None = None,
+    ) -> types.Tool:
+        """Create a Google Search grounding tool.
+
+        Pass the returned tool to the ``tools`` list of an agent or ``ChatOptions``.
+
+        Args:
+            search_types: Controls which search types are enabled (web search, image search).
+            blocking_confidence: Block sites at or above this phishing confidence level.
+                Not supported in Gemini API.
+            exclude_domains: List of domains to exclude from search results. Not supported in Gemini API.
+            time_range_filter: Restrict results to a specific time range. Not supported in Vertex AI.
+
+        Returns:
+            A ``types.Tool`` configured for Google Search grounding.
+        """
+        return types.Tool(
+            google_search=types.GoogleSearch(
+                search_types=search_types,
+                blocking_confidence=blocking_confidence,
+                exclude_domains=exclude_domains,
+                time_range_filter=time_range_filter,
+            )
+        )
+
+    @staticmethod
+    def get_mcp_tool(url: str, *, name: str | None = None, **kwargs: Any) -> types.Tool:
+        """Create an MCP (Model Context Protocol) server tool.
+
+        Pass the returned tool to the ``tools`` list of an agent or ``ChatOptions``.
+
+        Args:
+            url: The URL of the MCP server's streamable HTTP endpoint.
+            name: Optional display name for the MCP server.
+            **kwargs: Additional kwargs passed to ``StreamableHttpTransport``. Supported fields
+                include ``headers``, ``timeout``, ``sse_read_timeout``, and ``terminate_on_close``.
+
+        Returns:
+            A ``types.Tool`` configured for the given MCP server.
+        """
+        return types.Tool(
+            mcp_servers=[
+                types.McpServer(
+                    name=name,
+                    streamable_http_transport=types.StreamableHttpTransport(url=url, **kwargs),
+                )
+            ]
+        )
+
+    @staticmethod
+    def get_file_search_tool(
+        *,
+        file_search_store_names: list[str] | None = None,
+        top_k: int | None = None,
+        metadata_filter: str | None = None,
+    ) -> types.Tool:
+        """Create a file search tool backed by a Gemini file search store.
+
+        Pass the returned tool to the ``tools`` list of an agent or ``ChatOptions``.
+
+        Args:
+            file_search_store_names: Resource names of the file search stores to query.
+                Example: ``["fileSearchStores/my-file-search-store-123"]``.
+            top_k: Maximum number of retrieval chunks to return.
+            metadata_filter: CEL expression to filter retrieval results by metadata.
+                See https://google.aip.dev/160 for syntax.
+
+        Returns:
+            A ``types.Tool`` configured for file search retrieval.
+        """
+        return types.Tool(
+            file_search=types.FileSearch(
+                file_search_store_names=file_search_store_names,
+                top_k=top_k,
+                metadata_filter=metadata_filter,
+            )
+        )
+
+    @staticmethod
+    def get_maps_grounding_tool(
+        *,
+        enable_widget: bool | None = None,
+        auth_config: types.AuthConfig | None = None,
+    ) -> types.Tool:
+        """Create a Google Maps grounding tool.
+
+        Pass the returned tool to the ``tools`` list of an agent or ``ChatOptions``.
+
+        Args:
+            enable_widget: Return a widget context token in ``GroundingMetadata`` so callers
+                can render a Google Maps widget with geospatial context.
+            auth_config: Authentication config to access the Maps API. Only API key is
+                supported. Not supported in Gemini API.
+
+        Returns:
+            A ``types.Tool`` configured for Google Maps grounding.
+        """
+        return types.Tool(google_maps=types.GoogleMaps(enable_widget=enable_widget, auth_config=auth_config))
+
+    @override
+    def _inner_get_response(
+        self,
+        *,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+        if stream:
+
+            async def _stream() -> AsyncIterable[ChatResponseUpdate]:
+                validated = await self._validate_options(options)
+                model, contents, config = self._prepare_request(messages, validated)
+                async for chunk in await self._genai_client.aio.models.generate_content_stream(  # pyright: ignore[reportUnknownMemberType]
+                    model=model,
+                    contents=contents,  # type: ignore[arg-type]
+                    config=config,
+                ):
+                    yield self._process_chunk(chunk)
+
+            return self._build_response_stream(_stream(), response_format=options.get("response_format"))
+
+        async def _get_response() -> ChatResponse:
+            validated = await self._validate_options(options)
+            model, contents, config = self._prepare_request(messages, validated)
+            raw = await self._genai_client.aio.models.generate_content(model=model, contents=contents, config=config)  # type: ignore[arg-type]
+            return self._process_generate_response(raw, response_format=validated.get("response_format"))
+
+        return _get_response()
+
+    @override
+    def service_url(self) -> str:
+        """Return the base URL of the Gemini API service.
+
+        Returns:
+            The Gemini API base URL.
+        """
+        return _GEMINI_SERVICE_URL
+
+    # region Request preparation
+
+    def _prepare_request(
+        self,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+    ) -> tuple[str, list[types.Content], types.GenerateContentConfig]:
+        """Resolve the model ID, convert messages to Gemini contents, and build the generation config.
+
+        Call this after awaiting ``_validate_options`` so that tools and other options are
+        fully normalized before the request is assembled.
+
+        Args:
+            messages: The conversation history as framework Message objects.
+            options: Validated and normalized chat options.
+
+        Returns:
+            A tuple of the resolved model, the Gemini contents list, and the generation config.
+
+        Raises:
+            ValueError: If no model is set on the options or the client instance.
+        """
+        model = options.get("model") or self.model
+        if not model:
+            raise ValueError("Gemini model is required. Set via model parameter or GEMINI_MODEL environment variable.")
+
+        system_instruction, contents = self._prepare_gemini_messages(messages)
+        if call_instructions := options.get("instructions"):
+            system_instruction = (
+                f"{call_instructions}\n{system_instruction}" if system_instruction else call_instructions
+            )
+
+        return model, contents, self._prepare_config(options, system_instruction)
+
+    def _prepare_gemini_messages(self, messages: Sequence[Message]) -> tuple[str | None, list[types.Content]]:
+        """Convert framework messages to Gemini contents and extract system instruction.
+
+        Args:
+            messages: The full conversation history as framework Message objects.
+
+        Returns:
+            A tuple of (system_instruction_text, contents_list). System messages are extracted
+            into the instruction string; tool results are grouped into user-role content blocks.
+        """
+        system_parts: list[str] = []
+        contents: list[types.Content] = []
+        # Maps call_id to function name so function_result parts can include the required name field.
+        call_id_to_name: dict[str, str] = {}
+        # Accumulated functionResponse parts from consecutive tool messages.
+        pending_tool_parts: list[types.Part] = []
+
+        def flush_pending_tool_parts() -> None:
+            if pending_tool_parts:
+                contents.append(types.Content(role="user", parts=list(pending_tool_parts)))
+                pending_tool_parts.clear()
+
+        for message in messages:
+            if message.role == "system":
+                if message.text:
+                    system_parts.append(message.text)
+                continue
+
+            if message.role == "tool":
+                for content in message.contents:
+                    part = self._convert_function_result(content, call_id_to_name)
+                    if part is not None:
+                        pending_tool_parts.append(part)
+                continue
+
+            # Non-tool message — flush any accumulated tool parts first.
+            flush_pending_tool_parts()
+
+            parts = self._convert_message_contents(message.contents, call_id_to_name)
+            if not parts:
+                continue
+
+            role = "model" if message.role == "assistant" else "user"
+            contents.append(types.Content(role=role, parts=parts))
+
+        flush_pending_tool_parts()
+
+        system_instruction = "\n".join(system_parts) if system_parts else None
+        return system_instruction, contents
+
+    def _convert_message_contents(
+        self,
+        message_contents: Sequence[Content],
+        call_id_to_name: dict[str, str],
+    ) -> list[types.Part]:
+        """Convert framework Content objects to Gemini Part objects, tracking function call IDs.
+
+        Args:
+            message_contents: The content items of a single framework message.
+            call_id_to_name: Mutable mapping updated with any function call ID-to-name pairs found.
+
+        Returns:
+            A list of Gemini Part objects representing the message contents.
+        """
+        parts: list[types.Part] = []
+        for content in message_contents:
+            match content.type:
+                case "text":
+                    parts.append(types.Part(text=content.text or ""))
+                case "function_call":
+                    call_id = content.call_id or self._generate_tool_call_id()
+                    if content.name:
+                        call_id_to_name[call_id] = content.name
+                    parts.append(
+                        types.Part(
+                            function_call=types.FunctionCall(
+                                id=call_id,
+                                name=content.name or "",
+                                args=content.parse_arguments() or {},
+                            )
+                        )
+                    )
+                case _:
+                    logger.debug("Skipping unsupported content type for Gemini: %s", content.type)
+        return parts
+
+    def _convert_function_result(
+        self,
+        content: Content,
+        call_id_to_name: dict[str, str],
+    ) -> types.Part | None:
+        """Convert a function_result Content to a Gemini FunctionResponse Part.
+
+        Args:
+            content: The framework Content object, expected to be of type ``function_result``.
+            call_id_to_name: Mapping of call IDs to function names, used to resolve the required name field.
+
+        Returns:
+            A Gemini Part containing a FunctionResponse, or None if the content type is not
+            ``function_result`` or the call ID cannot be resolved.
+        """
+        if content.type != "function_result":
+            return None
+
+        name = call_id_to_name.get(content.call_id or "")
+        if not name:
+            logger.warning(
+                "Skipping function_result: no matching function_call found for call_id=%r",
+                content.call_id,
+            )
+            return None
+
+        response = self._coerce_to_dict(content.result)
+        return types.Part(
+            function_response=types.FunctionResponse(
+                id=content.call_id,
+                name=name,
+                response=response,
+            )
+        )
+
+    @staticmethod
+    def _coerce_to_dict(value: Any) -> dict[str, Any]:
+        """Ensure a tool result value is a dict as required by Gemini's FunctionResponse.
+
+        Args:
+            value: The raw tool result. May be a dict, JSON string, plain string, None, or any other value.
+
+        Returns:
+            A dict representation of the value. JSON strings are parsed; all other non-dict values
+            are wrapped as ``{"result": <str(value)>}``.
+        """
+        if isinstance(value, dict):
+            return cast(dict[str, Any], value)
+        if isinstance(value, str):
+            try:
+                parsed = json.loads(value)
+                if isinstance(parsed, dict):
+                    return cast(dict[str, Any], parsed)
+            except (json.JSONDecodeError, ValueError):
+                pass
+            return {"result": value}
+        if value is None:
+            return {"result": ""}
+        return {"result": str(value)}
+
+    def _prepare_config(
+        self,
+        options: Mapping[str, Any],
+        system_instruction: str | None,
+    ) -> types.GenerateContentConfig:
+        """Build a ``types.GenerateContentConfig`` from the resolved chat options.
+
+        Note: ``_OPTION_TRANSLATIONS`` keys are renamed, ``_OPTION_EXCLUDE_KEYS`` are skipped, and all
+        remaining keys are forwarded as-is, allowing new Gemini parameters to be adopted without
+        framework changes.
+
+        Args:
+            options: Resolved chat options mapping, typically a ``GeminiChatOptions`` dict.
+            system_instruction: Combined system instruction text, or None if absent.
+
+        Returns:
+            A fully populated ``GenerateContentConfig`` ready to pass to the Gemini API.
+        """
+        kwargs: dict[str, Any] = {}
+
+        if system_instruction:
+            kwargs["system_instruction"] = system_instruction
+
+        for key, value in options.items():
+            if key in _OPTION_EXCLUDE_KEYS or value is None:
+                continue
+            kwargs[_OPTION_TRANSLATIONS.get(key, key)] = value
+
+        if options.get("response_format") or options.get("response_schema"):
+            kwargs["response_mime_type"] = "application/json"
+        if schema := options.get("response_schema"):
+            kwargs["response_schema"] = schema
+        if tools := self._prepare_tools(options):
+            kwargs["tools"] = tools
+        if tool_config := self._prepare_tool_config(options.get("tool_choice")):
+            kwargs["tool_config"] = tool_config
+        if thinking_config := options.get("thinking_config"):
+            thinking_config_kwargs = {k: v for k, v in thinking_config.items() if v is not None}
+            if thinking_config_kwargs:
+                kwargs["thinking_config"] = types.ThinkingConfig(**thinking_config_kwargs)
+
+        return types.GenerateContentConfig(**kwargs)
+
+    def _prepare_tools(self, options: Mapping[str, Any]) -> list[types.Tool] | None:
+        """Translate the framework tool list into Gemini API tool objects.
+
+        The Gemini API does not accept framework ``FunctionTool`` objects directly.
+        This method acts as the translation boundary between the two type systems.
+        It handles two kinds of entries in ``options["tools"]``:
+
+        - ``FunctionTool``: a framework abstraction for a callable with a name,
+          description, and JSON schema. Translated to ``types.FunctionDeclaration``
+          (Gemini's equivalent) and grouped into a single ``types.Tool``, which is
+          how the Gemini API expects function declarations to be passed.
+        - ``types.Tool``: already in Gemini's native format (e.g. built-in tools
+          such as search or code execution). Passed through unchanged. Use the
+          ``get_*_tool`` factory methods on this class to produce these.
+
+        Args:
+            options: Resolved chat options whose ``tools`` entry may contain
+                ``FunctionTool`` instances, plain callables, or ``types.Tool`` objects.
+
+        Returns:
+            A non-empty list of ``types.Tool`` objects ready for the Gemini API,
+            or ``None`` if no tools are configured.
+        """
+        tools_option: list[Any] = options.get("tools") or []
+
+        result: list[types.Tool] = []
+
+        # Translate framework FunctionTool objects to Gemini API FunctionDeclaration objects
+        declarations = [
+            types.FunctionDeclaration(
+                name=tool.name,
+                description=tool.description or "",
+                parameters=tool.parameters(),  # type: ignore[arg-type]
+            )
+            for tool in tools_option
+            if isinstance(tool, FunctionTool)
+        ]
+        if declarations:
+            result.append(types.Tool(function_declarations=declarations))
+
+        # Objects of type types.Tool are already in Gemini's native format
+        result.extend(tool for tool in tools_option if isinstance(tool, types.Tool))
+
+        return result or None
+
+    def _prepare_tool_config(self, tool_choice: Any) -> types.ToolConfig | None:
+        """Build a Gemini ``ToolConfig`` from the framework ``tool_choice`` value.
+
+        Args:
+            tool_choice: Raw ``tool_choice`` value from options (string, dict, or None).
+
+        Returns:
+            A ``types.ToolConfig`` with the appropriate ``FunctionCallingConfig``, or None
+            if no ``tool_choice`` is set or the mode is unsupported.
+        """
+        tool_mode = validate_tool_mode(tool_choice)
+        if not tool_mode:
+            return None
+
+        match tool_mode.get("mode"):
+            case "auto":
+                function_calling_mode, allowed_names = types.FunctionCallingConfigMode.AUTO, None
+            case "none":
+                function_calling_mode, allowed_names = types.FunctionCallingConfigMode.NONE, None
+            case "required":
+                function_calling_mode = types.FunctionCallingConfigMode.ANY
+                name = tool_mode.get("required_function_name")
+                allowed_names = [name] if name else None
+            case unknown_mode:
+                logger.warning("Unsupported tool_choice mode for Gemini: %s", unknown_mode)
+                return None
+
+        function_calling_kwargs: dict[str, Any] = {"mode": function_calling_mode}
+        if allowed_names:
+            function_calling_kwargs["allowed_function_names"] = allowed_names
+
+        return types.ToolConfig(function_calling_config=types.FunctionCallingConfig(**function_calling_kwargs))
+
+    # endregion
+
+    # region Response parsing
+
+    def _process_generate_response(
+        self,
+        response: types.GenerateContentResponse,
+        *,
+        response_format: type[BaseModel] | None = None,
+    ) -> ChatResponse:
+        """Convert a Gemini generate_content response to a framework ChatResponse.
+
+        Args:
+            response: The raw ``GenerateContentResponse`` from the Gemini API.
+            response_format: Optional Pydantic model type for structured output parsing.
+                When provided, the response text is parsed into the given model and
+                made available via ``ChatResponse.value``.
+
+        Returns:
+            A ``ChatResponse`` with parsed messages, usage details, finish reason, and model ID.
+        """
+        candidate = response.candidates[0] if response.candidates else None
+        parts: list[types.Part] = (candidate.content.parts or []) if candidate and candidate.content else []
+        contents = self._parse_parts(parts)
+        return ChatResponse(
+            response_id=None,
+            messages=[Message(role="assistant", contents=contents, raw_representation=candidate)],
+            usage_details=self._parse_usage(response.usage_metadata),
+            model=response.model_version or self.model,
+            finish_reason=self._map_finish_reason(
+                candidate.finish_reason.name if candidate and candidate.finish_reason else None
+            ),
+            response_format=response_format,
+            raw_representation=response,
+        )
+
+    def _process_chunk(self, chunk: types.GenerateContentResponse) -> ChatResponseUpdate:
+        """Convert a single streaming chunk to a framework ChatResponseUpdate.
+
+        Usage details are attached only to the final chunk, identified by a non-None finish reason.
+
+        Args:
+            chunk: A streaming ``GenerateContentResponse`` chunk from the Gemini API.
+
+        Returns:
+            A ``ChatResponseUpdate`` with parsed contents, finish reason, and model ID.
+        """
+        candidate = chunk.candidates[0] if chunk.candidates else None
+        parts: list[types.Part] = (candidate.content.parts or []) if candidate and candidate.content else []
+        contents = self._parse_parts(parts)
+
+        finish_reason = self._map_finish_reason(
+            candidate.finish_reason.name if candidate and candidate.finish_reason else None
+        )
+
+        # Attach usage to the final chunk only (when finish_reason is set).
+        if finish_reason and (usage := self._parse_usage(chunk.usage_metadata)):
+            contents.append(Content.from_usage(usage_details=usage))
+
+        return ChatResponseUpdate(
+            contents=contents,
+            model=chunk.model_version,
+            finish_reason=finish_reason,
+            raw_representation=chunk,
+        )
+
+    def _parse_parts(self, parts: Sequence[types.Part]) -> list[Content]:
+        """Convert Gemini response parts to framework Content objects, skipping thought/reasoning parts.
+
+        Args:
+            parts: Sequence of ``types.Part`` objects from a Gemini response candidate.
+
+        Returns:
+            A list of framework ``Content`` objects (text, function_call, or function_result).
+        """
+        contents: list[Content] = []
+        for part in parts:
+            if part.thought:
+                continue
+            if part.text is not None:
+                contents.append(Content.from_text(text=part.text, raw_representation=part))
+            elif part.function_call is not None:
+                function_call = part.function_call
+                if function_call.id:
+                    call_id = function_call.id
+                else:
+                    call_id = self._generate_tool_call_id()
+                    logger.debug("function_call missing id; generated fallback call_id=%r", call_id)
+                contents.append(
+                    Content.from_function_call(
+                        call_id=call_id,
+                        name=function_call.name or "",
+                        arguments=function_call.args or {},
+                        raw_representation=part,
+                    )
+                )
+            elif part.function_response is not None:
+                function_response = part.function_response
+                contents.append(
+                    Content.from_function_result(
+                        call_id=function_response.id or self._generate_tool_call_id(),
+                        result=function_response.response,
+                        raw_representation=part,
+                    )
+                )
+            elif part.executable_code is not None:
+                if part.executable_code.code:
+                    contents.append(Content.from_text(text=part.executable_code.code, raw_representation=part))
+            elif part.code_execution_result is not None:
+                if part.code_execution_result.output:
+                    contents.append(Content.from_text(text=part.code_execution_result.output, raw_representation=part))
+            else:
+                logger.debug("Skipping unsupported response part from Gemini")
+        return contents
+
+    def _parse_usage(self, usage: types.GenerateContentResponseUsageMetadata | None) -> UsageDetails | None:
+        """Extract token usage counts from Gemini usage metadata.
+
+        Args:
+            usage: The ``GenerateContentResponseUsageMetadata`` from the API response, or None.
+
+        Returns:
+            A ``UsageDetails`` dict with available token counts, or None if no usage data is present.
+        """
+        if not usage:
+            return None
+        details: UsageDetails = {}
+        if (v := usage.prompt_token_count) is not None:
+            details["input_token_count"] = v
+        if (v := usage.candidates_token_count) is not None:
+            details["output_token_count"] = v
+        if (v := usage.total_token_count) is not None:
+            details["total_token_count"] = v
+        return details or None
+
+    def _map_finish_reason(self, reason: str | None) -> FinishReasonLiteral | None:
+        """Map a Gemini finish reason string to the framework's FinishReasonLiteral.
+
+        Args:
+            reason: The finish reason name from the Gemini API (e.g. ``"STOP"``), or None.
+
+        Returns:
+            The corresponding ``FinishReasonLiteral``, or None if the reason is absent or unmapped.
+        """
+        if not reason:
+            return None
+        return _FINISH_REASON_MAP.get(reason)
+
+    # endregion
+
+    @staticmethod
+    def _generate_tool_call_id() -> str:
+        """Generate a unique fallback ID for tool calls that lack one.
+
+        Returns:
+            A unique string in the format ``tool-call-<uuid_hex>``.
+        """
+        return f"tool-call-{uuid4().hex}"
+
+
+class GeminiChatClient(
+    FunctionInvocationLayer[GeminiChatOptionsT],
+    ChatMiddlewareLayer[GeminiChatOptionsT],
+    ChatTelemetryLayer[GeminiChatOptionsT],
+    RawGeminiChatClient[GeminiChatOptionsT],
+    Generic[GeminiChatOptionsT],
+):
+    """Gemini chat client for the Google Gemini API with function invocation, middleware, and telemetry.
+
+    This is the recommended client for most use cases. It builds on ``RawGeminiChatClient``
+    and adds:
+
+    - **Function invocation**: automatically calls ``FunctionTool`` implementations and feeds
+      results back to the model until it produces a final text response.
+    - **Middleware**: a composable chain for cross-cutting concerns (logging, retries, etc.).
+    - **Telemetry**: OpenTelemetry traces and metrics emitted for every request.
+
+    Use ``RawGeminiChatClient`` instead when you need full control over the request pipeline
+    and want to opt out of one or more of these layers.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        model: str | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        client: genai.Client | None = None,
+        additional_properties: dict[str, Any] | None = None,
+        middleware: Sequence[ChatAndFunctionMiddlewareTypes] | None = None,
+        function_invocation_configuration: FunctionInvocationConfiguration | None = None,
+    ) -> None:
+        """Create a Gemini chat client.
+
+        Args:
+            api_key: The Google AI Studio API key. Falls back to ``GEMINI_API_KEY`` environment variable.
+            model: Default model identifier. Falls back to ``GEMINI_MODEL`` environment variable.
+            env_file_path: Path to a ``.env`` file for credential loading.
+            env_file_encoding: Encoding for the ``.env`` file.
+            client: Pre-built ``genai.Client`` instance. When provided, ``api_key`` is not required.
+            additional_properties: Extra properties stored on the client instance.
+            middleware: Optional middleware chain applied to every call.
+            function_invocation_configuration: Optional configuration for the function invocation loop.
+        """
+        super().__init__(
+            api_key=api_key,
+            model=model,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+            client=client,
+            additional_properties=additional_properties,
+            middleware=middleware,
+            function_invocation_configuration=function_invocation_configuration,
+        )

python/packages/gemini/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+name = "agent-framework-gemini"
+description = "Google Gemini integration for Microsoft Agent Framework."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0a260410"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Framework :: Pydantic :: 2",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core>=1.0.0,<2.0",
+    "google-genai>=1.0.0,<2.0.0",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+markers = [
+    "integration: marks tests as integration tests that require external services",
+    "flaky: marks tests as flaky and eligible for automatic retry",
+]
+timeout = 120
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint.extend-per-file-ignores]
+"samples/**" = ["S", "T201"]
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["agent_framework_gemini"]
+exclude = ['tests']
+
+[tool.mypy]
+plugins = ['pydantic.mypy']
+strict = true
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+show_error_codes = true
+warn_unused_ignores = false
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+[tool.bandit]
+targets = ["agent_framework_gemini"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks.mypy]
+help = "Run MyPy for this package."
+cmd = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_gemini"
+
+[tool.poe.tasks.test]
+help = "Run the default unit test suite for this package."
+cmd = 'pytest -m "not integration" --cov=agent_framework_gemini --cov-report=term-missing:skip-covered tests'
+
+[tool.flit.module]
+name = "agent_framework_gemini"
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"

python/packages/gemini/samples/README.md

@@ -0,0 +1,18 @@
+# Google Gemini Examples
+
+This folder contains examples demonstrating how to use Google Gemini models with the Agent Framework.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`gemini_basic.py`](gemini_basic.py) | Basic agent with a weather tool, demonstrating both streaming and non-streaming responses. |
+| [`gemini_advanced.py`](gemini_advanced.py) | Extended thinking via `ThinkingConfig` for reasoning-heavy questions (Gemini 2.5+). |
+| [`gemini_with_google_search.py`](gemini_with_google_search.py) | Google Search grounding for up-to-date answers. |
+| [`gemini_with_google_maps.py`](gemini_with_google_maps.py) | Google Maps grounding for location and mapping information. |
+| [`gemini_with_code_execution.py`](gemini_with_code_execution.py) | Built-in code execution tool for computing precise answers in a sandboxed environment. |
+
+## Environment Variables
+
+- `GEMINI_API_KEY`: Your Google AI Studio API key (get one from [Google AI Studio](https://aistudio.google.com/apikey))
+- `GEMINI_MODEL`: The Gemini model to use (e.g., `gemini-2.5-flash`, `gemini-2.5-pro`)

python/packages/gemini/samples/gemini_advanced.py

@@ -0,0 +1,47 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable extended thinking with ThinkingConfig.
+
+Allows the model to reason through complex problems before responding.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient, GeminiChatOptions, ThinkingConfig
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Example of extended thinking with a Python version comparison question."""
+    print("=== Extended thinking ===")
+
+    options: GeminiChatOptions = {
+        "thinking_config": ThinkingConfig(thinking_budget=2048),
+    }
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="PythonAgent",
+        instructions="You are a helpful Python expert.",
+        default_options=options,
+    )
+
+    query = "What new language features were introduced in Python between 3.10 and 3.14?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_basic.py

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to use GeminiChatClient with an agent and a custom tool.
+
+Covers both non-streaming and streaming responses.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import Agent, tool
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, "The location to get the weather for."],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def non_streaming_example() -> None:
+    """Runs the agent and waits for the complete response before printing it."""
+    print("=== Non-streaming ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="WeatherAgent",
+        instructions="You are a helpful weather agent.",
+        tools=[get_weather],
+    )
+
+    query = "What's the weather like in Karlsruhe, Germany?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Result: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Runs the agent and prints each chunk as it is received."""
+    print("=== Streaming ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="WeatherAgent",
+        instructions="You are a helpful weather agent.",
+        tools=[get_weather],
+    )
+
+    query = "What's the weather like in Portland and in Paris?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    """Run non-streaming and streaming examples."""
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_with_code_execution.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable Gemini's built-in code execution tool.
+
+Allows the model to write and run code in a sandboxed environment to answer questions.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Run the code execution example."""
+    print("=== Code execution ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="CodeAgent",
+        instructions="You are a helpful assistant. Use code execution to compute precise answers.",
+        tools=[GeminiChatClient.get_code_interpreter_tool()],
+    )
+
+    query = "What are the first 20 prime numbers? Compute them in code."
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_with_google_maps.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable Google Maps grounding.
+
+Allows Gemini to retrieve location and mapping information before responding.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Run the Google Maps grounding example."""
+    print("=== Google Maps grounding ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="MapsAgent",
+        instructions="You are a helpful travel assistant. Use Google Maps to provide accurate location information.",
+        tools=[GeminiChatClient.get_maps_grounding_tool()],
+    )
+
+    query = "What are some highly rated restaurants in the city center of Karlsruhe, Germany?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/gemini/samples/gemini_with_google_search.py

@@ -0,0 +1,43 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shows how to enable Google Search grounding.
+
+Allows Gemini to retrieve up-to-date information from the web before responding.
+
+Requires the following environment variables to be set:
+- GEMINI_API_KEY
+- GEMINI_MODEL
+"""
+
+import asyncio
+
+from agent_framework import Agent
+from dotenv import load_dotenv
+
+from agent_framework_gemini import GeminiChatClient
+
+load_dotenv()
+
+
+async def main() -> None:
+    """Run the Google Search grounding example."""
+    print("=== Google Search grounding ===")
+
+    agent = Agent(
+        client=GeminiChatClient(),
+        name="SearchAgent",
+        instructions="You are a helpful assistant. Use Google Search to provide accurate, up-to-date answers.",
+        tools=[GeminiChatClient.get_web_search_tool()],
+    )
+
+    query = "What is the latest stable release of the .NET SDK?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run(query, stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/orchestrations/agent_framework_orchestrations/_handoff.py

@@ -287,7 +287,7 @@ class HandoffAgentExecutor(AgentExecutor):
             name=agent.name,
             description=agent.description,
             context_providers=agent.context_providers,
-            middleware=agent.agent_middleware,
+            middleware=agent.middleware,
             require_per_service_call_history_persistence=agent.require_per_service_call_history_persistence,
             default_options=cloned_options,  # type: ignore[assignment]
         )

python/packages/orchestrations/tests/test_handoff.py

@@ -18,11 +18,16 @@ from agent_framework import (
     ResponseStream,
     WorkflowEvent,
     WorkflowRunState,
+    function_middleware,
     resolve_agent_id,
     tool,
 )
 from agent_framework._clients import BaseChatClient
-from agent_framework._middleware import ChatMiddlewareLayer, FunctionInvocationContext, MiddlewareTermination
+from agent_framework._middleware import (
+    ChatMiddlewareLayer,
+    FunctionInvocationContext,
+    MiddlewareTermination,
+)
 from agent_framework._tools import FunctionInvocationLayer, FunctionTool
 from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder, HandoffSentEvent
 from pytest import param
@@ -745,6 +750,42 @@ async def test_handoff_clone_preserves_per_service_call_history_persistence() ->
     assert all(message.role != "tool" for message in stored_messages)
 
 
+async def test_handoff_clone_preserves_all_middleware_types() -> None:
+    """Handoff clones should preserve function and agent middleware from the original agent."""
+
+    @function_middleware
+    async def tracking_middleware(context: FunctionInvocationContext, call_next):
+        await call_next()
+
+    agent_a = Agent(
+        id="agent_a",
+        name="agent_a",
+        client=MockChatClient(name="agent_a", handoff_to="agent_b"),
+        middleware=[tracking_middleware],
+        require_per_service_call_history_persistence=True,
+    )
+    agent_b = Agent(
+        id="agent_b",
+        name="agent_b",
+        client=MockChatClient(name="agent_b"),
+        default_options={"tool_choice": "none"},
+        require_per_service_call_history_persistence=True,
+    )
+
+    workflow = (
+        HandoffBuilder(participants=[agent_a, agent_b], termination_condition=lambda _: False)
+        .with_start_agent(agent_a)
+        .add_handoff(agent_a, [agent_b])
+        .add_handoff(agent_b, [agent_a])
+        .build()
+    )
+
+    executor = workflow.executors[resolve_agent_id(agent_a)]
+    assert isinstance(executor, HandoffAgentExecutor)
+    cloned_middleware = executor._agent.middleware or []
+    assert tracking_middleware in cloned_middleware, "User function middleware should be preserved on cloned agent"
+
+
 def test_clean_conversation_for_handoff_keeps_text_only_history() -> None:
     """Tool-control messages must be excluded from persisted handoff history."""
     function_call = Content.from_function_call(

python/pyproject.toml

@@ -73,6 +73,7 @@ agent-framework-anthropic = { workspace = true }
 agent-framework-azurefunctions = { workspace = true }
 agent-framework-bedrock = { workspace = true }
 agent-framework-chatkit = { workspace = true }
+agent-framework-claude = { workspace = true }
 agent-framework-copilotstudio = { workspace = true }
 agent-framework-declarative = { workspace = true }
 agent-framework-devui = { workspace = true }
@@ -80,15 +81,15 @@ agent-framework-durabletask = { workspace = true }
 agent-framework-foundry = { workspace = true }
 agent-framework-foundry-hosting = { workspace = true }
 agent-framework-foundry-local = { workspace = true }
+agent-framework-gemini = { workspace = true }
+agent-framework-github-copilot = { workspace = true }
 agent-framework-lab = { workspace = true }
 agent-framework-mem0 = { workspace = true }
 agent-framework-ollama = { workspace = true }
 agent-framework-openai = { workspace = true }
+agent-framework-orchestrations = { workspace = true }
 agent-framework-purview = { workspace = true }
 agent-framework-redis = { workspace = true }
-agent-framework-github-copilot = { workspace = true }
-agent-framework-claude = { workspace = true }
-agent-framework-orchestrations = { workspace = true }
 litellm = { url = "https://files.pythonhosted.org/packages/57/77/0c6eca2cb049793ddf8ce9cdcd5123a35666c4962514788c4fc90edf1d3b/litellm-1.82.1-py3-none-any.whl" }
 
 [tool.ruff]

python/uv.lock

@@ -44,6 +44,7 @@ members = [
     "agent-framework-foundry",
     "agent-framework-foundry-hosting",
     "agent-framework-foundry-local",
+    "agent-framework-gemini",
     "agent-framework-github-copilot",
     "agent-framework-lab",
     "agent-framework-mem0",
@@ -536,6 +537,21 @@ requires-dist = [
     { name = "foundry-local-sdk", specifier = ">=0.5.1,<0.5.2" },
 ]
 
+[[package]]
+name = "agent-framework-gemini"
+version = "1.0.0a260410"
+source = { editable = "packages/gemini" }
+dependencies = [
+    { name = "agent-framework-core", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "google-genai", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "agent-framework-core", editable = "packages/core" },
+    { name = "google-genai", specifier = ">=1.0.0,<2.0.0" },
+]
+
 [[package]]
 name = "agent-framework-github-copilot"
 version = "1.0.0b260409"
@@ -2417,6 +2433,32 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e9/eb/c6c2478d8a8d633460be40e2a8a6f8f429171997a35a96f81d3b680dec83/google_auth-2.49.1-py3-none-any.whl", hash = "sha256:195ebe3dca18eddd1b3db5edc5189b76c13e96f29e73043b923ebcf3f1a860f7", size = 240737, upload-time = "2026-03-12T19:30:53.159Z" },
 ]
 
+[package.optional-dependencies]
+requests = [
+    { name = "requests", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+]
+
+[[package]]
+name = "google-genai"
+version = "1.68.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "distro", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "google-auth", extra = ["requests"], marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "httpx", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "pydantic", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "requests", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "sniffio", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "tenacity", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "typing-extensions", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "websockets", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9c/2c/f059982dbcb658cc535c81bbcbe7e2c040d675f4b563b03cdb01018a4bc3/google_genai-1.68.0.tar.gz", hash = "sha256:ac30c0b8bc630f9372993a97e4a11dae0e36f2e10d7c55eacdca95a9fa14ca96", size = 511285, upload-time = "2026-03-18T01:03:18.243Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/84/de/7d3ee9c94b74c3578ea4f88d45e8de9405902f857932334d81e89bce3dfa/google_genai-1.68.0-py3-none-any.whl", hash = "sha256:a1bc9919c0e2ea2907d1e319b65471d3d6d58c54822039a249fe1323e4178d15", size = 750912, upload-time = "2026-03-18T01:03:15.983Z" },
+]
+
 [[package]]
 name = "googleapis-common-protos"
 version = "1.73.1"