Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

feat: Add early exit mechanism to SequentialAgent using escalate action #2999

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tommyhutcheson wants to merge 2 commits into google:main
base: main
Choose a base branch
Loading
from tommyhutcheson:feat-Add-early-exit-mechanism-to-SequentialAgent-using-escalate-action

Conversation

@tommyhutcheson
Copy link

@tommyhutcheson tommyhutcheson commented Sep 22, 2025 •
edited
Loading

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

Copy link

Summary of Changes

Hello @tommyhutcheson, I'm Gemini Code Assist1 ! 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. ↩

mason-oh-querypie reacted with thumbs up emoji

Copy link
Collaborator

adk-bot commented Sep 22, 2025

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!

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@adk-bot adk-bot added bot triaged core [Component] This issue is related to the core interface and implementation labels Sep 22, 2025
@tommyhutcheson tommyhutcheson force-pushed the feat-Add-early-exit-mechanism-to-SequentialAgent-using-escalate-action branch from b7446cd to bee8029 Compare September 27, 2025 18:24
Copy link
Author

tommyhutcheson commented Oct 19, 2025 •
edited
Loading

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

@tommyhutcheson tommyhutcheson force-pushed the feat-Add-early-exit-mechanism-to-SequentialAgent-using-escalate-action branch from 7916dea to 2a420e9 Compare October 23, 2025 17:58
@tommyhutcheson tommyhutcheson force-pushed the feat-Add-early-exit-mechanism-to-SequentialAgent-using-escalate-action branch from 2a420e9 to 7e061b2 Compare October 23, 2025 18:16
Copy link
Collaborator

Hi @tommyhutcheson , can we achieve the same goal with a LoopAgent that has max_iteration=1?

Copy link
Author

Hi @tommyhutcheson , can we achieve the same goal with a LoopAgent that has max_iteration=1?

Hey @DeanChensj I thought we might have had a workaround there! but unfortunately not - here's the issue:

Current Structure:
SequentialAgent (parent)
├── agent_1
├── LoopAgent (validation loop) ← calls exit_loop() when validation is successfull
├── agent_2
└── agent_3

The Problem:
When the nested LoopAgent calls exit_loop(), it sets escalate=True. If I change the parent to
LoopAgent(max_iterations=1), the escalate flag propagates upward and exits the parent immediately -
skipping agent_2 and agent_3.

Is this the expected behaviour for nested escalate flags, or is there a different pattern I should use?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Jacksunwei Jacksunwei Awaiting requested review from Jacksunwei

@TheeraphatStudent TheeraphatStudent Awaiting requested review from TheeraphatStudent

1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

core [Component] This issue is related to the core interface and implementation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add SequentialAgent early exit mechanism

AltStyle によって変換されたページ (->オリジナル) /