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

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

- מסלול (התהליך): האם הנציג השתמש בכלי הנכון בזמן הנכון? האם הוא התקשר אל
check_inventoryלפניplace_order? - התשובה הסופית (הפלט): האם התשובה נכונה, מנומסת ומבוססת על הנתונים?
מחזור החיים של הפיתוח
ב-Codelab הזה נסביר על מחזור החיים המקצועי של בדיקת נציגים:
- בדיקה חזותית מקומית (ממשק המשתמש של ADK באינטרנט): צ'אט ידני ואימות הלוגיקה (שלב 1).
- בדיקת יחידה/רגרסיה (ADK CLI): הפעלת מקרי בדיקה ספציפיים באופן מקומי כדי לזהות שגיאות במהירות (שלבים 3 ו-4).
- ניפוי באגים (פתרון בעיות): ניתוח כשלים ותיקון הלוגיקה של ההנחיה (שלב 5).
- שילוב CI/CD (Pytest): אוטומציה של בדיקות בפייפליין של ה-build (שלב 6).
2. הגדרה
כדי להפעיל את סוכני ה-AI שלנו, אנחנו צריכים שני דברים: פרויקט ב-Google Cloud שיספק את הבסיס.
חלק ראשון: הפעלת החשבון לחיוב
כדי להריץ את ה-Codelab הזה, צריך חשבון לחיוב עם קרדיט. כדי להתחיל, השתמשו בקרדיטים מהבאנר שבחלק העליון של ה-Codelab הזה. אם כבר יש לכם חשבון לחיוב, אתם יכולים לדלג על השלב הזה.
חלק שני: סביבה פתוחה
- 👉 לוחצים על הקישור הזה כדי לעבור ישירות אל Cloud Shell Editor.
- 👉 אם תתבקשו לאשר בשלב כלשהו היום, לחצו על אישור כדי להמשיך.

- 👉 אם הטרמינל לא מופיע בתחתית המסך, פותחים אותו:
- לוחצים על הצגה.
- לוחצים על Terminal (מסוף).

- 👉💻 בטרמינל, מריצים את הפקודה הבאה כדי לוודא שכבר אומתתם ושהפרויקט מוגדר למזהה הפרויקט שלכם:
gcloud auth list - 👉💻 משכפלים את פרויקט ה-bootstrap מ-GitHub:
git clone https://github.com/cuppibla/adk_eval_starter - 👉💻 מריצים את סקריפט ההגדרות מספריית הפרויקט.
cd ~/adk_eval_starter ./init.sh
הסקריפט יטפל בשאר תהליך ההגדרה באופן אוטומטי.
- 👉💻 מגדירים את מזהה הפרויקט הנדרש:
gcloud config set project $(cat ~/project_id.txt) --quiet
חלק שלישי: הגדרת הרשאה
- 👉💻 מפעילים את ממשקי ה-API הנדרשים באמצעות הפקודה הבאה. הפעולה עשויה להימשך כמה דקות.
gcloud services enable \ cloudresourcemanager.googleapis.com \ servicenetworking.googleapis.com \ run.googleapis.com \ cloudbuild.googleapis.com \ artifactregistry.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com - 👉💻 כדי לתת את ההרשאות הנדרשות, מריצים את הפקודות הבאות בטרמינל:
. ~/adk_eval_starter/set_env.sh
שימו לב שנוצר בשבילכם קובץ .env. שם מוצגים פרטי הפרויקט.
3. יצירת קבוצת הנתונים המושלמת (adk web)

לפני שנוכל לתת ציון לנציג, אנחנו צריכים מפתח תשובות. ב-ADK, אנחנו קוראים לזה מערך הנתונים המאומת. קבוצת הנתונים הזו מכילה אינטראקציות "מושלמות" שמשמשות כאמת קרקע (ground truth) להערכה.
מהי קבוצת נתונים מושלמת?
קבוצת נתונים אידיאלית היא תמונת מצב של הסוכן שפועל כמו שצריך. זה לא רק רשימה של זוגות של שאלות ותשובות. הוא מתעד:
- השאילתה של המשתמש ("אני רוצה החזר כספי")
- המסלול (הרצף המדויק של קריאות ה-API לכלים:
check_order->verify_eligibility->refund_transaction). - התשובה הסופית (התשובה הטקסטואלית "המושלמת").
אנחנו משתמשים בזה כדי לזהות רגרסיות. אם תעדכנו את ההנחיה והנציג יפסיק פתאום לבדוק את הזכאות לפני ביצוע ההחזר הכספי, הבדיקה של קבוצת הנתונים המושלמת תיכשל כי המסלול כבר לא תואם.
פתיחת ממשק המשתמש באינטרנט
ממשק המשתמש של ADK Web מאפשר ליצור את מערכי הנתונים האלה בצורה אינטראקטיבית, על ידי תיעוד אינטראקציות אמיתיות עם הנציג.
- 👉💻 במסוף, מריצים את הפקודה:
cd ~/adk_eval_starter uv run adk web - 👉💻 פותחים את התצוגה המקדימה של ממשק המשתמש באינטרנט (בדרך כלל בכתובת
http://127.0.0.1:8000). - 👉 בממשק המשתמש של הצ'אט, מקלידים
Hi, I'm customer CUST001. Can you check my orders? I need a refund for order ORD-102. It arrived damaged.
תתקבל תגובה כמו:I've processed your refund for order ORD-102 due to the items arriving damaged. A full refund of $35.0 has been processed, and the status of order ORD-102 is now updated to "refunded". Is there anything else I can assist you with today, CUST001? 🛍️
איך לתעד אינטראקציות חשובות
עוברים לכרטיסייה סשנים. כאן אפשר לראות את היסטוריית השיחות של הסוכן בלחיצה על הסשן.
- אתם יכולים לנהל אינטראקציה עם הנציג כדי ליצור תהליך שיחה אידיאלי, כמו בדיקת היסטוריית הרכישות או בקשת החזר כספי.
- בודקים את השיחה כדי לוודא שהיא מייצגת את ההתנהגות הצפויה.

4. ייצוא של קבוצת הנתונים הרשמית
אימות באמצעות Trace View
לפני שאתם מייצאים, אתם צריכים לוודא שהנציג לא קיבל את התשובה הנכונה במקרה. צריך לבדוק את הלוגיקה הפנימית.
- לוחצים על הכרטיסייה Trace בממשק המשתמש באינטרנט.
- המעקבים מקובצים באופן אוטומטי לפי הודעת המשתמש. מעבירים את העכבר מעל שורת מעקב כדי להדגיש את ההודעה המתאימה בצ'אט.
- בודקים את השורות הכחולות: השורות האלה מציינות אירועים שנוצרו מהאינטראקציה. לוחצים על שורה כחולה כדי לפתוח את חלונית הבדיקה.
- כדי לאמת את הלוגיקה, בודקים את הכרטיסיות הבאות:
- תרשים: ייצוג חזותי של קריאות ה-API לכלי ושל זרימת הלוגיקה. האם הוא עבר בנתיב הנכון?
- בקשה/תשובה: בודקים בדיוק מה נשלח למודל ומה התקבל בחזרה.
- אימות: אם הנציג ניחש את סכום ההחזר הכספי בלי לקרוא לכלי של מסד הנתונים, זו "הזיה מוצלחת".

הוספת סשן ל-EvalSet
אחרי שאתם מרוצים מהשיחה ומהמעקב:
- 👉 לוחצים על הכרטיסייה
Eval, ואז על הכפתורCreate Evaluation Setומזינים את שם ההערכה:evalset1
- 👉 בקבוצת ההערכה הזו, לוחצים על
Add current session to evalset1, ובחלון הקופץ מזינים את שם הסשן:eval1
הפעלת הערכה ב-ADK Web
- 👉 בממשק האינטרנט של ADK, לוחצים על
Run Evaluation, בחלון הקופץ משנים את המדדים ולוחצים עלStart:

אימות של מערך נתונים במאגר
יופיע אישור על כך שקובץ של קבוצת נתונים (למשל, evalset1.evalset.json) נשמר במאגר. הקובץ הזה מכיל את המעקב הגולמי שנוצר אוטומטית אחרי השיחה שלכם.

5. The Evaluation Files

ממשק המשתמש של האתר יוצר קובץ .evalset.json מורכב, אבל לעיתים קרובות אנחנו רוצים ליצור קובץ בדיקה נקי ומובנה יותר לבדיקות אוטומטיות.
הכלי ADK Eval משתמש בשני רכיבים עיקריים:
- קובצי בדיקה: יכולים להיות קבוצת הנתונים המושלמת שנוצרה אוטומטית (למשל,
customer_service_agent/evalset1.evalset.json) או קבוצה שנאספה באופן ידני (למשל,customer_service_agent/eval.test.json). - קובצי תצורה (למשל,
customer_service_agent/test_config.json): מגדירים את המדדים ואת ערכי הסף למעבר.
הגדרת קובץ התצורה של הבדיקה
- 👉💻 בטרמינל של Cloud Shell Editor, מזינים את הפקודה הבאה:
cloudshell edit customer_service_agent/test_config.json - 👉 מזינים את הקוד הבא ב-
customer_service_agent/test_config.jsonבעורך.{ "criteria": { "tool_trajectory_avg_score": 0.8, "response_match_score": 0.5 } }
הסבר על המדדים
tool_trajectory_avg_score(התהליך): המדד הזה בודק אם הנציג השתמש בכלים בצורה נכונה.
- 0.8: אנחנו דורשים התאמה של 80%.
-
response_match_score(הפלט) המדד הזה משתמש ב-ROUGE-1 (חפיפת מילים) כדי להשוות את התשובה לתשובת הזהב.
- יתרונות: מהיר, דטרמיניסטי, חינמי.
- חסרונות: לא עובד אם הנציג מנסח את אותו רעיון בצורה שונה (למשל, "החזר כספי" לעומת "הכסף הוחזר").
מדדים מתקדמים (כשצריך יותר יכולות)
6. הרצת הערכה של מערך נתוני הזהב (adk eval)

השלב הזה מייצג את "הלולאה הפנימית" של הפיתוח. אתם מפתחים שמבצעים שינויים ורוצים לאמת את התוצאות במהירות.
הרצת מערך נתוני הזהב
נריץ את מערך הנתונים שיצרתם בשלב 1. כך אפשר לוודא שנקודת הבסיס שלכם יציבה.
- 👉💻 במסוף, מריצים את הפקודה:
cd ~/adk_eval_starter uv run adk eval customer_service_agent customer_service_agent/evalset1.evalset.json --config_file_path=customer_service_agent/test_config.json --print_detailed_results
מה קורה?
ה-ADK הוא עכשיו:
- הסוכן שלך נטען מ-
customer_service_agent. - הרצת שאילתות הקלט מ-
evalset1.evalset.json. - השוואה בין המסלול והתגובות בפועל של הנציג לבין המסלול והתגובות הצפויים.
- דירוג התוצאות על סמך הקריטריונים ב
test_config.json.
ניתוח התוצאות
צופים בפלט של הטרמינל. יוצג סיכום של הבדיקות שעברו והבדיקות שנכשלו.
Eval Run Summary
evalset1:
Tests passed: 1
Tests failed: 0
********************************************************************
Eval Set Id: evalset1
Eval Id: eval1
Overall Eval Status: PASSED
---------------------------------------------------------------------
Metric: tool_trajectory_avg_score, Status: PASSED, Score: 1.0, Threshold: 0.8
---------------------------------------------------------------------
Metric: response_match_score, Status: PASSED, Score: 0.5581395348837208, Threshold: 0.5
---------------------------------------------------------------------
Invocation Details:
+----+---------------------------+---------------------------+--------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
| | prompt | expected_response | actual_response | expected_tool_calls | actual_tool_calls | tool_trajectory_avg_score | response_match_score |
+====+===========================+===========================+==========================+===========================+===========================+=============================+========================+
| 0 | Hi, I'm customer CUST001. | Great news! Your refund | Great news, CUST001! 🎉 | id='adk-051409fe-c230-43f | id='adk-4e9aa570-1cc6-4c3 | Status: PASSED, Score: | Status: PASSED, Score: |
| | Can you check my orders? | for order **ORD-102** has | I've successfully | 4-a7f1- 5747280fd878' | c-aa3e- 91dbe113dd4b' | 1.0 | 0.5581395348837208 |
| | I need a refund for order | been successfully | processed a full refund | args={'customer_id': | args={'customer_id': | | |
| | ORD-102. It arrived | processed due to the item | of $35.0 for your order | 'CUST001'} name='get_purc | 'CUST001'} name='get_purc | | |
| | damaged. | arriving damaged. You | ORD-102 because it | hase_history' | hase_history' | | |
| | | should see a full refund | arrived damaged. The | partial_args=None | partial_args=None | | |
| | | of $35.0 back to your | status of that order has | will_continue=None id= 'a | will_continue=None | | |
| | | original payment method | been updated to | dk-8a194cb8-5a82-47ce-a3a | id='adk- dad1b376-9bcc-48 | | |
| | | shortly. The status of | "refunded." Is there | 7- 3d24551f8c90' | bb-996f-a30f6ef5b70b' | | |
| | | this order has been | anything else I can | args={'reason': | args={'reason': | | |
| | | updated to "refunded". | assist you with today? | 'damaged', 'order_id': | 'damaged', 'order_id': | | |
| | | Here's your updated | | 'ORD-102'} | 'ORD-102'} | | |
| | | purchase history for | | name='issue_refund' | name='issue_refund' | | |
| | | CUST001: * **ORD-101**: | | partial_args=None | partial_args=None | | |
| | | Wireless Headphones, | | will_continue=None | will_continue=None | | |
| | | delivered on 2023-10-15 | | | | | |
| | | (Total: $120) * | | | | | |
| | | **ORD-102**: USB-C Cable, | | | | | |
| | | Phone Case, refunded on | | | | | |
| | | 2023-11-01 (Total: $35) | | | | | |
| | | Is there anything else I | | | | | |
| | | can help you with today? | | | | | |
| | | 😊 | | | | | |
+----+---------------------------+---------------------------+--------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
הערה: מכיוון שיצרתם את זה מהנציג עצמו, זה אמור לעבור ב-100%. אם הבדיקה נכשלת, הסוכן לא דטרמיניסטי (אקראי).
7. יצירת מבחן מותאם אישית משלכם
למרות שקבוצות נתונים שנוצרות אוטומטית הן מצוינות, לפעמים צריך ליצור באופן ידני מקרי קצה (למשל, התקפות אדברסריות או טיפול בשגיאות ספציפיות). בואו נראה איך eval.test.json מאפשר לכם להגדיר "נכונות".
בואו נבנה חבילת מקרים לבדיקה מקיפה.
מסגרת הבדיקות
כשכותבים מקרה בדיקה ב-ADK, צריך לפעול לפי הנוסחה הזו, שמורכבת מ-3 חלקים:
- ההגדרה (
session_input): מי המשתמש? (למשל,user_id,state). כך אפשר לבודד את הבדיקה. - הטריגר (
user_content): מה הטריגר?
עם הטענות (הציפיות):
- מסלול (
tool_uses): האם החישוב נכון? (לוגיקה) - תשובה (
final_response): האם התשובה הייתה נכונה? (איכות) - בינוני (
intermediate_responses): האם הסוכנים המשניים דיברו בצורה נכונה? (תזמור)
כתיבת חבילת המקרים לבדיקה
- 👉💻 בטרמינל של Cloud Shell Editor, מזינים את הפקודה הבאה:
cloudshell edit customer_service_agent/eval.test.json - 👉 מזינים את הקוד הבא בקובץ
customer_service_agent/eval.test.json.{ "eval_set_id": "customer_service_eval", "name": "Customer Service Agent Evaluation", "description": "Evaluation suite for the customer service agent covering product info, purchase history, and refunds.", "eval_cases": [ { "eval_id": "product_info_check", "session_input": { "app_name": "customer_service_agent", "user_id": "eval_user_1", "state": {} }, "conversation": [ { "invocation_id": "turn_1_product_info", "user_content": { "role": "user", "parts": [ { "text": "Do you have wireless headphones in stock?" } ] }, "final_response": { "role": "model", "parts": [ { "text": "Yes, we have wireless headphones in stock! They are priced at $120.00 and feature noise-canceling with a 20-hour battery life. 🎧" } ] }, "intermediate_data": { "tool_uses": [ { "name": "lookup_product_info", "args": { "product_name": "wireless headphones" } } ], "intermediate_responses": [] } } ] }, { "eval_id": "purchase_history_check", "session_input": { "app_name": "customer_service_agent", "user_id": "eval_user_2", "state": {} }, "conversation": [ { "invocation_id": "turn_1_purchase_history", "user_content": { "role": "user", "parts": [ { "text": "What did I buy recently? My customer ID is CUST001." } ] }, "final_response": { "role": "model", "parts": [ { "text": "Here's your recent purchase history for Customer ID CUST001:\n\n* **Order ORD-101** (October 15, 2023): Wireless Headphones, Status: delivered, Total: $120\n* **Order ORD-102** (November 1, 2023): USB-C Cable, Phone Case, Status: refunded, Total: $35\n\nLet me know if you have any other questions or need further assistance! 🛍️" } ] }, "intermediate_data": { "tool_uses": [ { "name": "get_purchase_history", "args": { "customer_id": "CUST001" } } ], "intermediate_responses": [] } } ] }, { "eval_id": "refund_request", "session_input": { "app_name": "customer_service_agent", "user_id": "eval_user_3", "state": {} }, "conversation": [ { "invocation_id": "turn_1_refund", "user_content": { "role": "user", "parts": [ { "text": "I want a refund for order ORD-102 because it was damaged." } ] }, "final_response": { "role": "model", "parts": [ { "text": "Your refund for order **ORD-102** due to \"damaged\" has been successfully processed! Refund amount: **$35.0**. Your order status has been updated to **refunded**. \nIs there anything else I can help you with today? 🛍️" } ] }, "intermediate_data": { "tool_uses": [ { "name": "issue_refund", "args": { "order_id": "ORD-102", "reason": "damaged" } } ], "intermediate_responses": [] } } ] } ] }
פירוק סוגי הבדיקות
יצרנו כאן שלושה סוגים שונים של בדיקות. בואו נבין מה כל אחד מהם בודק ולמה.
- בדיקת כלי יחיד (
product_info_check)
- המטרה: לאמת אחזור מידע בסיסי.
- טענה מרכזית: אנחנו בודקים את
intermediate_data.tool_uses. אנחנו טוענים שמתבצעת קריאה ל-lookup_product_info. אנחנו טוענים שהארגומנטproduct_nameהוא בדיוק "אוזניות אלחוטיות". - למה: אם המודל ממציא מחיר בלי להפעיל את הכלי, הבדיקה הזו נכשלת. כך אפשר להבטיח עיגון.
- The Context Extraction Test (
purchase_history_check)
- המטרה: לוודא שהנציג יכול לחלץ ישויות (CUST001) מההנחיה של המשתמש ולהעביר אותן לכלי.
- טענת נכוֹנוּת (assertion) עיקרית: אנחנו בודקים אם מתבצעת קריאה ל-
get_purchase_historyעםcustomer_id: "CUST001". - למה: מצב כשל נפוץ הוא שהנציג קורא לכלי הנכון אבל עם מזהה null. כך אפשר לוודא שהפרמטרים מדויקים.
- בדיקת הפעולה/המסלול (
refund_request)
- המטרה: אימות של פעולת כתיבה קריטית.
- טענה מרכזית: המסלול. בתרחיש מורכב יותר, הרשימה הזו תכיל כמה שלבים:
[verify_order, calculate_refund, issue_refund]. ה-ADK בודק את הרשימה הזו לפי הסדר. - למה: בפעולות שמעבירות כסף או משנות נתונים, הרצף חשוב כמו התוצאה. לא כדאי לבצע החזר כספי לפני שמאמתים את הפרטים.
8. הרצת הערכה לבדיקות בהתאמה אישית (adk eval)

- 👉💻 במסוף, מריצים את הפקודה:
cd ~/adk_eval_starter uv run adk eval customer_service_agent customer_service_agent/eval.test.json --config_file_path=customer_service_agent/test_config.json --print_detailed_results
הסבר על הפלט
אתם אמורים לראות תוצאת PASS (עבר) שנראית כך:
Eval Run Summary
customer_service_eval:
Tests passed: 3
Tests failed: 0
********************************************************************
Eval Set Id: customer_service_eval
Eval Id: purchase_history_check
Overall Eval Status: PASSED
---------------------------------------------------------------------
Metric: tool_trajectory_avg_score, Status: PASSED, Score: 1.0, Threshold: 0.8
---------------------------------------------------------------------
Metric: response_match_score, Status: PASSED, Score: 0.5473684210526315, Threshold: 0.5
---------------------------------------------------------------------
Invocation Details:
+----+--------------------------+---------------------------+---------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
| | prompt | expected_response | actual_response | expected_tool_calls | actual_tool_calls | tool_trajectory_avg_score | response_match_score |
+====+==========================+===========================+===========================+===========================+===========================+=============================+========================+
| 0 | What did I buy recently? | Here's your recent | Looks like your recent | id=None | id='adk-8960eb53-2933-459 | Status: PASSED, Score: | Status: PASSED, Score: |
| | My customer ID is | purchase history for | orders include: * | args={'customer_id': | f-b306- 71e3c069e77e' | 1.0 | 0.5473684210526315 |
| | CUST001. | Customer ID CUST001: * | **ORD-101 (2023-10-15):** | 'CUST001'} name='get_purc | args={'customer_id': | | |
| | | **Order ORD-101** | Wireless Headphones for | hase_history' | 'CUST001'} name='get_purc | | |
| | | (October 15, 2023): | $120.00 - Status: | partial_args=None | hase_history' | | |
| | | Wireless Headphones, | Delivered 🎧 * **ORD-102 | will_continue=None | partial_args=None | | |
| | | Status: delivered, Total: | (2023-11-01):** USB-C | | will_continue=None | | |
| | | $120 * **Order | Cable, Phone Case for | | | | |
| | | ORD-102** (November 1, | $35.00 - Status: Refunded | | | | |
| | | 2023): USB-C Cable, Phone | 📱 Is there anything else | | | | |
| | | Case, Status: refunded, | I can help you with | | | | |
| | | Total: $35 Let me know | regarding these orders? | | | | |
| | | if you have any other | | | | | |
| | | questions or need further | | | | | |
| | | assistance! 🛍️ | | | | | |
+----+--------------------------+---------------------------+---------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
********************************************************************
Eval Set Id: customer_service_eval
Eval Id: product_info_check
Overall Eval Status: PASSED
---------------------------------------------------------------------
Metric: tool_trajectory_avg_score, Status: PASSED, Score: 1.0, Threshold: 0.8
---------------------------------------------------------------------
Metric: response_match_score, Status: PASSED, Score: 0.6829268292682927, Threshold: 0.5
---------------------------------------------------------------------
Invocation Details:
+----+----------------------+---------------------------+---------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
| | prompt | expected_response | actual_response | expected_tool_calls | actual_tool_calls | tool_trajectory_avg_score | response_match_score |
+====+======================+===========================+===========================+===========================+===========================+=============================+========================+
| 0 | Do you have wireless | Yes, we have wireless | Yes, we do! 🎧 We have | id=None | id='adk-4571d660-a92b-412 | Status: PASSED, Score: | Status: PASSED, Score: |
| | headphones in stock? | headphones in stock! They | noise-canceling wireless | args={'product_name': | a-a79e- 5c54f8b8af2d' | 1.0 | 0.6829268292682927 |
| | | are priced at $120.00 and | headphones with a 20-hour | 'wireless headphones'} na | args={'product_name': | | |
| | | feature noise-canceling | battery life available | me='lookup_product_info' | 'wireless headphones'} na | | |
| | | with a 20-hour battery | for $120. | partial_args=None | me='lookup_product_info' | | |
| | | life. 🎧 | | will_continue=None | partial_args=None | | |
| | | | | | will_continue=None | | |
+----+----------------------+---------------------------+---------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
********************************************************************
Eval Set Id: customer_service_eval
Eval Id: refund_request
Overall Eval Status: PASSED
---------------------------------------------------------------------
Metric: tool_trajectory_avg_score, Status: PASSED, Score: 1.0, Threshold: 0.8
---------------------------------------------------------------------
Metric: response_match_score, Status: PASSED, Score: 0.6216216216216216, Threshold: 0.5
---------------------------------------------------------------------
Invocation Details:
+----+---------------------------+---------------------------+---------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
| | prompt | expected_response | actual_response | expected_tool_calls | actual_tool_calls | tool_trajectory_avg_score | response_match_score |
+====+===========================+===========================+===========================+===========================+===========================+=============================+========================+
| 0 | I want a refund for order | Your refund for order | Your refund for order | id=None args={'order_id': | id='adk-fb8ff1cc- cf87-41 | Status: PASSED, Score: | Status: PASSED, Score: |
| | ORD-102 because it was | **ORD-102** due to | **ORD-102** has been | 'ORD-102', 'reason': | f2-9b11-d4571b14287f' | 1.0 | 0.6216216216216216 |
| | damaged. | "damaged" has been | successfully processed! | 'damaged'} | args={'order_id': | | |
| | | successfully processed! | You should see a full | name='issue_refund' | 'ORD-102', 'reason': | | |
| | | Refund amount: **$35.0**. | refund of $35.0 appear in | partial_args=None | 'damaged'} | | |
| | | Your order status has | your account shortly. We | will_continue=None | name='issue_refund' | | |
| | | been updated to | apologize for the | | partial_args=None | | |
| | | **refunded**. Is there | inconvenience! Is there | | will_continue=None | | |
| | | anything else I can help | anything else I can | | | | |
| | | you with today? 🛍️ | assist you with today? 😊 | | | | |
+----+---------------------------+---------------------------+---------------------------+---------------------------+---------------------------+-----------------------------+------------------------+
זה אומר שהנציג השתמש בכלים הנכונים ונתן תשובה שדומה מספיק לציפיות שלכם.
9. (אופציונלי: לקריאה בלבד) – פתרון בעיות וניפוי באגים
הבדיקות ייכשלו. זה התפקיד שלהם. אבל איך מתקנים אותן? בואו ננתח תרחישי כשל נפוצים ונראה איך לנפות בהם באגים.
תרחיש א': כישלון ב"מסלול"
השגיאה:
Result: FAILED
Reason: Criteria 'tool_trajectory_avg_score' failed. Score 0.0 < Threshold 1.0
Details:
EXPECTED: tool: lookup_order, then tool: issue_refund
ACTUAL: tool: issue_refund
אבחון: הנציג דילג על שלב האימות (lookup_order). זו שגיאה לוגית.
פתרון בעיות:
- אל תנחשו: חזרו אל ממשק המשתמש של ADK באינטרנט (adk web).
- שחזור: מקלידים בצ'אט את ההנחיה המדויקת מהבדיקה שנכשלה.
- Trace: פתיחת התצוגה Trace. מעיינים בכרטיסייה "תרשים".
- לתקן את ההנחיה: בדרך כלל צריך לעדכן את הנחיית המערכת. שינוי: "אתה סוכן מועיל". To: "You are a helpful agent. חשוב: חובה להפעיל את lookup_order כדי לאמת את הפרטים לפני שמפעילים את issue_refund."
- התאמת הבדיקה: אם הלוגיקה העסקית השתנתה (למשל, כבר לא צריך לבצע אימות), הבדיקה שגויה. מעדכנים את eval.test.json בהתאם למציאות החדשה.
תרחיש ב': הכישלון של ROUGE
השגיאה:
Result: FAILED
Reason: Criteria 'response_match_score' failed. Score 0.45 < Threshold 0.8
Expected: "The refund has been processed successfully."
Actual: "I've gone ahead and returned the money to your card."
אבחון: הנציג פעל נכון, אבל השתמש במילים אחרות. ROUGE (חפיפת מילים) העניש אותו.
איך לפתור את הבעיה:
- האם זה לא נכון? אם המשמעות נכונה, אל תשנו את ההנחיה.
- שינוי הסף: מנמיכים את הסף ב-
test_config.json(למשל, מ-0.8ל-0.5). - שדרוג המדד: עוברים אל
final_response_match_v2בהגדרות האישיות. הוא משתמש ב-LLM כדי לקרוא את שני המשפטים ולבדוק אם המשמעות שלהם זהה.
10. CI/CD עם Pytest (pytest)

פקודות CLI מיועדות לבני אדם. pytest מיועד למכונות. כדי להבטיח את אמינות הייצור, אנחנו עוטפים את ההערכות שלנו בחבילת מקרים לבדיקה של Python. כך צינור עיבוד הנתונים של ה-CI/CD (GitHub Actions, Jenkins) יכול לחסום פריסה אם הסוכן פוגע בביצועים.
מה הקובץ הזה כולל?
קובץ ה-Python הזה משמש כגשר בין ה-runner של ה-CI/CD לבין מעריך ה-ADK. הוא צריך:
- טעינת הנציג: מייבאים באופן דינמי את קוד הנציג.
- איפוס המצב: מוודאים שזיכרון הנציג נקי כדי שהבדיקות לא ישפיעו זו על זו.
- Run Evaluation: הפעלה של
AgentEvaluator.evaluate()באופן פרוגרמטי. - Assert Success: אם ציון ההערכה נמוך, ה-build ייכשל.
קוד בדיקת השילוב
- 👉 פותחים את
customer_service_agent/test_agent_eval.py. הסקריפט הזה משתמש ב-AgentEvaluator.evaluateכדי להריץ את הבדיקות שמוגדרות ב-eval.test.json. - 👉 מזינים את הקוד הבא ב-
customer_service_agent/test_agent_eval.pyבעורך.from google.adk.evaluation.agent_evaluator import AgentEvaluator import pytest import importlib import sys import os @pytest.mark.asyncio async def test_with_single_test_file(): """Test the agent's basic ability via a session file.""" # Load the agent module robustly module_name = "customer_service_agent.agent" try: agent_module = importlib.import_module(module_name) # Reset the mock data to ensure a fresh state for the test if hasattr(agent_module, 'reset_mock_data'): agent_module.reset_mock_data() except ImportError: # Fallback if running from a different context sys.path.append(os.getcwd()) agent_module = importlib.import_module(module_name) if hasattr(agent_module, 'reset_mock_data'): agent_module.reset_mock_data() # Use absolute path to the eval file to be robust to where pytest is run script_dir = os.path.dirname(os.path.abspath(__file__)) eval_file = os.path.join(script_dir, "eval.test.json") await AgentEvaluator.evaluate( agent_module=module_name, eval_dataset_file_path_or_dir=eval_file, num_runs=1, )
הפעלת Pytest
- 👉💻 במסוף, מריצים את הפקודה:
התוצאה תיראה כך:cd ~/adk_eval_starter uv pip install pytest uv run pytest customer_service_agent/test_agent_eval.py``` -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html =============== 1 passed, 15 warnings in 12.84s =============== ```
11. סיכום
מעולה! הערכתם בהצלחה את סוכן שירות הלקוחות באמצעות ADK Eval.
מה למדתם
ב-Codelab הזה למדתם איך:
- ✅ יוצרים קבוצת נתונים תקנית כדי לקבוע אמת קרקע (ground truth) לסוכן.
- ✅ להבין את הגדרת ההערכה כדי להגדיר קריטריונים להצלחה.
- ✅ מריצים הערכות אוטומטיות כדי לזהות רגרסיות בשלב מוקדם.
אם תשלבו את ADK Eval בתהליך הפיתוח, תוכלו לפתח סוכנים בראש שקט, כי תדעו שכל שינוי בהתנהגות יזוהה על ידי הבדיקות האוטומטיות.
שיעור ה-Lab הזה הוא חלק מתוכנית הלימודים "AI מוכן לייצור עם Google Cloud".
- עיינו בתוכנית הלימודים המלאה כדי לגשר על הפער בין אב טיפוס לייצור.
- רוצה לשתף את ההתקדמות שלך? אפשר להשתמש בהאשטאג
ProductionReadyAI.
רשימת קריאה: