feat: Add early exit mechanism to SequentialAgent using escalate action

[tommyhutcheson]

Summary

Implements early exit mechanism for SequentialAgent using escalate action to resolve #3000

Documentation PR: google/adk-docs#707

Implementation

New Tool:

• Created exit_sequence tool that sets escalate=True and skip_summarization=True
• Detailed docstring with practical use cases and examples
• Follows the same pattern as exit_loop for consistency

SequentialAgent Updates:

• Added escalate check in _run_async_impl to enable early termination
• Added escalate check in _run_live_impl for feature parity across modes
• Inline comments documenting escalate vs pause_invocation precedence

Test Coverage:

• test_run_async_with_escalate_action - Early exit when first agent escalates
• test_run_async_escalate_action_in_middle - Escalation in middle of sequence
• test_run_async_no_escalate_action - Normal operation without escalation
• test_run_live_with_escalate_action - Live mode escalate support

Behaviour

When a sub-agent calls exit_sequence(), the SequentialAgent terminates immediately, preventing both:

• Subsequent events from the current sub-agent
• All remaining sub-agents in the sequence

This works consistently in both async and live streaming modes.

Key Features

• Event-level granularity - Stops immediately after the escalating event
• Consistent API - Follows LoopAgent's exit_loop pattern
• Mode parity - Supported in both async and live modes
• Backwards compatible - Existing SequentialAgent workflows unchanged

Testing

All 9 tests passing:

• 5 existing tests (backwards compatibility verified)
• 4 new tests for escalate functionality

Fixes #3000

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

[tommyhutcheson]

Hey @boyangsvl @hangfei @Jacksunwei I have updated the PR to include exit_sequence support to both the _run_async_impl and _run_live_impl by implementing the escalate check in async and live modes. docs updated here too google/adk-docs#707
When possible could I get a review on this chagne.
Thank you Tommy