docs(plugins): correct before_run_callback flow control behavior#1822
Open
yana-gi wants to merge 1 commit into
Open
docs(plugins): correct before_run_callback flow control behavior#1822yana-gi wants to merge 1 commit into
yana-gi wants to merge 1 commit into
Conversation
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
The "Runner start callbacks" section described `before_run_callback` as
returning a `types.Content` to "replace the user's original message". That is
actually the behavior of `on_user_message_callback`; the text (including the
"Purpose" line) was duplicated from that section.
In the implementation, returning a `Content` from `before_run_callback` halts
the run: the Runner yields it as an early-exit event and skips all subsequent
processing instead of invoking the agent.
See `Runner._exec_with_plugin` in `src/google/adk/runners.py`:
early_exit_result = await plugin_manager.run_before_run_callback(...)
if isinstance(early_exit_result, types.Content):
early_exit_event = Event(..., content=early_exit_result)
...
yield early_exit_event # early exit, agent never runs
else:
# normal execution
This also matches the BasePlugin docstring: "Returning a value to halt
execution of the runner and ends the runner with that event."
Fix the "When It Runs", "Purpose", and "Flow Control" bullets accordingly.
yana-gi
force-pushed
the
fix/before-run-callback-flow-control
branch
from
08456dc to
bbcc5fd
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Runner start callbacks section of the Plugins guide describes
before_run_callbackas returning atypes.Contentto replace the user's original message. That is actually the behavior ofon_user_message_callback— the text (including the Purpose line) appears to have been duplicated from the User Message callbacks section.In the implementation, returning a
Contentfrombefore_run_callbackhalts the run (early exit): theRunneryields it as an early-exit event and skips all subsequent processing instead of invoking the agent.Evidence
Runner._exec_with_plugininsrc/google/adk/runners.py:This also matches the
BasePlugin.before_run_callbackdocstring:The early-exit behavior was established in adk-python
bf72426a("fix: runner was expecting Event object instead of Content object when using early exit feature", 2025-07-29), which predates this guide (added 2025-08-01). So the doc has been inaccurate since it was first written.Changes
Fix the When It Runs, Purpose, and Flow Control bullets for
before_run_callback:on_user_message_callback(the order shown in the callback diagram), not "before any other processing".on_user_message_callback).Contenthalts execution / early-exits, rather than replacing the user message.The
on_user_message_callbacksection is unchanged — its description is correct.