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

Schreibt den Ausführungsverlauf einer einzelnen Agent-Antwort für die interne Observability-Protokollierung. Diese Methode wird von eigenen Agent-Clients verwendet, z. B. dem Cowork-Agent für Gemini Enterprise-Desktop. Die Protokollierung hängt von der ObservabilityConfig der Engine ab. Attribute mit Inhalten werden unkenntlich gemacht, sofern die Protokollierung sensibler Inhalte nicht aktiviert ist. Der Verlauf wird als JSON-Objekt zur Fehlerbehebung in einen festen Google-internen GCS-Bucket geschrieben (niemals in ein Kundenprojekt). Sie wird NICHT im Nutzerereignis- oder Empfehlungsspeicher gespeichert.

HTTP-Anfrage

:


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

Für die URLs wird die Syntax der gRPC-Transcodierung verwendet.

Pfadparameter

Parameter
parent

string

Erforderlich. Die Engine, zu der der Pfad gehört, im Format projects/{project}/locations/{location}/collections/{collection}/engines/{engine}. Die Observability-Protokollierung ist an die ObservabilityConfig dieser Engine gebunden: Der Verlauf wird nur protokolliert (als JSON-Objekt in einen festen internen GCS-Bucket von Google geschrieben), wenn die Observability für die Engine aktiviert ist. Attribute mit Inhalten werden nur einbezogen, wenn die sensible Protokollierung aktiviert ist.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
Felder
agentTrajectory

object (AgentTrajectory)

Erforderlich. Die aufzuzeichnende Bahnkurve des Verkehrsteilnehmers.

Antworttext

Antwortnachricht für die Methode UserEventService.WriteAgentTrajectory.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "acceptedSpanCount": integer
}
Felder
acceptedSpanCount

integer

Die Anzahl der Spans, die für die Observability-Protokollierung akzeptiert wurden.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • 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

Weitere Informationen finden Sie unter Authentication Overview.

IAM-Berechtigungen

Erfordert die folgende IAM-Berechtigung für die Ressource parent:

  • discoveryengine.engines.createEngineUserData

Weitere Informationen finden Sie in der IAM-Dokumentation.

AgentTrajectory

„AgentTrajectory“ erfasst den Ausführungstrace eines einzelnen Agent-Turns, der auf den semantischen OpenTelemetry-Konventionen für generative KI basiert. Es wird von Erstanbieter-Clients (z.B. dem Cowork-Agent für Gemini Enterprise-Desktop) nur für die interne Protokollierung der Beobachtbarkeit gemeldet und nicht im Nutzerereignis- oder Empfehlungsspeicher gespeichert.

Der Server steuert die Protokollierung anhand der ObservabilityConfig der Engine, entfernt inhaltsbezogene Attribute, sofern die Protokollierung sensibler Inhalte nicht aktiviert ist, und schreibt den Pfad als JSON-Objekt in einen festen Google-internen GCS-Bucket zur Fehlerbehebung (niemals in ein Kundenprojekt).

JSON-Darstellung 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
Felder
spans[]

object (Span)

Erforderlich. Die Spannen, aus denen dieser Agenten-Turn besteht. Alle Spannen MÜSSEN dieselbe Span.trace_id haben.
sessionId

string

Optional. Eine eindeutige Kennung für die Agent-Sitzung, zu der dieser Turn gehört.
resourceAttributes

map (key: string, value: string)

Optional. Attribute auf Ressourcenebene, die von allen Spans gemeinsam genutzt werden und den semantischen OpenTelemetry-Konventionen für Ressourcen entsprechen (z.B. service.name, gen_ai.agent.name, gen_ai.agent.id). Diese sind standardmäßig für die Observability-Protokollierung aktiviert.

Span

Ein einzelner Span im Agent-Verlauf, der dem OpenTelemetry-Spandatenmodell entspricht.

JSON-Darstellung 
{
  "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)
    }
  ]
}
Felder
traceId

string

Erforderlich. Eine 32 Hexadezimalzeichen (16 Byte) umfassende Trace-ID, die von allen Spans des Turns gemeinsam genutzt wird.
spanId

string

Erforderlich. Eine 16-stellige Hexadezimal-ID (8 Byte), die diesen Span im Trace eindeutig identifiziert.
parentSpanId

string

Optional. Die Span-ID des übergeordneten Spans, sofern vorhanden. Leer für den Stamm-Span.
displayName

string

Erforderlich. Ein menschenlesbarer Name für den Bereich, z.B. invoke_agent, generate_content oder execute_tool <toolName>.
spanKind

enum (SpanKind)

Optional. Die Art des Zeitraums.
startTime

string (Timestamp format)

Erforderlich. Der Beginn des Zeitraums.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"
endTime

string (Timestamp format)

Erforderlich. Das Ende des Zeitraums.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Optional. Attribute für Spannen, die nicht zum Inhalt gehören und den semantischen Konventionen von OpenTelemetry GenAI entsprechen (z.B. gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens). Numerische Werte sind als String codiert. Für diese ist das Observability-Logging standardmäßig aktiviert.
contentAttributes

map (key: string, value: string)

Optional. Inhaltsbezogene Attribute (z.B. Prompts, Antworten, Tool-Argumente und Ergebnisse). Diese sind standardmäßig vom Beobachtbarkeits-Logging ausgeschlossen und werden nur protokolliert, wenn der Kunde das Logging sensibler Inhalte aktiviert hat.
status

object (Status)

Optional. Der Status des Zeitraums. code ist ein google.rpc.Code. OK (0) gibt Erfolg an und jeder Code ungleich null weist auf einen Fehler hin.
events[]

object (Event)

Optional. Zeitgesteuerte Ereignisse, die während des Zeitraums aufgetreten sind.

SpanKind

Die Art des Spans, die mit OpenTelemetry SpanKind übereinstimmt.

Enums
SPAN_KIND_UNSPECIFIED Nicht angegeben. Wird als INTERN behandelt.
INTERNAL Ein interner Vorgang innerhalb des Agents (z.B. „invoke_agent“).
SERVER Ein Handler für synchrone eingehende Anfragen.
CLIENT Eine synchrone ausgehende Anfrage (z.B. ein Modell- oder Toolaufruf).
PRODUCER Ein asynchroner Ersteller einer Nachricht.
CONSUMER Ein asynchroner Empfänger einer Nachricht.

Ereignis

Ein zeitgesteuertes Ereignis, das während des Zeitraums aufgetreten ist (z.B. ein gestreamter Chunk).

JSON-Darstellung 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
Felder
displayName

string

Erforderlich. Ein menschenlesbarer Name für das Ereignis.
eventTime

string (Timestamp format)

Erforderlich. Die Uhrzeit, zu der das Ereignis aufgetreten ist.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Optional. Attribute, die das Ereignis beschreiben, aber keine Inhalte sind.