משתנים

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

סוגי משתנים

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

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

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

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

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

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

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

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

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

אפשר לעדכן משתנים דינמיים בכל שלב במהלך השיחה באמצעות כלים, קריאות חוזרות (callbacks) או בקשות 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.

נתונים משתנים

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

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

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

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

משתני הנציג משתמשים במצב ההקשר של 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 לכל הערכים של משתנה הנציג כאובייקט.