fix(cli): Improve error message when adk web is run in wrong directory

[jpantsjoha]

Summary

Enhances the AgentLoader error message to provide clear guidance when users run adk web from incorrect directories.

Motivation

During internal workshops, multiple teams encountered confusion when starting adk web from the wrong directory. This often happened when:

• Running adk web my_agent/ instead of adk web .
• Being inside an agent directory when executing the command
• Configuring incorrect start paths during development

Changes

• Smart detection: Checks if agent.py or root_agent.yaml exists in the current directory
• Visual diagram: Shows expected directory structure with actual agent name
• Explicit command: Includes adk web <agents_dir> usage example
• Conditional hint: Provides targeted guidance when user is detected to be inside an agent directory

Example Error Message

Before

ValueError: No root_agent found for 'my_agent'. Searched in 'my_agent.agent.root_agent', 'my_agent.root_agent' and 'my_agent/root_agent.yaml'. Ensure 'path/my_agent' is structured correctly, an .env file can be loaded if present, and a root_agent is exposed.

After

ValueError: No root_agent found for 'my_agent'. Searched in 'my_agent.agent.root_agent', 'my_agent.root_agent' and 'my_agent/root_agent.yaml'.

Expected directory structure:
  <agents_dir>/
    my_agent/
      agent.py (with root_agent) OR
      root_agent.yaml

Then run: adk web <agents_dir>

Ensure 'path/my_agent' is structured correctly, an .env file can be loaded if present, and a root_agent is exposed.

HINT: 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.

Testing

• ✅ Existing unit tests pass (17/22, with 5 pre-existing failures unrelated to this change)
• ✅ test_agent_not_found_error passes, confirming error message enhancement works correctly
• ✅ Code follows ADK contribution guidelines

Type

• Bug fix (improved error messaging)
• Feature
• Breaking change
• Documentation

Related

Fixes #3195

---

Tags: #non-breaking

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @jpantsjoha, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses user confusion experienced during workshops by enhancing the error message displayed when the adk web command is run from an incorrect directory. The changes introduce intelligent detection of common misconfigurations, provide a clear visual guide for the expected directory structure, and offer a specific command example, along with a contextual hint to help users quickly resolve path-related issues.

Highlights

• Enhanced Error Messaging: The AgentLoader now provides a significantly improved error message when adk web is executed from an incorrect directory, offering clearer guidance to users.
• Smart Directory Detection: The system now checks for the presence of agent.py or root_agent.yaml in the current directory to intelligently determine if the user might be running the command from within an agent's directory.
• Visual Guidance and Command Example: The error message includes a visual diagram of the expected directory structure and an explicit example of the correct command to run (adk web <agents_dir>).
• Contextual Hint: A conditional hint is provided when the system detects that the user is likely running adk web from inside an agent directory, guiding them to execute it from the parent directory instead.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[adk-bot]

Response from ADK Triaging Agent

Hello @jpantsjoha, thank you for your contribution!

Before we can merge this PR, you need to sign the Contributor License Agreement (CLA). You can find more information at https://cla.developers.google.com/.

Once you have signed the CLA, the status check will be updated, and we can proceed with the review.

[gemini-code-assist]

Code Review

This pull request improves the error message when adk web is run from an incorrect directory. The changes add a smart detection mechanism to check for common mistakes, such as running the command from within an agent directory, and provide a clear, actionable hint to the user. The error message now also includes a visual diagram of the expected directory structure. My review focuses on improving the code's readability and modernizing the path handling.

[adk-bot]

Response from ADK Triaging Agent

Hello @jpantsjoha, thank you for your contribution!

It looks like a few of the status checks are failing (pyink-check, test). Before we can proceed with a review, all status checks need to pass.

Could you please run the auto-formatter and the unit tests locally to fix these issues?

• For the pyink-check failure, please run ./autoformat.sh.
• For the test failures, please run pytest ./tests/unittests to identify and fix the issues.

You can find more details in our contribution guidelines.

Let us know if you have any questions. Thanks!

[DeanChensj]

Could you fix the lint error by running ./autoformat.sh?

[GWeale]

This has been merged! Thank you for your contribution