feat(live): run before and after model callbacks in live mode

Run agent and plugin model callbacks on the bidi streaming path.
- typed input reaches before model callback before it is forwarded
- spoken input reaches the before model callback once the model returns
  its transcription of the utterance
- model output reaches after model callback as it streams

A callback that returns a replacement response blocks the turn. Where
the model has already been given the input, the block reconnects the
live session so it does not continue the blocked turn.

Co-authored-by: Jason Zhang <jasoncz@google.com>
PiperOrigin-RevId: 970678524

Author: 2 people

docs/guides/README.md

@@ -27,6 +27,9 @@ This directory contains specific developer guides for the ADK Python implementat
 * [Event and NodeInfo](events/event/index.md) - Understanding Event and NodeInfo in workflows.
 * [RequestInput](events/request_input/index.md) - How to use RequestInput for human-in-the-loop interactions.
 
+### Flows
+* [Live model callbacks](flows/llm_flows/base_llm_flow/live_model_callbacks.md) - Inspecting or blocking content on a live bidirectional session.
+
 ### Memory
 * [BaseMemoryService](memory/memory_service/index.md) - Storing finished sessions and recalling them from later conversations.
 

docs/guides/flows/llm_flows/base_llm_flow/live_model_callbacks.md

@@ -0,0 +1,195 @@
+# Live model callbacks
+
+`before_model_callback` and `after_model_callback` run during `run_live`, giving
+you a place to inspect or block content on a live bidirectional session.
+Returning an `LlmResponse` from either callback substitutes your content and
+ends the current turn.
+
+## Introduction
+
+A live agent maintains an open, bidirectional connection to the model. While the
+connection is active, the client streams audio, text, or video, and the model
+streams back audio and text.
+
+Model callbacks intercept interactions on this connection for tasks such as
+guardrails, redaction, audit logging, and content filtering. `BaseLlmFlow`
+invokes both agent-level callbacks (`LlmAgent.before_model_callback`) and
+plugin callbacks (`BasePlugin.before_model_callback`).
+
+## Get started
+
+Callbacks that inspect user input and model output for blocked terms:
+
+```python
+from typing import Optional
+
+from google.adk.agents import Agent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.genai import types
+
+
+def block_input_keyword(
+    callback_context: CallbackContext,
+    llm_request: LlmRequest,
+) -> Optional[LlmResponse]:
+  """Blocks user input containing a forbidden keyword."""
+  text = None
+  if llm_request.contents and llm_request.contents[-1].parts:
+    text = ''.join(
+        part.text for part in llm_request.contents[-1].parts if part.text
+    )
+
+  if not text or 'forbidden' not in text.lower():
+    return None  # Send the request to the model.
+
+  return LlmResponse(
+      content=types.Content(
+          role='model',
+          parts=[types.Part(text='That input is not allowed.')],
+      )
+  )
+
+
+def block_output_keyword(
+    callback_context: CallbackContext,
+    llm_response: LlmResponse,
+) -> Optional[LlmResponse]:
+  """Ends the turn when the model's output so far mentions a blocked term."""
+  text = None
+  if llm_response.output_transcription:
+    text = llm_response.output_transcription.text
+
+  if not text or 'forbidden' not in text.lower():
+    return None  # Deliver the response unchanged.
+
+  return LlmResponse(
+      content=types.Content(
+          role='model',
+          parts=[types.Part(text="I can't help with that.")],
+      )
+  )
+
+
+root_agent = Agent(
+    name='guarded_agent',
+    instruction='Answer the user.',
+    before_model_callback=block_input_keyword,
+    after_model_callback=block_output_keyword,
+)
+```
+
+Run this agent with `run_live`. When the model output matches the keyword, the
+client receives the replacement text on an event with `turn_complete=True`, the
+connection resets, and the conversation continues on the next user turn.
+
+## How it works
+
+### `before_model_callback`
+
+`before_model_callback` inspects user input before the model acts on it. In live
+sessions, it handles two forms of user input:
+
+- **Typed text**: Evaluated before the text is sent to the model.
+- **Spoken audio**: Evaluated once the user finishes speaking and the model
+  transcribes the speech.
+
+#### What it receives
+
+The callback receives an `LlmRequest` whose `contents` list contains the user
+message or transcription currently being evaluated. Because live mode streams
+data continuously, this request object is a read-only snapshot.
+
+#### What a returned response does
+
+- **Returning `None`**: The user input is sent to the model (or generation
+  proceeds normally).
+- **Returning an `LlmResponse`**: The user input is blocked. The framework emits
+  your replacement response to the client with `turn_complete=True` and records
+  it in the session.
+  - For **typed text**, the original message is withheld from the model entirely.
+  - For **spoken audio**, the active connection automatically resets so the
+    model drops any in-flight response it began generating while listening.
+
+### `after_model_callback`
+
+`after_model_callback` inspects the model's response as it is generated, before
+it is delivered to the user.
+
+- **Streaming evaluation**: The callback runs as model output arrives, evaluating
+  accumulated audio transcriptions.
+
+#### What it receives
+
+The callback receives an `LlmResponse` whose `output_transcription` contains the
+accumulated text generated by the model so far in the current turn.
+
+#### What a returned response does
+
+- **Returning `None`**: Output continues streaming to the client unchanged.
+- **Returning an `LlmResponse`**: Generation halts immediately. The framework
+  delivers your replacement response to the client with `turn_complete=True`,
+  and resets the active live connection so the model does not retain the blocked generation.
+
+### Reconnecting after a refusal
+
+When `before_model_callback` blocks spoken audio or `after_model_callback` blocks
+model output, the model has already processed part of the exchange. To ensure the
+model does not remember refused content in subsequent turns:
+
+1. The framework closes the active live connection.
+2. It opens a fresh live session with session resumption cleared.
+3. The new connection's history is populated from session events, which contain
+   the replacement response rather than the blocked content.
+
+## Configuration options
+
+Live model callbacks use the standard ADK model callback interfaces:
+
+| Callback | Return `None` | Return `LlmResponse` |
+| :--- | :--- | :--- |
+| `before_model_callback` | Send the user's content to the model. | Withhold it and emit the replacement instead. Reconnects when the input was spoken. |
+| `after_model_callback` | Deliver the model's response unchanged. | Emit the replacement, end the turn, and reconnect. |
+
+Both are available as agent callbacks on `LlmAgent` and as plugin callbacks on
+`BasePlugin`. Plugin callbacks run first; if a plugin returns a response, the
+agent callbacks are skipped.
+
+## Limitations
+
+**Audio blobs are not screened.** The model callbacks run on live bidi input
+text as well as *transcriptions* of spoken and model audio. Input transcriptions
+are expected to arrive before the main model response. Output transcriptions are
+expected to arrive interleaved with the audio.
+
+**Output text modality is not screened.** A text-only live agent emits no
+output transcription, so it doesn't fire `after_model_callback` and its output
+is unscreened. This is a current limitation and will be fixed to include text
+output screening in the future.
+
+**Turn-level semantics**: Output callbacks receive the accumulated text of the
+turn, and returning an `LlmResponse` ends the turn with your replacement.
+Modifying individual streaming chunks while leaving generation active is
+currently not supported.
+
+**Mutating LLM requests and responses.** Callbacks in live may receive copies of
+`LlmRequest` and `LlmResponse` which are meant to be read-only. An `LlmResponse`
+can be returned to replace the turn. `on_event_callback` can be used to annotate
+events.
+
+**Callback latency.** The callback is awaited inside the receive loop, so
+blocking operations or network calls may add latency to the streaming session.
+
+### Live vs. non-live comparison
+
+While live and non-live (unary) flows share the same `before_model_callback` and `after_model_callback` interfaces, their behavior reflects the differences between batch generation and bidirectional streaming:
+
+| Behavior | Non-live (Unary) | Live (Bidirectional Streaming) |
+| :--- | :--- | :--- |
+| **`before_model_callback` timing** | Once per LLM call before generation. | Evaluated for typed text before sending, but for spoken audio only after transcription. |
+| **`before_model_callback` payload** | Full conversation history in `llm_request.contents`. | A single-item `contents` list containing the specific user message or transcription being evaluated. |
+| **`after_model_callback` timing** | Once per completed model response. | Continuously as output arrives, evaluating accumulated audio transcriptions. |
+| **`after_model_callback` payload** | Full generated `Content` in `llm_response.content`. | Accumulated text in `llm_response.output_transcription`. |
+| **Blocking refusal behavior** | Directly replaces the response or halts execution. | Replaces the turn and resets the connection to clear refused content from model memory. |
+| **Request & response mutability** | Standard mutable objects. | Read-only snapshots. |