Merge branch 'main' into main

Author: llalitkumarrr

contributing/adk_project_overview_and_architecture.md

@@ -45,6 +45,14 @@ agent.py: Must define the agent and assign it to a variable named root_agent. Th
 
 `__init__.py`: In each agent directory, it must contain `from . import agent` to make the agent discoverable.
 
+### Nested Agent Directories (Dev Mode / `adk web`)
+
+In the local development server (`adk web` / `dev_server`), ADK supports deeply nested agent directories (e.g., sub-packages or structured folders).
+
+- **Recursive Discovery**: The loader recursively walks directories to discover all valid agent applications containing an `agent.py`, `root_agent.yaml`, or `__init__.py` file.
+- **Dot Naming Convention**: Nested agents are represented in the system and referenced inside the Web UI using a standard dot-separated namespace notation (e.g., `agent_samples.empty_agent` or `workflow_samples.fan_out_fan_in`).
+- **Isolation**: Production environments (`adk api_server`) only support flat single-level agent directories for maximum security and isolation.
+
 ## Local Development & Debugging
 
 Interactive UI (adk web): This is our primary debugging tool. It's a decoupled system:

contributing/samples/mcp/mcp_sse_agent/agent.py

@@ -14,11 +14,15 @@
 
 
 import os
+import pprint
+from typing import Any
 
 from google.adk.agents.llm_agent import LlmAgent
 from google.adk.agents.mcp_instruction_provider import McpInstructionProvider
+from google.adk.tools.base_tool import BaseTool
 from google.adk.tools.mcp_tool.mcp_session_manager import SseConnectionParams
 from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
+from google.adk.tools.tool_context import ToolContext
 
 _allowed_path = os.path.dirname(os.path.abspath(__file__))
 
@@ -27,6 +31,20 @@
     headers={'Accept': 'text/event-stream'},
 )
 
+
+def after_tool_debug_callback(
+    tool: BaseTool,
+    args: dict[str, Any],
+    tool_context: ToolContext,
+    tool_response: dict[str, Any],
+) -> dict[str, Any] | None:
+  # pylint: disable=unused-argument
+  print(f'\n=== HTTP Debug Info (from Callback for {tool.name}) ===')
+  pprint.pprint(tool_context.custom_metadata.get('http_debug_info'))
+  print('====================================================\n')
+  return None
+
+
 root_agent = LlmAgent(
     name='enterprise_assistant',
     instruction=McpInstructionProvider(
@@ -57,4 +75,5 @@
             require_confirmation=True,
         )
     ],
+    after_tool_callback=after_tool_debug_callback,
 )

pyproject.toml

@@ -154,6 +154,7 @@ optional-dependencies.extensions = [
   "llama-index-embeddings-google-genai>=0.3",
   "llama-index-readers-file>=0.4",
   "lxml>=5.3",
+  "openai>=2.20,<3",
   "pypika>=0.50",
   "toolbox-adk>=1,<2",
 ]
@@ -195,6 +196,7 @@ optional-dependencies.test = [
   "anyio>=4.9,<5",
   "beautifulsoup4>=3.2.2",
   "crewai[tools]; python_version>='3.11' and python_version<'3.12'", # For CrewaiTool tests; chromadb/pypika fail on 3.12+
+  "docker>=7",                                                       # For ContainerCodeExecutor tests
   "e2b>=2,<3",
   "gepa>=0.1",
   "google-antigravity>=0.1,<0.2",
@@ -223,7 +225,7 @@ optional-dependencies.test = [
   "llama-index-readers-file>=0.4",
   "lxml>=5.3",
   "mcp>=1.24,<2",
-  "openai>=1.100.2",
+  "openai>=2.20,<3",
   "opentelemetry-exporter-gcp-logging>=1.9.0a0,<=1.12.0a0",
   "opentelemetry-exporter-gcp-monitoring>=1.9.0a0,<2",
   "opentelemetry-exporter-gcp-trace>=1.9,<2",

src/google/adk/agents/config_agent_utils.py

@@ -82,6 +82,31 @@ def _resolve_agent_class(agent_class: str) -> type[BaseAgent]:
   )
 
 
+_BLOCKED_YAML_KEYS = frozenset({"args"})
+_ENFORCE_YAML_KEY_DENYLIST = False
+
+
+def _set_enforce_yaml_key_denylist(value: bool) -> None:
+  global _ENFORCE_YAML_KEY_DENYLIST
+  _ENFORCE_YAML_KEY_DENYLIST = value
+
+
+def _check_config_for_blocked_keys(node: Any, filename: str) -> None:
+  """Recursively check if the configuration contains any blocked keys."""
+  if isinstance(node, dict):
+    for key, value in node.items():
+      if key in _BLOCKED_YAML_KEYS:
+        raise ValueError(
+            f"Blocked key {key!r} found in {filename!r}. "
+            f"The '{key}' field is not allowed in agent configurations "
+            "because it can execute arbitrary code."
+        )
+      _check_config_for_blocked_keys(value, filename)
+  elif isinstance(node, list):
+    for item in node:
+      _check_config_for_blocked_keys(item, filename)
+
+
 def _load_config_from_path(config_path: str) -> AgentConfig:
   """Load an agent's configuration from a YAML file.
 
@@ -102,6 +127,9 @@ def _load_config_from_path(config_path: str) -> AgentConfig:
   with open(config_path, "r", encoding="utf-8") as f:
     config_data = yaml.safe_load(f)
 
+  if _ENFORCE_YAML_KEY_DENYLIST:
+    _check_config_for_blocked_keys(config_data, config_path)
+
   return AgentConfig.model_validate(config_data)
 
 

src/google/adk/agents/context.py

@@ -229,6 +229,12 @@ def __init__(
     self._error: Exception | None = None
     self._error_node_path: str = ''
 
+  @property
+  def custom_metadata(self) -> dict[str, Any]:
+    """Returns the custom metadata dictionary."""
+    # pylint: disable=protected-access
+    return self._invocation_context._custom_metadata
+
   @property
   def function_call_id(self) -> str | None:
     """The function call id of the current tool call."""
@@ -446,10 +452,47 @@ async def run_node(
       use_sub_branch: If True, the dynamic node will be executed in a sub-branch
         to isolate its state and events from the main branch.
       override_branch: An optional branch to use instead of parent's branch.
+      override_isolation_scope: An optional isolation scope to use instead of
+        the parent's scope.
+      raise_on_wait: If True, raises NodeInterruptedError when the child node
+        is WAITING instead of returning None.
 
     Returns:
       The output of the dynamically executed node, once it finishes executing.
     """
+    return await self._run_node_internal(
+        node,
+        node_input,
+        use_as_output=use_as_output,
+        run_id=run_id,
+        use_sub_branch=use_sub_branch,
+        override_branch=override_branch,
+        override_isolation_scope=override_isolation_scope,
+        raise_on_wait=raise_on_wait,
+        resume_inputs=None,
+        return_ctx=False,
+    )
+
+  async def _run_node_internal(
+      self,
+      node: NodeLike,
+      node_input: Any = None,
+      *,
+      use_as_output: bool = False,
+      run_id: str | None = None,
+      use_sub_branch: bool = False,
+      override_branch: str | None = None,
+      override_isolation_scope: str | None = None,
+      raise_on_wait: bool = False,
+      return_ctx: bool = False,
+      resume_inputs: dict[str, Any] | None = None,
+  ) -> Any:
+    """Executes a node dynamically (Internal Orchestration API).
+
+    See public ``run_node`` for public argument details.
+    Additional internal args:
+      return_ctx: If True, returns the child's Context instead of its output.
+    """
 
     if not self._node_rerun_on_resume:
       raise ValueError(
@@ -532,7 +575,7 @@ async def run_node(
           and not child_ctx.actions.transfer_to_agent
       ):
         raise NodeInterruptedError()
-      return child_ctx.output
+      return child_ctx if return_ctx else child_ctx.output
 
     # Mode 2: Standalone execution (outside of workflow).
     # Run the node directly via NodeRunner.
@@ -544,6 +587,7 @@ async def run_node(
         override_branch=override_branch,
         override_isolation_scope=override_isolation_scope,
         run_id=run_id,
+        resume_inputs=resume_inputs,
     )
     if result.error:
       from ..workflow import _errors
@@ -562,7 +606,7 @@ async def run_node(
       from ..workflow._errors import NodeInterruptedError
 
       raise NodeInterruptedError()
-    return result.output
+    return result if return_ctx else result.output
 
   # ============================================================================
   # Artifact methods

src/google/adk/agents/invocation_context.py

@@ -259,6 +259,9 @@ class InvocationContext(BaseModel):
   credential_by_key: dict[str, AuthCredential] = Field(default_factory=dict)
   """The resolved credentials for this invocation, keyed by credential_key."""
 
+  _custom_metadata: dict[str, Any] = PrivateAttr(default_factory=dict)
+  """Custom metadata for attaching low-level execution telemetry."""
+
   _invocation_cost_manager: _InvocationCostManager = PrivateAttr(
       default_factory=_InvocationCostManager
   )

src/google/adk/cli/api_server.py

@@ -87,7 +87,6 @@
 from .cli_eval import EVAL_SESSION_ID_PREFIX
 from .utils import cleanup
 from .utils import common
-from .utils import envs
 from .utils.base_agent_loader import BaseAgentLoader
 from .utils.shared_value import SharedValue
 
@@ -569,6 +568,11 @@ def _setup_instrumentation_lib_if_installed():
       )
 
 
+def _get_app_basename(name: str) -> str:
+  """Returns the last segment of a dot-delimited app name."""
+  return name.split(".")[-1]
+
+
 class ApiServer:
   """Helper class for setting up and running the ADK web server on FastAPI.
 
@@ -657,7 +661,6 @@ async def get_runner_async(self, app_name: str) -> Runner:
       return self.runner_dict[app_name]
 
     # Create new runner
-    envs.load_dotenv_for_agent(os.path.basename(app_name), self.agents_dir)
     agent_or_app = self.agent_loader.load_agent(app_name)
 
     if self.default_llm_model:
@@ -712,7 +715,7 @@ def _wrap_loaded_agent(
             plugins=plugins,
         )
       return App(
-          name=app_name,
+          name=_get_app_basename(app_name),
           root_agent=agent_or_app,
           plugins=plugins,
       )
@@ -737,7 +740,7 @@ def _wrap_loaded_agent(
     if is_visual_builder_agent:
       object.__setattr__(agentic_app, "_is_visual_builder_app", True)
 
-    runner = self._create_runner(agentic_app)
+    runner = self._create_runner(agentic_app, app_name)
     self.runner_dict[app_name] = runner
     return runner
 
@@ -747,10 +750,11 @@ def _get_root_agent(self, agent_or_app: BaseAgent | App) -> BaseAgent:
       return agent_or_app.root_agent
     return agent_or_app
 
-  def _create_runner(self, agentic_app: App) -> Runner:
+  def _create_runner(self, agentic_app: App, app_name: str) -> Runner:
     """Create a runner with common services."""
     return Runner(
         app=agentic_app,
+        app_name=app_name,
         artifact_service=self.artifact_service,
         session_service=self.session_service,
         memory_service=self.memory_service,

src/google/adk/cli/dev_server.py

@@ -60,6 +60,8 @@
 from ..evaluation.eval_result import EvalSetResult
 from ..evaluation.eval_set import EvalSet
 from .api_server import ApiServer
+
+NESTED_APP_SEPARATOR = "."
 from .utils import common
 from .utils import evals
 from .utils.graph_serialization import serialize_app_info
@@ -157,6 +159,40 @@ class DevServer(ApiServer):
   endpoints for evaluation, debugging, and developer UI features.
   """
 
+  def _get_agent_dir(self, app_name: str) -> str:
+    """Resolves the agent directory and validates the app name to prevent path traversal."""
+    if not self.agents_dir:
+      raise HTTPException(
+          status_code=500, detail="Agents directory is not configured"
+      )
+    if not app_name:
+      raise HTTPException(status_code=400, detail="App name cannot be empty")
+
+    # Validate app_name structure (must be dot-separated identifiers)
+    parts = app_name.split(NESTED_APP_SEPARATOR)
+    for part in parts:
+      if not part or not part.isidentifier():
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                f"Invalid app name: {app_name!r}. App names must be valid "
+                "Python identifiers or paths separated by dots."
+            ),
+        )
+
+    # Resolve path
+    app_path = app_name.replace(NESTED_APP_SEPARATOR, "/")
+    agents_base = Path(self.agents_dir).resolve()
+    resolved_path = (agents_base / app_path).resolve()
+
+    if not resolved_path.is_relative_to(agents_base):
+      raise HTTPException(
+          status_code=400,
+          detail=f"Access denied: {app_name!r} is outside the agents directory",
+      )
+
+    return str(resolved_path)
+
   def _register_dev_endpoints(
       self,
       app: FastAPI,
@@ -502,7 +538,8 @@ async def get_app_info(app_name: str) -> Any:
         if self.agents_dir:
           import os
 
-          readme_path = os.path.join(self.agents_dir, app_name, "README.md")
+          agent_dir = self._get_agent_dir(app_name)
+          readme_path = os.path.join(agent_dir, "README.md")
           if os.path.exists(readme_path):
             try:
               with open(readme_path, "r", encoding="utf-8") as f:
@@ -557,7 +594,7 @@ async def get_app_info_image(
     @app.get("/dev/apps/{app_name}/tests")
     async def list_tests(app_name: str) -> list[str]:
       """Lists all test JSON files for the given app."""
-      agent_dir = os.path.join(self.agents_dir, app_name)
+      agent_dir = self._get_agent_dir(app_name)
       tests_dir = os.path.join(agent_dir, "tests")
       if not os.path.exists(tests_dir):
         return []
@@ -573,7 +610,7 @@ async def rebuild_app_tests(
         app_name: str, test_name: Optional[str] = None
     ) -> dict[str, str]:
       """Rebuilds tests for the app."""
-      agent_dir = os.path.join(self.agents_dir, app_name)
+      agent_dir = self._get_agent_dir(app_name)
 
       if test_name:
         if not test_name.endswith(".json"):
@@ -592,7 +629,7 @@ async def run_app_tests(
         app_name: str, test_name: Optional[str] = None
     ) -> StreamingResponse:
       """Runs tests and streams pytest output."""
-      agent_dir = os.path.join(self.agents_dir, app_name)
+      agent_dir = self._get_agent_dir(app_name)
 
       import subprocess
       import sys
@@ -656,7 +693,7 @@ async def create_test(
       """Creates or updates a test file from session data."""
       # Sanitize test_name to prevent directory traversal
       test_name = os.path.basename(test_name)
-      agent_dir = os.path.join(self.agents_dir, app_name)
+      agent_dir = self._get_agent_dir(app_name)
       tests_dir = os.path.join(agent_dir, "tests")
       os.makedirs(tests_dir, exist_ok=True)
 
@@ -673,7 +710,7 @@ async def create_test(
     @app.delete("/dev/apps/{app_name}/tests/{test_name}")
     async def delete_test(app_name: str, test_name: str) -> dict[str, str]:
       """Deletes a specific test file."""
-      agent_dir = os.path.join(self.agents_dir, app_name)
+      agent_dir = self._get_agent_dir(app_name)
       tests_dir = os.path.join(agent_dir, "tests")
 
       if not test_name.endswith(".json"):
@@ -690,7 +727,7 @@ async def delete_test(app_name: str, test_name: str) -> dict[str, str]:
     @app.get("/dev/apps/{app_name}/tests/{test_name}")
     async def get_test_content(app_name: str, test_name: str) -> dict[str, Any]:
       """Fetches the content of a specific test file."""
-      agent_dir = os.path.join(self.agents_dir, app_name)
+      agent_dir = self._get_agent_dir(app_name)
       tests_dir = os.path.join(agent_dir, "tests")
 
       if not test_name.endswith(".json"):