‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

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

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

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

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

נתוני המעקב מאוחסנים בפורמט שתואם בדרך כלל לקובצי ה-proto שמוגדרים על ידי פרוטוקול OpenTelemetry. עם זאת, יכול להיות שהשדות יומרו מסוג נתונים ספציפי ל-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(
            OTLPLogExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/logs",
            )
        )
    )
    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 .

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

בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (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, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

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 .

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

בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (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

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

כדי לקבל את ההרשאות שנדרשות כדי שאפליקציית הדוגמה תכתוב נתוני יומנים, מדדים ומעקב, בקשו מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- כתיבת נתוני מעקב ב-Cloud Telemetry ‏ (roles/telemetry.tracesWriter)
- כתיבת יומנים (roles/logging.logWriter)
- כתיבת מדדי מעקב (roles/monitoring.metricWriter)
- Vertex AI User (roles/aiplatform.user)
ההרשאות האלה מספיקות אם מריצים את הדוגמה ב-Cloud Shell, במשאבי Google Cloud או בסביבת פיתוח מקומית.

חשוב: אפליקציות בסביבת ייצור בדרך כלל מסתמכות על חשבון שירות כדי לספק את פרטי הכניסה שנדרשים לכתיבת נתוני יומנים, מדדים ומעקב. בתרחישים האלה, צריך להקצות לחשבון השירות את התפקידים הקודמים.
חשוב לוודא שאתם מציינים פרויקט לצורכי מכסה. ב-Vertex AI API (aiplatform.googleapis.com) צריך לציין פרויקט לחיוב על מכסות. למידע נוסף, קראו את המאמר הגדרת הפרויקט לצורכי מכסה. לדוגמה, הפקודה הבאה יכולה להגדיר פרויקט לחיוב על מכסות.
```
gcloud config set billing/quota_project PROJECT_ID
```

הרצת הדוגמה

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

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

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

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

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

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

# 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.

יוצרים סביבה וירטואלית ומריצים את הדוגמה:
```
uv run main.py
```
באפליקציה תוצג הודעה דומה לזו:
```
Starting agent using ephemeral SQLite DB.
```

כדי ליצור מסד נתונים, מזינים ערך בהנחיה Talk to the SQL agent >> ולוחצים על 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;

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

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

הצגת המעקבים, המדדים ורישומי היומן

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

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

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

צפייה ביומנים (roles/logging.viewer)
צפייה במעקב (roles/monitoring.viewer)
Cloud Trace User (roles/cloudtrace.user)

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

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

הצגת נתוני הטלמטריה

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

במסוף Google Cloud , נכנסים לדף Trace explorer:
כניסה לדף Trace Explorer

אפשר גם למצוא את הדף הזה באמצעות שורת החיפוש.
בסרגל הכלים, לוחצים על Add filter, בוחרים באפשרות Span name ואז בוחרים ב-invoke agent.

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

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

הדף Details נפתח. בדף הזה מוצג המעקב המשויך והתקופות שלו. בטבלה שבדף מוצג מידע מפורט על ה-span שנבחר. המידע הזה כולל:
- בכרטיסייה Inputs/Outputs מוצגים אירועים של סוכני AI גנרטיבי. מידע נוסף על האירועים האלה זמין במאמר צפייה באירועי AI גנרטיבי.
  
  בצילום המסך הבא מוצג מעקב שבו ל-span אחד יש את השם invoke_agent. הטווח הזה מפעיל את Gemini. התקופה של Gemini כוללת אירועים של AI גנרטיבי:
- בכרטיסייה Logs & Events מופיעה רשימה של רשומות ביומן ואירועים שמשויכים ל-span. כדי לראות את נתוני היומן ב-Logs Explorer, לוחצים על View logs בסרגל הכלים של הכרטיסייה.
  
  נתוני היומן כוללים את התשובה של הסוכן ב-LangGraph. לדוגמה, בהרצה לדוגמה, המטען הייעודי (payload) של ה-JSON כולל את התוכן הבא:
```
{
  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 , אבל היא לא יוצרת מדדים.

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

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

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

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

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

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

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

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

הרצת הדוגמה

הצגת המעקבים, המדדים ורישומי היומן

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

הצגת נתוני הטלמטריה

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