Skip to content

Conversation

tommyhutcheson
Copy link

@tommyhutcheson tommyhutcheson commented Sep 22, 2025

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.

@adk-bot
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
@adk-bot adk-bot requested a review from Jacksunwei September 22, 2025 18:11
@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
tommyhutcheson and others added 4 commits September 27, 2025 19:29
…lAgent similar to what exists in LoopAgent. Here's what was accomplished
…n the agent terminates the sequence immediately preventing subsequent agents from running.
@tommyhutcheson
Copy link
Author

tommyhutcheson commented Oct 19, 2025

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

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

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add SequentialAgent early exit mechanism

5 participants