From bbcc5fd2dba3b09c3016bf1c9c1d2ef0285a0bcd Mon Sep 17 00:00:00 2001 From: yana-gi Date: Tue, 9 Jun 2026 14:52:05 +0900 Subject: [PATCH] docs(plugins): correct before_run_callback flow control behavior 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. --- docs/plugins/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 24f769ed6c..0bbe007725 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -796,12 +796,12 @@ object takes the potentially modified user message and prepares for execution. The `before_run_callback` fires here, allowing for global setup before any agent logic begins. -- **When It Runs:** Immediately after `runner.run()` is called, before - any other processing. -- **Purpose:** The first opportunity to inspect or modify the user's raw - input. -- **Flow Control:** Return a `types.Content` object to **replace** the - user's original message. +- **When It Runs:** After the `on_user_message_callback`, when the `Runner` + prepares for execution and before any agent logic begins. +- **Purpose:** Global setup or initialization before the invocation runs. +- **Flow Control:** Return a `types.Content` object to **halt execution**: + the `Runner` exits early and ends the run with that content as the result. + Return `None` to proceed normally. The following code example shows the basic syntax of this callback: