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

内部オブザーバビリティ ロギング用に、単一のエージェント ターンの実行軌跡を書き込みます。このメソッドは、ファーストパーティのエージェント クライアント（Gemini Enterprise デスクトップ Cowork エージェントなど）で使用されます。ロギングはエンジンの ObservabilityConfig によって制御されます。機密コンテンツのロギングが有効になっていない限り、コンテンツを含む属性は編集され、軌跡はデバッグ用に固定の Google 内部 GCS バケットに JSON オブジェクトとして書き込まれます（顧客プロジェクトには書き込まれません）。ユーザー イベントやレコメンデーション ストアには保存されません。

HTTP リクエスト


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

この URL は gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
parent

string

必須。軌跡が属する Engine（projects/{project}/locations/{location}/collections/{collection}/engines/{engine} 形式）。オブザーバビリティ ロギングは、このエンジンの ObservabilityConfig によって制御されます。オブザーバビリティがエンジンで有効になっている場合にのみ、軌跡がログに記録され（固定の Google 内部 GCS バケットに JSON オブジェクトとして書き込まれます）。コンテンツを含む属性は、機密情報のロギングが有効になっている場合にのみ含まれます。

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

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 バケットに書き込みます（お客様のプロジェクトには書き込みません）。

JSON 表現 
{
  "spans": [
    {
      object (Span)
    }
  ],
  "sessionId": string,
  "resourceAttributes": {
    string: string,
    ...
  }
}
フィールド
spans[]

object (Span)

必須。このエージェント ターンを構成するスパン。すべてのスパンは同じ Span.trace_id を共有しなければなりません。
sessionId

string

省略可。このターンが属するエージェント セッションの固有識別子。
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 進数（16 バイト）のトレース ID。
spanId

string

必須。トレース内でこのスパンを一意に識別する 16 桁の 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 として扱われます。
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)

省略可。イベントを説明するコンテンツ以外の属性。