Fix Windows Path Handling and Normalize Cross-Platform Path Resolution in AgentLoader

[p-kris10]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: Agent Config : Sub Agents not working on Windows 11 #3062
• Related: Main Issue: ADK Windows platform issues #3306

Problem:
On Windows, the ADK CLI failed to correctly resolve agent directories due to inconsistent use of hard-coded POSIX separators / and manual string slicing of paths. This caused incorrect path construction in both functional logic and error messages.
Specifically, users encountered errors such as:

ValueError: No root_agent found for 'my_agent2'. Searched in 
'my_agent2.agent.root_agent', 'my_agent2.root_agent' and 
'my_agent2/root_agent.yaml'. Ensure 'D:<folder path>\my_agent2' is structured correctly...

Primary issues included:

• Hardcoded / separators in path logic and error messages
• Fragile path slicing using rsplit("/", 1)
• Incorrect path formatting on Windows
• Mixed separators (/ and \) breaking directory resolution

Solution:
This PR standardizes path handling across the ADK CLI to ensure true cross-platform compatibility.

Key improvements:

• Replaced manual string slicing with os.path.dirname()
• Normalized agents_dir using pathlib.Path for consistent behavior on Windows, macOS, and Linux
• Updated error messages to use os.sep and os.path.join() for correct OS-native formatting
• Ensured mixed separators (e.g., "C:\\Dev/adk\\subdir/") no longer break resolution
• Added comprehensive tests covering Windows-style paths, mixed separators, and normalized path expectations

Testing Plan

• Added new tests:
  • Mock-based regression test to catch Windows path handling bugs on Unix CI
  • Error message verification for consistent os.sep usage
  • Functional test for resolve_agent_reference
• All existing tests pass alongside new ones

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Manual End-to-End (E2E) Tests:

Setup the subagent from yaml example from here on a windows environment and run adk web then ask the question what is pi?. The root agent should transfer to math_tutor agent without breaking, the code used to break earlier before the fix.

Before :
No output in web ui and following in the terminal

After the fix :

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

Add any other context or screenshots about the feature request here.

[gemini-code-assist]

Summary of Changes

Hello @p-kris10, 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 resolves critical path resolution issues within the ADK CLI, particularly on Windows, by implementing a standardized and robust approach to path handling. It replaces error-prone string manipulations with Python's built-in os.path and pathlib.Path utilities, ensuring consistent agent directory resolution and accurate error reporting across different operating systems. The changes significantly improve the reliability and cross-platform compatibility of the ADK CLI.

Highlights

• Cross-Platform Path Handling: The pull request standardizes path handling across the ADK CLI to ensure true cross-platform compatibility, specifically addressing issues on Windows where inconsistent use of POSIX separators and fragile string slicing led to incorrect path construction.
• Improved Path Resolution Logic: Manual string slicing (rsplit("/", 1)) has been replaced with os.path.dirname() for more robust directory extraction. The agents_dir is now normalized using pathlib.Path for consistent behavior across Windows, macOS, and Linux.
• Enhanced Error Messages: Error messages have been updated to use os.sep and os.path.join() for correct OS-native path formatting, providing clearer and more accurate information to users.
• Robustness to Mixed Separators: The changes ensure that mixed path separators (e.g., C:\Dev/adk\subdir/) no longer break directory resolution, improving the resilience of the path handling logic.
• Comprehensive Testing: New tests have been added to cover Windows-style path normalization on Unix environments, handling of mixed / and \ separators, and verification that error messages include correctly joined paths. All existing tests continue to pass.

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. ↩

[gemini-code-assist]

Code Review

This pull request effectively addresses cross-platform path handling issues, particularly for Windows environments, by replacing manual string manipulation with os.path and pathlib utilities. The changes in config_agent_utils.py and agent_loader.py are solid improvements for robustness. The added tests are a great step, but I've identified an issue where one of the new tests will fail on non-Windows platforms and another has a weak assertion. I've provided a suggestion to combine and improve these tests to be platform-aware and more robust.

[p-kris10]

@Jacksunwei can you take a look at this

[ryanaiagent]

Hi @p-kris10 , Thank you for your contribution! We appreciate you taking the time to submit this pull request. Your PR has been received by the team and is currently under review. We will provide feedback as soon as we have an update to share.

[ryanaiagent]

Hi @DeanChensj , can you please review this.