ADKに追加されたBigQuery Agent Analytics Pluginを試してみる

概要

Agent Development Kit（ADK）の1.19.0にBigQuery Agent Analytics Pluginが追加されました。

https://github.com/google/adk-python/releases/tag/v1.19.0

BigQuery Agent Analytics Pluginは、数行のコードを追加するだけで、リクエスト、レスポンス、LLMツールの呼び出しなどのアクティビティをBigQueryに追加することが可能です。

https://cloud.google.com/blog/products/data-analytics/introducing-bigquery-agent-analytics/?hl=en

従来では、エージェントの月次利用者数などを分析するためには、BigQueryのクライアントライブラリを用いて、自前で処理を追加する必要がありました。BigQuery Agent Analytics Pluginの登場によって、数行のコード追加のみでBigQueryへのデータ追加をできるようになりました。この機能の登場は、まさに多くの開発者が待ち望んでいたものではないかと思います。

本記事では、BigQuery Agent Analytics Pluginで構成したエージェントをAgentEngineにデプロイし、実際にBigQuery Agent Analytics Pluginがどんなものであるか試したいと思います。

BigQuery Agent Analytics Pluginを試してみる

準備

1. BigQueryにスキーマを構築

まず初めに、BigQuery側にデータセットとテーブルを用意します。
テーブルのスキーマ構成は、公式ドキュメントを参考にします。

https://google.github.io/adk-docs/tools/google-cloud/bigquery-agent-analytics/#schema-and-production-setup

以下のようにTerraformで定義しました。

resource "google_bigquery_dataset" "adk_agent_logs" {
  project    = "sample_project"
  dataset_id = "adk_agent_logs"
  location   = "asia-northeast1"

  description = "Event logs for ADK agents (contains the partitioned table agent_events)."
}

resource "google_bigquery_table" "agent_events" {
  project    = "sample_project"
  dataset_id = google_bigquery_dataset.adk_agent_logs.dataset_id
  table_id   = "agent_events"

  description = "Agent event stream with DAY partitioning on timestamp and clustering on event_type, agent, user_id."

  schema = jsonencode([
    {
      name        = "timestamp"
      type        = "TIMESTAMP"
      mode        = "REQUIRED"
      description = "The UTC time at which the event was logged."
    },
    {
      name        = "event_type"
      type        = "STRING"
      description = "Indicates the type of event being logged (e.g., 'LLM_REQUEST', 'TOOL_COMPLETED')."
    },
    {
      name        = "agent"
      type        = "STRING"
      description = "The name of the ADK agent or author associated with the event."
    },
    {
      name        = "session_id"
      type        = "STRING"
      description = "A unique identifier to group events within a single conversation or user session."
    },
    {
      name        = "invocation_id"
      type        = "STRING"
      description = "A unique identifier for each individual agent execution or turn within a session."
    },
    {
      name        = "user_id"
      type        = "STRING"
      description = "The identifier of the user associated with the current session."
    },
    {
      name        = "content"
      type        = "STRING"
      description = "The event-specific data (payload). Format varies by event_type."
    },
    {
      name        = "error_message"
      type        = "STRING"
      description = "Populated if an error occurs during the processing of the event."
    },
    {
      name        = "is_truncated"
      type        = "BOOLEAN"
      description = "Boolean flag indicates if the content field was truncated due to size limits."
    }
  ])

  # Time partitioning by DATE(timestamp)
  time_partitioning {
    type  = "DAY"
    field = "timestamp"
  }

  # Clustering (older provider versions may require attribute form)
  clustering = ["event_type", "agent", "user_id"]

  # Disable deletion protection to allow tf destroy if needed
  deletion_protection = false
}

2. AgentEngineのサービスエージェントに権限付与

次に、AgentEngineが使うサービスエージェント（[e-mail]）にBigQueryにデータを追加するための権限を付与します。
公式ドキュメントにも記載がある通り、roles/bigquery.jobUserとroles/bigquery.dataEditorの2つを付与します。

https://google.github.io/adk-docs/tools/google-cloud/bigquery-agent-analytics/#iam-permissions

以下のようにTerraformで定義しました。

resource "google_project_iam_member" "agent_engine_bigquery_job_user_role" {
  project = var.project_name
  role    = "roles/bigquery.jobUser"
  member  = "serviceAccount:[e-mail]"
}

resource "google_project_iam_member" "agent_engine_bigquery_data_editor_role" {
  project = var.project_name
  role    = "roles/bigquery.dataEditor"
  member  = "serviceAccount:[e-mail]"
}

3. エージェントをAgentEngineにデプロイ

最後に、エージェントをAgentEngineにデプロイします。
公式ドキュメントにも記載がある通り、Pythonコード上でBigQueryAgentAnalyticsPluginを利用することで、BigQuery Agent Analytics Pluginの利用が可能になります。

https://google.github.io/adk-docs/tools/google-cloud/bigquery-agent-analytics/#use-with-agent

以下のように定義を行い、プログラムを実行してAgentEngineにデプロイを行います。

bq_logging_plugin = BigQueryAgentAnalyticsPlugin(
    project_id=GOOGLE_CLOUD_PROJECT,
    dataset_id=AGENT_ANALYTICS_DATASET,
    table_id=AGENT_ANALYTICS_TABLE,
)

# この部分でplguinsとしてbq_logging_pluginを渡す
app = agent_engines.AdkApp(agent=root_agent, plugins=[bq_logging_plugin])

remote_app = agent_engines.create(
    display_name=AGENT_NAME,
    agent_engine=app,
    env_vars={
        "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
        "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
    },
    requirements=[
        "google-cloud-aiplatform[adk,agent_engines]",
    ],
)

エージェントを利用してBigQueryを確認

準備が完了したので、実際にエージェントを利用して、やりとりの内容がBigQueryに連携されるのか確認してみます。
REST経由やChatUIからSDK経由などでエージェントを呼び出すといったように、やり方は色々あると思いますが、今回は最近追加されたプレイグラウンド（プレビュー状態）からエージェントを呼び出してみます。

AgentEngineのコンソールからプレイグラウンドは利用することが可能です。

エージェントと数回やりとりをしてみたので、BigQueryを確認してみると、やりとりに関するデータが追加されていることが確認できました。

event_typeにはどんなものがあるのかは、公式ドキュメントに説明があるので、分析の際の参考になりそうです。

https://google.github.io/adk-docs/tools/google-cloud/bigquery-agent-analytics/#event-types

まとめ

• ADKに新たに追加されたBigQuery Agent Analytics Pluginは、事前のインフラ側の準備とADK上の数行のコードで容易にエージェントの分析が可能になるPluginであることを確認しました。