Merge branch 'main' into skill-script-utf8-output

Author: rohityan

docs/guides/README.md

@@ -13,6 +13,9 @@ This directory contains specific developer guides for the ADK Python implementat
 * [Event and NodeInfo](events/event/index.md) - Understanding Event and NodeInfo in workflows.
 * [RequestInput](events/request_input/index.md) - How to use RequestInput for human-in-the-loop interactions.
 
+### Tools
+* [to_mcp_server](tools/mcp_tool/agent_to_mcp/index.md) - Expose an ADK agent as an MCP server so any MCP host can drive it as a single tool (the MCP counterpart of to_a2a).
+
 ### Workflows
 * [Workflow](workflow/workflow/index.md) - Graph-based orchestration of complex, multi-step agent interactions.
 * [Workflow Graphs](workflow/graph/index.md) - Understanding nodes, edges, and graph structures in workflows.

docs/guides/tools/mcp_tool/agent_to_mcp/index.md

@@ -0,0 +1,139 @@
+# to_mcp_server
+
+Exposes an ADK agent as an MCP server so any MCP host (Claude Code, OpenAI
+Codex, an IDE, or any MCP client) can drive it as a single tool. It is the MCP
+counterpart of `to_a2a`.
+
+## Introduction
+
+`to_mcp_server` turns a whole ADK agent into a standard
+[Model Context Protocol](https://modelcontextprotocol.io/) server. The agent —
+its model loop and all of its tools — is registered as a *single* MCP tool named
+after the agent. A host that speaks MCP sends a request string and receives the
+agent's final response; it never imports ADK and does not see the agent's
+individual tools.
+
+This solves the problem of making an ADK agent consumable by harnesses that are
+not ADK. Where `to_a2a` publishes an agent over A2A, `to_mcp_server` publishes it
+over MCP, so coding agents and IDEs that already speak MCP can delegate a task to
+an ADK agent as if it were any other tool. It builds on `Runner` to execute the
+agent and returns a `FastMCP` server, leaving the choice of transport (stdio for
+local hosts, streamable-http for networked ones) to the caller.
+
+## Get started
+
+Define an agent and expose it. Running the file starts the MCP server on stdio;
+an MCP host can also launch it as a subprocess.
+
+```python
+import random
+
+from google.adk.agents import LlmAgent
+from google.adk.tools.mcp_tool import to_mcp_server
+
+
+def roll_die(sides: int) -> int:
+  """Roll a die with the given number of sides and return the result."""
+  return random.randint(1, sides)
+
+
+dice_agent = LlmAgent(
+    name="dice_agent",
+    description="Rolls dice with any number of sides and reports the outcome.",
+    instruction="Use the roll_die tool to roll the dice the user asks for.",
+    tools=[roll_die],
+)
+
+# The whole agent becomes one MCP tool named "dice_agent".
+server = to_mcp_server(dice_agent)
+
+if __name__ == "__main__":
+  server.run(transport="stdio")
+```
+
+A host configured to launch this file sees one tool, `dice_agent`, and calls it
+with a `request` string; the ADK agent runs its own model and `roll_die` loop and
+returns the answer.
+
+## How it works
+
+`to_mcp_server` creates a `FastMCP` server and registers one tool whose handler
+runs the agent through a `Runner`. If no `runner` is supplied, one is built with
+in-memory session, artifact, memory, and credential services.
+
+On each tool call the handler:
+
+1.  Resolves an ADK session (see below), then wraps the incoming `request` string
+    as a user `Content`.
+2.  Drives `Runner.run_async` and iterates the event stream.
+3.  Forwards intermediate (non-final) text events to the host as MCP **progress
+    notifications**, so the host can show the agent working in real time.
+4.  Maps the parts of the final response to MCP content blocks and returns them:
+    text becomes `TextContent`, inline image data becomes `ImageContent`, audio
+    becomes `AudioContent`, and any other inline data becomes an
+    `EmbeddedResource`. This is why a multimodal agent's output is preserved
+    rather than flattened to text.
+
+### Session continuity
+
+`to_mcp_server` keeps one ADK session per MCP connection, so successive tool
+calls on the same connection form a single multi-turn conversation. The mapping
+from connection to session is held in a `weakref.WeakKeyDictionary`, so a
+session's entry is dropped when its connection is garbage-collected. Over stdio
+there is one connection per process, so all calls share one conversation; over
+streamable-http each client connection gets its own session.
+
+`to_mcp_server` depends on `Runner`, the agent (`BaseAgent`/`LlmAgent`),
+`google.genai.types`, and `mcp.server.fastmcp.FastMCP`; it returns a `FastMCP`
+that the caller runs on a transport of their choice.
+
+## Configuration options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `agent` | `BaseAgent` | *required* | The agent to serve. Its model loop and all of its tools are exposed together as one MCP tool. |
+| `name` | `str \| None` | `None` | The MCP server and tool name. Defaults to the agent's name (or `"adk_agent"`). Set it when you want the tool to appear under a name other than the agent's. |
+| `instructions` | `str \| None` | `None` | Optional server instructions an MCP host may surface to its model to describe how to use the tool. |
+| `runner` | `Runner \| None` | `None` | A pre-built `Runner`. If omitted, one is created with in-memory services. Supply your own to use persistent or custom session, artifact, memory, or credential services — this is the recommended path for a long-lived networked server. |
+
+## Advanced applications
+
+### Serving over the network
+
+*   **Problem solved**: a host on another machine needs to reach the agent.
+*   **Implementation**: run the same server with the networked transport:
+    `server.run(transport="streamable-http")`. Nothing about the agent changes;
+    only the transport differs.
+
+### Bringing your own services
+
+*   **Problem solved**: the default in-memory services do not persist across
+    process restarts and are not suited to multi-client production serving.
+*   **Implementation**: build a `Runner` with your chosen services and pass it in:
+    `to_mcp_server(agent, runner=my_runner)`. The tool then uses those services
+    for every call.
+
+### Multimodal responses
+
+*   **Problem solved**: the agent produces images or audio, not just text.
+*   **Implementation**: no extra work — non-text parts of the final response are
+    returned as `ImageContent`, `AudioContent`, or `EmbeddedResource`, so the
+    host receives them alongside any text.
+
+## Limitations
+
+*   **Text input only**: the tool accepts a single `request` string. Passing
+    media *into* the agent is not supported through the tool call, because MCP
+    tool arguments are JSON that the host's model fills in and hosts do not place
+    media in tool arguments. For media input, use MCP resources or elicitation
+    instead.
+*   **Default services are in-memory**: for a long-lived streamable-http server,
+    sessions accumulate with no eviction; inject a `runner` with a persistent or
+    cleaning session service. Tool calls on a single connection are expected to
+    be sequential, since they share one session.
+*   **Experimental**: `to_mcp_server` is `@experimental` and lives behind the
+    `mcp` extra; its behavior may change in future releases.
+
+## Related samples
+
+*   [MCP: serve an ADK agent](../../../../../contributing/samples/mcp/mcp_serve_agent)

src/google/adk/apps/llm_event_summarizer.py

@@ -50,7 +50,13 @@ class LlmEventSummarizer(BaseEventsSummarizer):
       ' It may or may not start from a compacted history. Please identify and'
       ' reiterate the user request, summarize the context so far, focusing on'
       ' key decisions made and information obtained, as well as any unresolved'
-      ' questions or tasks. The summary should be concise and capture the'
+      ' questions or tasks. '
+      'CRITICAL INSTRUCTIONS: '
+      '1. Explicitly identify and state the primary language used by the user '
+      'at the top of your summary (e.g., "Conversation Language: English"). '
+      '2. If the agent called any tools, accurately list the exact tool names '
+      'used to maintain tool grounding. '
+      'The rest of the summary should be concise and capture the'
       ' essence of the interaction.\n\n{conversation_history}'
   )
 

src/google/adk/tools/environment/_read_file_tool.py

@@ -17,7 +17,6 @@
 from __future__ import annotations
 
 import logging
-import shlex
 from typing import Any
 from typing import Optional
 from typing import TYPE_CHECKING
@@ -103,31 +102,12 @@ async def run_async(
     start_line = args.get('start_line')
     end_line = args.get('end_line')
 
-    # Use `sed` to read the file if start_line or end_line are specified.
-    if (start_line and start_line > 1) or end_line:
-      start = start_line or 1
-      if end_line:
-        sed_range = f'{start},{end_line}'
-      else:
-        sed_range = f'{start},$'
-      path_arg = shlex.quote(path)
-      sed_arg = shlex.quote(f'{sed_range}p')
-      cmd = f'cat -n {path_arg} | sed -n {sed_arg}'
-      res = await self._environment.execute(cmd)
-      if res.exit_code == 0:
-        return {
-            'status': 'ok',
-            'content': _truncate(
-                res.stdout,
-                limit=self._max_output_chars,
-            ),
-        }
-
     try:
+      # TODO: Avoid loading the entire file into memory to prevent OOM on large files.
       data_bytes = await self._environment.read_file(path)
-      text = data_bytes.decode('utf-8', errors='replace')
-      lines = text.splitlines(True)
-      total = len(lines)
+      # Slice data_bytes by line boundaries before decoding.
+      lines_bytes = data_bytes.splitlines(keepends=True)
+      total = len(lines_bytes)
       start = max(1, start_line or 1)
       end = min(total, end_line or total)
       if start > total:
@@ -144,9 +124,13 @@ async def run_async(
             'error': f'`start_line` ({start}) is after `end_line` ({end}).',
             'total_lines': total,
         }
-      selected = lines[start - 1 : end]
+      selected_bytes = lines_bytes[start - 1 : end]
+      lines = [
+          line_bytes.decode('utf-8', errors='replace')
+          for line_bytes in selected_bytes
+      ]
       numbered = ''.join(
-          f'{start + i:6d}\t{line}' for i, line in enumerate(selected)
+          f'{start + i:6d}\t{line}' for i, line in enumerate(lines)
       )
       result = {
           'status': 'ok',

src/google/adk/workflow/_workflow.py

@@ -351,6 +351,7 @@ def get_recovered_sequence_index(t):
 
       sorted_done = sorted(ordered_done, key=get_recovered_sequence_index)
 
+      error_to_raise = None
       for task in sorted_done:
         name = self._pop_completed_task(loop_state, task)
 
@@ -365,14 +366,17 @@ def get_recovered_sequence_index(t):
           node_state = loop_state.nodes[name]
           node_state.status = NodeStatus.FAILED
 
-          ctx._error = child_ctx.error
-          ctx._error_node_path = child_ctx.error_node_path
-
-          loop_state.error_shut_down = True
-          logger.debug('node %s execute loop end.', ctx.node_path)
-          return
+          if not error_to_raise:
+            ctx._error = child_ctx.error
+            ctx._error_node_path = child_ctx.error_node_path
+            error_to_raise = child_ctx.error
+        else:
+          self._handle_completion(loop_state, name, node, child_ctx)
 
-        self._handle_completion(loop_state, name, node, child_ctx)
+      if error_to_raise:
+        loop_state.error_shut_down = True
+        logger.debug('node %s execute loop end.', ctx.node_path)
+        return
 
     # Await fire-and-forget dynamic tasks.
     # TODO: Handle dynamic task failures and interrupts here.

tests/unittests/tools/environment/test_read_file_tool.py

@@ -0,0 +1,96 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pathlib import Path
+from typing import Optional
+
+from google.adk.environment._base_environment import BaseEnvironment
+from google.adk.environment._base_environment import ExecutionResult
+from google.adk.tools.environment._tools import ReadFileTool
+import pytest
+
+
+class _StubEnvironment(BaseEnvironment):
+  """Minimal environment double for ReadFileTool tests."""
+
+  def __init__(self, files: dict[str, bytes]):
+    self._files = files
+    self.execute_calls: list[str] = []
+
+  @property
+  def working_dir(self) -> Path:
+    return Path('/tmp/adk-test')
+
+  async def execute(
+      self,
+      command: str,
+      *,
+      timeout: Optional[float] = None,
+  ) -> ExecutionResult:
+    del timeout
+    self.execute_calls.append(command)
+    raise AssertionError('ReadFileTool should not invoke execute().')
+
+  async def read_file(self, path: Path) -> bytes:
+    key = str(path)
+    if key not in self._files:
+      raise FileNotFoundError(key)
+    return self._files[key]
+
+  async def write_file(self, path: Path, content: str | bytes) -> None:
+    del path, content
+    raise NotImplementedError
+
+
+@pytest.mark.asyncio
+async def test_read_file_with_line_range_uses_direct_file_read():
+  """ReadFileTool slices lines without shelling out."""
+  environment = _StubEnvironment({
+      'notes.txt': b'alpha\nbeta\ngamma\ndelta\n',
+  })
+
+  result = await ReadFileTool(environment).run_async(
+      args={'path': 'notes.txt', 'start_line': 2, 'end_line': 3},
+      tool_context=None,
+  )
+
+  assert result == {
+      'status': 'ok',
+      'content': '     2\tbeta\n     3\tgamma\n',
+      'total_lines': 4,
+  }
+  assert environment.execute_calls == []
+
+
+@pytest.mark.asyncio
+async def test_read_file_with_line_range_treats_shell_payload_as_literal_path():
+  """Shell metacharacters in the path do not trigger command execution."""
+  environment = _StubEnvironment({
+      'safe.txt': b'line1\nline2\n',
+  })
+  payload = (
+      '\'; python3 -c "from pathlib import Path;'
+      " Path('pwned.txt').write_text('owned')\"; echo '"
+  )
+
+  result = await ReadFileTool(environment).run_async(
+      args={'path': payload, 'start_line': 1, 'end_line': 2},
+      tool_context=None,
+  )
+
+  assert result == {
+      'status': 'error',
+      'error': f'File not found: {payload}',
+  }
+  assert environment.execute_calls == []