会話ロギングの概要

会話型分析の会話ロギングを使用すると、データ エージェントの会話をプロジェクトの BigQuery テーブルに記録できます。これにより、会話型分析エージェント全体で回答の品質の確認、導入状況の追跡、費用のモニタリングを行うことができます。各ターンについて、ログにはユーザーの質問、エージェントの回答、レイテンシ、モデルトークンの使用状況、エージェント、会話、ユーザーごとにターンをグループ化するために必要な識別子が記録されます。行は、BigQuery Storage Write API（gRPC）を介して BigQuery エージェント分析スキーマを使用して書き込まれます。

ログに記録される内容

ログに記録された各ターンでは、次の情報を記録する複数のイベント行（イベント）が宛先テーブルに書き込まれます。

  • ユーザーの質問。

  • エージェントの回答: テキスト、分析情報、前提条件、推奨されるフォローアップ質問、引用元、データ結果やグラフの名前。

  • ターンごとのレイテンシ。

  • モデルのトークン使用量、モデル バージョン、各モデル呼び出しの終了理由（モデルがトークンの生成を停止した理由）。

  • データ エージェント ID と会話 ID。これにより、1 つのテーブルで複数のエージェントを分析できます。

  • ユーザー識別子。ユーザー識別子の詳細については、ユーザー ID をご覧ください。

  • ステータスとエラーの詳細。

ログに記録されない内容

会話ロギングでは、次のものは記録されません。

  • エージェントが実行する SQL クエリ: ログには、最終的な回答と、参照されたデータの結果とグラフの名前が含まれますが、それらを生成したクエリは含まれません。ただし、ユーザーがエージェントに SQL の表示や説明を明示的にリクエストした場合は、回答テキストに SQL が表示されることがあります。

  • エージェントのツール呼び出し: 各モデル呼び出しは 1 つの LLM_RESPONSE 行を書き込みます。これには、モデルがツールを実行することを決定した呼び出しも含まれます。行が書き込まれる前に、モデルの出力（呼び出したツールの名前と引数を含む）が削除されます。トークンの使用状況、モデル バージョン、終了理由のみが保持されます。

  • ユーザー フィードバック: 高評価または低評価のフィードバックはログに記録されません。

BigQuery Studio のプレビュー ペインでの会話など、一部の会話はまったくログに記録されません。サポートされていない会話サーフェスの詳細については、制限事項をご覧ください。

会話ロギングの仕組み

会話ロギングが有効になっているデータ エージェントとユーザーがチャットすると、会話分析は次のステージで各ターンを処理します。

  1. 構成: エージェント オーナーが会話ロギングを有効にし、BigQuery Studio のエージェントのプロジェクトで既存の宛先データセットとテーブル名を選択します。

  2. 質問: ユーザーがエージェントに質問を送信します。BigQuery Studio では、会話がログに記録されるという通知がユーザーに表示されます。

  3. プライバシー チェック: エージェントがターンを開始する前に、プライバシー チェックがチャット ユーザーの認証情報を使用して、エージェントのナレッジソース テーブルのメタデータを読み取ります。このチェックでは、テーブルで行レベルのセキュリティ（行アクセス ポリシー）、列レベルのセキュリティ（ポリシータグ）、動的データ マスキングが使用されていないことを確認します。チェックでポリシーが見つかった場合、またはポリシーがないことを確認できない場合、ターンはログに記録されず、エージェントはユーザーの質問に回答します。

  4. 回答: エージェントは通常どおりユーザーに回答します。

  5. 書き込み: プロジェクトの Conversational Analytics API サービス エージェント（service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.s3ns-system.iam.gserviceaccount.com）が、Storage Write API（gRPC）を介して宛先テーブルにログ行を書き込みます。最初のログに記録されたターンで、サービス エージェントはテーブルが存在しない場合にテーブルを作成します。

  6. クエリ: 通常、回答が完了してから数秒以内に行が表示されます。お届け日時の指定はできません。

ロギングエラーによってターンが失敗することはありません。プライバシー チェックとログの書き込みによってレイテンシが増加する可能性があります。ログ データセットに権限がない、データセットが存在しない、割り当てが不足している場合でも、チャット リクエストは失敗しません。会話分析では、チャット インターフェースや Cloud Logging でロギングの失敗は報告されません。

プライバシー、データ ガバナンス、セキュリティ

エージェントの会話ロギングを有効にする場合は、エンドユーザーへの通知、データアクセス、暗号化、ネットワーク制御がログにどのように適用されるかを確認してください。

エンドユーザーへの通知とログに記録されるコンテンツ

次の通知とルールは、会話ロギングが記録する内容と、記録されたデータを表示できるユーザーを規定しています。

  • BigQuery Studio のエンドユーザー向け通知: エージェントの会話ロギングが有効になっている場合、BigQuery Studio でエージェントとチャットするユーザーには、会話ロギングが有効になっているときに、次の通知が表示されます。これには、ユーザーが最初のプロンプトを送信する前の新しい会話画面も含まれます。

    すべてのプロンプトと回答は BigQuery に記録され、データセットの権限を持つユーザーがアクセスできます。

  • API を使用する際の責任: データ エージェントで会話ロギング（トレース ロギング）を有効にし、独自のアプリケーションまたは統合を介してそのエージェントをエンドユーザーが利用できるようにした場合、Google はそれらのユーザーに通知を表示できません。適用される法律およびエンドユーザーとの契約に基づいて、ログに記録された会話に適用される通知、開示、同意については、お客様が責任を負うものとします。詳細については、Conversational Analytics API のセキュリティ、プライバシー、リスク、コンプライアンスをご覧ください。

  • ログの内容と閲覧できるユーザー: 宛先テーブルには、次のプライバシー ルールに基づいて質問と回答のコンテンツが保存されます。

    • 完全な質問と回答: 回答には、ナレッジソースから返された値を含めることができます。ログテーブルを読み取ることができるユーザーは、エージェントがユーザーに返したデータ（ソーステーブルで読み取ることができないデータを含む）を表示できます。このコンテンツを表示する必要があるユーザーにのみ、ログ データセットへの読み取りアクセス権を付与します。

    • ユーザー識別子と書き込み場所: user_id 列は、質問した呼び出し元を識別します（ユーザー ID を参照）。行は、エージェントのプロジェクトで構成した宛先にのみ書き込まれます。

    • 行レベルのセキュリティ、列レベルのセキュリティ、またはデータ マスキングが適用されたテーブル: エージェントのナレッジソースで行レベルのセキュリティ（行アクセス ポリシー）、列レベルのセキュリティ（ポリシータグ）、または動的データ マスキングが使用されている場合、そのターンはログに記録されません。プライバシー チェックでは、bigquery-public-data のテーブルはスキップされ、ナレッジソースとして選択したテーブルとビューのみが参照されます。ビューの背後にあるテーブルは参照されません。

      • これらのポリシーを使用するテーブルのビューはチェックに合格するため、そのターンをログに記録できます。ロギングを有効にする前に、ビューの背後にあるテーブルで行アクセス ポリシー、ポリシータグ、データ マスキングが使用されていないことを確認してください。

      • これらのポリシーのいずれかを後でソーステーブルに追加すると、すでにログに記録されている行はログテーブルに残ります。保持ポリシーまたはガバナンス ポリシーでこれらの行の保持が禁止されている場合は、削除します。

アクセス制御、暗号化、ネットワーク セキュリティ

会話ログの保持、アクセス、暗号化、境界セキュリティは、次の設定を使用して管理できます。

  • ログ データセットの保持とアクセス制御: 保持、データセット ロール、テーブル ポリシー、宛先テーブルの監査ログを構成します。

    • 保持: Google がログ行を削除することはありません。ポリシーに一致するログ データセットまたはテーブルにパーティションの有効期限を設定します（例: 90 日）。

    • 最小権限: ログ データセットを他のデータセットから分離して、共有の Conversational Analytics API サービス エージェントの書き込みアクセスが他のテーブルに及ばないようにします。アナリストにログ データセットに対する roles/bigquery.dataViewer を付与するか、承認済みビューまたは承認済みデータセットへのアクセス権のみを付与します。

    • ログテーブルの列レベルと行レベルの制御: ポリシータグ、データ マスキング、行アクセス ポリシーをログテーブル自体（content や user_id など）に適用できます。これらのログテーブル コントロールは、ナレッジソースのプライバシー チェックに影響しません。

    • 監査ロギング: データ エージェントの変更は、管理アクティビティ監査ログに記録されます。BigQuery 監査ログでは、サービス エージェントによるテーブルの作成とメタデータの更新は bigquery.googleapis.com に記録され、Storage Write API（gRPC）による行の追加は bigquerystorage.googleapis.com に記録されます。

  • CMEK、VPC Service Controls、データ所在地: 会話ロギングには、次の暗号化、境界、ロケーションの制御が適用されます。

    • CMEK: ログ データセットで顧客管理の Cloud KMS 鍵（CMEK）を使用する場合は、BigQuery 暗号化サービス アカウント（bq-PROJECT_NUMBER@bigquery-encryption.s3ns-system.iam.gserviceaccount.com）に鍵の roles/cloudkms.cryptoKeyEncrypterDecrypter ロールを付与します。データ エージェントの CMEK は、ログテーブルではなくエージェント リソースを暗号化します（顧客管理の暗号鍵をご覧ください）。

    • VPC Service Controls: サービス境界を使用する場合は、エージェントのプロジェクトを含む境界に geminidataanalytics.googleapis.com と bigquery.googleapis.com の両方を含めます。サービス エージェントは、Google が管理するインフラストラクチャからログテーブルに書き込みます。境界で bigquery.googleapis.com が制限されている場合は、次のような上り（内向き）ルールを追加します。PROJECT_NUMBER は、エージェントのプロジェクト番号に置き換えます。

      - ingressFrom:
    identities:
    - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.s3ns-system.iam.gserviceaccount.com
    sources:
    - accessLevel: "*"
  ingressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - permission: bigquery.tables.get
      - permission: bigquery.tables.create
      - permission: bigquery.tables.update
      - permission: bigquery.tables.updateData
    resources:
    - projects/PROJECT_NUMBER

      詳細については、VPC Service Controls を使用して境界セキュリティを構成するをご覧ください。

    • データ所在地: ログ行と自動作成されたテーブルは、ログ データセットのロケーションに保存されます。このロケーションには、リソース ロケーションの組織のポリシー（gcp.resourceLocations）が適用されます。

制限事項

会話ロギングには次の制限があります。

  • BigQuery Studio エージェント エディタの [プレビュー] ペインはログに記録されません。

  • データ エージェントを使用しない直接会話はログに記録されません。

  • 特定のテーブルではなく検索スコープを使用するエージェントや、BigQuery テーブルを宣言しないエージェントはログに記録されません。BigQuery プロパティ グラフをナレッジソースとして構成するエージェントはログに記録されません。

  • 生成された SQL、ツール呼び出し、Agent Development Kit（ADK）ツールまたはリクエスト イベント（TOOL_STARTING、TOOL_COMPLETED、TOOL_ERROR、LLM_REQUEST）はログに記録されません。ログに記録されるのは、回答とそのデータ結果とグラフの名前のみです。検証済みクエリから直接回答されたターンでは LLM_RESPONSE 行は書き込まれず、検証済みクエリの失敗したターンはログに記録されません。

  • ユーザーからの高評価 / 低評価のフィードバックはログに記録されません。

  • ナレッジソースで行アクセス ポリシー、列レベルのセキュリティ（ポリシータグ）、データ マスキングが使用されている場合、またはプライバシー チェックを完了できない場合、ターンはログに記録されません。このチェックでは、ビューを介してその背後にあるテーブルを調べることはありません。

  • BigQuery テーブル エージェントのみがサポートされています。Looker、データポータル、AlloyDB、Spanner、Cloud SQL のデータソースはサポートされていません。

  • 宛先データセットは、エージェントと同じプロジェクトにすでに存在している必要があります。

  • 既存のテーブルに対するスキーマの変更は追加のみです。競合する列タイプまたはモードでは、そのテーブルへの書き込みが停止します。

  • 対象となるすべてのターンがサンプリング設定なしでログに記録されます。代わりにクエリ時にサンプリングします（すべてのエージェントの質問と回答をサンプリングして確認するをご覧ください）。

  • agent 列には、エージェントの表示名ではなく、エージェント タイプが格納されます。attributes のデータ エージェント ID を使用します。

  • 多くのエンドユーザーに 1 つのサービス アカウントを使用する API 呼び出し元には、すべての行にそのサービス アカウントのメールアドレスが表示されます。

  • 512,000 文字（500 * 1,024）を超えるテキスト値は、サフィックス ...[TRUNCATED] で切り捨てられ、削除された部分は復元できません。

  • 書き込みはベスト エフォートで行われ、再試行回数は制限されています。書き込みに失敗したターンはログに記録されず、再試行によって重複行が生成されることがあります（重複を排除するには event_id を使用します）。

  • エージェントは、プロジェクト レベルのオブザーバビリティ設定を継承しません。

料金

会話分析では、会話ロギングに対して個別に課金されることはありません。プロジェクトでは、BigQuery Storage Write API（gRPC）のデータ取り込み、ストレージ、分析クエリに対して標準の BigQuery 料金が適用されます。BigQuery Storage Write API（gRPC）の取り込みには、請求先アカウントごとに 1 か月あたり 2 TiB の無料使用量が含まれます。これは、Storage Write API（gRPC）の使用量全体で共有されます。timestamp でクエリをフィルタして、スキャンされるバイト数を減らします。事前ターン プライバシー チェックでは、テーブル メタデータが読み取られ、ドライラン クエリが無料で実行されます。

次のステップ