chore: Add single folder support in adk web

Change-Id: If593c0118bb44ec4a4dd836d8c5d5c4025591af2

Author: wyf7107

README.md

@@ -93,7 +93,7 @@ root_agent = Workflow(
 # Interactive CLI
 adk run path/to/my_agent
 
-# Web UI
+# Web UI (supports multi-agent directories or pointing directly to a single agent folder)
 adk web path/to/agents_dir
 ```
 

contributing/adk_project_overview_and_architecture.md

@@ -83,7 +83,7 @@ async def health_check():
 
 By default, the ADK API server expects an explicit application context in all requests (e.g., via the `/apps/{app_name}/...` path or in the payload body).
 
-However, if the environment variable `ADK_DEFAULT_APP_NAME` is set, the server will automatically resolve and fall back to the default application whenever a request lacks an explicit app name:
+However, if the environment variable `ADK_DEFAULT_APP_NAME` is set, or if the server is running in **single agent mode** (when pointing directly to a directory containing an agent instead of a directory of agents), the server will automatically resolve and fall back to that agent as the default application whenever a request lacks an explicit app name. In single agent mode, the local agent takes precedence over the `ADK_DEFAULT_APP_NAME` environment variable.
 
 - **URL Path-Rewriting (Production Endpoints)**: Requests to production endpoints that omit the `/apps/{app_name}` prefix (such as `/users/{user_id}/sessions` or `/app-info`) are automatically rewritten by an internal ASGI middleware to target the default application. (Note: `/dev` and `/builder` endpoints are excluded from rewriting).
 - **Agent Execution & Streaming**: Requests to `/run`, `/run_sse`, or `/run_live` that omit the `app_name` parameter in their payload body or query string will automatically resolve to the default application.

src/google/adk/cli/cli_tools_click.py

@@ -1774,8 +1774,9 @@ def cli_web(
 ):
   """Starts a FastAPI server with Web UI for agents.
 
-  AGENTS_DIR: The directory of agents, where each subdirectory is a single
-  agent, containing at least `__init__.py` and `agent.py` files.
+  AGENTS_DIR: The directory of agents (where each subdirectory is a single
+  agent containing `agent.py` or `root_agent.yaml` files) or a path pointing
+  directly to a single agent folder.
 
   Example:
 
@@ -1893,8 +1894,9 @@ def cli_api_server(
 ):
   """Starts a FastAPI server for agents.
 
-  AGENTS_DIR: The directory of agents, where each subdirectory is a single
-  agent, containing at least `__init__.py` and `agent.py` files.
+  AGENTS_DIR: The directory of agents (where each subdirectory is a single
+  agent containing `agent.py` or `root_agent.yaml` files) or a path pointing
+  directly to a single agent folder.
 
   Example:
 

src/google/adk/cli/fast_api.py

@@ -44,6 +44,7 @@
 from .service_registry import load_services_module
 from .utils import envs
 from .utils.agent_change_handler import AgentChangeEventHandler
+from .utils.agent_loader import is_single_agent_directory
 from .utils.base_agent_loader import BaseAgentLoader
 from .utils.service_factory import _create_task_store_from_options
 from .utils.service_factory import create_artifact_service_from_options
@@ -459,6 +460,16 @@ def get_fast_api_app(
 
     config_agent_utils._set_enforce_denylist(True)
 
+  # Detect single agent mode
+  agents_path = Path(agents_dir).resolve()
+  is_single_agent = is_single_agent_directory(agents_path)
+
+  original_agents_dir = agents_dir
+  single_agent_name = None
+  if is_single_agent:
+    single_agent_name = agents_path.name
+    agents_dir = str(agents_path.parent)
+
   # Set up eval managers.
   if eval_storage_uri:
     from .utils import evals
@@ -476,9 +487,11 @@ def get_fast_api_app(
     )
 
   # initialize Agent Loader if not passed as argument
+  this_module = sys.modules[__name__]
   if agent_loader is None:
-    this_module = sys.modules[__name__]
-    agent_loader = this_module.AgentLoader(agents_dir)
+    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)
 
   # Load services.py from agents_dir for custom service registration.
   load_services_module(agents_dir)
@@ -537,6 +550,10 @@ def get_fast_api_app(
       default_llm_model=default_llm_model,
   )
 
+  # In single agent mode, use that agent as the default app.
+  if is_single_agent:
+    adk_web_server.default_app_name = single_agent_name
+
   # Callbacks & other optional args for when constructing the FastAPI instance
   extra_fast_api_args = {}
 

src/google/adk/cli/utils/agent_loader.py

@@ -39,6 +39,16 @@
 
 logger = logging.getLogger("google_adk." + __name__)
 
+
+def is_single_agent_directory(path: Path | str) -> bool:
+  """Returns True if the directory contains a single agent configuration or file."""
+  p = Path(path).resolve()
+  return (
+      p.joinpath("agent.py").is_file()
+      or p.joinpath("root_agent.yaml").is_file()
+  )
+
+
 # Special agents directory for agents with names starting with double underscore
 SPECIAL_AGENTS_DIR = os.path.join(
     os.path.dirname(__file__), "..", "built_in_agents"
@@ -60,10 +70,36 @@ class AgentLoader(BaseAgentLoader):
   """
 
   def __init__(self, agents_dir: str):
-    self.agents_dir = str(Path(agents_dir))
+    agents_path = Path(agents_dir).resolve()
+    is_single_agent = is_single_agent_directory(agents_path)
+    if is_single_agent:
+      self._is_single_agent = True
+      self._single_agent_name = agents_path.name
+      self.agents_dir = str(agents_path.parent)
+    else:
+      self._is_single_agent = False
+      self._single_agent_name = None
+      self.agents_dir = str(agents_path)
+
     self._original_sys_path = None
     self._agent_cache: dict[str, Union[BaseAgent, App]] = {}
 
+  @property
+  def is_single_agent(self) -> bool:
+    """Returns True if the loader is in single agent mode."""
+    return self._is_single_agent
+
+  @property
+  def single_agent_name(self) -> Optional[str]:
+    """Returns the name of the agent in single agent mode."""
+    return self._single_agent_name
+
+  def _set_single_agent_mode(self, name: str, agents_dir: str) -> None:
+    """Internal method to force single agent mode. Use with care."""
+    self._is_single_agent = True
+    self._single_agent_name = name
+    self.agents_dir = agents_dir
+
   def _load_from_module_or_package(
       self, agent_name: str
   ) -> Optional[Union[BaseAgent, App]]:
@@ -204,6 +240,13 @@ def _validate_agent_name(self, agent_name: str) -> None:
       name_to_check = agent_name
       check_dir = self.agents_dir
 
+    if self._is_single_agent and not agent_name.startswith("__"):
+      if agent_name != self._single_agent_name:
+        raise ValueError(
+            f"Agent not found: {agent_name!r}. In single agent mode, only "
+            f"'{self._single_agent_name}' is accessible."
+        )
+
     if not self._VALID_AGENT_NAME_RE.match(name_to_check):
       raise ValueError(
           f"Invalid agent name: {agent_name!r}. Agent names must be valid"
@@ -368,6 +411,8 @@ def load_agent(self, agent_name: str) -> Union[BaseAgent, App]:
   @override
   def list_agents(self) -> list[str]:
     """Lists all agents available in the agent loader (sorted alphabetically)."""
+    if self._is_single_agent:
+      return [self._single_agent_name]
     base_path = Path.cwd() / self.agents_dir
     agent_names = [
         x

tests/unittests/cli/test_fast_api.py

@@ -2753,5 +2753,188 @@ def test_run_live_websocket_missing_app_name_raises_error(
   assert exc_info.value.code == 1008
 
 
+def test_is_single_agent_directory(tmp_path):
+  """Verify that is_single_agent_directory only identifies directories with agent.py or root_agent.yaml."""
+  from google.adk.cli.utils.agent_loader import is_single_agent_directory
+
+  # Directory with agent.py (should be identified as agent)
+  agent_py_dir = tmp_path / "agent_py_dir"
+  agent_py_dir.mkdir()
+  (agent_py_dir / "agent.py").write_text("root_agent = 'dummy'")
+  assert is_single_agent_directory(str(agent_py_dir)) is True
+
+  # Directory with root_agent.yaml (should be identified as agent)
+  yaml_dir = tmp_path / "yaml_dir"
+  yaml_dir.mkdir()
+  (yaml_dir / "root_agent.yaml").write_text("root_agent: dummy")
+  assert is_single_agent_directory(str(yaml_dir)) is True
+
+  # Normal directory or standard package with __init__.py only (should NOT be identified as agent)
+  normal_pkg = tmp_path / "normal_pkg"
+  normal_pkg.mkdir()
+  (normal_pkg / "__init__.py").write_text(
+      "from .app import App\nimport something"
+  )
+  assert is_single_agent_directory(str(normal_pkg)) is False
+
+
+def test_agent_loader_single_agent_mode(tmp_path):
+  """Verify that AgentLoader automatically detects and configures single agent mode."""
+  agent_folder = tmp_path / "my_test_agent"
+  agent_folder.mkdir()
+  (agent_folder / "agent.py").write_text("root_agent = 'dummy'")
+
+  loader = fast_api_module.AgentLoader(str(agent_folder))
+
+  assert loader._is_single_agent is True
+  assert loader._single_agent_name == "my_test_agent"
+  assert loader.agents_dir == str(tmp_path)
+  assert loader.list_agents() == ["my_test_agent"]
+
+
+def test_single_agent_mode_detection(
+    tmp_path,
+    mock_session_service,
+    mock_artifact_service,
+    mock_memory_service,
+    mock_eval_sets_manager,
+    mock_eval_set_results_manager,
+):
+  """Verify that pointing agents_dir to a single agent folder enables single agent mode."""
+  agent_folder = tmp_path / "my_only_agent"
+  agent_folder.mkdir()
+  (agent_folder / "agent.py").write_text("root_agent = None")
+
+  with (
+      patch.object(signal, "signal", autospec=True, return_value=None),
+      patch.object(
+          fast_api_module,
+          "create_session_service_from_options",
+          autospec=True,
+          return_value=mock_session_service,
+      ),
+      patch.object(
+          fast_api_module,
+          "create_artifact_service_from_options",
+          autospec=True,
+          return_value=mock_artifact_service,
+      ),
+      patch.object(
+          fast_api_module,
+          "create_memory_service_from_options",
+          autospec=True,
+          return_value=mock_memory_service,
+      ),
+      patch.object(
+          fast_api_module,
+          "LocalEvalSetsManager",
+          autospec=True,
+          return_value=mock_eval_sets_manager,
+      ),
+      patch.object(
+          fast_api_module,
+          "LocalEvalSetResultsManager",
+          autospec=True,
+          return_value=mock_eval_set_results_manager,
+      ),
+  ):
+    app = get_fast_api_app(
+        agents_dir=str(agent_folder),
+        web=True,
+        session_service_uri="",
+        artifact_service_uri="",
+        memory_service_uri="",
+        allow_origins=None,
+        a2a=False,
+        host="127.0.0.1",
+        port=8000,
+    )
+    client = TestClient(app)
+
+    response = client.get("/list-apps")
+    assert response.status_code == 200
+    assert response.json() == ["my_only_agent"]
+
+
+def test_single_agent_mode_sets_default_app(
+    tmp_path,
+    mock_session_service,
+    mock_artifact_service,
+    mock_memory_service,
+    mock_eval_sets_manager,
+    mock_eval_set_results_manager,
+    monkeypatch,
+):
+  """Verify that in single agent mode, the agent is used as default app."""
+  # Set environment variable to something else, but single mode should take precedence.
+  monkeypatch.setenv("ADK_DEFAULT_APP_NAME", "some_other_app")
+
+  agent_folder = tmp_path / "my_only_agent"
+  agent_folder.mkdir()
+  (agent_folder / "agent.py").write_text("root_agent = None")
+
+  # Setup session data in the in-memory service
+  async def setup_session():
+    await mock_session_service.create_session(
+        app_name="my_only_agent",
+        user_id="test_user",
+        session_id="test_session",
+        state={},
+    )
+
+  asyncio.run(setup_session())
+
+  with (
+      patch.object(signal, "signal", autospec=True, return_value=None),
+      patch.object(
+          fast_api_module,
+          "create_session_service_from_options",
+          autospec=True,
+          return_value=mock_session_service,
+      ),
+      patch.object(
+          fast_api_module,
+          "create_artifact_service_from_options",
+          autospec=True,
+          return_value=mock_artifact_service,
+      ),
+      patch.object(
+          fast_api_module,
+          "create_memory_service_from_options",
+          autospec=True,
+          return_value=mock_memory_service,
+      ),
+      patch.object(
+          fast_api_module,
+          "LocalEvalSetsManager",
+          autospec=True,
+          return_value=mock_eval_sets_manager,
+      ),
+      patch.object(
+          fast_api_module,
+          "LocalEvalSetResultsManager",
+          autospec=True,
+          return_value=mock_eval_set_results_manager,
+      ),
+  ):
+    app = get_fast_api_app(
+        agents_dir=str(agent_folder),
+        web=True,
+        session_service_uri="",
+        artifact_service_uri="",
+        memory_service_uri="",
+        allow_origins=None,
+        a2a=False,
+        host="127.0.0.1",
+        port=8000,
+    )
+    client = TestClient(app)
+
+    # Accessing /users/{user_id}/sessions/{session_id} should work because of rewrite
+    response = client.get("/users/test_user/sessions/test_session")
+    assert response.status_code == 200
+    assert response.json()["id"] == "test_session"
+
+
 if __name__ == "__main__":
   pytest.main(["-xvs", __file__])

tests/unittests/cli/utils/test_agent_loader.py

@@ -308,11 +308,21 @@ def test_agent_loader_with_mocked_windows_path(self, monkeypatch):
     del self
     windows_path = "C:\\Users\\dev\\agents\\"
 
+    class MockWindowsPath(PureWindowsPath):
+
+      def resolve(self):
+        return self
+
     with monkeypatch.context() as m:
       m.setattr(
           agent_loader_module,
           "Path",
-          lambda path_str: PureWindowsPath(path_str),
+          MockWindowsPath,
+      )
+      m.setattr(
+          agent_loader_module,
+          "is_single_agent_directory",
+          lambda path: False,
       )
       loader = AgentLoader(windows_path)
 
@@ -458,7 +468,7 @@ def __init__(self):
   def test_sys_path_modification(self):
     """Test that agents_dir is added to sys.path correctly."""
     with tempfile.TemporaryDirectory() as temp_dir:
-      temp_path = Path(temp_dir)
+      temp_path = Path(temp_dir).resolve()
 
       # Create agent
       self.create_agent_structure(temp_path, "path_agent", "module")