fix(litellm): preserve reasoning replay and optionally share agent thoughts

Merge #5572

**Please ensure you have read the [contribution guide](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) before creating a pull request.**

### Link to Issue or Description of Change

**1. Link to an existing issue (if applicable):**

- Closes: N/A
- Related: N/A

**2. Or, if no issue exists, describe the change:**

**Problem:**
LiteLLM-backed reasoning content can be streamed as small text fragments, notably with vLLM. ADK stores those fragments as separate `Part(thought=True)` entries. When replaying prior assistant/model thoughts back into LiteLLM, ADK previously joined those fragments with newlines, which changed the original reasoning text.

In multi-agent flows, ADK also always excluded thoughts from other agents when presenting their messages as context. That default is privacy-preserving, but it removes a useful coordination signal for advanced multi-agent systems. For example, an orchestrator, reviewer, planner, or supervisor agent may benefit from seeing another agent’s reasoning trail when deciding whether to continue, retry, delegate, or synthesize results.

**Solution:**
This PR updates LiteLLM reasoning replay so plain thought text fragments are concatenated without inserting separators. This preserves vLLM-style streamed reasoning chunks when ADK sends previous model output back to LiteLLM.

The PR also adds an opt-in `RunConfig.include_thoughts_from_other_agents` flag. The default remains `False`, so existing behavior and privacy expectations are preserved. When enabled for full-history context, other-agent thoughts are converted into explicit user-context text, e.g. `[agent] thought: ...`, so downstream model adapters do not drop them as user-side `thought=True` parts.

The option is intentionally developer-controlled because whether reasoning should cross agent boundaries is application-specific. It can be valuable in orchestrated systems where agents are trusted collaborators and reasoning improves handoff quality, but it should not be enabled silently for all apps.

### Testing Plan

**Unit Tests:**

- [x] I have added or updated unit tests for my change.
- [x] All unit tests pass locally.

Passed locally:

- `uv run --extra test pytest tests/unittests/models/test_litellm.py`
  - `257 passed`
- `uv run --extra test pytest tests/unittests/flows/llm_flows/test_contents_other_agent.py`
  - `12 passed`

**Manual End-to-End (E2E) Tests:**

Not run. The change is covered by focused unit tests for LiteLLM reasoning replay and other-agent context construction.

### Checklist

- [x] I have read the [CONTRIBUTING.md](https://github.com/google/adk-python/blob/main/CONTRIBUTING.md) document.
- [x] I have performed a self-review of my own code.
- [x] I have commented my code, particularly in hard-to-understand areas.
- [x] I have added tests that prove my fix is effective or that my feature works.
- [x] New and existing unit tests pass locally with my changes.
- [ ] I have manually tested my changes end-to-end.
- [ ] Any dependent changes have been merged and published in downstream modules.

### Additional context

The other-agent thought sharing behavior is deliberately opt-in. In many apps, thoughts should remain private and excluded from cross-agent context. In more controlled multi-agent systems, however, exposing reasoning to orchestrator-like agents can improve routing, recovery, auditing, and synthesis decisions.

This may not be the final API shape for the capability, but having an explicit option to include other agents’ reasoning is useful and worth discussing.

Co-authored-by: George Weale <gweale@google.com>
COPYBARA_INTEGRATE_REVIEW=#5572 from lorenzbaraldi:feature/pass_reasoning_content 7d6d3e6
PiperOrigin-RevId: 944562507

Author: 2 people

src/google/adk/agents/run_config.py

@@ -379,6 +379,14 @@ class RunConfig(BaseModel):
   callers provide per-turn context without changing the conversation history.
   """
 
+  include_thoughts_from_other_agents: bool = False
+  """Whether to include other agents' thought parts in LLM context.
+
+  By default, thoughts from other agents are excluded when their messages are
+  reformatted as user context for the current agent. Enable this only when
+  agents are expected to share internal reasoning with one another.
+  """
+
   @model_validator(mode='before')
   @classmethod
   def check_for_deprecated_save_live_audio(cls, data: Any) -> Any:

src/google/adk/flows/llm_flows/contents.py

@@ -81,6 +81,12 @@ async def run_async(
     # Preserve all contents that were added by instruction processor
     # (since llm_request.contents will be completely reassigned below)
     instruction_related_contents = llm_request.contents
+    run_config = invocation_context.run_config
+    include_thoughts_from_other_agents = (
+        run_config.include_thoughts_from_other_agents
+        if run_config is not None
+        else False
+    )
 
     is_single_turn = getattr(agent, 'mode', None) == 'single_turn'
     if agent.include_contents == 'default':
@@ -93,6 +99,7 @@ async def run_async(
           isolation_scope=invocation_context.isolation_scope,
           is_single_turn=is_single_turn,
           user_content=invocation_context.user_content,
+          include_thoughts_from_other_agents=include_thoughts_from_other_agents,
       )
     else:
       # Include current turn context only (no conversation history)
@@ -104,6 +111,7 @@ async def run_async(
           isolation_scope=invocation_context.isolation_scope,
           is_single_turn=is_single_turn,
           user_content=invocation_context.user_content,
+          include_thoughts_from_other_agents=False,
       )
 
     if (
@@ -274,7 +282,9 @@ def _rearrange_events_for_latest_function_response(
   return result_events
 
 
-def _is_part_invisible(p: types.Part) -> bool:
+def _is_part_invisible(
+    p: types.Part, *, include_thoughts: bool = False
+) -> bool:
   """Returns whether a part is invisible for LLM context.
 
   A part is invisible if:
@@ -294,7 +304,7 @@ def _is_part_invisible(p: types.Part) -> bool:
   if p.function_call or p.function_response:
     return False
 
-  return p.thought or not (
+  return (p.thought and not include_thoughts) or not (
       p.text
       or p.inline_data
       or p.file_data
@@ -303,7 +313,9 @@ def _is_part_invisible(p: types.Part) -> bool:
   )
 
 
-def _contains_empty_content(event: Event) -> bool:
+def _contains_empty_content(
+    event: Event, *, include_thoughts: bool = False
+) -> bool:
   """Check if an event should be skipped due to missing or empty content.
 
   This can happen to the events that only changed session state.
@@ -325,7 +337,10 @@ def _contains_empty_content(event: Event) -> bool:
       not event.content
       or not event.content.role
       or not event.content.parts
-      or all(_is_part_invisible(p) for p in event.content.parts)
+      or all(
+          _is_part_invisible(p, include_thoughts=include_thoughts)
+          for p in event.content.parts
+      )
   ) and (not event.output_transcription and not event.input_transcription)
 
 
@@ -393,6 +408,8 @@ def _should_include_event_in_context(
     current_branch: Optional[str],
     event: Event,
     isolation_scope: Optional[str] = None,
+    *,
+    include_thoughts: bool = False,
 ) -> bool:
   """Determines if an event should be included in the LLM context.
 
@@ -418,7 +435,7 @@ def _should_include_event_in_context(
   if ev_iso != isolation_scope:
     return False
   return not (
-      _contains_empty_content(event)
+      _contains_empty_content(event, include_thoughts=include_thoughts)
       or not _is_event_belongs_to_branch(current_branch, event)
       or _is_adk_framework_event(event)
       or _is_auth_event(event)
@@ -577,6 +594,7 @@ def _get_contents(
     isolation_scope: Optional[str] = None,
     is_single_turn: bool = False,
     user_content: Optional[types.Content] = None,
+    include_thoughts_from_other_agents: bool = False,
 ) -> list[types.Content]:
   """Get the contents for the LLM request.
 
@@ -592,6 +610,8 @@ def _get_contents(
     user_content: Fallback first user turn for task agents whose
       originating delegation FC is not in session (workflow-node
       task case).
+    include_thoughts_from_other_agents: Whether to include thought parts from
+      other agents when presenting their messages as user context.
 
   Returns:
     A list of processed contents.
@@ -624,7 +644,13 @@ def _get_contents(
       e
       for e in rewind_filtered_events
       if _should_include_event_in_context(
-          current_branch, e, isolation_scope=isolation_scope
+          current_branch,
+          e,
+          isolation_scope=isolation_scope,
+          include_thoughts=(
+              include_thoughts_from_other_agents
+              and _is_other_agent_reply(agent_name, e)
+          ),
       )
   ]
 
@@ -699,7 +725,9 @@ def _get_contents(
             break
 
     if is_other_reply:
-      if converted_event := _present_other_agent_message(event):
+      if converted_event := _present_other_agent_message(
+          event, include_thoughts=include_thoughts_from_other_agents
+      ):
         filtered_events.append(converted_event)
     else:
       filtered_events.append(event)
@@ -752,6 +780,7 @@ def _get_current_turn_contents(
     is_single_turn: bool = False,
     isolation_scope: Optional[str] = None,
     user_content: Optional[types.Content] = None,
+    include_thoughts_from_other_agents: bool = False,
 ) -> list[types.Content]:
   """Get contents for the current turn only (no conversation history).
 
@@ -768,6 +797,8 @@ def _get_current_turn_contents(
     events: A list of all session events.
     agent_name: The name of the agent.
     preserve_function_call_ids: Whether to preserve function call ids.
+    include_thoughts_from_other_agents: Whether to include thought parts from
+      other agents when presenting their messages as user context.
 
   Returns:
     A list of contents for the current turn only, preserving context needed
@@ -778,7 +809,13 @@ def _get_current_turn_contents(
     event = events[i]
     if (
         _should_include_event_in_context(
-            current_branch, event, isolation_scope=isolation_scope
+            current_branch,
+            event,
+            isolation_scope=isolation_scope,
+            include_thoughts=(
+                include_thoughts_from_other_agents
+                and _is_other_agent_reply(agent_name, event)
+            ),
         )
         and (event.author == 'user' or _is_other_agent_reply(agent_name, event))
         and not _is_direct_transfer(event)
@@ -791,6 +828,7 @@ def _get_current_turn_contents(
           isolation_scope=isolation_scope,
           is_single_turn=is_single_turn,
           user_content=user_content,
+          include_thoughts_from_other_agents=include_thoughts_from_other_agents,
       )
 
   return []
@@ -851,14 +889,18 @@ def _is_other_agent_reply(current_agent_name: str, event: Event) -> bool:
   )
 
 
-def _present_other_agent_message(event: Event) -> Optional[Event]:
+def _present_other_agent_message(
+    event: Event, *, include_thoughts: bool = False
+) -> Optional[Event]:
   """Presents another agent's message as user context for the current agent.
 
   Reformats the event with role='user' and adds '[agent_name] said:' prefix
   to provide context without confusion about authorship.
 
   Args:
     event: The event from another agent to present as context.
+    include_thoughts: Whether to include thought parts as explicit text
+      context.
 
   Returns:
     Event reformatted as user-role context with agent attribution, or None
@@ -872,7 +914,10 @@ def _present_other_agent_message(event: Event) -> Optional[Event]:
   content.parts = [types.Part(text='For context:')]
   for part in event.content.parts:
     if part.thought:
-      # Exclude thoughts from the context.
+      if include_thoughts and part.text is not None and part.text.strip():
+        content.parts.append(
+            types.Part(text=f'[{event.author}] thought: {part.text}')
+        )
       continue
     elif part.text is not None and part.text.strip():
       content.parts.append(

src/google/adk/models/lite_llm.py

@@ -882,6 +882,28 @@ def _extract_reasoning_tokens(usage: Any) -> int:
   return 0
 
 
+def _merge_reasoning_texts(reasoning_parts: Iterable[types.Part]) -> str:
+  """Merges reasoning text fragments into a single provider payload.
+
+  Streaming providers such as vLLM can emit reasoning as token-sized chunks.
+  ADK stores those chunks as consecutive thought parts, so inserting separators
+  here changes the model's original reasoning text.
+  """
+  reasoning_texts = []
+  for part in reasoning_parts:
+    if part.text:
+      reasoning_texts.append(part.text)
+    elif (
+        part.inline_data
+        and part.inline_data.data
+        and part.inline_data.mime_type
+        and part.inline_data.mime_type.startswith("text/")
+    ):
+      reasoning_texts.append(_decode_inline_text_data(part.inline_data.data))
+
+  return "".join(reasoning_texts)
+
+
 def _extract_thought_signature_from_tool_call(
     tool_call: ChatCompletionMessageToolCall,
 ) -> Optional[bytes]:
@@ -1088,18 +1110,6 @@ async def _content_to_message_param(
         msg["thinking_blocks"] = thinking_blocks  # type: ignore[typeddict-unknown-key]
         return msg
 
-    reasoning_texts = []
-    for part in reasoning_parts:
-      if part.text:
-        reasoning_texts.append(part.text)
-      elif (
-          part.inline_data
-          and part.inline_data.data
-          and part.inline_data.mime_type
-          and part.inline_data.mime_type.startswith("text/")
-      ):
-        reasoning_texts.append(_decode_inline_text_data(part.inline_data.data))
-
     # Anthropic routes require thinking blocks to be embedded directly in the
     # message content list. LiteLLM's prompt template for Anthropic drops the
     # top-level reasoning_content field, so thinking blocks disappear from
@@ -1128,9 +1138,7 @@ async def _content_to_message_param(
           tool_calls=tool_calls or None,
       )
 
-    # Preserve reasoning deltas exactly as received. Injecting separators
-    # between fragments can corrupt provider-streamed thinking text.
-    reasoning_content = "".join(text for text in reasoning_texts if text)
+    reasoning_content = _merge_reasoning_texts(reasoning_parts)
     return ChatCompletionAssistantMessage(
         role=role,
         content=final_content,

tests/unittests/flows/llm_flows/test_contents_other_agent.py

@@ -15,6 +15,7 @@
 """Behavioral tests for other agent message processing in contents module."""
 
 from google.adk.agents.llm_agent import Agent
+from google.adk.agents.run_config import RunConfig
 from google.adk.events.event import Event
 from google.adk.flows.llm_flows.contents import request_processor
 from google.adk.models.llm_request import LlmRequest
@@ -85,6 +86,111 @@ async def test_other_agent_thoughts_are_excluded():
   ]
 
 
+@pytest.mark.asyncio
+async def test_other_agent_thoughts_can_be_included_as_context():
+  """Test opt-in inclusion of thoughts from other agents."""
+  agent = Agent(model="gemini-2.5-flash", name="current_agent")
+  llm_request = LlmRequest(model="gemini-2.5-flash")
+  invocation_context = await testing_utils.create_invocation_context(
+      agent=agent,
+      run_config=RunConfig(include_thoughts_from_other_agents=True),
+  )
+  other_agent_event = Event(
+      invocation_id="test_inv",
+      author="other_agent",
+      content=types.ModelContent([
+          types.Part(text="Public message", thought=False),
+          types.Part(text="Private thought", thought=True),
+          types.Part(text="Another public message"),
+      ]),
+  )
+  invocation_context.session.events = [other_agent_event]
+
+  async for _ in request_processor.run_async(invocation_context, llm_request):
+    pass
+
+  assert llm_request.contents[0].role == "user"
+  assert llm_request.contents[0].parts == [
+      types.Part(text="For context:"),
+      types.Part(text="[other_agent] said: Public message"),
+      types.Part(text="[other_agent] thought: Private thought"),
+      types.Part(text="[other_agent] said: Another public message"),
+  ]
+
+
+@pytest.mark.asyncio
+async def test_other_agent_thought_only_message_can_be_included_as_context():
+  """Test opt-in inclusion of thought-only messages from other agents."""
+  agent = Agent(model="gemini-2.5-flash", name="current_agent")
+  llm_request = LlmRequest(model="gemini-2.5-flash")
+  invocation_context = await testing_utils.create_invocation_context(
+      agent=agent,
+      run_config=RunConfig(include_thoughts_from_other_agents=True),
+  )
+  other_agent_event = Event(
+      invocation_id="test_inv",
+      author="other_agent",
+      content=types.ModelContent([
+          types.Part(text="First private thought", thought=True),
+          types.Part(text="Second private thought", thought=True),
+      ]),
+  )
+  invocation_context.session.events = [other_agent_event]
+
+  async for _ in request_processor.run_async(invocation_context, llm_request):
+    pass
+
+  assert llm_request.contents[0].role == "user"
+  assert llm_request.contents[0].parts == [
+      types.Part(text="For context:"),
+      types.Part(text="[other_agent] thought: First private thought"),
+      types.Part(text="[other_agent] thought: Second private thought"),
+  ]
+
+
+@pytest.mark.asyncio
+async def test_other_agent_thoughts_excluded_from_current_turn_only_context():
+  """Test include_contents='none' does not include other-agent thoughts."""
+  agent = Agent(
+      model="gemini-2.5-flash",
+      name="current_agent",
+      include_contents="none",
+  )
+  llm_request = LlmRequest(model="gemini-2.5-flash")
+  invocation_context = await testing_utils.create_invocation_context(
+      agent=agent,
+      run_config=RunConfig(include_thoughts_from_other_agents=True),
+  )
+  invocation_context.session.events = [
+      Event(
+          invocation_id="inv1",
+          author="user",
+          content=types.UserContent("Earlier user message"),
+      ),
+      Event(
+          invocation_id="inv2",
+          author="other_agent",
+          content=types.ModelContent([
+              types.Part(text="Private thought", thought=True),
+              types.Part(text="Visible handoff"),
+          ]),
+      ),
+  ]
+
+  async for _ in request_processor.run_async(invocation_context, llm_request):
+    pass
+
+  assert llm_request.contents == [
+      types.Content(
+          role="user",
+          parts=[
+              types.Part(text="For context:"),
+              types.Part(text="[other_agent] said: Visible handoff"),
+          ],
+      )
+  ]
+
+
 @pytest.mark.asyncio
 async def test_other_agent_function_calls():
   """Test that function calls from other agents are preserved in context."""