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

Grava a trajetória de execução de uma única interação do agente para o registro de observabilidade interna. Esse método é usado por clientes de agentes próprios, como o agente Cowork para computador do Gemini Enterprise. O registro em registros é controlado pelo ObservabilityConfig do mecanismo. Os atributos que contêm conteúdo são editados, a menos que o registro de conteúdo sensível esteja ativado, e a trajetória é gravada como um objeto JSON em um bucket fixo do GCS interno do Google para depuração (nunca em um projeto do cliente). Ela NÃO é mantida no evento do usuário ou na loja de recomendações.

Solicitação HTTP


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

Os URLs usam a sintaxe de Transcodificação gRPC.

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. O Engine a que a trajetória pertence, no formato projects/{project}/locations/{location}/collections/{collection}/engines/{engine}. O registro de observabilidade é controlado por ObservabilityConfig deste mecanismo: a trajetória só é registrada (gravada como um objeto JSON em um bucket fixo do GCS interno do Google) quando a observabilidade está ativada para o mecanismo, e os atributos que contêm conteúdo só são incluídos quando o registro sensível está ativado.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
Campos
agentTrajectory

object (AgentTrajectory)

Obrigatório. A trajetória do agente a ser registrada.

Corpo da resposta

Mensagem de resposta para o método UserEventService.WriteAgentTrajectory.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "acceptedSpanCount": integer
}
Campos
acceptedSpanCount

integer

O número de intervalos aceitos para o registro de observabilidade.

Escopos de autorização

Requer um dos seguintes escopos do 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 mais informações, consulte Authentication Overview.

Permissões do IAM

Requer a seguinte permissão do IAM no recurso parent:

  • discoveryengine.engines.createEngineUserData

Para mais informações, consulte a documentação do IAM.

AgentTrajectory

O AgentTrajectory captura o rastreamento de execução de uma única interação do agente, modelada nas convenções semânticas de IA generativa do OpenTelemetry. Ele é informado por clientes próprios (por exemplo, o agente Cowork para computador do Gemini Enterprise) apenas para registro interno de capacidade de observação. Ele não é mantido no evento do usuário / repositório de recomendações.

O servidor controla o registro em ObservabilityConfig do mecanismo, encobre atributos que contêm conteúdo, a menos que o registro de conteúdo sensível esteja ativado, e grava a trajetória como um objeto JSON em um bucket fixo do GCS interno do Google para depuração (nunca em um projeto do cliente).

Representação JSON 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
Campos
spans[]

object (Span)

Obrigatório. Os intervalos que compõem essa interação do agente. Todos os intervalos precisam compartilhar o mesmo Span.trace_id.
sessionId

string

Opcional. Um identificador exclusivo da sessão do agente a que esta vez pertence.
resourceAttributes

map (key: string, value: string)

Opcional. Atributos no nível do recurso compartilhados por todos os intervalos, seguindo as convenções semânticas de recursos do OpenTelemetry (por exemplo, service.name, gen_ai.agent.name, gen_ai.agent.id). Eles são ativados para geração de registros de observabilidade por padrão.

Período

Um único intervalo na trajetória do agente, alinhado ao modelo de dados de intervalo do OpenTelemetry.

Representação 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

Obrigatório. Um ID de rastreamento de 32 caracteres hexadecimais (16 bytes) compartilhado por todos os períodos da vez.
spanId

string

Obrigatório. Um ID de período de 16 caracteres hexadecimais (8 bytes) que identifica exclusivamente esse período no rastreamento.
parentSpanId

string

Opcional. O ID do período pai deste período, se houver. Vazio para o período raiz.
displayName

string

Obrigatório. Um nome legível por humanos para o intervalo (por exemplo, invoke_agent, generate_content, execute_tool <toolName>).
spanKind

enum (SpanKind)

Opcional. O tipo do intervalo.
startTime

string (Timestamp format)

Obrigatório. O horário de início do intervalo.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Obrigatório. O horário de término do intervalo.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "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)

Opcional. Atributos de extensão não relacionados a conteúdo seguindo as convenções semânticas de IA generativa do OpenTelemetry (por exemplo, gen_ai.system, gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens). Os valores numéricos são codificados como strings. Eles são ativados para o registro de observabilidade por padrão.
contentAttributes

map (key: string, value: string)

Opcional. Atributos que contêm conteúdo (por exemplo, comandos, respostas, argumentos e resultados de ferramentas). Por padrão, eles não participam da geração de registros de observabilidade e só são registrados quando o cliente ativa a geração de registros de conteúdo sensível.
status

object (Status)

Opcional. O status do intervalo. code é um google.rpc.Code. OK (0) indica sucesso, e qualquer código diferente de zero indica um erro.
events[]

object (Event)

Opcional. Eventos com carimbo de data/hora que ocorreram durante o período.

SpanKind

O tipo do intervalo, alinhado com o SpanKind do OpenTelemetry.

Tipos enumerados
SPAN_KIND_UNSPECIFIED Não especificado. Tratado como INTERNAL.
INTERNAL Uma operação interna no agente (por exemplo, invoke_agent).
SERVER Um gerenciador de solicitações síncronas recebidas.
CLIENT Uma solicitação síncrona de saída (por exemplo, uma chamada de modelo ou ferramenta).
PRODUCER Um produtor assíncrono de uma mensagem.
CONSUMER Um consumidor assíncrono de uma mensagem.

Evento

Um evento cronometrado que ocorreu durante o período (por exemplo, um trecho transmitido).

Representação JSON 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
Campos
displayName

string

Obrigatório. Um nome legível por humanos para o evento.
eventTime

string (Timestamp format)

Obrigatório. O horário em que o evento ocorreu.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "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)

Opcional. Atributos não relacionados ao conteúdo que descrevem o evento.