משתנים

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

סוגי משתנים

בונה הסוכנים תומך בשני סוגים שונים של משתנים בהוראות: משתנים סטטיים ומשתנים דינמיים.

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

משתנים סטטיים

משתנים סטטיים עוברים קומפילציה ישירות להנחיה של הסוכן לפני שהמודל מתקשר. הם פועלים כהחלפת טקסט ישירה של 1:1 והם מתעדכנים לעיתים רחוקות.

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

כדי להפנות למשתנה סטטי לפי שם בהוראות, משתמשים בסוגריים מסולסלים כפולים: {{variable_name}}.

לדוגמה, אם אתם יוצרים סוכן מכירות עם קטלוג מוצרים גדול וסטטי, אתם יכולים להשתמש בהוראה כמו:

You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.

משתנים דינמיים

אפשר לעדכן משתנים דינמיים בכל שלב במהלך שיחה באמצעות כלים, קריאות חוזרות (callback) או בקשות API. הם לא מוצבים ישירות בטקסט של ההנחיה. במקום זאת, כשהם מתעדכנים, הערכים החדשים שלהם מצורפים להיסטוריית השיחות כאירועים.state update לדוגמה: <state_update>var_name: value</state_update>.

משתמשים במשתנים דינמיים כדי לאחסן מידע שחולץ מהמשתמש במהלך השיחה, פלט שנשלף מממשקי API חיצוניים (כלים) או כל מצב שמשתנה ככל שהשיחה מתקדמת.

החסרונות הבאים רלוונטיים למשתנים דינמיים:

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

כדי להפנות למשתנה דינמי לפי שם בהוראות, צריך להשתמש בסוגריים מסולסלים בודדים: {variable_name}.

לדוגמה, אם אתם יוצרים סוכן שצריך לאמת משתמש ואז לחפש את פרטי החשבון הספציפיים שלו באמצעות כלי, אתם יכולים להשתמש בהוראה כמו:

If the user asks for their balance, call the {@TOOL: LookupBalance}.
The tool will update the {current_account_balance} variable.
Always share the {current_account_balance} with the user.

נתוני משתנים

המשתנים כוללים את הנתונים הבאים:

  • שם: שם המשתנה בפורמט snake case
  • סוג: סוג הנתונים הבסיסי:
    • טקסט: ערכי מחרוזת
    • ‫Number: ערכים מספריים
    • כן/לא: ערכים בוליאניים
    • אובייקט בהתאמה אישית: אתם מספקים סכימה לאובייקט
    • רשימה: רשימת משתנים. צריך לספק את הערכים כרשימה מופרדת בפסיקים.
  • ערך ברירת מחדל: ערך ברירת המחדל של המשתנה
  • תיאור: תיאור אופציונלי של המשתנה

עדכון ערכי משתנים

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

משתני הסוכן משתמשים במצב ההקשר של ADK, שאפשר להשתמש בו כדי לעדכן משתנים. משתנה גלובלי בשם context זמין לשימוש בקוד של כלי Python. לדוגמה, אפשר להשתמש בהצהרה הבאה בכלי Python כדי לעדכן משתנה באמצעות תכונות ADK:

context.state["variable_name"] = value

משתני הקשר מובנים של סשן

בנוסף למשתנים מותאמים אישית, כלים של OpenAPI ו-MCP יכולים להפנות למשתני הקשר המובנים של הסשן. הפרמטרים האלה זמינים כברירת מחדל, ואפשר להעביר אותם בכותרות HTTP או בפרמטרים של בקשות. אי אפשר להפנות למשתנים האלה בהוראות, ואי אפשר להחליף אותם באופן ידני. המשתנים המובנים הבאים זמינים:

  • ‫$context.project_id, $context.project_number, $context.location, $context.app_id, $context.session_id, $context.turn_index למזהי משאבים ברמת האפליקציה או ברמת הסשן.
  • ‫$context.variables.variable_name לערך ספציפי של משתנה של סוכן.
  • ‫$context.variables לכל הערכים של משתנה הסוכן כאובייקט.