התקשרות חזרה

פונקציות Callback הן תכונה מתקדמת שמספקת מנגנון יעיל להתחברות לתהליך הביצוע של סוכן ספציפי באמצעות קוד Python. הן מאפשרות לכם לצפות בהתנהגות של הסוכן, להתאים אותה אישית ואפילו לשלוט בה בנקודות ספציפיות ומוגדרות מראש.

יש מגוון סוגים של קריאות חוזרות שאפשר להשתמש בהן, כשכל סוג של קריאה חוזרת מופעל בשלב מסוים בתור לשיחה. הסוגים האלה מתוארים בקטעים הבאים.

זמן ריצה ומחלקות של Python

בקוד הקריאה החוזרת של Python, יש לכם גישה למחלקות ולפונקציות מסוימות שעוזרות לכם לכתוב את הקוד. מידע נוסף זמין במאמר בנושא Python runtime reference.

הגבלות על ארגז חול ורשת

קוד של פונקציית Callback ב-Python מופעל בסביבת ארגז חול. הסביבה הזו כוללת את המגבלות הבאות:

• אין גישה לרשת פרטית (PNA): קריאות חוזרות לא יכולות לגשת ישירות לכתובות IP פרטיות או לפתור דומייני DNS פרטיים, גם אם הוגדר Service Directory. אם אתם צריכים לגשת למשאבים ברשת פרטית, אתם צריכים להשתמש בכלי שתומך בגישה לרשת פרטית (כמו כלי OpenAPI או MCP).
• גישה לאינטרנט הציבורי: אפשר להשתמש בקריאות חוזרות רק כדי לגשת לנקודות קצה שזמינות לכולם באינטרנט.

סוגי קריאות חוזרות

בהתאם לסוג פונקציית הקריאה החוזרת, פונקציית הקריאה החוזרת הראשית צריכה להיות בעלת שם ספציפי. כך תוכלו להגדיר פונקציות עזר עם כל שם שתרצו בקוד של פונקציית הקריאה החוזרת.

כל סוג של קריאה חוזרת מופעל בשלב מסוים בתור לשיחה:

אם מגדירים כמה קריאות חוזרות (callback) מסוג מסוים, הן יופעלו לפי הסדר שבו הגדרתם אותן.

בקטעים הבאים מתואר כל סוג של קריאה חוזרת (callback), ומוסבר לגבי כל סוג:

X	X
שם	שם פונקציית הקריאה החוזרת הנדרש
הרצה	נקודת הביצוע במהלך תור השיחה.
מטרה	תרחישים שימושיים לשימוש בקריאה חוזרת (callback).
ארגומנטים	ארגומנטים של קלט לפונקציה.
חזור	הערך המוחזר של הפונקציה.
קריאה חוזרת (callback) של ADK	קישור לתיעוד של הקריאה החוזרת (callback) המתאימה ב-ADK.

לפני שהסוכן מתחיל (before_agent_callback)

X	X
שם	before_agent_callback
הרצה	הפונקציה נקראת לפני הפעלת הסוכן.
מטרה	האפשרות הזו שימושית להגדרת משאבים או מצב שנדרשים לסוכן, לביצוע בדיקות אימות של מצב הסשן או למניעת הפעלה של הסוכן.
ארגומנטים	CallbackContext
חזור	תוכן(אופציונלי): אם מוגדר, הסוכן לא מופעל והתגובה שסופקה משמשת.
קריאה חוזרת (callback) של ADK	לפני שיחה חוזרת מנציג

קוד לדוגמה:

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

אחרי שהנציג מסיים (after_agent_callback)

X	X
שם	after_agent_callback
הרצה	הפונקציה נקראת אחרי שהסוכן משלים את הפעולה.
מטרה	התכונה הזו שימושית למשימות ניקוי, לאימות אחרי ההפעלה, לשינוי המצב הסופי או לעדכון התגובה של הסוכן.
ארגומנטים	CallbackContext
חזור	תוכן(אופציונלי): אם ההגדרה הזו מוגדרת, הפלט של הסוכן מוחלף בפלט שצוין.
קריאה חוזרת (callback) של ADK	אחרי שיחה חוזרת מנציג

קוד לדוגמה:

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)

לפני קריאה למודל שפה גדול (before_model_callback)

X	X
שם	before_model_callback
הרצה	הפונקציה מופעלת לפני בקשת המודל.
מטרה	האפשרות הזו שימושית לבדיקה או לשינוי של בקשת המודל, או כדי להימנע משימוש במודל.
ארגומנטים	CallbackContext, ‏ LlmRequest
חזור	‫LlmResponse: אם הערך מוגדר, המערכת מדלגת על קריאת המודל ומשתמשת בתשובה כאילו היא הגיעה מהמודל.
קריאה חוזרת (callback) של ADK	לפני הקריאה החוזרת של המודל

קוד לדוגמה:

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"))

אחרי שיחה עם LLM‏ (after_model_callback)

X	X
שם	after_model_callback
הרצה	הפונקציה מופעלת אחרי שמתקבלת תשובה מהמודל.
מטרה	הכלי הזה שימושי לשינוי הפורמט של תשובות המודל, לצנזור מידע רגיש שנוצר על ידי המודל, לניתוח נתונים מובְנים מהמודל לשימוש במשתנים ולטיפול בשגיאות במודל.
ארגומנטים	CallbackContext, ‏ LlmResponse
חזור	‫LlmResponse: אם ההגדרה הזו מוגדרת, התשובה של המודל מוחלפת בתשובה שסופקה.
קריאה חוזרת (callback) של ADK	after model callback

קוד לדוגמה:

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

לפני קריאה לכלי (before_tool_callback)

X	X
שם	before_tool_callback
הרצה	הקריאה מתבצעת לפני קריאות לכלי.
מטרה	האפשרות הזו שימושית לבדיקה ולשינוי של ארגומנטים של כלים, לבדיקות הרשאה לפני הפעלת כלי או להטמעה של שמירת נתונים במטמון ברמת הכלי.
ארגומנטים	‫Tool, ‏ Dict[str,Any]: קלט של כלי, CallbackContext
חזור	Dict[str,Any] : אם מוגדר, דילוג על הפעלת הכלי והפלט הזה מסופק למודל.
קריאה חוזרת (callback) של ADK	before tool callback

קוד לדוגמה:

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"}

אחרי קריאה לכלי (after_tool_callback)

X	X
שם	after_tool_callback
הרצה	הפונקציה נקראת אחרי שהכלי מסיים את הפעולה.
מטרה	הפונקציה הזו שימושית לבדיקה ולשינוי של תשובת הכלי לפני שליחתה חזרה למודל, לעיבוד שלאחר קבלת תוצאות הכלי או לשמירה של חלקים ספציפיים בתשובת הכלי במשתנים.
ארגומנטים	‫Tool, ‏ Dict[str,Any]: קלט של הכלי, CallbackContext, ‏ Dict[str,Any]: תגובה של הכלי
חזור	Dict[str,Any]: אם המשתנה הזה מוגדר, הוא מבטל את התגובה של הכלי שמועברת למודל.
קריאה חוזרת (callback) של ADK	אחרי קריאה חוזרת לכלי

קוד לדוגמה:

# 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

יצירת בקשה להחזרת שיחה

כדי ליצור בקשה להתקשרות חוזרת:

1. פותחים את הגדרות הסוכן.
2. לוחצים על הוספת קוד.
3. בוחרים סוג של בקשה להחזרת שיחה.
4. צריך לספק קוד Python.
5. לוחצים על Save.

מטענים ייעודיים (payloads) בהתאמה אישית (custom_payloads)

מטענים ייעודיים מאפשרים לכלול בתגובה של הסוכן נתונים משלימים, לא טקסטואליים ומובְנים (בדרך כלל בפורמט JSON). המטען הייעודי (payload) הזה עוזר להנחות את האינטראקציה של הסוכן עם מערכות חיצוניות או עם אפליקציות לקוח, או להוסיף לה מידע.

ערך המטען הייעודי (payload) לא גלוי למודל השפה הגדול (LLM), הוא משמש רק ליצירת התשובה הסופית. מטענים ייעודיים (payloads) מותאמים אישית נוצרים ומוגדרים באמצעות קריאות חוזרות (callbacks), ובאופן ספציפי באמצעות before_model_callback או after_model_callback.

אפשר להשתמש במטען הייעודי (payload) למגוון מטרות, בעיקר כדי לאפשר אינטראקציות עשירות ומובנות:

• העברה לטיפול של נציג: הפעולה הזו משמשת לעיתים קרובות להעברת אינטראקציה לנציג אנושי על ידי מתן הוראות ניתוב (לדוגמה, התור הספציפי שאליו צריך לנתב את האינטראקציה).
• תוכן עשיר ופעולות בצד הלקוח: הוא תומך בהטמעה של ווידג'טים עשירים ותוכן עשיר אחר ישירות בחוויות הצ'אט, מה שימושי במיוחד לשילובים מותאמים אישית של צ'אט.
  • לדוגמה, הצגת כתובות URL של תמונות או צ'יפים ואפשרויות של תשובה מהירה ללקוח באמצעות ממשק כמו Call Companion.
• Response Composition (הרכב התגובה): אפשר להגדיר החזרות של מטען ייעודי (payload) מותאם אישית במגוון דרכים:
  • החזרת מטען ייעודי (payload) בלבד באופן דטרמיניסטי.
  • החזרת מטען ייעודי (payload) יחד עם תשובת טקסט שנוצרה על ידי LLM.
  • החזרת מטען ייעודי (payload) עם תשובה סטטית בטקסט

הגדרת הסוכן

אפשר ליצור ולהגדיר מטענים ייעודיים (payloads) בהתאמה אישית רק באמצעות קריאות חוזרות (callbacks). המטען הייעודי (payload) מוגדר כ-Blob עם mime_type של application/json.

Part.from_json(data=payload_string)

דוגמה ל-after_model_callback

זוהי דוגמה ל-after_model_callback שמחזירה את תגובת המודל יחד עם תגובת מטען ייעודי (payload) מותאם אישית נוסף.

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_json_string))

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

דוגמה ל-before_model_callback

זוהי דוגמה ל-before_model_callback שמחזירה מטען ייעודי (payload) מותאם אישית נוסף אחרי הפעלה של כלי מסוים.

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)]))

אימות מטען ייעודי (payload) בתגובה בזמן ריצה

המטען הייעודי (payload) מאוכלס כ-Struct בשדה payload עבור RunSession וגם עבור BidiRunSession.

הערך של מטען הייעודי לא גלוי ל-LLM.