Callback

I callback sono una funzionalità avanzata che fornisce un meccanismo potente per collegarsi al processo di esecuzione di un agente specifico utilizzando il codice Python. Ti consentono di osservare, personalizzare e persino controllare il comportamento dell'agente in punti specifici e predefiniti.

Esistono vari tipi di callback che puoi utilizzare, ognuno dei quali viene eseguito in un punto specifico del turno conversazionale. Questi tipi sono descritti nelle sezioni seguenti.

Runtime e classi Python

Nel codice di callback Python, hai accesso a determinate classi e funzioni che ti aiutano a scrivere il codice. Per saperne di più, consulta il riferimento al runtime Python.

Tipi di callback

A seconda del tipo di callback, la funzione di callback principale deve avere un nome specifico. In questo modo, puoi definire funzioni di supporto con qualsiasi nome all'interno del codice di callback.

Ogni tipo di callback viene eseguito in un punto specifico del turno conversazionale:

Se definisci più callback di un tipo specifico, vengono eseguiti nell'ordine in cui li definisci.

Le sezioni seguenti descrivono ogni tipo di callback, dove per ciascun tipo sono descritte le seguenti informazioni:

X	X
Nome	Nome della funzione di callback obbligatoria
Esecuzione	Punto di esecuzione all'interno del turno conversazionale.
Finalità	Scenari utili per utilizzare il callback.
Argomenti	Argomenti di input per la funzione.
Restituisci il dispositivo	Valore restituito per la funzione.
Callback ADK	Link alla documentazione del callback ADK corrispondente.

Prima dell'inizio dell'agente (before_agent_callback)

X	X
Nome	before_agent_callback
Esecuzione	Chiamato prima dell'invocazione dell'agente.
Finalità	Utile per configurare le risorse o lo stato necessari per l'agente, eseguire controlli di convalida sullo stato della sessione o evitare l'invocazione dell'agente.
Argomenti	CallbackContext
Restituisci il dispositivo	Contenuti(facoltativo): se impostato, l'agente non viene richiamato e viene utilizzata la risposta fornita.
Callback ADK	prima del richiamo dell'agente

Esempio di codice:

import random

def before_agent_callback(
  callback_context: CallbackContext
) -> Optional[Content]:
  username = callback_context.variables.get("username", None)
  if not username:
    # default user
    final_name = "Default Name"
  else:
    # add a random integer to the username
    final_name = f"{username} {random.randint(1,10)}"
  # update the username variable
  callback_context.variables["username"] = final_name

Dopo che l'agente ha terminato (after_agent_callback)

X	X
Nome	after_agent_callback
Esecuzione	Chiamato al termine dell'agente.
Finalità	Utile per le attività di pulizia, la convalida post-esecuzione, la modifica dello stato finale o l'aggiornamento della risposta dell'agente.
Argomenti	CallbackContext
Restituisci il dispositivo	Contenuto(facoltativo): se impostato, sostituisce l'output dell'agente con l'output fornito.
Callback ADK	dopo il richiamo dell'agente

Esempio di codice:

def after_agent_callback(
  callback_context: CallbackContext
) -> Optional[Content]:
  if callback_context.agent_name == "Routing Agent":
    counter = callback_context.variables.get("counter", 0)
    counter += 1
    # increment the invoked counter for this agent
    callback_context.variables["counter"] = int(counter)

Prima della chiamata LLM (before_model_callback)

X	X
Nome	before_model_callback
Esecuzione	Chiamato prima della richiesta del modello.
Finalità	Utile per l'ispezione/modifica della richiesta del modello o per evitare l'utilizzo del modello.
Argomenti	CallbackContext, LlmRequest
Restituisci il dispositivo	LlmResponse: se impostato, la chiamata al modello viene ignorata e la risposta viene utilizzata come se provenisse dal modello.
Callback ADK	before model callback

Esempio di codice:

def before_model_callback(
  callback_context: CallbackContext,
  llm_request: LlmRequest
) -> Optional[LlmResponse]:
  """
  This callback executes *before* a request is sent to the LLM.

  By returning an `LlmResponse` object, we are intercepting the call to the
  LLM. The LLM will *not* be called, and the framework will instead use the
  `LlmResponse` we provide as if it came from the model.

  This is the core mechanism for implementing input guardrails, prompt
  validation, or serving responses from a cache. Here, we force the agent to
  call a function instead of thinking with the LLM.
  """
  # Modify the shared session state.
  callback_context.variables['foo'] = 'baz'

  # Skip the LLM call and return a custom response telling the agent to
  # execute a specific function.
  return LlmResponse(
    content=Content(parts=[Part(
      function_call=FunctionCall(
        name="function_name", args={"arg_name": "arg_value"}))],
      role="model"))

Dopo la chiamata LLM (after_model_callback)

X	X
Nome	after_model_callback
Esecuzione	Chiamato dopo aver ricevuto una risposta del modello.
Finalità	Utile per riformattare le risposte del modello, censurare le informazioni sensibili generate dal modello, analizzare i dati strutturati del modello per l'utilizzo nelle variabili e gestione degli errori del modello.
Argomenti	CallbackContext, LlmResponse
Restituisci il dispositivo	LlmResponse: se impostato, sostituisce la risposta del modello con la risposta fornita.
Callback ADK	after model callback

Esempio di codice:

def after_model_callback(
  callback_context: CallbackContext,
  llm_response: LlmResponse
) -> Optional[LlmResponse]:
  """
  This callback executes *after* a response has been received from the LLM,
  but before the agent processes it.

  The `llm_response` parameter contains the actual data from the LLM.
  By returning `None`, we are approving this response and allowing the agent
  to use it as-is.

  If we returned a new `LlmResponse` object, it would *replace* the original,
  which is useful for redacting sensitive information, enforcing output
  formatting, or adding disclaimers.
  """
  # Returning None allows the LLM's actual response to be used.
  return None

Prima della chiamata allo strumento (before_tool_callback)

X	X
Nome	before_tool_callback
Esecuzione	Chiamate precedenti alle chiamate dello strumento.
Finalità	Utile per l'ispezione e la modifica degli argomenti dello strumento, i controlli di autorizzazione prima dell'esecuzione dello strumento o l'implementazione della memorizzazione nella cache a livello di strumento.
Argomenti	Tool, Dict[str,Any]: tool inputs, CallbackContext
Restituisci il dispositivo	Dict[str,Any] : se impostato, l'esecuzione dello strumento viene ignorata e questo output viene fornito al modello.
Callback ADK	before tool callback

Esempio di codice:

def before_tool_callback(
  tool: Tool,
  input: dict[str, Any],
  callback_context: CallbackContext
) -> Optional[dict[str, Any]]:
  """
  This callback executes *before* a specific tool is called by the agent.

  Here, we modify the input arguments intended for the tool and then return
  a dictionary. By returning a dictionary instead of `None`, we are
  overriding the default behavior. The actual tool function will *not* be
  executed. Instead, the dictionary we return will be treated as the
  llm.tool's result and passed back to the LLM for the next step.

  This is ideal for validating tool inputs, applying policies, or returning
  mocked/cached data for testing.
  """
  # Modify the shared session state.
  callback_context.variables['foo'] = 'baz'

  # Modify the arguments for the tool call in-place.
  input['input_arg'] = 'updated_val1'
  input['additional_arg'] = 'updated_val2'

  # Override the tool call and return a mocked result.
  return {"result": "ok"}

Dopo la chiamata allo strumento (after_tool_callback)

X	X
Nome	after_tool_callback
Esecuzione	Chiamata dopo il completamento dello strumento.
Finalità	Utile per l'ispezione e la modifica della risposta dello strumento prima di inviarla di nuovo al modello, per il post-elaborazione dei risultati dello strumento o per salvare parti specifiche di una risposta dello strumento nelle variabili.
Argomenti	Tool, Dict[str,Any]: tool inputs, CallbackContext, Dict[str,Any]: tool response
Restituisci il dispositivo	Dict[str,Any]: se impostato, esegue l'override della risposta dello strumento fornita al modello.
Callback ADK	after tool callback

Esempio di codice:

# Previous tool was named `get_user_info`
# Previous tool returned the payload:
# {"username": "Patrick", "fave_food": ["pizza"]}

def after_tool_callback(
  tool: Tool,
  input: dict[str, Any],
  callback_context: CallbackContext,
  tool_response: dict
) -> Optional[dict]:

  if tool.name == "get_user_info":
    tool_response["username"] = "Gary"
    tool_response["pet"] = "dog"

    # Override tool response
    return tool_response

Creare un callback

Per creare un callback:

1. Apri le impostazioni dell'agente.
2. Fai clic su Aggiungi codice.
3. Seleziona un tipo di richiamata.
4. Fornisci il codice Python.
5. Fai clic su Salva.

Payload personalizzati (custom_payloads)

I payload personalizzati facilitano l'inclusione di dati strutturati supplementari, non testuali (in genere formattati come JSON) all'interno della risposta di un agente. Questo payload è fondamentale per indirizzare o aumentare l'interazione dell'agente con sistemi esterni o applicazioni client.

Il valore del payload non è visibile al modello linguistico di grandi dimensioni (LLM); viene utilizzato solo per generare la risposta finale. I payload personalizzati vengono generati e impostati utilizzando i callback, in particolare before_model_callback o after_model_callback.

Il payload personalizzato può essere utilizzato per diversi scopi, generalmente incentrati sull'attivazione di interazioni avanzate e strutturate:

• Riassegnazione/trasferimento dell'agente: viene spesso utilizzato per trasferire un'interazione a un agente umano fornendo istruzioni di routing (ad esempio, la coda specifica a cui eseguire il routing).
• Contenuti avanzati e azioni lato client: Supporta l'incorporamento di widget avanzati e altri contenuti avanzati direttamente nelle esperienze di chat, il che è particolarmente utile per le integrazioni di chat personalizzate.
  • Alcuni esempi includono la visualizzazione di URL di immagini o chip e opzioni di risposta rapida per un cliente che utilizza un'interfaccia come Assistente chiamate.
• Composizione della risposta: I payload personalizzati possono essere configurati per essere restituiti in vari modi:
  • Restituisci solo il payload esplicito in modo deterministico.
  • Restituisce il payload insieme a una risposta di testo generata dall'LLM.
  • Restituisci il payload con una risposta di testo statica

Configurazione dell'agente

I payload personalizzati possono essere generati e impostati solo utilizzando i callback. Il payload è impostato come Blob con un mime_type di application/json.

Part.from_json(data=payload_string)

Esempio di after_model_callback

Questo è un esempio di after_model_callback che restituisce la risposta del modello insieme a una risposta di payload personalizzata aggiuntiva.

import json

def after_model_callback(callback_context: CallbackContext, llm_response: LlmResponse) -> Optional[LlmResponse]:
 """
 Adds a custom payload to every model response which is a text
 """
 if (llm_response.content.parts[0].text is not None):
   # construct payload
   payload_dict = { "custom_payload_key": "custom_payload_value"}
   payload_json_string = json.dumps(payload_dict)

   new_parts = []
   # Keep the origial agent response part, as model only sees text in the historical context.
   new_parts.append(Part(text=llm_response.content.parts[0].text))

   # Append custom payload
   new_parts.append(Part.from_json(data=payload_string))

   return LlmResponse(content=Content(parts=new_parts))

Esempio di before_model_callback

Questo è un esempio di before_model_callback che restituisce un payload personalizzato aggiuntivo dopo l'attivazione di un determinato strumento.

import json

def has_escalate(llm_request: LlmRequest) -> bool:
  for content in llm_request.contents:
    for part in content.parts:
      if part.function_call and part.function_call.name == 'escalate':
        return True
  return False

def before_model_callback(callback_context: CallbackContext, llm_request: LlmRequest) -> Optional[LlmResponse]:
  # checks if `escalate` tool is being called
  if not has_escalate(llm_request):
    return None
  payload_dict = { "escalate": "user ask for escalation"}
  payload_json_string = json.dumps(payload_dict)

  return LlmResponse(content=Content(parts=[Part(text="ESCALATE!!!"), Part.from_json(data=payload_json_string)]))

Verifica del payload in fase di runtime nella risposta

Il payload viene compilato come Struct nel campo payload sia per RunSession che per BidiRunSession.

Il valore del payload non è visibile al LLM.