יצירת אפליקציה של סוכן

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

לפני שמתחילים

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

יצירת אפליקציה של סוכן

יוצרים אפליקציית סוכן וסוכן בסיס:

1. פותחים את מסוף CX Agent Studio.
2. בוחרים את הפרויקט הרצוי.
3. לוחצים על יצירת סוכן או על סוכן חדש.
4. מזינים את השם weather app (אפליקציית מזג האוויר) לסוכן.
5. לוחצים על יצירה. אם זו הפעם הראשונה שאתם יוצרים אפליקציית סוכן לפרויקט, יכול להיות שייקח דקה או שתיים ליצור אותה. מוצג agent builder ונוצר בשבילכם סוכן ראשי.

יצירת היררכיית הסוכנים

אפליקציית הסוכן הזו תשתמש בשלושה סוכנים:

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

סוכן הבסיס כבר נוצר, אבל צריך לעדכן את ההגדרות של הסוכן הזה:

1. לוחצים על סרגל הכותרת של הסוכן הראשי.
2. אפשר לשנות את שם הסוכן.
3. מזינים את התיאור: 'מטפל בפניות פשוטות של משתמשים ומעביר אותן לסוכנים אחרים'.
4. לוחצים על שמירה ואז סוגרים את חלונית ההגדרות.

יוצרים את סוכן מזג האוויר:

1. לוחצים על הלחצן + בתחתית סוכן הבסיס.
2. לוחצים על הוספת סוכן משנה חדש.
3. לוחצים על סרגל הכותרת של הסוכן החדש.
4. משנים את השם ל-Weather agent.
5. מזינים את התיאור: "נותן מענה לכל שאלה שקשורה למזג האוויר מהמשתמש".
6. לוחצים על שמירה ואז סוגרים את חלונית ההגדרות.

באופן דומה, יוצרים עוד סוכן משנה של הסוכן הראשי בשם Farewell agent (סוכן הפרידה) עם התיאור Handles user farewells and goodbyes (מטפל בפרידות של משתמשים).

יצירת כלי מזג אוויר

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

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

יוצרים את כלי מזג האוויר:

1. לוחצים על לחצן ההגדרות בצד שמאל של הכלי ליצירת סוכנים.
2. לוחצים על + כדי ליצור כלי חדש לאפליקציית הנציג.
3. לוחצים על קוד Python.

4. מדביקים את הקוד הבא:

   def get_weather(city: str) -> dict:
     """Retrieves the current weather report for a specified city.
   
     Args:
       city (str): The name of the city.
   
     Returns:
       dict: A dictionary containing the weather information.
             Includes a 'status' key ('success' or 'error').
             If 'success', includes a 'report' key with weather details.
             If 'error', includes an 'error_message' key.
     """
     city_normalized = city.lower().replace(" ", "")
   
     mock_weather_db = {
       "newyork": {"status": "success",
         "report": "The weather in New York is sunny and 25°C."},
       "london": {"status": "success",
         "report": "It's cloudy in London and  15°C."},
       "tokyo": {"status": "success",
         "report": "Tokyo is experiencing light rain and 18°C."},
     }
     if city_normalized in mock_weather_db:
       return mock_weather_db[city_normalized]
     else:
       return {"status": "error",
         "error_message": f"No weather information for '{city}'."}
   

5. לוחצים על יצירה.

עכשיו צריך להוסיף את הכלי הזה לסוכן מזג האוויר:

1. לוחצים על הלחצן + בסרגל הכותרת של סוכן מזג האוויר.
2. לוחצים על הוספת כלי.
3. בוחרים בכלי מזג האוויר.

יצירת הוראות לסוכן

לכל סוכן יש קבוצה של הוראות שמגדירות מה הסוכן צריך לעשות.

כשמספקים הוראות שמתייחסות לסוכן, צריך להשתמש בתחביר {@AGENT: Agent name}. כדי להפנות לכלי, משתמשים ב-{@TOOL: tool_name}.

יוצרים הוראות לכל סוכן:

1. לוחצים על הלחצן + בסרגל הכותרת של סוכן הבסיס.
2. לוחצים על הוספת הוראות.

3. מזינים את ההוראות הבאות:

   You are a helpful weather application.
   Your job is to greet the user and delegate to other sub-agents as needed.
   When greeting the user, describe how you can help them.
   When the user asks for the weather, delegate to {@AGENT: Weather agent}.
   When the user is ending the conversation,
   delegate to {@AGENT: Farewell agent}.
   Handle only weather requests, greetings, and farewells.
   

4. לוחצים על יצירה.

5. באופן דומה, מוסיפים את ההוראות הבאות לסוכן מזג האוויר:

   You are a helpful weather agent.
   When the user asks for the weather in a specific city,
   use {@TOOL: get_weather} to find the information.
   If the tool returns an error, inform the user politely.
   If the tool is successful, present the weather report clearly.
   

6. באופן דומה, מוסיפים את ההוראות הבאות לסוכן הפרידה:

   You are the Farewell Agent.
   Your ONLY task is to provide a polite goodbye message.
   

בדיקת הנציג

האפליקציה של הסוכן מוכנה עכשיו לאינטראקציות באמצעות הסימולטור:

1. בפינה הימנית התחתונה של מסך הקונסולה, לוחצים על הסרגל תצוגה מקדימה של הסוכן כדי להרחיב את החלון אם הוא לא מורחב.
2. מקלידים 'שלום' ואז מקישים על Enter. הנציג עונה עם ברכה גנרית.
3. מקלידים "what is the weather in new york?‎" ולוחצים על Enter. הסוכן משיב עם מידע על מזג האוויר.
4. מקלידים goodbye ומקישים על Enter. הנציג מסיים את השיחה.

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

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

כדי ליצור את המשתנה:

1. לוחצים על לחצן המשתנים בצד שמאל של הכלי ליצירת סוכנים.
2. לוחצים על יצירת משתנה או על +.
3. כותבים username בתור שם המשתנה.
4. משאירים את הסוג כטקסט.
5. לוחצים על יצירה.

אחרי שהגדרתם את המשתנה, צריך להגדיר כלי שיאפשר לנציג לעדכן את המשתנה:

1. לוחצים על לחצן ההגדרות בצד שמאל של הכלי ליצירת סוכנים.
2. לוחצים על + כדי ליצור כלי חדש לאפליקציית הנציג.
3. לוחצים על קוד Python.

4. מדביקים את הקוד הבא:

   from typing import Optional
   
   def update_username(username: str) -> Optional[str]:
     """Updates the current user's name"""
     set_variable("username", username)
   

5. לוחצים על יצירה.

מוסיפים את הכלי הזה לסוכן הבסיסי:

1. לוחצים על הלחצן + בסרגל הכותרת של סוכן הבסיס.
2. לוחצים על הוספת כלי.
3. בוחרים בכלי update_username.

מוסיפים את המשפט הבא להוראות של סוכן הבסיס, שמפנה למשתנה באמצעות התחביר {variable_name}:

If provided, the current user is {username},
and you should address them with this name.
You can use {@TOOL: update_username} to update the user's name if they provide
it.

אפשר לבדוק שוב את הסוכן כדי לוודא שנעשה שימוש במשתנה:

1. לוחצים על התחלת שיחה חדשה בסרגל הכותרת של הסימולטור.
2. מזינים את הטקסט "שלום, קוראים לי פרנק".
3. מזינים את השאלה 'עד כמה המידע שלך מדויק?'.

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

איך מסיימים את הסשן

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

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

מוסיפים את ההוראות הבאות להוראות של סוכן הפרידה:

After providing the goodbye message and confirming the user has no more
questions, execute the tool {@TOOL: end_session}(reason="success").

שימוש בהתקשרות חוזרת כדי להציג הודעה סטטית בסיום הסשן

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

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

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

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

4. מזינים את הקוד הבא:

   SURVEY_MESSAGE = "Click here to take our post call survey."
   
   def after_model_callback(
       callback_context: CallbackContext,
       llm_response: LlmResponse
   ) -> Optional[LlmResponse]:
     for index, part in enumerate(llm_response.content.parts):
       if part.has_function_call('end_session'):
         return LlmResponse.from_parts(parts=[
           *llm_response.content.parts,
           Part.from_text(SURVEY_MESSAGE)
   
       ])
     return None
   

5. לוחצים על סיום.

6. לוחצים על Save.

אפשר לבדוק שוב את הנציג כדי לוודא את ההתנהגות של סיום הסשן:

1. לוחצים על התחלת שיחה חדשה בסרגל הכותרת של הסימולטור.
2. מזינים את המילה "Hello".
3. מזינים את המילה Goodbye (להתראות).

שימו לב שהסוכן עונה עכשיו באמצעות ההודעה שצירפתם.

הוראות לגבי המבנה

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

1. פותחים את חלונית ההוראות לסוכן.
2. לוחצים על הלחצן מבנה בפינה השמאלית העליונה.
3. לוחצים על Save.

כלים לפריסה

אחרי שיש לכם סוכן פעיל, יש לכם כמה אפשרויות פריסה.