Merge branch 'main' into release/candidate

Author: wyf7107

src/google/adk/cli/conformance/_generate_markdown_utils.py

@@ -17,22 +17,27 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
 from typing import Optional
 from typing import TYPE_CHECKING
 
 import click
 
-from ... import version
-
 if TYPE_CHECKING:
   from .cli_test import _ConformanceTestSummary
 
 
 def generate_markdown_report(
-    summary: _ConformanceTestSummary, report_dir: Optional[str]
+    version_data: dict[str, Any],
+    summary: _ConformanceTestSummary,
+    report_dir: Optional[str],
 ) -> None:
   """Generates a Markdown report of the test results."""
-  report_name = f"python_{'_'.join(version.__version__.split('.'))}_report.md"
+  server_version = version_data.get("version", "Unknown")
+  language = version_data.get("language", "Unknown")
+  language_version = version_data.get("language_version", "Unknown")
+
+  report_name = f"python_{'_'.join(server_version.split('.'))}_report.md"
   if not report_dir:
     report_path = Path(report_name)
   else:
@@ -44,7 +49,8 @@ def generate_markdown_report(
 
     # Summary
     f.write("## Summary\n\n")
-    f.write(f"- **ADK Version**: {version.__version__}\n")
+    f.write(f"- **ADK Version**: {server_version}\n")
+    f.write(f"- **Language**: {language} {language_version}\n")
     f.write(f"- **Total Tests**: {summary.total_tests}\n")
     f.write(f"- **Passed**: {summary.passed_tests}\n")
     f.write(f"- **Failed**: {summary.failed_tests}\n")

src/google/adk/cli/conformance/adk_web_server_client.py

@@ -207,6 +207,17 @@ async def update_session(
       response.raise_for_status()
       return Session.model_validate(response.json())
 
+  async def get_version_data(self) -> Dict[str, str]:
+    """Retrieve version data from the ADK web server.
+
+    Returns:
+      Dictionary containing version information
+    """
+    async with self._get_client() as client:
+      response = await client.get("/version")
+      response.raise_for_status()
+      return response.json()
+
   async def run_agent(
       self,
       request: RunAgentRequest,

src/google/adk/cli/conformance/cli_test.py

@@ -328,8 +328,9 @@ async def run_conformance_test(
     runner = ConformanceTestRunner(test_paths, client, mode)
     summary = await runner.run_all_tests()
 
-  if generate_report:
-    generate_markdown_report(summary, report_dir)
+    if generate_report:
+      version_data = await client.get_version_data()
+      generate_markdown_report(version_data, summary, report_dir)
 
   _print_test_summary(summary)
 

src/google/adk/cli/fast_api.py

@@ -45,6 +45,7 @@
 from .utils import evals
 from .utils.agent_change_handler import AgentChangeEventHandler
 from .utils.agent_loader import AgentLoader
+from .utils.base_agent_loader import BaseAgentLoader
 from .utils.service_factory import create_artifact_service_from_options
 from .utils.service_factory import create_memory_service_from_options
 from .utils.service_factory import create_session_service_from_options
@@ -72,6 +73,7 @@ def __getattr__(name: str):
 def get_fast_api_app(
     *,
     agents_dir: str,
+    agent_loader: Optional[BaseAgentLoader] = None,
     session_service_uri: Optional[str] = None,
     session_db_kwargs: Optional[Mapping[str, Any]] = None,
     artifact_service_uri: Optional[str] = None,
@@ -93,6 +95,52 @@ def get_fast_api_app(
     logo_image_url: Optional[str] = None,
     auto_create_session: bool = False,
 ) -> FastAPI:
+  """Constructs and returns a FastAPI application for serving ADK agents.
+
+  This function orchestrates the initialization of core ADK services (Session,
+  Artifact, Memory, and Credential) based on the provided configuration,
+  configures the ADK Web Server, and optionally enables advanced features
+  like Agent-to-Agent (A2A) protocol support and cloud telemetry.
+
+  Args:
+    agents_dir: The root directory containing agent definitions. This path is
+      used to discover agents, load custom service registrations (via
+      services.py/yaml), and as a base for local storage.
+    agent_loader: An optional custom loader for retrieving agent instances. If
+      not provided, a default AgentLoader targeting agents_dir is used.
+    session_service_uri: A URI defining the backend for session persistence.
+      Supports schemes like 'memory://', 'sqlite://', 'postgresql://',
+      'mysql://', or 'agentengine://'. Defaults to per-agent local SQLite
+      storage if None.
+    session_db_kwargs: Optional keyword arguments for custom session service
+      initialization. These are passed to the service factory along with the
+      URI.
+    artifact_service_uri: URI for the artifact service. Uses local artifact
+      service if None.
+    memory_service_uri: URI for the memory service. Uses local memory service if
+      None.
+    use_local_storage: Whether to use local storage for session and artifacts.
+    eval_storage_uri: URI for evaluation storage. If provided, uses GCS
+      managers.
+    allow_origins: List of allowed origins for CORS.
+    web: Whether to enable the web UI and serve its assets.
+    a2a: Whether to enable Agent-to-Agent (A2A) protocol support.
+    host: Host address for the server (defaults to 127.0.0.1).
+    port: Port number for the server (defaults to 8000).
+    url_prefix: Optional prefix for all URL routes.
+    trace_to_cloud: Whether to export traces to Google Cloud Trace.
+    otel_to_cloud: Whether to export OpenTelemetry data to Google Cloud.
+    reload_agents: Whether to watch for file changes and reload agents.
+    lifespan: Optional FastAPI lifespan context manager.
+    extra_plugins: List of extra plugin names to load.
+    logo_text: Text to display in the web UI logo area.
+    logo_image_url: URL for an image to display in the web UI logo area.
+    auto_create_session: Whether to automatically create a session when
+      not found.
+
+  Returns:
+    The configured FastAPI application instance.
+  """
 
   # Set up eval managers.
   if eval_storage_uri:
@@ -105,8 +153,10 @@ def get_fast_api_app(
     eval_sets_manager = LocalEvalSetsManager(agents_dir=agents_dir)
     eval_set_results_manager = LocalEvalSetResultsManager(agents_dir=agents_dir)
 
-  # initialize Agent Loader
-  agent_loader = AgentLoader(agents_dir)
+  # initialize Agent Loader if not passed as argument
+  if agent_loader is None:
+    agent_loader = AgentLoader(agents_dir)
+
   # Load services.py from agents_dir for custom service registration.
   load_services_module(agents_dir)
 

src/google/adk/tools/mcp_tool/mcp_tool.py

@@ -31,6 +31,7 @@
 from google.genai.types import FunctionDeclaration
 from mcp.shared.session import ProgressFnT
 from mcp.types import Tool as McpBaseTool
+from opentelemetry import propagate
 from typing_extensions import override
 
 from ...agents.callback_context import CallbackContext
@@ -313,6 +314,12 @@ async def _run_async_impl(
       headers.update(dynamic_headers)
     final_headers = headers if headers else None
 
+    # Propagate trace context in the _meta field as sprcified by MCP protocol.
+    # See https://agentclientprotocol.com/protocol/extensibility#the-meta-field
+    trace_carrier: Dict[str, str] = {}
+    propagate.get_global_textmap().inject(carrier=trace_carrier)
+    meta_trace_context = trace_carrier if trace_carrier else None
+
     # Get the session from the session manager
     session = await self._mcp_session_manager.create_session(
         headers=final_headers
@@ -325,6 +332,7 @@ async def _run_async_impl(
         self._mcp_tool.name,
         arguments=args,
         progress_callback=resolved_callback,
+        meta=meta_trace_context,
     )
     return response.model_dump(exclude_none=True, mode="json")
 

tests/unittests/tools/mcp_tool/test_mcp_tool.py

@@ -25,6 +25,7 @@
 from google.adk.auth.auth_credential import ServiceAccount
 from google.adk.features import FeatureName
 from google.adk.features._feature_registry import temporary_feature_override
+from google.adk.tools.mcp_tool import mcp_tool
 from google.adk.tools.mcp_tool.mcp_session_manager import MCPSessionManager
 from google.adk.tools.mcp_tool.mcp_tool import MCPTool
 from google.adk.tools.tool_context import ToolContext
@@ -225,7 +226,7 @@ async def test_run_async_impl_no_auth(self):
     )
     # Fix: call_tool uses 'arguments' parameter, not positional args
     self.mock_session.call_tool.assert_called_once_with(
-        "test_tool", arguments=args, progress_callback=None
+        "test_tool", arguments=args, progress_callback=None, meta=None
     )
 
   @pytest.mark.asyncio
@@ -262,6 +263,55 @@ async def test_run_async_impl_with_oauth2(self):
     headers = call_args[1]["headers"]
     assert headers == {"Authorization": "Bearer test_access_token"}
 
+  @patch.object(mcp_tool, "propagate", autospec=True)
+  @pytest.mark.asyncio
+  async def test_run_async_impl_with_trace_context(self, mock_propagate):
+    """Test running tool with trace context injection."""
+    mock_propagator = Mock()
+
+    def inject_context(carrier, context=None) -> None:
+      carrier["traceparent"] = (
+          "00-1234567890abcdef1234567890abcdef-1234567890abcdef-01"
+      )
+      carrier["tracestate"] = "foo=bar"
+      carrier["baggage"] = "baz=qux"
+
+    mock_propagator.inject.side_effect = inject_context
+    mock_propagate.get_global_textmap.return_value = mock_propagator
+
+    tool = MCPTool(
+        mcp_tool=self.mock_mcp_tool,
+        mcp_session_manager=self.mock_session_manager,
+    )
+
+    mcp_response = CallToolResult(
+        content=[TextContent(type="text", text="success")]
+    )
+    self.mock_session.call_tool = AsyncMock(return_value=mcp_response)
+
+    tool_context = Mock(spec=ToolContext)
+    args = {"param1": "test_value"}
+
+    await tool._run_async_impl(
+        args=args, tool_context=tool_context, credential=None
+    )
+
+    self.mock_session_manager.create_session.assert_called_once_with(
+        headers=None
+    )
+    self.mock_session.call_tool.assert_called_once_with(
+        "test_tool",
+        arguments=args,
+        progress_callback=None,
+        meta={
+            "traceparent": (
+                "00-1234567890abcdef1234567890abcdef-1234567890abcdef-01"
+            ),
+            "tracestate": "foo=bar",
+            "baggage": "baz=qux",
+        },
+    )
+
   @pytest.mark.asyncio
   async def test_get_headers_oauth2(self):
     """Test header generation for OAuth2 credentials."""
@@ -778,7 +828,7 @@ async def test_run_async_impl_with_header_provider_no_auth(self):
         headers=expected_headers
     )
     self.mock_session.call_tool.assert_called_once_with(
-        "test_tool", arguments=args, progress_callback=None
+        "test_tool", arguments=args, progress_callback=None, meta=None
     )
 
   @pytest.mark.asyncio
@@ -821,7 +871,7 @@ async def test_run_async_impl_with_header_provider_and_oauth2(self):
         "X-Tenant-ID": "test-tenant",
     }
     self.mock_session.call_tool.assert_called_once_with(
-        "test_tool", arguments=args, progress_callback=None
+        "test_tool", arguments=args, progress_callback=None, meta=None
     )
 
   def test_init_with_progress_callback(self):
@@ -875,7 +925,10 @@ async def my_progress_callback(
     )
     # Verify progress_callback was passed to call_tool
     self.mock_session.call_tool.assert_called_once_with(
-        "test_tool", arguments=args, progress_callback=my_progress_callback
+        "test_tool",
+        arguments=args,
+        progress_callback=my_progress_callback,
+        meta=None,
     )
 
   @pytest.mark.asyncio