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

Scrive la traiettoria di esecuzione di un singolo turno dell'agente per la registrazione interna dell'osservabilità. Questo metodo viene utilizzato dai client degli agenti proprietari (ad esempio, l'agente Cowork desktop di Gemini Enterprise). Il logging è controllato da ObservabilityConfig del motore; gli attributi contenenti contenuti vengono oscurati a meno che non sia attivato il logging dei contenuti sensibili e la traiettoria viene scritta come oggetto JSON in un bucket GCS interno a Google fisso per il debug (mai in un progetto cliente). NON viene mantenuto nell'archivio di eventi utente o suggerimenti.

Richiesta HTTP


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

Gli URL utilizzano la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
parent

string

Obbligatorio. La Engine a cui appartiene la traiettoria, nel formato projects/{project}/locations/{location}/collections/{collection}/engines/{engine}. La registrazione dell'osservabilità è controllata da ObservabilityConfig di questo motore: la traiettoria viene registrata (scritta come oggetto JSON in un bucket GCS interno a Google fisso) solo quando l'osservabilità è abilitata per il motore e gli attributi contenenti contenuti vengono inclusi solo quando è abilitata la registrazione sensibile.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
Campi
agentTrajectory

object (AgentTrajectory)

Obbligatorio. La traiettoria dell'agente da registrare.

Corpo della risposta

Messaggio di risposta per il metodo UserEventService.WriteAgentTrajectory.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "acceptedSpanCount": integer
}
Campi
acceptedSpanCount

integer

Il numero di span accettati per la registrazione dell'osservabilità.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti 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

Per saperne di più, consulta la Authentication Overview.

Autorizzazioni IAM

Richiede la seguente autorizzazione IAM per la risorsa parent:

  • discoveryengine.engines.createEngineUserData

Per saperne di più, consulta la documentazione di IAM.

AgentTrajectory

AgentTrajectory acquisisce la traccia di esecuzione di un singolo turno dell'agente, modellata sulle convenzioni semantiche OpenTelemetry GenAI. Viene segnalato dai client proprietari (ad es. l'agente Cowork di Gemini Enterprise per computer) solo per la registrazione interna dell'osservabilità; non viene salvato nell'archivio di eventi / consigli per gli utenti.

Il server attiva la registrazione in ObservabilityConfig del motore, redige gli attributi contenenti contenuti, a meno che non sia attivata la registrazione di contenuti sensibili, e scrive la traiettoria come oggetto JSON in un bucket GCS interno a Google fisso per il debug (mai in un progetto cliente).

Rappresentazione JSON 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
Campi
spans[]

object (Span)

Obbligatorio. Gli intervalli che compongono il turno di questo agente. Tutti gli intervalli DEVONO condividere lo stesso Span.trace_id.
sessionId

string

Facoltativo. Un identificatore univoco della sessione dell'agente a cui appartiene questo turno.
resourceAttributes

map (key: string, value: string)

Facoltativo. Attributi a livello di risorsa condivisi da tutti gli span, in base alle convenzioni semantiche delle risorse OpenTelemetry (ad es. service.name, gen_ai.agent.name, gen_ai.agent.id). Questi attributi sono attivati per la registrazione dell'osservabilità per impostazione predefinita.

Intervallo

Un singolo span all'interno della traiettoria dell'agente, allineato al modello dei dati dello span OpenTelemetry.

Rappresentazione 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)
    }
  ]
}
Campi
traceId

string

Obbligatorio. Un ID traccia esadecimale a 32 caratteri (16 byte) condiviso da tutti gli span del turno.
spanId

string

Obbligatorio. Un ID span di 16 caratteri esadecimali (8 byte) che identifica in modo univoco questo span all'interno della traccia.
parentSpanId

string

Facoltativo. L'ID span del parent di questo span, se presente. Vuoto per lo span principale.
displayName

string

Obbligatorio. Un nome leggibile per lo span (ad es. invoke_agent, generate_content, execute_tool <toolName>).
spanKind

enum (SpanKind)

Facoltativo. Il tipo di span.
startTime

string (Timestamp format)

Obbligatorio. L'ora di inizio dello span.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Obbligatorio. L'ora di fine dell'intervallo.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Facoltativo. Attributi di intervallo non di contenuti che seguono le convenzioni semantiche OpenTelemetry GenAI (ad es. gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens). I valori numerici sono codificati come stringhe. Questi sono attivati per la registrazione dell'osservabilità per impostazione predefinita.
contentAttributes

map (key: string, value: string)

Facoltativo. Attributi contenenti contenuti (ad es. prompt, risposte, argomenti e risultati degli strumenti). Questi sono disattivati per impostazione predefinita per la registrazione dell'osservabilità e vengono registrati solo quando il cliente ha attivato la registrazione dei contenuti sensibili.
status

object (Status)

Facoltativo. Lo stato dello span. code è un google.rpc.Code; OK (0) indica la riuscita e qualsiasi codice diverso da zero indica un errore.
events[]

object (Event)

Facoltativo. Eventi temporizzati che si sono verificati durante l'intervallo.

SpanKind

Il tipo di span, allineato a OpenTelemetry SpanKind.

Enum
SPAN_KIND_UNSPECIFIED Non specificato. Trattato come INTERNO.
INTERNAL Un'operazione interna all'agente (ad es. invoke_agent).
SERVER Un gestore di richieste sincrone in entrata.
CLIENT Una richiesta sincrona in uscita (ad es. una chiamata al modello o allo strumento).
PRODUCER Un produttore asincrono di un messaggio.
CONSUMER Un consumatore asincrono di un messaggio.

Evento

Un evento temporizzato che si è verificato durante l'intervallo (ad es. un segmento di streaming).

Rappresentazione JSON 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
Campi
displayName

string

Obbligatorio. Un nome leggibile per l'evento.
eventTime

string (Timestamp format)

Obbligatorio. L'ora in cui si è verificato l'evento.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Facoltativo. Attributi non di contenuti che descrivono l'evento.