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 bucket)，且只有在啟用敏感記錄功能時，系統才會納入含有內容的屬性。

要求主體

要求主體包含下列結構的資料：

JSON 表示法 
{
  "agentTrajectory": {
    object (AgentTrajectory)
  }
}
欄位
agentTrajectory

object (AgentTrajectory)

這是必要旗標，要記錄的代理程式軌跡。

回應主體

UserEventService.WriteAgentTrajectory 方法的回應訊息。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "acceptedSpanCount": integer
}
欄位
acceptedSpanCount

integer

接受用於觀測能力記錄的時距數量。

授權範圍

需要下列其中一種 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 bucket，以利偵錯 (絕不會寫入客戶專案)。

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

object (Span)

這是必要旗標，構成這個代理回合的範圍。所有範圍都必須共用相同的 Span.trace_id。
sessionId

string

選用。這個輪次所屬的代理程式工作階段專屬 ID。
resourceAttributes

map (key: string, value: string)

選用。所有時距共用的資源層級屬性，遵循 OpenTelemetry 資源語意慣例 (例如 service.name、gen_ai.agent.name、gen_ai.agent.id)。這些屬性預設會加入可觀測性記錄。

時距

代理程式軌跡中的單一時距，與 OpenTelemetry 時距資料模型一致。

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，由回合的所有範圍共用。
spanId

string

這是必要旗標，16 個十六進位字元 (8 位元組) 的範圍 ID，可明確識別追蹤記錄中的這個範圍。
parentSpanId

string

選用。這個時距的父項時距 ID (如有)。根時距為空白。
displayName

string

這是必要旗標，人類可讀的範圍名稱 (例如 invoke_agent、generate_content、execute_tool <toolName>)。
spanKind

enum (SpanKind)

選用。時距種類。
startTime

string (Timestamp format)

這是必要旗標，範圍的開始時間。

使用 RFC 3339，產生的輸出內容一律會經過 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 正規化，並使用 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 語意慣例的非內容時距屬性 (例如 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)

選用。範圍的狀態。code 是 google.rpc.Code；OK (0) 表示成功，任何非零代碼則表示錯誤。
events[]

object (Event)

選用。這段時間內發生的計時事件。

SpanKind

時距類型，與 OpenTelemetry SpanKind 一致。

列舉
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 正規化，並使用 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)

選用。描述活動的非內容屬性。