From cd08cf2c512be459a907b610fc2b21bdefe883dc Mon Sep 17 00:00:00 2001 From: jaywang172 <38661797jay@gmail.com> Date: Sat, 5 Sep 2026 09:53:58 +0800 Subject: [PATCH] docs(callbacks): align callback contracts with runtime behavior --- src/google/adk/agents/base_agent.py | 23 ++++++++++++++------ src/google/adk/agents/llm_agent.py | 33 ++++++++++++++++++----------- 2 files changed, 37 insertions(+), 19 deletions(-) diff --git a/src/google/adk/agents/base_agent.py b/src/google/adk/agents/base_agent.py index d8692a933e2..bad42108f63 100644 --- a/src/google/adk/agents/base_agent.py +++ b/src/google/adk/agents/base_agent.py @@ -169,29 +169,38 @@ class MyAgent(BaseAgent): """Callback or list of callbacks to be invoked before the agent run. When a list of callbacks is provided, the callbacks will be called in the - order they are listed until a callback does not return None. + order they are listed until a callback returns a truthy value. + + Arguments are passed by keyword first. If keyword binding fails, ADK tries + positional binding in the argument order below. Keyword-only parameters must + use the documented names; positional parameters may use different names. Args: - callback_context: MUST be named 'callback_context' (enforced). + callback_context: The context of the agent invocation. Returns: Optional[types.Content]: The content to return to the user. - When the content is present, the agent run will be skipped and the + When the content is truthy, the agent run will be skipped and the provided content will be returned to user. """ after_agent_callback: Optional[AfterAgentCallback] = None """Callback or list of callbacks to be invoked after the agent run. When a list of callbacks is provided, the callbacks will be called in the - order they are listed until a callback does not return None. + order they are listed until a callback returns a truthy value. + + Arguments are passed by keyword first. If keyword binding fails, ADK tries + positional binding in the argument order below. Keyword-only parameters must + use the documented names; positional parameters may use different names. Args: - callback_context: MUST be named 'callback_context' (enforced). + callback_context: The context of the agent invocation. Returns: Optional[types.Content]: The content to return to the user. - When the content is present, an additional event with the provided content - will be appended to event history as an additional agent response. + When the content is truthy, an additional event with the provided + content will be appended to event history as an additional agent + response. """ def _load_agent_state( diff --git a/src/google/adk/agents/llm_agent.py b/src/google/adk/agents/llm_agent.py index 2eeb82f90c2..0f3e5022527 100644 --- a/src/google/adk/agents/llm_agent.py +++ b/src/google/adk/agents/llm_agent.py @@ -485,7 +485,7 @@ class LlmAgent(BaseAgent, abc.ABC): """Callback or list of callbacks to be called before calling the LLM. When a list of callbacks is provided, the callbacks will be called in the - order they are listed until a callback does not return None. + order they are listed until a callback returns a truthy value. Args: callback_context: CallbackContext, @@ -493,22 +493,23 @@ class LlmAgent(BaseAgent, abc.ABC): request. Returns: - The content to return to the user. When present, the model call will be - skipped and the provided content will be returned to user. + Optional[LlmResponse]: A response to use instead of calling the model. + A truthy response skips the model call. Return None to continue. """ after_model_callback: Optional[AfterModelCallback] = None """Callback or list of callbacks to be called after calling the LLM. When a list of callbacks is provided, the callbacks will be called in the - order they are listed until a callback does not return None. + order they are listed until a callback returns a truthy value. Args: callback_context: CallbackContext, llm_response: LlmResponse, the actual model response. Returns: - The content to return to the user. When present, the actual model response - will be ignored and the provided content will be returned to user. + Optional[LlmResponse]: A response to use instead of the actual model + response. A truthy response replaces the model response. Return None + to keep the original response. """ on_model_error_callback: Optional[OnModelErrorCallback] = None """Callback or list of callbacks to be called when a model call encounters an error. @@ -522,8 +523,9 @@ class LlmAgent(BaseAgent, abc.ABC): error: The error from the model call. Returns: - The content to return to the user. When present, the error will be - ignored and the provided content will be returned to user. + Optional[LlmResponse]: A recovery response to use instead of propagating + the model error. Any non-None response stops the callback chain. Return + None to allow subsequent callbacks to handle the error. """ before_tool_callback: Optional[BeforeToolCallback] = None """Callback or list of callbacks to be called before calling the tool. @@ -537,8 +539,9 @@ class LlmAgent(BaseAgent, abc.ABC): tool_context: ToolContext, Returns: - The tool response. When present, the returned tool response will be used and - the framework will skip calling the actual tool. + Optional[dict[str, Any]]: A response to use instead of calling the tool. + Any non-None response, including an empty dict, stops the callback chain + and skips the tool call. Return None to continue. """ after_tool_callback: Optional[AfterToolCallback] = None """Callback or list of callbacks to be called after calling the tool. @@ -553,7 +556,10 @@ class LlmAgent(BaseAgent, abc.ABC): tool_response: The response from the tool. Returns: - When present, the returned dict will be used as tool result. + Optional[dict[str, Any]]: A response to use instead of the tool result. + Any non-None response, including an empty dict, stops the callback chain + and replaces the tool result. Return None to keep the current result + and allow subsequent callbacks to run. """ on_tool_error_callback: Optional[OnToolErrorCallback] = None """Callback or list of callbacks to be called when a tool call encounters an error. @@ -568,7 +574,10 @@ class LlmAgent(BaseAgent, abc.ABC): error: The error from the tool call. Returns: - When present, the returned dict will be used as tool result. + Optional[dict[str, Any]]: A recovery response to use instead of propagating + the tool error. Any non-None response, including an empty dict, stops the + callback chain. Return None to allow subsequent callbacks to handle the + error. """ # Callbacks - End