feat: refactor ADK CLI server to support nested agents in dev mode and simplify API

This change introduces `NestedAgentLoader` for the `adk web` command, enabling recursive discovery of agents within subdirectories and using dot-separated names (e.g., `folder.app`). The production `adk api_server` continues to use the flat `AgentLoader`

Co-authored-by: Yifan Wang <wanyif@google.com>
PiperOrigin-RevId: 938188643

Author: wyf7107

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:

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"):

src/google/adk/cli/fast_api.py

@@ -80,6 +80,7 @@ class _QueryRequest(BaseModel):
 
 _LAZY_SERVICE_IMPORTS: dict[str, str] = {
     "AgentLoader": ".utils.agent_loader",
+    "NestedAgentLoader": ".utils._nested_agent_loader",
     "LocalEvalSetResultsManager": "..evaluation.local_eval_set_results_manager",
     "LocalEvalSetsManager": "..evaluation.local_eval_sets_manager",
 }
@@ -514,7 +515,10 @@ def get_fast_api_app(
   # initialize Agent Loader if not passed as argument
   this_module = sys.modules[__name__]
   if agent_loader is None:
-    agent_loader = this_module.AgentLoader(original_agents_dir)
+    if web:
+      agent_loader = this_module.NestedAgentLoader(original_agents_dir)
+    else:
+      agent_loader = this_module.AgentLoader(original_agents_dir)
   elif is_single_agent and isinstance(agent_loader, this_module.AgentLoader):
     agent_loader._set_single_agent_mode(single_agent_name, agents_dir)