Merge branch 'main' into fix/2237-infer-agent-card

Author: rohityan

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/agents/remote_a2a_agent.py

@@ -508,6 +508,8 @@ async def _handle_a2a_response(
           event = convert_a2a_task_to_event(
               task, self.name, ctx, self._a2a_part_converter
           )
+          if not event:
+            return None
           # for streaming task, we update the event with the task status.
           # We update the event as Thought updates.
           if (
@@ -555,6 +557,8 @@ async def _handle_a2a_response(
           event = convert_a2a_task_to_event(
               task, self.name, ctx, self._a2a_part_converter
           )
+          if not event:
+            return None
         else:
           # This is a streaming update without a message (e.g. status change)
           # or a partial artifact update. We don't emit an event for these

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,