חקירת שיחות MCP באמצעות Trace

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

טווח מתעד פונקציה או פעולה יחידה שהיא חלק מפעולה גדולה יותר מקצה לקצה. Trace מייצג פעולה אחת מקצה לקצה ומורכב מ-spans. לכן, trace מספק מידע על רצף הפונקציות שנקראו ועל זמן האחזור הכולל, בעוד ש-span מספק מידע על הסטטוס ועל זמן האחזור של פונקציה ספציפית.

מידע על כלים

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

‫Model Context Protocol‏ (MCP) הוא מפרט שמגדיר דרך סטנדרטית לסוכני AI לתקשר עם כלים חיצוניים, מקורות נתונים ומשאבים, ולקיים איתם אינטראקציות. רשימה מלאה של מוצרים שכוללים שרת MCP וקישורים למאמרי העזרה שלהם זמינה כאן.

איך מעבירים הקשר של מעקב לשרת MCP

בדפי העזרה של MCP, כמו המסמכים בנושא list_log_entries, מופיעה דוגמה לפקודה curl שאפשר להשתמש בה כדי לשלוח בקשות HTTP לכלי. מטען ה-JSON הייעודי (payload) שנשלח בבקשה דומה לזה:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "id": 1
}

הערך בשדה name הוא שם הכלי, כמו list_log_entries. השדה arguments מכיל את המידע שנדרש כדי שהפעולה תשלים את הבקשה.

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

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
    "_meta": {
        "traceparent": "00-TRACE_ID-PARENT_SPAN_ID-SAMPLED_FLAG"
        "tracestate": "Vendor specific information."
      }
  },
  "id": 1
}

הנתונים של _meta כוללים את השדה traceparent. הפורמט של הערך בשדה הזה מוגדר על ידי הכותרת traceparent של World Wide Web Consortium ‏ (W3C). הערך כולל את:

  • גרסה של מפרט traceparent (00).
  • המזהה של המעקב (TRACE_ID).
  • המזהה של הטווח שקורא (PARENT_SPAN_ID).
  • השדה הזה מציין אם הטווח שקורא לפונקציה דגם את הבקשה (SAMPLED_FLAG). הערך של השדה הוא 01 אם בוצעה דגימה ו-00 אם לא בוצעה דגימה.

השדה tracestate מכיל מידע ספציפי לספק לצורך מעקב.

מגבלות

  • הקשר המעקב צריך להיות בהתאם לתקן W3C Trace Context, וצריך להגדיר את הדגל sampled לערך 1.

  • שרתי MCP מרוחקים של Google Cloud יכולים ליצור טווח יחיד לפעולה tools/call, אבל הם לא יוצרים טווחים לסוגים אחרים של פעולות או טווחי צאצא לפעולה tools/call.

  • שרתי MCP מרוחקים של Google Cloud יוצרים טווח רק כשהבקשה מאומתת, מורשית ועוברת בדיקות פנימיות אחרות.

שרתי MCP שתומכים במעקב

בקטע הזה מפורטים שרתי Google ו- Google Cloud MCP מרוחקים שתומכים במעקב. הוא גם מתאר איך שרתי MCP באירוח עצמי יכולים ליצור טווחים של מעקב.

שרתים באירוח עצמי

מומלץ להגדיר את שרתי ה-MCP המתארחים באופן עצמאי כך שישלחו נתוני טלמטריה לפרויקט Google Cloud . אם אתם משתמשים ב-Python, המכשיר יכול ליצור טווחים עבור פעולות tools/call. מידע נוסף זמין במאמר ביצוע אינסטרומנטציה לשרת MCP באירוח עצמי באמצעות OpenTelemetry.

שרתי Google ו-MCP מרוחקים שתומכים במעקב Google Cloud

המוצרים הבאים מכילים אינטגרציה שמאפשרת לשרת ה-MCP המרוחק שלהם ליצור טווח מעקב לפעולה tools/call:

איך מגדירים את האפליקציה

אפשר להשתמש בכל מסגרת או SDK שמעבירים את הקשר של המעקב באמצעות השדה _meta. מסגרות וערכות ה-SDK האלה כוללות את אלה שתומכות במוסכמות הסמנטיות של OpenTelemetry ל-MCP.

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

איך מציגים טווחים

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

כדי לראות את יחידות לוגיות למעקב שנכתבו על ידי שרתי MCP, מסננים את נתוני מעקב לפי שם היחידה לוגית למעקב. לדוגמה, חלק משרתי ה-MCP המרוחקים של Google Cloud יכולים ליצור טווח מעקב כשהם מקבלים פעולה של tools/call. השמות של טווחי הזמן האלה נקבעים לפי המוסכמה הבאה:

tools/call NAME

בדוגמה הקודמת, NAME מתייחס לנקודת הקצה שהופעלה. לדוגמה, יכול להיות שזה יהיה משהו דומה ל-list_keys. מוסכמת השמות הזו מוגדרת במוסכמות הסמנטיות של OpenTelemetry עבור MCP.

כדי למצוא את טווחי התאריכים האלה, משתמשים בסרגל הסינון ומוסיפים מסנן מאפיינים לmcp.method.name. מגדירים את ערך המסנן ל-tools/call.

דוגמאות לאינסטרומנטציה

המלצות להטמעה מפורטות במאמר בחירת גישה להטמעה.

הדוגמאות של שדרוג המידע שאנחנו מספקים משתמשות ב-OpenTelemetry: