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

写入单个代理回合的执行轨迹，以用于内部可观测性日志记录。第一方代理客户端（例如 Gemini Enterprise 桌面版 Cowork 代理）会使用此方法。日志记录受引擎的 ObservabilityConfig 限制；除非启用了敏感内容日志记录，否则包含内容的属性会被编校，并且轨迹会作为 JSON 对象写入固定的 Google 内部 GCS 存储桶以进行调试（绝不会写入客户项目）。不会持久保存到用户事件或推荐存储区。

HTTP 请求

：


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

网址使用 gRPC 转码语法。

路径参数

参数
parent

string

必需。轨迹所属的 Engine，格式为 projects/{project}/locations/{location}/collections/{collection}/engines/{engine}。可观测性日志记录受此引擎的 ObservabilityConfig 限制：只有在为引擎启用可观测性时，轨迹才会记录（以 JSON 对象的形式写入固定的 Google 内部 GCS 存储桶）；只有在启用敏感日志记录时，才会包含包含内容的属性。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
字段
agentTrajectory

object (AgentTrajectory)

必需。要记录的代理轨迹。

响应正文

UserEventService.WriteAgentTrajectory 方法的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "acceptedSpanCount": integer
}
字段
acceptedSpanCount

integer

已接受用于可观测性日志记录的 span 的数量。

授权范围

需要以下 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

如需了解详情，请参阅 Authentication Overview。

IAM 权限

需要拥有 parent 资源的以下 IAM 权限：

  • discoveryengine.engines.createEngineUserData

如需了解详情，请参阅 IAM 文档。

AgentTrajectory

AgentTrajectory 会捕获单个代理回合的执行轨迹，并根据 OpenTelemetry GenAI 语义惯例进行建模。它由第一方客户端（例如 Gemini Enterprise 桌面版 Cowork 代理）报告，仅用于内部可观测性日志记录；不会持久保存到用户事件 / 推荐存储区。

服务器会根据引擎的 ObservabilityConfig 门控日志记录，除非启用了敏感内容日志记录，否则会编辑包含内容的属性，并将轨迹作为 JSON 对象写入固定的 Google 内部 GCS 存储桶以进行调试（绝不会写入客户项目）。

JSON 表示法 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
字段
spans[]

object (Span)

必需。构成此代理回合的 span。所有 span 都必须共享同一 Span.trace_id。
sessionId

string

可选。相应轮次所属的代理会话的唯一标识符。
resourceAttributes

map (key: string, value: string)

可选。所有 span 共享的资源级属性，遵循 OpenTelemetry 资源语义惯例（例如 service.name、gen_ai.agent.name、gen_ai.agent.id）。默认情况下，这些属性会选择加入可观测性日志记录。

span

智能体轨迹中的单个 span，与 OpenTelemetry span 数据模型保持一致。

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)
    }
  ]
}
字段
traceId

string

必需。一个 32 个十六进制字符（16 字节）的轨迹 ID，由该轮次的所有 span 共享。
spanId

string

必需。一个 16 个十六进制字符（8 字节）的 span ID，用于在轨迹中唯一标识相应 span。
parentSpanId

string

可选。相应 span 的父级的 span ID（如有）。对于根 span，该字段为空。
displayName

string

必需。span 的人类可读名称（例如 invoke_agent、generate_content、execute_tool <toolName>）。
spanKind

enum (SpanKind)

可选。跨度的种类。
startTime

string (Timestamp format)

必需。时间段的开始时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

必需。时间段的结束时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
attributes

map (key: string, value: string)

可选。遵循 OpenTelemetry GenAI 语义惯例的非内容 span 属性（例如 gen_ai.system、gen_ai.operation.name、gen_ai.request.model、gen_ai.usage.input_tokens）。数值采用字符串编码。这些默认选择启用可观测性日志记录。
contentAttributes

map (key: string, value: string)

可选。包含内容的属性（例如提示、回答、工具实参和结果）。这些内容默认选择不进行可观测性日志记录，只有在客户启用敏感内容日志记录时才会记录。
status

object (Status)

可选。span 的状态。code 是一个 google.rpc.Code；OK (0) 表示成功，任何非零代码表示错误。
events[]

object (Event)

可选。相应时间段内发生的定时事件。

SpanKind

与 OpenTelemetry SpanKind 一致的 span 类型。

枚举
SPAN_KIND_UNSPECIFIED 未指定。视为内部。
INTERNAL 代理中的内部操作（例如 invoke_agent）。
SERVER 同步传入请求处理程序。
CLIENT 同步的出站请求（例如模型或工具调用）。
PRODUCER 消息的异步生产者。
CONSUMER 消息的异步消费者。

事件

在时间段内发生的定时事件（例如，流式传输的块）。

JSON 表示法 
{
  "displayName": string,
  "eventTime": string,
  "attributes": {
    string: string,
    ...
  }
}
字段
displayName

string

必需。事件的人类可读名称。
eventTime

string (Timestamp format)

必需。事件发生的实际时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
attributes

map (key: string, value: string)

可选。描述活动的非内容属性。