feat: Add early exit mechanism to SequentialAgent using escalate action

[tommyhutcheson]

Summary

I have implemented an early exit mechanism for SequentialAgent similar to what exists in LoopAgent to resolve #3000

Documentation PR - google/adk-docs#707

• post rebase from main if escalate is true in the sequential_agent then the agent terminates the sequence immediately preventing subsequent agents from running.

Here's what was accomplished:

Implementation Complete

1. Created exit_sequence tool (adk-python/src/google/adk/tools/exit_sequence_tool.py)
   - New tool function that sets escalate=True and skip_summarization=True
   - Proper docstring explaining when to use the tool
   - Follows the same pattern as exit_loop tool
2. Updated SequentialAgent (adk-python/src/google/adk/agents/sequential_agent.py)
   - Modified _run_async_impl to check for event.actions.escalate after each event
   - Added early termination logic with break and return statements
   - Prevents subsequent agents from executing when escalation is triggered
3. Exported new tool adk-python/src/google/adk/tools/init.py)
   - Added import for exit_sequence
   - Added to all list for public API
4. Comprehensive test suite (adk-python/tests/unittests/agents/test_sequential_agent.py)
   - test_run_async_with_escalate_action: Tests early exit when first agent escalates
   - test_run_async_escalate_action_in_middle: Tests escalation in middle of sequence
   - test_run_async_no_escalate_action: Ensures normal operation when no escalation
   - All tests passing

Key Features

• Early Termination: Agents can call exit_sequence to stop the sequential execution
• Event-Level Granularity: Stops immediately after the escalating event, not after the entire agent
• Consistent API: Follows the same pattern as LoopAgent for familiar developer experience
• Backwards Compatible: Existing SequentialAgent behaviour unchanged when no escalation occurs

[gemini-code-assist]

Summary of Changes

Hello @tommyhutcheson, 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 introduces a critical early exit mechanism for the SequentialAgent, aligning its functionality with the existing LoopAgent. This enhancement enables a sequence of agents to terminate prematurely if any sub-agent within the workflow triggers an 'escalate' action, thereby preventing unnecessary execution of subsequent agents. This provides improved control over agent workflows, especially in situations where a definitive or blocking condition is met, leading to increased efficiency and responsiveness. The changes are fully tested and designed to maintain backward compatibility.

Highlights

• New exit_sequence Tool: A new tool, exit_sequence_tool.py, has been created. This tool allows agents to signal an early exit from a sequential workflow by setting escalate=True and skip_summarization=True on the ToolContext.
• SequentialAgent Early Termination: The _run_async_impl method within SequentialAgent has been modified to check for the escalate action after each sub-agent's event. If event.actions.escalate is true, the sequential execution terminates immediately, preventing subsequent agents from running.
• Tool Export: The newly created exit_sequence tool has been exported and made publicly accessible by adding it to the __all__ list in adk-python/src/google/adk/tools/__init__.py.
• Comprehensive Test Coverage: New unit tests have been added to test_sequential_agent.py to thoroughly validate the early exit mechanism. These tests cover scenarios where escalation occurs at the beginning of a sequence, in the middle, and also confirm normal operation when no escalation is triggered.

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

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 @tommyhutcheson, thank you for your contribution!

To help us track and review this new feature, could you please create and associate a GitHub issue with this PR?

Additionally, since this change introduces a new user-facing tool (exit_sequence), please consider if an update to the user documentation is needed. If so, please open a PR in the adk-docs repository.

This information will help reviewers to review your PR more efficiently. Thanks!

[gemini-code-assist]

Code Review

This pull request introduces an early exit mechanism for SequentialAgent, which is a great feature for controlling agent flow. The implementation is clean and the new exit_sequence tool is well-defined. The tests are also comprehensive and cover the main scenarios.

I have a couple of suggestions for improvement:

• In sequential_agent.py, the early exit logic can be simplified for better readability.
• In test_sequential_agent.py, one of the assertions is a bit confusing and could be removed to improve test clarity.

Additionally, I noticed that the early exit mechanism has been implemented for _run_async_impl, but it seems to be missing from _run_live_impl. For consistency and to fully implement the feature, you should consider adding similar logic to _run_live_impl to handle the escalate action and prevent subsequent agents from running in a live session as well.

Overall, this is a solid contribution. My comments are aimed at refining the implementation.