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

Écrit la trajectoire d'exécution d'un tour d'agent unique pour la journalisation de l'observabilité interne. Cette méthode est utilisée par les clients d'agents propriétaires (par exemple, l'agent Cowork Gemini Enterprise pour ordinateur). La journalisation est contrôlée par la configuration ObservabilityConfig du moteur. Les attributs contenant du contenu sont masqués, sauf si la journalisation du contenu sensible est activée. La trajectoire est écrite sous forme d'objet JSON dans un bucket GCS interne fixe de Google à des fins de débogage (jamais dans un projet client). Elle n'est PAS conservée dans le magasin d'événements utilisateur ni dans le magasin de recommandations.

Requête HTTP


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

Les URL utilisent la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
parent

string

Obligatoire. Le Engine auquel appartient la trajectoire, au format projects/{project}/locations/{location}/collections/{collection}/engines/{engine}. La journalisation de l'observabilité est contrôlée par le ObservabilityConfig de ce moteur : la trajectoire n'est journalisée (écrite sous forme d'objet JSON dans un bucket GCS interne à Google) que lorsque l'observabilité est activée pour le moteur, et les attributs contenant du contenu ne sont inclus que lorsque la journalisation des informations sensibles est activée.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
Champs
agentTrajectory

object (AgentTrajectory)

Obligatoire. Trajectoire de l'agent à enregistrer.

Corps de la réponse

Message de réponse pour la méthode UserEventService.WriteAgentTrajectory.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON 
{
  "acceptedSpanCount": integer
}
Champs
acceptedSpanCount

integer

Nombre de spans acceptés pour la journalisation de l'observabilité.

Niveaux d'accès des autorisations

Nécessite l'un des niveaux d'accès OAuth suivants :

  • 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

Pour plus d'informations, consultez la page Authentication Overview.

Autorisations IAM

Nécessite l'autorisation IAM suivante sur la ressource parent :

  • discoveryengine.engines.createEngineUserData

Pour en savoir plus, consultez la documentation IAM.

AgentTrajectory

AgentTrajectory capture la trace d'exécution d'un seul tour d'agent, modélisée sur les conventions sémantiques OpenTelemetry GenAI. Il est signalé par les clients propriétaires (par exemple, l'agent Cowork Gemini Enterprise pour ordinateur) uniquement pour la journalisation interne de l'observabilité. Il n'est pas conservé dans le magasin d'événements / recommandations utilisateur.

Le serveur contrôle la journalisation sur ObservabilityConfig du moteur, masque les attributs contenant du contenu, sauf si la journalisation du contenu sensible est activée, et écrit la trajectoire sous forme d'objet JSON dans un bucket GCS interne fixe de Google à des fins de débogage (jamais dans un projet client).

Représentation JSON 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
Champs
spans[]

object (Span)

Obligatoire. Les portées qui composent ce tour d'agent. Toutes les portées DOIVENT partager le même Span.trace_id.
sessionId

string

Facultatif. Identifiant unique de la session d'agent à laquelle appartient ce tour.
resourceAttributes

map (key: string, value: string)

Facultatif. Attributs au niveau des ressources partagés par toutes les portées, suivant les conventions sémantiques des ressources OpenTelemetry (par exemple, service.name, gen_ai.agent.name, gen_ai.agent.id). La journalisation de l'observabilité est activée par défaut pour ces attributs.

Segment

Portée unique dans la trajectoire de l'agent, alignée sur le modèle de données de portée OpenTelemetry.

Représentation 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)
    }
  ]
}
Champs
traceId

string

Obligatoire. ID de trace de 32 caractères hexadécimaux (16 octets) partagé par toutes les portées du tour.
spanId

string

Obligatoire. ID de segment de 16 caractères hexadécimaux (8 octets) qui identifie de manière unique ce segment dans la trace.
parentSpanId

string

Facultatif. ID du segment parent de ce segment, le cas échéant. Vide pour le segment racine.
displayName

string

Obligatoire. Nom lisible par l'humain du segment (par exemple, invoke_agent, generate_content, execute_tool <toolName>).
spanKind

enum (SpanKind)

Facultatif. Type de la portée.
startTime

string (Timestamp format)

Obligatoire. Heure de début de la période.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Obligatoire. Heure de fin de la période.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Facultatif. Attributs de portée non liés au contenu suivant les conventions sémantiques OpenTelemetry GenAI (par exemple, gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens). Les valeurs numériques sont encodées sous forme de chaîne. La journalisation de l'observabilité est activée par défaut pour ces services.
contentAttributes

map (key: string, value: string)

Facultatif. Attributs contenant du contenu (par exemple, requêtes, réponses, arguments et résultats d'outils). Par défaut, la journalisation de l'observabilité est désactivée pour ces journaux. Ils ne sont enregistrés que lorsque le client a activé la journalisation des contenus sensibles.
status

object (Status)

Facultatif. État de la portée. code est un google.rpc.Code. OK (0) indique le succès, et tout code non nul indique une erreur.
events[]

object (Event)

Facultatif. Événements ponctuels survenus au cours de la période.

SpanKind

Type de segment, aligné sur SpanKind d'OpenTelemetry.

Enums
SPAN_KIND_UNSPECIFIED Non spécifié. Traitée comme INTERNE.
INTERNAL Opération interne à l'agent (par exemple, invoke_agent).
SERVER Gestionnaire de requêtes entrantes synchrones.
CLIENT Requête sortante synchrone (par exemple, un appel de modèle ou d'outil).
PRODUCER Producteur asynchrone d'un message.
CONSUMER Consommateur asynchrone d'un message.

Événement

Événement temporel survenu pendant la durée (par exemple, un bloc diffusé).

Représentation JSON 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
Champs
displayName

string

Obligatoire. Nom de l'événement lisible par l'humain.
eventTime

string (Timestamp format)

Obligatoire. Heure à laquelle l'événement s'est produit.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
attributes

map (key: string, value: string)

Facultatif. Attributs non liés au contenu décrivant l'événement.