feat: Add development mode with auto-reload (--dev flag)

[notnotdurgesh]

Link to Issue or Description of Change

1. Link to an existing issue : Add Development Mode with Auto-Reload for Agent Development (--dev flag) #3679

Problem

Currently, when developing agents with ADK, developers need to manually restart the agent process every time they make changes to Python or YAML files. This creates a poor development experience, especially when iterating on agent logic, tools, or configuration. Developers have to stop the running agent, make code changes, restart the agent, and resume testing - a slow and disruptive workflow similar to how web developers had to manually restart servers before tools like nodemon existed.

Solution

Add a --dev flag to the adk run command that enables development mode with automatic agent reloading. When enabled, the system monitors the agent directory for changes to .py and .yaml files, automatically reloads the agent when files are modified or created, provides visual feedback when auto-reload is active, and continues the existing session context after reload. This improves the developer experience by reducing friction and enabling faster iteration cycles.

Implementation Details

• Added --dev flag to adk run command in cli_tools_click.py.
• Implemented DevModeChangeHandler class in cli.py using the existing watchdog library dependency.
• Added file monitoring for .py and .yaml files in agent directories with recursive watching.
• Integrated auto-reload functionality with existing CLI infrastructure using threading events.
• Provides visual feedback with "Auto-reload enabled - watching for file changes..." message.

Usage

adk run --dev path/to/my_agent

Testing Plan

Unit Tests

• I have added unit tests for the new DevModeChangeHandler class functionality.
• All existing unit tests pass locally.
• New tests verify file change detection and reload signaling.

Pytest results summary:

collected 30 items / 25 deselected / 5 selected                                                         

tests/unittests/cli/utils/test_cli_tools_click.py::test_dev_mode_change_handler_py_file PASSED    [ 20%]
tests/unittests/cli/utils/test_cli_tools_click.py::test_dev_mode_change_handler_yaml_file PASSED  [ 40%]
tests/unittests/cli/utils/test_cli_tools_click.py::test_dev_mode_change_handler_ignores_non_matching_files PASSED [ 60%]
tests/unittests/cli/utils/test_cli_tools_click.py::test_dev_mode_change_handler_ignores_directories PASSED [ 80%]
tests/unittests/cli/utils/test_cli_tools_click.py::test_dev_mode_change_handler_on_created PASSED [100%]
============================= 5 passed, 25 deselected, 1 warning in 2.95s ============================== 

Manual End-to-End (E2E) Tests

• Setup: Install ADK in development mode (pip install -e .).
• Test dev mode activation: Run adk run --dev contributing/samples/quickstart.
  • Expected: See "Auto-reload enabled - watching for file changes..." message.
• Test file change detection: Modify agent.py while agent is running.
  • Expected: Agent detects change and reloads automatically.
• Test session preservation: Interact with agent, make changes, verify session context is maintained.
• Test normal mode: Run adk run contributing/samples/quickstart (without --dev flag).
  • Expected: No auto-reload functionality, normal operation.

Test Logs:

2025-11-23 21:13:31 INFO Auto-reload enabled - watching for file changes...
2025-11-23 21:13:45 INFO Change detected in agents directory: /path/to/agent.py
2025-11-23 21:13:45 INFO Agent reloaded successfully, continuing session...

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.

Code Review Comments

• Added comprehensive docstrings for DevModeChangeHandler class and methods.
• Used existing watchdog dependency (no new dependencies added).
• Followed ADK's threading patterns and error handling conventions.
• Integrated cleanly with existing CLI argument parsing and session management.
• No breaking changes to existing adk run functionality.

Additional Context

Technical Implementation

• The DevModeChangeHandler class extends watchdog.events.FileSystemEventHandler.
• Uses threading.Event for thread-safe reload signaling between watchdog thread and main CLI thread.
• Monitors on_modified and on_created events for .py and .yaml files only.
• Recursively watches the agent directory to catch changes in subdirectories.
• Gracefully handles observer startup/shutdown in CLI lifecycle.

Performance Considerations

• File watching is lightweight and only active during development.
• Uses event-driven approach instead of polling for efficiency.
• Minimal memory footprint with single background thread.
• No impact on production agent performance.

Compatibility

• Works on all platforms supported by watchdog (Windows, macOS, Linux).
• Compatible with existing session persistence and agent loading mechanisms.
• No conflicts with other CLI flags or functionality.

Future Enhancements

• Could be extended to support custom file patterns via additional flags.
• Could add configuration options for reload debounce timing.
• Could integrate with IDE extensions for enhanced development experience.

[gemini-code-assist]

Summary of Changes

Hello @notnotdurgesh, 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 significantly enhances the developer experience for ADK agents by introducing a development mode with automatic agent reloading. Previously, developers had to manually restart their agents after every code or configuration change, leading to a slow and disruptive workflow. The new --dev flag automates this process, allowing for faster iteration and a more seamless development cycle by monitoring relevant files and reloading the agent on changes while preserving the session context.

Highlights

• Development Mode Flag: Introduced a --dev flag for the adk run command to enable a development mode.
• Automatic Agent Reloading: Implemented automatic agent reloading when .py or .yaml files within the agent's directory are modified or created.
• File System Monitoring: Utilized the watchdog library and threading for efficient, event-driven file system monitoring.
• Session Context Preservation: Ensures that the existing session context is preserved across reloads, significantly improving the iterative development experience.
• User Feedback: Provides clear visual feedback to the user when auto-reload is enabled and when an agent reload occurs.

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 introduces a --dev flag for adk run to enable an auto-reload development mode, which is a great enhancement for the developer experience. The implementation using watchdog is appropriate, and the feature is well-covered by new unit tests. My review includes a couple of minor suggestions to improve code maintainability and adhere to Python's standard style conventions.