הטמעה של סוכן LangGraph ReAct באמצעות OpenTelemetry

במאמר הזה מפורטים השלבים להוספת אינסטרומנטציה לסוכן LangGraph ReAct באמצעות OpenTelemetry, כדי לאפשר איסוף טלמטריה מהסוכן. ההנחיות של המשתמשים, התשובות והבחירות של הסוכן כלולים בטלמטריה כמאפיינים שמצורפים לטווחים. התשובות של הסוכן נכללות גם ברשומות ביומן שמשויכות לטווחים שמכילים אירועים של AI גנרטיבי. ההוראות במסמך הזה רלוונטיות כשהסוכן משתמש ב-ChatVertexAI של Langchain כדי לקרוא למודל Gemini.

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

לבצע אינסטרומנטציה באפליקציית AI גנרטיבי כדי לאסוף נתוני טלמטריה

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

1. התקנת חבילות OpenTelemetry
2. הגדרת OpenTelemetry לאיסוף ושליחה של טלמטריה
3. מעקב אחר הפעלת סוכן AI גנרטיבי

התקנת חבילות OpenTelemetry

מוסיפים את חבילות המכשירים והייצוא הבאות של OpenTelemetry:

uv add 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-otlp-proto-grpc'

נתוני היומנים והמדדים נשלחים לפרויקט Google Cloud שלכם באמצעות Cloud Logging API או Cloud Monitoring API. ספריית opentelemetry-exporter-gcp-logging מפעילה נקודות קצה בממשקי ה-API האלה.

נתוני מעקב ומדדים נשלחים אל Google Cloud באמצעות Telemetry (OTLP) API, שמטמיע את OpenTelemetry Line Protocol. ספריית opentelemetry-exporter-otlp-proto-grpc מפעילה את נקודת הקצה ל-API של Telemetry (OTLP).

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

הגדרת OpenTelemetry לאיסוף ושליחה של טלמטריה

בתוך קוד האתחול של סוכן LangGraph, מגדירים את OpenTelemetry כדי לתעד ולשלוח טלמטריה לפרויקט Google Cloud :

כדי לראות את הדוגמה המלאה, בסרגל הכלים של הדוגמה, לוחצים על הלוגו של GitHub.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "langgraph-sql-agent",
            CLOUD_PROVIDER: "gcp",
            CLOUD_ACCOUNT_ID: project_id,
            # The project to send spans to
            "gcp.project_id": project_id,
            CLOUD_REGION: "us-central1",
            SERVICE_NAMESPACE: "local",
            SERVICE_INSTANCE_ID: "local-instance",
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(
        OTLPMetricExporter(
            credentials=channel_creds,
            endpoint="https://telemetry.googleapis.com:443/v1/metrics",
        )
    )
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

מעקב אחר הפעלת סוכן AI גנרטיבי

כדי לעקוב אחרי הרצת סוכן LangGraph, יוצרים יחידה לוגית למעקב מותאמת אישית סביב ההפעלה של הסוכן:

כדי לראות את הדוגמה המלאה, בסרגל הכלים של הדוגמה, לוחצים על הלוגו של GitHub.

# Invoke the agent within a span
with tracer.start_as_current_span("invoke agent"):
    result = agent.invoke({"messages": [prompt]}, config=config)

כדאי לכלול את הקוד הקודם במקומות מרכזיים בקוד האפליקציה.

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

מריצים את הדוגמה

הדוגמה הזו היא סוכן LangGraph שמוגדר עם OpenTelemetry כדי לשלוח עקבות ויומנים עם הנחיות ותשובות של AI גנרטיבי, ומדדים לפרויקטGoogle Cloud .

פרסונה של סוכן LangGraph

סוכן LangGraph מוגדר כמומחה ל-SQL עם גישה מלאה למסד נתונים זמני של SQLite. הסוכן מיושם באמצעות סוכן ReAct מוכן מראש של LangGraph, והוא ניגש למסד הנתונים, שבתחילה ריק, באמצעות SQLDatabaseToolkit.

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

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

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

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

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את ממשקי ה-API של Vertex AI,‏ Service Usage,‏ Telemetry,‏ Cloud Logging,‏ Cloud Monitoring ו-Cloud Trace:

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

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

• יוצרים Google Cloud פרויקט:

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

• בוחרים את הפרויקט שיצרתם: Google Cloud

  gcloud config set project PROJECT_ID

  מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את ממשקי ה-API של Vertex AI,‏ Service Usage,‏ Telemetry,‏ Cloud Logging,‏ Cloud Monitoring ו-Cloud Trace:

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

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

   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
   • Logs Writer (roles/logging.logWriter)
   • כתיבת מדדי מעקב (roles/monitoring.metricWriter)
   • משתמש Vertex AI (roles/aiplatform.user)

   ההרשאות האלה מספיקות אם מריצים את הדוגמה ב-Cloud Shell, במשאבים או בסביבת פיתוח מקומית. Google Cloud

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

2. חשוב לוודא שמציינים פרויקט מכסה. ‫Vertex AI API‏ (aiplatform.googleapis.com) מחייב לציין מכסה בפרויקט. מידע נוסף זמין במאמר בנושא הגדרת פרויקט לצורכי מכסה. לדוגמה, הפקודה הבאה יכולה להגדיר פרויקט של מכסת שימוש.

   gcloud config set billing/quota_project PROJECT_ID

הרצת דוגמה

כדי להריץ את הדוגמה:

1. ב-Cloud Shell, משכפלים את המאגר:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git
   

2. עוברים לספריית הדוגמאות:

   cd opentelemetry-samples/python/langgraph-sql-agent
   

3. מגדירים משתני סביבה:

   # Capture GenAI prompts and responses
   export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
   # Capture application logs automatically
   export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
   # Set the location to one that supports gemini-3.5-flash
   export GOOGLE_CLOUD_REGION=global
   

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

4. יוצרים סביבה וירטואלית ומריצים את הדוגמה:

   uv run main.py
   

   באפליקציה מוצגת הודעה שדומה להודעה הבאה:

   Starting agent using ephemeral SQLite DB.
   

5. כדי ליצור מסד נתונים, מזינים ערך בהנחיה Talk to the SQL agent >> (שיחה עם סוכן SQL) ואז מקישים על Enter.

   הפעולות שהסוכן מבצע מוצגות ב-Cloud Shell.

   בדוגמה הבאה מוצגות אינטראקציות לדוגמה בין משתמש לבין האפליקציה:

   Talk to the SQL agent >> Create a new table to hold weather data.
   👤 User: Create a new table to hold weather data.
   🤖 Agent: Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
   
   CREATE TABLE weather (
     date DATE,
     location VARCHAR(255),
     temperature REAL,
     humidity REAL,
     precipitation REAL
   );
   
   🤖 Agent: I have created the weather table.
   👤 User: Add altitude to the table.
   🤖 Agent
   
   ALTER TABLE weather ADD COLUMN altitude REAL;
   
   

6. כדי לצאת, מזינים Ctrl-C.

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

צפייה בנתוני המעקב, במדדים וביומנים

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

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

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

• כלי הצפייה ביומנים (roles/logging.viewer)
• צפייה ב-Monitoring (roles/monitoring.viewer)
• משתמש Cloud Trace (roles/cloudtrace.user)

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

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

צפייה בטלמטריה

כדי לראות את האירועים של ה-AI הגנרטיבי, משתמשים בדף Trace Explorer:

1. נכנסים לדף Trace explorer במסוף Google Cloud :

   כניסה אל Trace explorer

   אפשר גם להשתמש בסרגל החיפוש כדי למצוא את הדף הזה.

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

   בקטע Run sample (הרצת דוגמה) יש דוגמה להרצה שבה נשלחות שתי הנחיות לאפליקציה. האיור הבא מציג את הדף Trace Explorer אחרי סינון הנתונים:

   

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

3. כדי לעיין בנתוני יחידה לוגית למעקב ויומן, בטבלה Spans, בוחרים יחידה לוגית למעקב.

   הדף פרטים נפתח. בדף הזה מוצג ה-trace המשויך וה-spans שלו. בטבלה שבדף מוצג מידע מפורט על טווח התאריכים שבחרתם. המידע הזה כולל את הפרטים הבאים:

   • בכרטיסייה Inputs/Outputs מוצגים אירועים של סוכני AI גנרטיבי. מידע נוסף על האירועים האלה זמין במאמר צפייה באירועים של AI גנרטיבי.

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

     

   • בכרטיסייה Logs & Events (יומנים ואירועים) מופיעים רשומות ביומן ואירועים שמשויכים לטווח. אם רוצים לראות את נתוני היומן ב-Logs Explorer, בסרגל הכלים של הכרטיסייה הזו בוחרים באפשרות הצגת יומנים.

     נתוני היומן כוללים את התשובה של סוכן LangGraph. לדוגמה, בהרצת הדוגמה, מטען ה-JSON הייעודי (payload) כולל את התוכן הבא:

     {
       logName: "projects/my-project/logs/otel_python_inprocess_log_name_temp"
       jsonPayload: {
         message: {
           role: "model"
           content: [
             0: {
               text: "Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
     
               CREATE TABLE weather (
                   date DATE,
                   location VARCHAR(255),
                   temperature REAL,
                   humidity REAL,
                   precipitation REAL
               );
               "
             }
           ]
         }
       index: 0
       }
     ...
     }
     

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