דלגו לתוכן
גיליון 001·חי·20:20 IL
→ יומן/2026-11-03·9 דק׳

Google ADK Python 2.13.0: מהפך סכמת הטלמטריה ולאן תוכן הפרומפט הולך עכשיו

ADK Python 2.13.0 מסירה את ה-span של call_llm כברירת מחדל ועוברת למוסכמות OpenTelemetry GenAI. קראתי את ערות הגרסה, את ה-commit של השינוי השובר, את מדריך TelemetryConfig ואת המקור ב-tag, ומצאתי שהמדריך והקוד מתארים ברירות מחדל שונות.

מאת Harel Asaf·בונה בינה מלאכותית·תל אביב

ADK ל-Python של גוגל v2.13.0 פורסמה ב-GitHub ב-23 באוקטובר 2026, והשינוי השובר היחיד המפורט שלה הוא טלמטריה. כברירת מחדל ADK פולטת עכשיו את סכמת OpenTelemetry GenAI, spans של call_llm נעלמו, והרבה attributes של gcp.vertex.agent.* הפכו ל-gen_ai.*. אם הדשבורדים או ההתראות שלכם ממוקדים ב-call_llm, הם משתנים בשדרוג אלא אם מגדירים ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN=otel_semconv_1_36. אותה גרסה גם שולחת מדריך TelemetryConfig שאומר שפרומפטים נכתבים ל-spans כברירת מחדל. נקרא לצד הקוד, המדריך הזה מתאר את הסכמה הישנה.

קראתי את ערות הגרסה של v2.13.0, את הודעת ה-commit של השינוי השובר, את מדריך TelemetryConfig ב-tag, ואת קבצי המקור של הסכמה וה-tracing ב-tag דרך GitHub API. לא התקנתי ADK, לא הרצתי סוכן, ולא הסתכלתי ב-trace. איפה שאני מסיק התנהגות מקוד, אני אומר זאת.

מה הגרסה אומרת

חלק השינויים השוברים של ערות הגרסה מכיל פריט אחד: טלמטריה "defaults to OpenTelemetry GenAI v2 (otel_semconv_1_44, removing call_llm)". כדי לשמור על סכמת v1 המדורשת, הגדירו ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN=otel_semconv_1_36.

ה-commit מאחורי זה, "Deprecate call_llm span and OpenTelemetry 1.36 GenAI semconv", מפרט את השינויים הבולטים:

  • לוגים נפרדים של gen_ai.* OpenTelemetry מאוחדים תחת gen_ai.client.inference.operation.details.
  • ה-span של call_llm כבר לא נפלט.
  • attributes של gcp.vertex.agent.* השתנו ל-gen_ai.* איפה שיש מקבילות.

כתוב שהסכמה הישנה נתמכת "at least until 31st of March 2027".

מה הקוד ב-tag אומר

ה-docstring של _schema_version.py מגדיר את שני הערכים. 2 או otel_semconv_1_44 הוא ברירת המחדל: מיושר GenAI semconv, invoke_workflow מחליף את invocation, אין span של call_llm, תוכן כלי הוא gen_ai.tool.call.*, וה-GenAI semconv הניסיוני הוא ברירת המחדל. 1 או otel_semconv_1_36 הוא הפורמט המדורש. כתוב ש-1 נתמך לפחות עד 2027-03-31, "then removed with this knob".

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

ב-tracing.py, _start_call_llm_span לא מחזיר כלום תחת סכמה 2, ו-trace_call_llm מתואר כ-no-op שם. לקריאות כלים, הענף המדורש כותב gcp.vertex.agent.tool_call_args ו-tool_response כש-should_add_content_to_legacy_spans הוא true. הענף הלא-מדורש כותב gen_ai.tool.call.arguments ואת התוצאה רק כש-should_add_content_to_experimental_spans הוא true.

המדריך והקוד חולקים על ברירת המחדל

מדריך TelemetryConfig באותו tag נפתח בטענת פרטיות: בלי קונפיגורציה, "prompt and response content is written to ADK's spans". הטבלה שלו מגדירה should_add_content_to_legacy_spans ל-True כברירת מחדל ו-should_add_content_to_experimental_spans ל-False. הוא אומר שהודעת המשתמש מופיעה במלואה על ה-span של call_llm תחת gcp.vertex.agent.llm_request. הוא לא מזכיר otel_semconv_1_44 או ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN; חיפשתי את הקובץ לשניהם.

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

עובדות אחרות מהמדריך עקביות בכל מקרה:

  • ל-TelemetryConfig ארבעה שדות: capture_message_content, genai_semconv_stability_opt_in, adk_experimental_telemetry_opt_in ו-experimental_features_opt_in.
  • סדר הפענוח הוא נעילת האדמין ADK_TELEMETRY_IGNORE_RUN_CONFIG, אחר כך השדה לכל בקשה, אחר כך משתנה הסביבה, אחר כך ברירת המחדל.
  • ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false משתיק רק את ה-spans המדורשים של ADK עצמה. capture_message_content=NO_CONTENT משתיק הכל. EVENT_ONLY גם מכבה תוכן span מדורש.
  • ערך לא מזוהה למשתנה התוכן מפוענח ל-NO_CONTENT בלי אזהרה.
  • כשתוכן מודחק, ה-attributes המדורשים מוגדרים למחרוזת "{}", לא מושמטים.
  • אם opentelemetry-instrumentation-google-genai מותקן, הוא יוצר את span ההסקה בעצמו ועקיפות לכל בקשה לא מגיעות ל-span הזה.

מה עוד יש ב-2.13.0

היילייטים של הגרסה גם מפרטים 12 פיצ'רים ניסיוניים שקודמו ליציבים, TypesafeClassifier ו-ClassifierNode לניתוב workflow, אודיו חי עם barge-in, MongoDbSessionService ו-MongoDbMemoryService (שניהם ניסיוניים), וטענה של עד 8x ביצועי צעדי הרצה מהירים יותר לסוכני מודל-מחרוזת. אלה הצהרות ערות-גרסה. לא קראתי את המדריכים האלה ולא בדקתי את טענת הביצועים.

מה הייתי בודק

אלה הצעות שלא בדקתי, לא התנהגות מתועדת.

  • לפני שדרוג, חפשו בכללי ההתראה, דשבורדים ושאילתות לוג את call_llm, invocation ו-gcp.vertex.agent. אלה השמות שהגרסה אומרת שהשתנו.
  • הריצו סוכן אחד ב-staging על כל ערך סכמה ו-diff את ה-spans המיוצאים. ההשוואה אומרת לכם יותר מכל מסמך.
  • הגדירו ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS ו-OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT במפורש בפריסה במקום לסמוך על ברירות מחדל. אל תסמכו על הקריאה שלי של לאן ברירת המחדל הלכה.
  • אם פרטיות היא הסיבה שאכפת לכם, בדקו את ה-attributes המיוצאים לטקסט פרומפט בעצמכם על שתי הסכמות.
  • תכננו לעזוב את otel_semconv_1_36 לפני 31 במרץ 2027, מכיוון שהקוד אומר שהוא מוסר אחרי זה.

מה לא הייתי מסיק

  • לא הייתי מסיק שפרומפטים אף פעם לא מיוצאים על 2.13.0. רשומות לוג ונתיב ה-span הניסיוני נפרדים, ולא עקבתי אחריהם.
  • לא הייתי מסיק שהמדריך טועה באופן כללי. הוא נקרא כמדויק לסכמה המדורשת.
  • לא הייתי מסיק שהפיצ'רים שקודמו-ליציבים או טענת המהירות תקפים לעומס העבודה שלכם.
  • לא הייתי מסיק שום דבר על ADK Java או Kotlin. זה מכסה רק את חבילת Python.

שאלות נפוצות

מה השתנה בטלמטריה של ADK Python 2.13.0?

סכמת ברירת המחדל היא עכשיו OpenTelemetry GenAI v2, מכונה גם otel_semconv_1_44. ה-span של call_llm כבר לא נפלט, invoke_workflow מחליף את invocation, והרבה attributes של gcp.vertex.agent.* הפכו ל-gen_ai.*.

איך שומרים על הטלמטריה הישנה?

מגדירים ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN=otel_semconv_1_36. הקוד אומר שהיא נתמכת לפחות עד 2027-03-31.

האם שגיאת כתיב במשתנה הזה שומרת על הסכמה הישנה?

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

האם ADK עדיין שמה פרומפטים על spans כברירת מחדל?

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

מה ההבדל בין שתי הדרכים לכבות תוכן?

לפי המדריך, ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false משתיק רק את ה-spans המדורשים של ADK, בעוד capture_message_content=NO_CONTENT משתיק הכל.

האם קוד אפליקציה יכול לדרוס מדיניות טלמטריה של פלטפורמה?

לפי המדריך, הגדרת ADK_TELEMETRY_IGNORE_RUN_CONFIG ל-1 או true גורמת ל-ADK להתעלם מהשדות לכל בקשה.

הרצת את זה?

לא. קראתי ערות גרסה, הודעת commit, מדריך וקבצי מקור. לא התקנתי ADK ולא בדקתי שום trace.

מקורות

כולם נקראו ב-3 בנובמבר 2026.

לא נקרא: מקור הקונפיגורציה שמגדיר את ברירות המחדל, מפרט OpenTelemetry GenAI, המדריכים לקלאסיפיירים, MongoDB ואודיו חי, וכל trace מיוצא.

קריאה נוספת

יומן הבנייה

לעקוב אחרי העבודה.

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

עקבו ב-RSS