Skip to content

docs(callbacks): align callback contracts with runtime behavior #7022

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.

Sign up for GitHub

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
jaywang172 wants to merge 1 commit into
base: main
Choose a base branch
from
+37 −19
Open

docs(callbacks): align callback contracts with runtime behavior #7022

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions src/google/adk/agents/base_agent.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
33 changes: 21 additions & 12 deletions src/google/adk/agents/llm_agent.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -485,30 +485,31 @@ 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,
llm_request: LlmRequest, The raw model request. Callback can mutate the
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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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

Expand Down