feat(adk): migrate to REASONING events and add encrypted value support (#1411)

* feat(adk): migrate from deprecated THINKING events to REASONING events and add encrypted value support

Migrates the ADK middleware from deprecated THINKING_* events to the newer
REASONING_* event types, and adds support for thought signatures via
REASONING_ENCRYPTED_VALUE events. This brings the ADK integration in line
with the Claude Agent SDK and LangGraph integrations.

Changes:
- Replace ThinkingStart/End and ThinkingTextMessage* events with
  ReasoningStart/End and ReasoningMessage* events
- Extract thought_signature from Google GenAI SDK Part objects and emit
  as REASONING_ENCRYPTED_VALUE events (base64-encoded)
- Update all internal state tracking variables (_is_thinking -> _is_reasoning, etc.)
- Update comprehensive tests and integration tests to expect REASONING events
- Add new tests for thought signature / encrypted value handling

Closes #1406

https://claude.ai/code/session_01Tn74iGdv36gg9zys3yQaAz

* test(adk): add e2e tests for reasoning message_id consistency, role, encrypted values, and stream ordering

Adds 5 new integration tests (requiring GOOGLE_API_KEY) that validate:
- All reasoning events in a block share the same message_id
- REASONING_MESSAGE_START carries role="reasoning"
- REASONING_ENCRYPTED_VALUE events contain valid base64 thought signatures
  with correct entity_id and subtype
- Reasoning stream is fully closed before text message events begin

https://claude.ai/code/session_01Tn74iGdv36gg9zys3yQaAz

* fix(adk): fix e2e tests for multi-block reasoning and require reasoning events

- Reasoning events are now required (not optional) since gemini-2.5-flash
  with include_thoughts=True always produces them
- Fix message_id consistency test to validate per-block rather than
  globally, since streaming can produce multiple reasoning blocks when
  thought/text parts interleave across partial events
- Replace stream-ordering test with well-formedness check that validates
  each block is properly opened/closed (START/END balanced, no overlap)
- Add helper _get_reasoning_blocks() to extract START-to-END blocks

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(adk): add reasoning chat example and update changelog for #1406

- Add agentic_chat_reasoning example agent using Gemini 2.5 Flash with
  include_thoughts=True, registered at /adk-reasoning-chat
- Update CHANGELOG.md unreleased section to document all changes:
  migration from THINKING to REASONING events, encrypted value support,
  and the new example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: contextablemark

integrations/adk-middleware/python/CHANGELOG.md

@@ -7,8 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING**: Migrate from deprecated `THINKING_*` events to `REASONING_*` events (#1406)
+  - `THINKING_START` / `THINKING_END` → `REASONING_START` / `REASONING_END`
+  - `THINKING_TEXT_MESSAGE_START` / `CONTENT` / `END` → `REASONING_MESSAGE_START` / `CONTENT` / `END`
+  - All reasoning events now carry a `message_id` for client-side correlation and `role="reasoning"` on message start
+  - Internal state variables renamed accordingly (`_is_thinking` → `_is_reasoning`, etc.)
+  - Aligns the ADK middleware with the Claude Agent SDK and LangGraph integrations, which already use `REASONING_*` events
+
 ### Added
 
+- **NEW**: `REASONING_ENCRYPTED_VALUE` support for Gemini thought signatures (#1406)
+  - Extracts `thought_signature` (opaque bytes) from Google GenAI SDK `Part` objects when present
+  - Emits `REASONING_ENCRYPTED_VALUE` events with `subtype="message"` and base64-encoded signature
+  - Enables encrypted reasoning / zero-data-retention workflows with Gemini models
+
+- **NEW**: Reasoning chat example (`examples/server/api/agentic_chat_reasoning.py`)
+  - Demonstrates `REASONING_*` event emission using Gemini 2.5 Flash with `include_thoughts=True`
+  - Registered at `/adk-reasoning-chat` in the example server
+
 - **NEW**: Support for multimodal input types (`ImageInputContent`, `AudioInputContent`, `VideoInputContent`, `DocumentInputContent`) (#1405)
   - Replaces reliance on the deprecated `BinaryInputContent` with the newer modality-specific types defined in the AG-UI protocol
   - `InputContentDataSource` (inline base64) converts to `types.Part(inline_data=types.Blob(...))`, same as before

integrations/adk-middleware/python/examples/server/__init__.py

@@ -19,6 +19,7 @@
 
 from .api import (
     agentic_chat_app,
+    agentic_chat_reasoning_app,
     agentic_generative_ui_app,
     tool_based_generative_ui_app,
     human_in_the_loop_app,
@@ -37,6 +38,7 @@
 app.include_router(shared_state_app.router, prefix='/adk-shared-state-agent', tags=['Shared State'])
 app.include_router(backend_tool_rendering_app.router, prefix='/backend_tool_rendering', tags=['Backend Tool Rendering'])
 app.include_router(predictive_state_updates_app.router, prefix='/adk-predictive-state-agent', tags=['Predictive State Updates'])
+app.include_router(agentic_chat_reasoning_app.router, prefix='/adk-reasoning-chat', tags=['Agentic Chat Reasoning'])
 
 
 @app.get("/")
@@ -51,6 +53,7 @@ async def root():
             "shared_state": "/adk-shared-state-agent",
             "backend_tool_rendering": "/backend_tool_rendering",
             "predictive_state_updates": "/adk-predictive-state-agent",
+            "agentic_chat_reasoning": "/adk-reasoning-chat",
             "docs": "/docs"
         }
     }
@@ -91,6 +94,7 @@ def main():
     print(f"  • Human in the Loop: http://localhost:{port}/adk-human-in-loop-agent")
     print(f"  • Shared State: http://localhost:{port}/adk-shared-state-agent")
     print(f"  • Predictive State Updates: http://localhost:{port}/adk-predictive-state-agent")
+    print(f"  • Agentic Chat Reasoning: http://localhost:{port}/adk-reasoning-chat")
     print(f"  • API docs: http://localhost:{port}/docs")
     uvicorn.run(app, host="0.0.0.0", port=port)
 

integrations/adk-middleware/python/examples/server/api/__init__.py

@@ -7,9 +7,11 @@
 from .shared_state import app as shared_state_app
 from .predictive_state_updates import app as predictive_state_updates_app
 from .backend_tool_rendering import app as backend_tool_rendering_app
+from .agentic_chat_reasoning import app as agentic_chat_reasoning_app
 
 __all__ = [
     "agentic_chat_app",
+    "agentic_chat_reasoning_app",
     "agentic_generative_ui_app",
     "tool_based_generative_ui_app",
     "human_in_the_loop_app",

integrations/adk-middleware/python/examples/server/api/agentic_chat_reasoning.py

@@ -0,0 +1,45 @@
+"""Agentic Chat with Reasoning (Thinking) feature.
+
+Demonstrates REASONING_* events emitted when Gemini's include_thoughts
+is enabled, including encrypted thought signatures.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from ag_ui_adk import ADKAgent, AGUIToolset, add_adk_fastapi_endpoint
+from google.adk.agents import LlmAgent
+from google.adk.planners import BuiltInPlanner
+from google.genai import types
+
+# Create a reasoning-enabled ADK agent using Gemini 2.5 Flash
+reasoning_agent = LlmAgent(
+    name="reasoning_assistant",
+    model="gemini-2.5-flash",
+    instruction="""You are a helpful assistant that thinks carefully before responding.
+    Work through problems step by step in your reasoning.
+    """,
+    planner=BuiltInPlanner(
+        thinking_config=types.ThinkingConfig(
+            include_thoughts=True
+        )
+    ),
+    tools=[
+        AGUIToolset(),
+    ],
+)
+
+# Create ADK middleware agent instance
+chat_agent = ADKAgent(
+    adk_agent=reasoning_agent,
+    app_name="demo_app",
+    user_id="demo_user",
+    session_timeout_seconds=3600,
+    use_in_memory_services=True,
+)
+
+# Create FastAPI app
+app = FastAPI(title="ADK Middleware Reasoning Chat")
+
+# Add the ADK endpoint
+add_adk_fastapi_endpoint(app, chat_agent, path="/")

integrations/adk-middleware/python/src/ag_ui_adk/event_translator.py

@@ -16,8 +16,9 @@
     ToolCallResultEvent, StateSnapshotEvent, StateDeltaEvent,
     CustomEvent, Message, UserMessage, AssistantMessage, ToolMessage, ReasoningMessage,
     ToolCall, FunctionCall,
-    ThinkingStartEvent, ThinkingEndEvent,
-    ThinkingTextMessageStartEvent, ThinkingTextMessageContentEvent, ThinkingTextMessageEndEvent,
+    ReasoningStartEvent, ReasoningEndEvent,
+    ReasoningMessageStartEvent, ReasoningMessageContentEvent, ReasoningMessageEndEvent,
+    ReasoningEncryptedValueEvent,
 )
 import json
 from google.adk.events import Event as ADKEvent
@@ -51,7 +52,7 @@ def _check_thought_support() -> bool:
                 _HAS_THOUGHT_SUPPORT = hasattr(types.Part, 'thought')
 
             if _HAS_THOUGHT_SUPPORT:
-                logger.info("Thought support detected in google-genai SDK; thoughts will be emitted as THINKING events")
+                logger.info("Thought support detected in google-genai SDK; thoughts will be emitted as REASONING events")
             else:
                 logger.info("Thought support not available in google-genai SDK; thoughts will be treated as regular text")
         except Exception as e:
@@ -216,10 +217,11 @@ def __init__(
         # in parallel (e.g. 5 concurrent create_item calls).
         self.lro_emitted_ids_by_name: Dict[str, List[str]] = {}
 
-        # Track thinking message streaming state (for thought parts)
-        self._is_thinking: bool = False  # Whether we're currently in a thinking block
-        self._is_streaming_thinking: bool = False  # Whether we're streaming thinking content
-        self._current_thinking_text: str = ""  # Accumulates thinking text for the active stream
+        # Track reasoning message streaming state (for thought parts)
+        self._is_reasoning: bool = False  # Whether we're currently in a reasoning block
+        self._is_streaming_reasoning: bool = False  # Whether we're streaming reasoning content
+        self._current_reasoning_text: str = ""  # Accumulates reasoning text for the active stream
+        self._current_reasoning_message_id: Optional[str] = None  # Current reasoning message ID
 
         # Predictive state configuration
         self._predict_state_mappings = normalize_predict_state(predict_state)
@@ -482,6 +484,7 @@ async def _translate_text_content(
         # Extract text from all parts, separating thought parts from regular text
         text_parts = []
         thought_parts = []
+        thought_signatures: List[Optional[bytes]] = []
         has_thought_support = _check_thought_support()
 
         # The check for adk_event.content.parts happens in the main translate method
@@ -499,18 +502,21 @@ async def _translate_text_content(
 
             if is_thought:
                 thought_parts.append(part.text)
+                # Capture thought_signature if available (opaque bytes for encrypted reasoning)
+                sig = getattr(part, 'thought_signature', None)
+                thought_signatures.append(sig)
             else:
                 text_parts.append(part.text)
 
-        # Handle thought parts first (emit THINKING events)
+        # Handle thought parts first (emit REASONING events)
         if thought_parts:
-            async for event in self._translate_thinking_content(thought_parts):
+            async for event in self._translate_reasoning_content(thought_parts, thought_signatures):
                 yield event
 
         # If no text AND it's not a final response, we can safely skip.
         # Otherwise, we must continue to process the final_response signal.
         if not text_parts and not is_final_response:
-            # If we only had thought parts and this is not final, close any active thinking
+            # If we only had thought parts and this is not final, close any active reasoning
             # but don't return yet if we need to handle final response
             return
 
@@ -523,7 +529,7 @@ async def _translate_text_content(
             # This is the final, complete message event.
 
             # Close any active thinking stream first
-            async for event in self._close_thinking_stream():
+            async for event in self._close_reasoning_stream():
                 yield event
 
             # Case 1: A text stream is actively running. We must close it.
@@ -606,7 +612,7 @@ async def _translate_text_content(
         if not self._is_streaming:
             # Close any active thinking stream before starting regular text
             # (transition from thinking to response)
-            async for event in self._close_thinking_stream():
+            async for event in self._close_reasoning_stream():
                 yield event
 
             # Start of new message - emit START event
@@ -660,20 +666,25 @@ async def _translate_text_content(
             self._is_streaming = False
             logger.info("🏁 Streaming completed, state reset")
 
-    async def _translate_thinking_content(
+    async def _translate_reasoning_content(
         self,
-        thought_parts: List[str]
+        thought_parts: List[str],
+        thought_signatures: Optional[List[Optional[bytes]]] = None,
     ) -> AsyncGenerator[BaseEvent, None]:
-        """Translate thought parts to AG-UI THINKING events.
+        """Translate thought parts to AG-UI REASONING events.
 
-        This method emits THINKING_START, THINKING_TEXT_MESSAGE_START/CONTENT/END,
-        and tracks thinking state for proper stream management.
+        This method emits REASONING_START, REASONING_MESSAGE_START/CONTENT/END,
+        and tracks reasoning state for proper stream management. When thought_signatures
+        are present, emits REASONING_ENCRYPTED_VALUE events for each signature.
 
         Args:
             thought_parts: List of thought text strings to emit
+            thought_signatures: Optional list of opaque signatures (bytes) for each
+                thought part, used for encrypted reasoning (e.g., Gemini thought signatures).
 
         Yields:
-            Thinking events (THINKING_START, THINKING_TEXT_MESSAGE_START/CONTENT/END)
+            Reasoning events (REASONING_START, REASONING_MESSAGE_START/CONTENT/END,
+            REASONING_ENCRYPTED_VALUE)
         """
         if not thought_parts:
             return
@@ -682,55 +693,78 @@ async def _translate_thinking_content(
         if not combined_thought:
             return
 
-        # Start thinking block if not already in one
-        if not self._is_thinking:
-            self._is_thinking = True
-            yield ThinkingStartEvent(
-                type=EventType.THINKING_START,
-                title="Model Thinking"
+        # Start reasoning block if not already in one
+        if not self._is_reasoning:
+            self._is_reasoning = True
+            self._current_reasoning_message_id = str(uuid.uuid4())
+            yield ReasoningStartEvent(
+                type=EventType.REASONING_START,
+                message_id=self._current_reasoning_message_id,
             )
-            logger.debug("🧠 Started thinking block")
-
-        # Start thinking text message if not already streaming
-        if not self._is_streaming_thinking:
-            self._is_streaming_thinking = True
-            self._current_thinking_text = ""
-            yield ThinkingTextMessageStartEvent(
-                type=EventType.THINKING_TEXT_MESSAGE_START
+            logger.debug("🧠 Started reasoning block")
+
+        # Start reasoning message if not already streaming
+        if not self._is_streaming_reasoning:
+            self._is_streaming_reasoning = True
+            self._current_reasoning_text = ""
+            if not self._current_reasoning_message_id:
+                self._current_reasoning_message_id = str(uuid.uuid4())
+            yield ReasoningMessageStartEvent(
+                type=EventType.REASONING_MESSAGE_START,
+                message_id=self._current_reasoning_message_id,
+                role="reasoning",
             )
-            logger.debug("🧠 Started thinking text message")
-
-        # Emit thinking content
-        self._current_thinking_text += combined_thought
-        yield ThinkingTextMessageContentEvent(
-            type=EventType.THINKING_TEXT_MESSAGE_CONTENT,
-            delta=combined_thought
+            logger.debug("🧠 Started reasoning message")
+
+        # Emit reasoning content
+        self._current_reasoning_text += combined_thought
+        yield ReasoningMessageContentEvent(
+            type=EventType.REASONING_MESSAGE_CONTENT,
+            message_id=self._current_reasoning_message_id,
+            delta=combined_thought,
         )
-        logger.debug(f"🧠 Emitted thinking content: {len(combined_thought)} chars")
+        logger.debug(f"🧠 Emitted reasoning content: {len(combined_thought)} chars")
+
+        # Emit encrypted value events for thought signatures
+        if thought_signatures and self._current_reasoning_message_id:
+            import base64
+            for sig in thought_signatures:
+                if sig is not None:
+                    encrypted_value = base64.b64encode(sig).decode("ascii") if isinstance(sig, (bytes, bytearray)) else str(sig)
+                    yield ReasoningEncryptedValueEvent(
+                        type=EventType.REASONING_ENCRYPTED_VALUE,
+                        subtype="message",
+                        entity_id=self._current_reasoning_message_id,
+                        encrypted_value=encrypted_value,
+                    )
+                    logger.debug("🧠 Emitted reasoning encrypted value (thought signature)")
 
-    async def _close_thinking_stream(self) -> AsyncGenerator[BaseEvent, None]:
-        """Close any active thinking stream.
+    async def _close_reasoning_stream(self) -> AsyncGenerator[BaseEvent, None]:
+        """Close any active reasoning stream.
 
-        This should be called when transitioning from thinking to regular output,
+        This should be called when transitioning from reasoning to regular output,
         or when the response is finalized.
 
         Yields:
-            THINKING_TEXT_MESSAGE_END and THINKING_END events if needed
+            REASONING_MESSAGE_END and REASONING_END events if needed
         """
-        if self._is_streaming_thinking:
-            yield ThinkingTextMessageEndEvent(
-                type=EventType.THINKING_TEXT_MESSAGE_END
+        if self._is_streaming_reasoning:
+            yield ReasoningMessageEndEvent(
+                type=EventType.REASONING_MESSAGE_END,
+                message_id=self._current_reasoning_message_id or "",
             )
-            self._is_streaming_thinking = False
-            self._current_thinking_text = ""
-            logger.debug("🧠 Closed thinking text message")
-
-        if self._is_thinking:
-            yield ThinkingEndEvent(
-                type=EventType.THINKING_END
+            self._is_streaming_reasoning = False
+            self._current_reasoning_text = ""
+            logger.debug("🧠 Closed reasoning message")
+
+        if self._is_reasoning:
+            yield ReasoningEndEvent(
+                type=EventType.REASONING_END,
+                message_id=self._current_reasoning_message_id or "",
             )
-            self._is_thinking = False
-            logger.debug("🧠 Closed thinking block")
+            self._is_reasoning = False
+            self._current_reasoning_message_id = None
+            logger.debug("🧠 Closed reasoning block")
 
     async def translate_lro_function_calls(self,adk_event: ADKEvent)-> AsyncGenerator[BaseEvent, None]:
         """Translate long running function calls from ADK event to AG-UI tool call events.
@@ -1164,10 +1198,11 @@ def reset(self):
         self._emitted_confirm_for_tools.clear()
         self._predictive_state_tool_call_ids.clear()
         self._deferred_confirm_events.clear()
-        # Reset thinking state
-        self._is_thinking = False
-        self._is_streaming_thinking = False
-        self._current_thinking_text = ""
+        # Reset reasoning state
+        self._is_reasoning = False
+        self._is_streaming_reasoning = False
+        self._current_reasoning_text = ""
+        self._current_reasoning_message_id = None
         # Reset streaming FC args state
         self._active_streaming_fc_id = None
         self._active_streaming_fc_name = None