会話ロギングを使用すると、会話型分析 API データ エージェントの会話をプロジェクトの BigQuery テーブルに記録できます。これにより、回答の品質の確認、導入状況の追跡、費用のモニタリングが可能になります。各ターンについて、ログにはユーザーの質問、エージェントの回答、レイテンシ、モデルトークンの使用状況、エージェント、会話、ユーザーごとにターンをグループ化するために必要な識別子が記録されます。行は、BigQuery Storage Write API(gRPC)を介して BigQuery エージェント分析スキーマを使用して書き込まれます。データソースが BigQuery テーブルを参照するデータ エージェントのロギングを有効にするには、bigqueryAgentAnalyticsEnabled フィールドと bigqueryAgentAnalyticsTable フィールドを設定します。手順については、会話ロギングを有効にするをご覧ください。
ログに記録される内容
ログに記録された各ターンでは、次の情報を記録する複数のイベント行(イベント)が宛先テーブルに書き込まれます。
ユーザーの質問。
エージェントの回答: テキスト、分析情報、前提条件、推奨されるフォローアップ質問、引用元、データ結果またはグラフの名前。
ターンごとのレイテンシ。
モデル呼び出しごとのモデルトークンの使用状況、モデル バージョン、終了理由(モデルがトークンの生成を停止した理由)。
データ エージェント ID と会話 ID(会話参照を使用したチャットの場合)。これにより、1 つのテーブルで複数のエージェントを分析できます。
ユーザー ID。ユーザー ID の詳細については、ユーザー ID をご覧ください。
ステータスとエラーの詳細。
ログに記録されない内容
会話ロギングでは、次のものは記録されません。
エージェントが実行する SQL クエリ: ログには、最終的な回答と、参照されたデータの結果とグラフの名前が含まれますが、それらを生成したクエリは含まれません。ただし、ユーザーがエージェントに SQL の表示や説明を明示的にリクエストした場合は、回答テキストに SQL が表示されることがあります。
エージェントのツール呼び出し: 各モデル呼び出しは 1 つの
LLM_RESPONSE行を書き込みます。これには、モデルがツールを実行することを決定した呼び出しも含まれます。行が書き込まれる前に、モデルの出力(呼び出したツールの名前と引数を含む)が削除されます。トークンの使用状況、モデル バージョン、終了理由のみが保持されます。ユーザー フィードバック: 高評価または低評価のフィードバックはログに記録されません。
データ エージェントを使用しないステートレス API 呼び出しなど、一部の会話はまったくログに記録されません。サポートされていない会話サーフェスの詳細については、制限事項をご覧ください。
会話ロギングの仕組み
会話ロギングが有効になっているデータ エージェントとユーザーがチャットすると、会話型分析は次のステージで各ターンを処理します。
構成: エージェントのオーナーが会話ロギングを有効にし、会話型分析 API を使用して、エージェントのプロジェクト内の既存の宛先データセットとテーブル名を指定します。
質問: ユーザーがエージェントに質問を送信します。独自のアプリケーションから Conversational Analytics API を呼び出す場合は、ユーザーに通知する責任があります。BigQuery Studio でエージェントとチャットするユーザーには、会話がログに記録されるという通知が表示されます。
プライバシー チェック: エージェントがターンを開始する前に、プライバシー チェックがチャット ユーザーの認証情報を使用して、エージェントのナレッジソース テーブル(BigQuery データソース)のメタデータを読み取ります。このチェックでは、行レベルのセキュリティ(行アクセス ポリシー)、列レベルのセキュリティ(ポリシータグ)、動的データ マスキングを使用しているテーブルがないことを確認します。チェックでポリシーが見つかった場合、またはポリシーがないことを確認できない場合、ターンはログに記録されず、エージェントはユーザーの質問に回答します。
回答: エージェントは通常どおりユーザーに回答します。
書き込み: プロジェクトの会話型分析 API サービス エージェント(
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com)が、Storage Write API(gRPC)を介してログ行を宛先テーブルに書き込みます。最初のログに記録されたターンで、サービス エージェントはテーブルが存在しない場合にテーブルを作成します。クエリ: 通常、回答が完了してから数秒以内に行が表示されます。お届け日数は保証されません。
ロギングエラーによってターンが失敗することはありません。プライバシー チェックとログの書き込みによってレイテンシが増加する可能性があります。ログ データセットに対する権限がない、データセットが存在しない、割り当てが不足している場合でも、チャット リクエストや API 呼び出しは失敗しません。会話型分析では、チャット インターフェース、API レスポンス、Cloud Logging でロギングエラーが報告されません。
プライバシー、データ ガバナンス、セキュリティ
エージェントの会話ロギングを有効にする場合は、エンドユーザーへの通知、データアクセス、暗号化、ネットワーク制御、監査ロギングがログにどのように適用されるかを確認してください。
エンドユーザーへの通知とログに記録されるコンテンツ
次の通知とルールは、会話ロギングが記録する内容と、記録されたデータを表示できるユーザーを管理します。
BigQuery Studio のエンドユーザー向け通知: エージェントの会話ロギングが有効になっている場合、BigQuery Studio でエージェントとチャットするユーザーには、会話ロギングが有効になっているときに、ユーザーが最初のプロンプトを送信する前の新しい会話画面など、次の通知が表示されます。
すべてのプロンプトと回答は BigQuery に記録され、データセットの権限を持つユーザーがアクセスできます。
API を使用する際の責任: データ エージェントで会話ロギング(トレース ロギング)を有効にし、独自のアプリケーションまたは統合を通じてそのエージェントをエンドユーザーが利用できるようにした場合、Google はそれらのユーザーに通知を表示できません。適用される法律およびエンドユーザーとの契約に基づいて、ログに記録された会話に適用される通知、開示、同意については、お客様が責任を負うものとします。詳細については、Conversational Analytics API のセキュリティ、プライバシー、リスク、コンプライアンスをご覧ください。
ログの内容と閲覧できるユーザー: 宛先テーブルには、次のプライバシー ルールに基づいて質問と回答のコンテンツが保存されます。
完全な質問と回答: 回答には、ナレッジソースから返された値を含めることができます。ログテーブルを読み取ることができるユーザーは、エージェントがユーザーに返したデータ(ソーステーブルで読み取ることができないデータを含む)を表示できます。このコンテンツを表示する必要があるユーザーにのみ、ログ データセットへの読み取りアクセス権を付与します。
ユーザー ID と書き込み場所:
user_id列は、質問した呼び出し元を識別します(ユーザー ID を参照)。行は、エージェントのプロジェクトで構成した宛先にのみ書き込まれます。行レベルのセキュリティ、列レベルのセキュリティ、またはデータ マスキングが適用されたテーブル: エージェントのナレッジソースで行レベルのセキュリティ(行アクセス ポリシー)、列レベルのセキュリティ(ポリシータグ)、または動的データ マスキングが使用されている場合、そのターンはログに記録されません。プライバシー チェックでは、
bigquery-public-data内のテーブルはスキップされ、ナレッジソースとして選択したテーブルとビューのみが確認されます。ビューの背後にあるテーブルは確認されません。これらのポリシーを使用するテーブルのビューはチェックに合格するため、そのターンをログに記録できます。ロギングを有効にする前に、ビューの背後にあるテーブルで行アクセス ポリシー、ポリシータグ、データ マスキングが使用されていないことを確認してください。
これらのポリシーのいずれかを後でソーステーブルに追加すると、すでにログに記録されている行はログテーブルに残ります。保持ポリシーまたはガバナンス ポリシーでこれらの行の保持が禁止されている場合は、削除します。
アクセス制御、暗号化、ネットワーク セキュリティ
会話ログの保持、アクセス、暗号化、境界セキュリティは、次の設定を使用して管理できます。
ログ データセットの保持とアクセス制御: 宛先テーブルの保持、データセット ロール、テーブル ポリシー、監査ログを構成します。
保持: Google はログ行を削除しません。ポリシーに一致するログ データセットまたはテーブルにパーティションの有効期限を設定します(例: 90 日)。
最小権限: ログ データセットを他のデータセットから分離して、共有の会話型分析 API サービス エージェントの書き込みアクセスが他のテーブルにアクセスしないようにします。アナリストにログ データセットに対する
roles/bigquery.dataViewerを付与するか、承認済みビューまたは承認済みデータセットへのアクセス権のみを付与します。ログテーブルの列レベルと行レベルの制御: ポリシータグ、データ マスキング、行アクセス ポリシーをログテーブル自体(
contentやuser_idなど)に適用できます。これらのログテーブル コントロールは、ナレッジソースのプライバシー チェックに影響しません。監査ロギング: データ エージェントの構成変更とログテーブル オペレーションが監査ログに記録されます。詳細については、監査対象オペレーションをご覧ください。
CMEK、VPC Service Controls、データ所在地: 会話ロギングには、次の暗号化、境界、ロケーションの制御が適用されます。
CMEK: ログ データセットで顧客管理の Cloud KMS 鍵(CMEK)を使用する場合は、BigQuery 暗号化サービス アカウント(
bq-PROJECT_NUMBER@bigquery-encryption.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.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)が適用されるログ データセットのロケーションに保存されます。
サービス エージェントと呼び出し元の属性
ログテーブルの作成と更新、行の追加は、チャット ユーザーではなく、会話型分析 API サービス エージェントが行います。これらのオペレーションを実行するには、サービス エージェントにログ データセットに対する BigQuery データ編集者(roles/bigquery.dataEditor)ロールが必要です。
Cloud Audit Logs が記録する監査ログエントリでは、authenticationInfo.principalEmail フィールド(またはフェデレーション ID の authenticationInfo.principalSubject)によって、各オペレーションを実行したプリンシパルが識別されます。
ログテーブルの作成、スキーマの更新、行の追加: サービス エージェント
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com。データ エージェント構成リクエスト(
CreateDataAgent、CreateDataAgentSync、UpdateDataAgent、UpdateDataAgentSync): API を呼び出すユーザー、サービス アカウント、またはフェデレーション ID。委任されたサービス アカウントの認証情報が適用される場合、これらのエントリにはauthenticationInfo.serviceAccountDelegationInfoも含まれます。
監査対象のオペレーション
Cloud Audit Logs は、次のサービスの会話ロギング構成の変更とログテーブル オペレーションを記録します。
会話型分析 API: 次のメソッドは、
geminidataanalytics.googleapis.comで監査ログを生成します。CreateDataAgent、CreateDataAgentSync、UpdateDataAgent、UpdateDataAgentSyncは、宛先プロジェクト、データセット、テーブルなど、エージェントのbigqueryAgentAnalyticsEnabledフィールドとbigqueryAgentAnalyticsTableフィールドを記録する管理アクティビティ監査ログを生成します。SetAgentOpsObservabilityは、リクエストのdataSourceType、telemetryEnabled、bqaaEnabled、updateMaskフィールドを記録する管理アクティビティ監査ログを生成します。RetrieveAgentOpsObservabilityは、geminidataanalytics.googleapis.comで対応するADMIN_READまたはDATA_READ監査ログタイプが有効になっている場合に、データアクセス監査ログを生成します。
BigQuery: サービス エージェントがログテーブルに対して行うオペレーションと、ログテーブルに対して実行するクエリによって、次の監査ログが生成されます。
ログテーブルの作成とスキーマの更新により、
bigquery.googleapis.comに管理アクティビティ監査ログが生成されます。Storage Write API(gRPC)を介して行を追加すると、
google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRowsメソッドのデータアクセス監査ログが生成されます。これには、TableDataChangeメタデータ(WRITE_API_APPEND_ROWS)が含まれます。これらのエントリでは、bigquerystorage.googleapis.comではなくbigquery.googleapis.comサービス名が使用されます。bigquerystorage.googleapis.comを使用するのは、ポリシー拒否監査ログのみです。ログテーブルに対するクエリは、
bigquery.googleapis.comの下にデータアクセスの監査ログ(JobInsertion、JobChange、TableDataReadエントリなど)を生成します。
詳細については、会話型分析 API の監査ロギングと BigQuery 監査ログの概要をご覧ください。
制限事項
会話ロギングには次の制限があります。
BigQuery Studio エージェント エディタの [プレビュー] ペインはログに記録されません。
データ エージェントを使用しないステートレス API 呼び出しはログに記録されません。
特定のテーブルではなく検索スコープを使用するエージェントや、BigQuery テーブルを宣言しないエージェントはログに記録されません。BigQuery プロパティ グラフのみ(BigQuery テーブルなし)をナレッジソースとして構成するエージェントはログに記録されません。
生成された SQL、ツール呼び出し、Agent Development Kit(ADK)ツールまたはリクエスト イベント(
TOOL_STARTING、TOOL_COMPLETED、TOOL_ERROR、LLM_REQUEST)はログに記録されません。回答と、そのデータ結果とグラフの名前のみがログに記録されます。検証済みクエリから直接回答されたターンでは、LLM_RESPONSE行は書き込まれません。また、検証済みクエリの失敗したターンはログに記録されません。ユーザーからの高評価 / 低評価のフィードバックは記録されません。
ナレッジソースで行アクセス ポリシー、列レベルのセキュリティ(ポリシータグ)、またはデータ マスキング(列に直接適用されたデータポリシーを含む)が使用されている場合、ターンはログに記録されません。プライバシー チェックでこれらのポリシーを確認できない場合(チャット ユーザーにテーブルのポリシー メタデータを検査する権限がない場合や、チェックがタイムアウトした場合など)も、ターンはログに記録されません。このチェックでは、ビューを介してその背後にあるテーブルを調べることはありません。
BigQuery テーブル エージェントのみがサポートされています。Looker、データポータル、AlloyDB for PostgreSQL、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 でクエリをフィルタして、スキャンされるバイト数を減らします。事前ターン プライバシー チェックでは、テーブル メタデータが読み取られ、ドライラン クエリが無料で実行されます。