From d73a5c60e28e6f44d6fbf985132aad4adec0c6c0 Mon Sep 17 00:00:00 2001 From: Jaroslav Pantsjoha Date: Thu, 16 Oct 2025 10:29:39 +0100 Subject: [PATCH 1/3] fix(cli): improve error message when adk web is run in wrong directory Enhances the AgentLoader error message to help users who run 'adk web' from incorrect directories. This issue affected multiple teams during internal workshops when getting started with ADK. Changes: - Adds visual directory structure diagram to error message - Includes explicit 'adk web ' usage example - Detects when user is inside an agent directory and provides targeted hint to run 'adk web .' from parent directory Fixes #3195 --- src/google/adk/cli/utils/agent_loader.py | 25 +++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/src/google/adk/cli/utils/agent_loader.py b/src/google/adk/cli/utils/agent_loader.py index d5cb08cf0e..815ea58d79 100644 --- a/src/google/adk/cli/utils/agent_loader.py +++ b/src/google/adk/cli/utils/agent_loader.py @@ -224,13 +224,32 @@ def _perform_load(self, agent_name: str) -> Union[BaseAgent, App]: return root_agent # If no root_agent was found by any pattern + # Check if user might be in the wrong directory + hint = "" + if os.path.isfile(os.path.join(agents_dir, "agent.py")) or os.path.isfile( + os.path.join(agents_dir, "root_agent.yaml") + ): + hint = ( + "\n\nHINT: It looks like you might be running 'adk web' from inside an" + " agent directory. Try running 'adk web .' from the parent directory" + " that contains your agent folder, not from within the agent folder" + " itself." + ) + raise ValueError( f"No root_agent found for '{agent_name}'. Searched in" f" '{actual_agent_name}.agent.root_agent'," f" '{actual_agent_name}.root_agent' and" - f" '{actual_agent_name}/root_agent.yaml'. Ensure" - f" '{agents_dir}/{actual_agent_name}' is structured correctly, an .env" - " file can be loaded if present, and a root_agent is exposed." + f" '{actual_agent_name}/root_agent.yaml'." + f"\n\nExpected directory structure:" + f"\n /" + f"\n {actual_agent_name}/" + f"\n agent.py (with root_agent) OR" + f"\n root_agent.yaml" + f"\n\nThen run: adk web " + f"\n\nEnsure '{agents_dir}/{actual_agent_name}' is structured correctly," + " an .env file can be loaded if present, and a root_agent is exposed." + f"{hint}" ) def _ensure_app_name_matches( From becc786e0797d2bbfb60862938abbca77e77628d Mon Sep 17 00:00:00 2001 From: Jaroslav Pantsjoha Date: Thu, 16 Oct 2025 11:30:21 +0100 Subject: [PATCH 2/3] refactor: use pathlib.Path for file existence checks Applies Gemini Code Assist bot suggestion to use pathlib.Path instead of os.path for improved readability and platform-agnostic path handling. Changes: - Replace os.path.isfile(os.path.join(...)) with Path.joinpath(...).is_file() - More concise and modern Python idiom - No semantic changes, maintains identical behavior --- src/google/adk/cli/utils/agent_loader.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/google/adk/cli/utils/agent_loader.py b/src/google/adk/cli/utils/agent_loader.py index 815ea58d79..5e94df092c 100644 --- a/src/google/adk/cli/utils/agent_loader.py +++ b/src/google/adk/cli/utils/agent_loader.py @@ -226,9 +226,10 @@ def _perform_load(self, agent_name: str) -> Union[BaseAgent, App]: # If no root_agent was found by any pattern # Check if user might be in the wrong directory hint = "" - if os.path.isfile(os.path.join(agents_dir, "agent.py")) or os.path.isfile( - os.path.join(agents_dir, "root_agent.yaml") - ): + agents_path = Path(agents_dir) + if agents_path.joinpath("agent.py").is_file() or agents_path.joinpath( + "root_agent.yaml" + ).is_file(): hint = ( "\n\nHINT: It looks like you might be running 'adk web' from inside an" " agent directory. Try running 'adk web .' from the parent directory" From 18b6f6dd63752dc3cae799da0f3095ad26702390 Mon Sep 17 00:00:00 2001 From: Jaroslav Pantsjoha Date: Sat, 18 Oct 2025 13:21:36 +0100 Subject: [PATCH 3/3] fix(cli): Apply pyink formatting to agent_loader.py Reformatted code to comply with pyink style guide: - Line length limits enforced - Multi-line conditional formatting improved - String concatenation formatting optimized Addresses lint check failure in PR #3196. --- src/google/adk/cli/utils/agent_loader.py | 31 +++++++++++------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/src/google/adk/cli/utils/agent_loader.py b/src/google/adk/cli/utils/agent_loader.py index 5e94df092c..6ea3fc3626 100644 --- a/src/google/adk/cli/utils/agent_loader.py +++ b/src/google/adk/cli/utils/agent_loader.py @@ -227,30 +227,27 @@ def _perform_load(self, agent_name: str) -> Union[BaseAgent, App]: # Check if user might be in the wrong directory hint = "" agents_path = Path(agents_dir) - if agents_path.joinpath("agent.py").is_file() or agents_path.joinpath( - "root_agent.yaml" - ).is_file(): + if ( + agents_path.joinpath("agent.py").is_file() + or agents_path.joinpath("root_agent.yaml").is_file() + ): hint = ( - "\n\nHINT: It looks like you might be running 'adk web' from inside an" - " agent directory. Try running 'adk web .' from the parent directory" - " that contains your agent folder, not from within the agent folder" - " itself." + "\n\nHINT: It looks like you might be running 'adk web' from inside" + " an agent directory. Try running 'adk web .' from the parent" + " directory that contains your agent folder, not from within the" + " agent folder itself." ) raise ValueError( f"No root_agent found for '{agent_name}'. Searched in" f" '{actual_agent_name}.agent.root_agent'," f" '{actual_agent_name}.root_agent' and" - f" '{actual_agent_name}/root_agent.yaml'." - f"\n\nExpected directory structure:" - f"\n /" - f"\n {actual_agent_name}/" - f"\n agent.py (with root_agent) OR" - f"\n root_agent.yaml" - f"\n\nThen run: adk web " - f"\n\nEnsure '{agents_dir}/{actual_agent_name}' is structured correctly," - " an .env file can be loaded if present, and a root_agent is exposed." - f"{hint}" + f" '{actual_agent_name}/root_agent.yaml'.\n\nExpected directory" + f" structure:\n /\n {actual_agent_name}/\n " + " agent.py (with root_agent) OR\n root_agent.yaml\n\nThen run:" + f" adk web \n\nEnsure '{agents_dir}/{actual_agent_name}' is" + " structured correctly, an .env file can be loaded if present, and a" + f" root_agent is exposed.{hint}" ) def _ensure_app_name_matches(