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

Escribe la trayectoria de ejecución de un solo turno del agente para el registro interno de observabilidad. Los clientes de agentes propios (por ejemplo, el agente de Cowork de escritorio de Gemini Enterprise) usan este método. El registro se limita a la ObservabilityConfig del motor; los atributos que contienen contenido se ocultan, a menos que se habilite el registro de contenido sensible, y la trayectoria se escribe como un objeto JSON en un bucket de GCS interno fijo de Google para la depuración (nunca en un proyecto del cliente). NO se persiste en el almacén de eventos del usuario ni en el de recomendaciones.

Solicitud HTTP


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

Las URL usan la sintaxis de transcodificación gRPC.

Parámetros de ruta de acceso

Parámetros
parent

string

Obligatorio. Es el Engine al que pertenece la trayectoria, en el formato projects/{project}/locations/{location}/collections/{collection}/engines/{engine}. El registro de observabilidad se limita al ObservabilityConfig de este motor: la trayectoria solo se registra (se escribe como un objeto JSON en un bucket de GCS interno fijo de Google) cuando se habilita la observabilidad para el motor, y los atributos que contienen contenido solo se incluyen cuando se habilita el registro sensible.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
Campos
agentTrajectory

object (AgentTrajectory)

Obligatorio. Es la trayectoria del agente que se registrará.

Cuerpo de la respuesta

Mensaje de respuesta para el método UserEventService.WriteAgentTrajectory.

Si se ejecuta correctamente, el cuerpo de la respuesta contiene datos con la siguiente estructura:

Representación JSON 
{
  "acceptedSpanCount": integer
}
Campos
acceptedSpanCount

integer

Es la cantidad de intervalos que se aceptaron para el registro de observabilidad.

Permisos de autorización

Se necesita uno de los siguientes permisos de 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

Para obtener más información, consulta Authentication Overview.

Permisos de IAM

Se requiere el siguiente permiso de IAM en el recurso parent:

  • discoveryengine.engines.createEngineUserData

Para obtener más información, consulta la documentación de IAM.

AgentTrajectory

AgentTrajectory captura el registro de ejecución de un solo turno del agente, modelado según las convenciones semánticas de OpenTelemetry GenAI. Los clientes de origen (p.ej., el agente de Cowork de Gemini Enterprise para computadoras) lo registran solo para el registro interno de observabilidad; no se conserva en el almacén de recomendaciones o eventos del usuario.

El servidor limita el registro en ObservabilityConfig del motor, oculta los atributos que contienen contenido, a menos que se habilite el registro de contenido sensible, y escribe la trayectoria como un objeto JSON en un bucket de GCS interno fijo de Google para la depuración (nunca en un proyecto del cliente).

Representación JSON 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
Campos
spans[]

object (Span)

Obligatorio. Son los tramos que componen este turno del agente. Todos los tramos DEBEN compartir el mismo Span.trace_id.
sessionId

string

Es opcional. Es un identificador único de la sesión del agente a la que pertenece este turno.
resourceAttributes

map (key: string, value: string)

Es opcional. Son atributos a nivel del recurso que comparten todos los intervalos y que siguen las convenciones semánticas de recursos de OpenTelemetry (p.ej., service.name, gen_ai.agent.name, gen_ai.agent.id). Estos se habilitan de forma predeterminada para el registro de observabilidad.

Intervalo

Es un solo intervalo dentro de la trayectoria del agente, alineado con el modelo de datos de intervalo de OpenTelemetry.

Representación 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)
    }
  ]
}
Campos
traceId

string

Obligatorio. Es un ID de seguimiento de 32 caracteres hexadecimales (16 bytes) que comparten todos los intervalos del turno.
spanId

string

Obligatorio. Es un ID de intervalo de 16 caracteres hexadecimales (8 bytes) que identifica de forma única este intervalo dentro del registro.
parentSpanId

string

Es opcional. ID del intervalo principal de este intervalo, si existe. Está vacío para el intervalo raíz.
displayName

string

Obligatorio. Nombre legible por humanos del intervalo (p.ej., invoke_agent, generate_content, execute_tool <toolName>).
spanKind

enum (SpanKind)

Es opcional. Es el tipo de intervalo.
startTime

string (Timestamp format)

Obligatorio. Es la hora de inicio del período.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Obligatorio. Es la hora de finalización del período.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "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)

Es opcional. Son atributos de tramo que no son de contenido y que siguen las convenciones semánticas de OpenTelemetry GenAI (p.ej., gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens). Los valores numéricos se codifican como cadenas. Estas opciones están habilitadas para el registro de observabilidad de forma predeterminada.
contentAttributes

map (key: string, value: string)

Es opcional. Atributos que contienen contenido (p. ej., instrucciones, respuestas, argumentos y resultados de herramientas) De forma predeterminada, estos registros están INHABILITADOS para el registro de observabilidad y solo se registran cuando el cliente habilitó el registro de contenido sensible.
status

object (Status)

Es opcional. Es el estado del intervalo. code es un google.rpc.Code; OK (0) indica éxito y cualquier código distinto de cero indica un error.
events[]

object (Event)

Es opcional. Son los eventos cronometrados que ocurrieron durante el intervalo.

SpanKind

Es el tipo de intervalo, alineado con SpanKind de OpenTelemetry.

Enums
SPAN_KIND_UNSPECIFIED Sin especificar. Se trata como INTERNAL.
INTERNAL Es una operación interna dentro del agente (p.ej., invoke_agent).
SERVER Es un controlador de solicitudes entrantes síncronas.
CLIENT Es una solicitud saliente síncrona (p.ej., una llamada a un modelo o una herramienta).
PRODUCER Es un productor asíncrono de un mensaje.
CONSUMER Es un consumidor asíncrono de un mensaje.

Evento

Es un evento cronometrado que ocurrió durante el intervalo (p.ej., un fragmento transmitido).

Representación JSON 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
Campos
displayName

string

Obligatorio. Es un nombre legible por humanos para el evento.
eventTime

string (Timestamp format)

Obligatorio. Es la hora del reloj de pared en la que ocurrió el evento.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "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)

Es opcional. Son atributos que no son de contenido y que describen el evento.