Summary

Callbacks as described here: https://google.github.io/adk-docs/callbacks/

Acceptance Criteria

Support for Callback Types

The system must support callback hooks at these points in an agent’s execution:

before_agent / after_agent

before_model / after_model

before_tool / after_tool

Each of those callbacks must be callable with appropriate inputs and contexts.
Google GitHub

Context Objects Availability

Each callback must receive a context object (CallbackContext or ToolContext) that provides:

the agent’s name or identifier

invocation details (e.g. which request/message triggered it)

session / state information

Return Values and Control Flow

For before_* callbacks:

If the callback returns None (or the language equivalent, e.g. Optional.empty() in Java), the default behaviour proceeds (e.g. calling the model, executing the tool).
Google GitHub

If the callback returns a specific object of the right type, it can skip the default step, replacing it with the returned object. For example:

before_model_callback returning an LlmResponse → skip the model call.
Google GitHub

before_tool_callback returning a dict/Map → skip tool execution.
Google GitHub

For after_* callbacks:

Returning None should mean using the result produced by the standard flow.
Google GitHub

Returning a specific object of the expected type should replace the standard result (post‐processing, sanitizing, etc.).
Google GitHub

Mutability / Ability to Inspect & Modify Inputs/Outputs

Callbacks must allow inspecting and possibly modifying inputs flowing into the agent, model, or tool (for example, modifying the request before it goes to the LLM).
Google GitHub

Callbacks must also allow inspecting and possibly modifying outputs after model/tool invocation via after_* hooks.
Google GitHub

Skip / Override Capability

It must be possible via a callback to short‐circuit or override parts of the agent execution: e.g. totally skip the model call (for guardrails, caching, etc.), or skip tool invocation.

Registration / Configuration of Callbacks

When creating an agent, there must be a way to assign (register) the callback functions for each supported callback point.
Google GitHub

The signature of the callback functions must match what’s required by ADK in the given language (Python, Java): e.g. take context, request (or tool): correct types.
Google GitHub

Correct Behaviour of Default Flow When Callbacks Not Provided / Returning None

If no callback is provided for a hook, the default normal agent flow proceeds.
Google GitHub

If callback is provided but returns None (or equivalent), behaviour matches default (aside from any in-place modifications allowed).
Google GitHub

Error Handling & Safety

If the callback logic fails (throws exception), the agent system should handle it gracefully (fallback to default behaviour or error propagation clearly documented). (Although less emphasized, this is a generally expected requirement for robust systems.)

Documentation & Developer Guidance

The system must provide clear documentation for:

what each callback hook does, when it’s called in the lifecycle.
Google GitHub

what return types are allowed, and what their effects are.
Google GitHub

use cases (how to implement guardrails, caching, or other customization via callbacks).