Method: projects.locations.collections.engines.agentTrajectories.write

כתיבת מסלול הביצוע של תור יחיד של סוכן לצורך רישום ביומן של נתונים פנימיים לצורך מעקב. השיטה הזו משמשת לקוחות של סוכנים מאינטראקציה ישירה (לדוגמה, סוכן Gemini Enterprise למחשב). הרישום ביומן מוגבל על ידי ObservabilityConfig של המנוע. מאפיינים שמכילים תוכן מצונזרים אלא אם מופעל רישום ביומן של תוכן רגיש, והמסלול נכתב כאובייקט JSON בקטגוריית GCS פנימית קבועה של Google לצורך ניפוי באגים (אף פעם לא בפרויקט של לקוח). הוא לא נשמר בחנות האירועים או ההמלצות של המשתמש.

בקשת HTTP


POST https://discoveryengine.googleapis.com/v1alpha/{parent=projects/*/locations/*/collections/*/engines/*}/agentTrajectories:write

כתובות ה-URL כתובות בתחביר של gRPC Transcoding.

פרמטרים של נתיב

פרמטרים
parent

string

חובה. המספר Engine שאליו שייכת טרגקטוריה, בפורמט projects/{project}/locations/{location}/collections/{collection}/engines/{engine}. הרישום ביומן של נתוני יכולת הצפייה מוגבל על ידי ObservabilityConfig של המנוע הזה: הנתונים של המסלול נרשמים ביומן (נכתבים כאובייקט JSON בדלי GCS קבוע פנימי של Google) רק כשמופעלת יכולת הצפייה במנוע, והמאפיינים שמכילים תוכן נכללים רק כשמופעל רישום ביומן של נתונים רגישים.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
שדות
agentTrajectory

object (AgentTrajectory)

חובה. המסלול של הסוכן לרישום ביומן.

גוף התשובה

הודעת תגובה לשיטה UserEventService.WriteAgentTrajectory.

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "acceptedSpanCount": integer
}
שדות
acceptedSpanCount

integer

מספר טווחי הזמן שהתקבלו לרישום ביומן לצורך יכולת מעקב.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.serving.readwrite

ניתן למצוא מידע נוסף כאן: Authentication Overview.

הרשאות IAM

נדרשת הרשאת IAM הבאה במשאב parent:

  • discoveryengine.engines.createEngineUserData

מידע נוסף מופיע במאמרי העזרה בנושא IAM.

AgentTrajectory

‫AgentTrajectory מתעד את נתיב הביצוע של תור יחיד של סוכן, על בסיס מודל של מוסכמות סמנטיות של OpenTelemetry GenAI. האירוע הזה מדווח על ידי לקוחות מהדומיין הנוכחי (למשל, סוכן Gemini Enterprise למחשב) לצורך רישום ביומן של נתונים שניתנים לצפייה פנימית בלבד. הוא לא נשמר בחנות של אירועי משתמשים או המלצות.

השרת מגביל את הרישום ביומן ב-ObservabilityConfig של המנוע, מצנזר מאפיינים שמכילים תוכן אלא אם הופעל רישום ביומן של תוכן רגיש, וכותב את המסלול כאובייקט JSON בקטגוריית GCS פנימית קבועה של Google לצורך ניפוי באגים (אף פעם לא בפרויקט של לקוח).

ייצוג ב-JSON 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
שדות
spans[]

object (Span)

חובה. הטווחים שמרכיבים את תור הסוכן הזה. כל הטווחים חייבים לכלול את אותו Span.trace_id.
sessionId

string

זה שינוי אופציונלי. מזהה ייחודי של סשן הסוכן שאליו שייכת הפנייה הזו.
resourceAttributes

map (key: string, value: string)

זה שינוי אופציונלי. מאפיינים ברמת המשאב שמשותפים לכל הטווחים, בהתאם למוסכמות הסמנטיות של משאבי OpenTelemetry (לדוגמה, service.name,‏ gen_ai.agent.name,‏ gen_ai.agent.id). המאפיינים האלה מופעלים כברירת מחדל ביומן הרישום של יכולת התצפית.

Span

טווח יחיד בנתיב של הסוכן, שתואם למודל הנתונים של טווח OpenTelemetry.

ייצוג ב-JSON 
{
  "traceId": string,
  "spanId": string,
  "parentSpanId": string,
  "displayName": string,
  "spanKind": enum (SpanKind),
  "startTime": string,
  "endTime": string,
  "attributes": {
    string: string,
    ...
  },
  "contentAttributes": {
    string: string,
    ...
  },
  "status": {
    object (Status)
  },
  "events": [
    {
      object (Event)
    }
  ]
}
שדות
traceId

string

חובה. מזהה מעקב הקסדצימלי של 32 תווים (16 בייטים) שמשותף לכל הטווחים של התור.
spanId

string

חובה. מזהה טווח הקסדצימלי של 16 תווים (8 בייטים) שמזהה באופן ייחודי את הטווח הזה בתוך העקבה.
parentSpanId

string

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

string

חובה. שם קריא לאנשים של הטווח (למשל invoke_agent, ‏ generate_content, ‏ execute_tool <toolName>).
spanKind

enum (SpanKind)

זה שינוי אופציונלי. סוג הטווח.
startTime

string (Timestamp format)

חובה. שעת ההתחלה של טווח הזמן.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

חובה. שעת הסיום של טווח הזמן.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

זה שינוי אופציונלי. מאפייני טווח שאינם קשורים לתוכן, בהתאם למוסכמות הסמנטיות של OpenTelemetry GenAI (לדוגמה, gen_ai.system,‏ gen_ai.operation.name,‏ gen_ai.request.model,‏ gen_ai.usage.input_tokens). ערכים מספריים מקודדים כמחרוזות. הם מופעלים כברירת מחדל לרישום ביומן של נתוני תצפית.
contentAttributes

map (key: string, value: string)

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

object (Status)

זה שינוי אופציונלי. הסטטוס של ה-span. ‫code הוא google.rpc.Code; OK (0) מציין הצלחה וכל קוד שאינו אפס מציין שגיאה.
events[]

object (Event)

זה שינוי אופציונלי. אירועים מתוזמנים שהתרחשו במהלך התקופה.

SpanKind

סוג ה-span, בהתאם ל-OpenTelemetry SpanKind.

טיפוסים בני מנייה (enum)
SPAN_KIND_UNSPECIFIED לא צוין. הסיווג הוא INTERNAL.
INTERNAL פעולה פנימית בסוכן (למשל, invoke_agent).
SERVER מטפל סינכרוני בבקשות נכנסות.
CLIENT בקשה יוצאת סינכרונית (למשל, קריאה למודל או לכלי).
PRODUCER יצרן אסינכרוני של הודעה.
CONSUMER צרכן אסינכרוני של הודעה.

אירוע

אירוע מתוזמן שהתרחש במהלך טווח הזמן (למשל, נתח של סטרימינג).

ייצוג ב-JSON 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
שדות
displayName

string

חובה. שם האירוע שקריא לאנשים.
eventTime

string (Timestamp format)

חובה. השעה שהאירוע התרחש בה.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

זה שינוי אופציונלי. מאפיינים שאינם קשורים לתוכן ומתארים את האירוע.