From f9d853a10eea6f1bad73b614e8f923ef6a6b4c66 Mon Sep 17 00:00:00 2001 From: Shahin Saadati Date: Wed, 19 Aug 2026 11:06:24 -0700 Subject: [PATCH 1/6] Add the Kotlin tab for the BigQuery agent analytics quickstart adk-kotlin 0.8.0 ships BigQueryAgentAnalyticsPlugin, so the quickstart's setup group can carry a Kotlin tab alongside Python and Java. Transcluded, so CI compiles and lints it. The tab says plainly what the Kotlin plugin does not do, because a bare third tab under this page's overview would promise far more than it delivers. It logs INVOCATION_STARTING and INVOCATION_COMPLETED only - not the LLM, tool, state or HITL events the page's table lists - fills the identity columns and content while leaving trace_id, latency_ms and attributes null, and writes rows one at a time through insertAll synchronously on the invocation path, not asynchronously through the Storage Write API the page describes. Grounded in BigQueryAgentAnalyticsPlugin.kt at the v0.8.0 tag, not the working tree. Only the setup group gets Kotlin. The page's six other groups cover event payloads and configuration surface the Kotlin plugin does not have. The plugin lives in the integrations module, so examples/kotlin needs that artifact to compile the snippet. One line is enough: unlike the a2a artifact, google-adk-kotlin-integrations publishes google-cloud-bigquery and google-auth on jvmApiElements, so the types its constructor defaults name are already on the compile classpath. Verified with the snippet ladder: L0 symbols, L1 compile, L2 ktlint, L3 transclusions, L5 registration and L6 badge all pass against the 0.8.0 pin. --- docs/integrations/bigquery-agent-analytics.md | 21 ++++++- examples/kotlin/build.gradle.kts | 5 ++ .../integrations/BigQueryAnalyticsExample.kt | 62 +++++++++++++++++++ tools/kotlin-snippets/files_to_test.txt | 1 + 4 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt diff --git a/docs/integrations/bigquery-agent-analytics.md b/docs/integrations/bigquery-agent-analytics.md index 37ae1e7dad..4da3587673 100644 --- a/docs/integrations/bigquery-agent-analytics.md +++ b/docs/integrations/bigquery-agent-analytics.md @@ -8,7 +8,7 @@ catalog_tags: ["observability", "google"] # BigQuery Agent Analytics plugin for ADK
- Supported in ADKPython v1.21.0Java v1.5.0 + Supported in ADKPython v1.21.0Java v1.5.0Kotlin v0.8.0
The BigQuery Agent Analytics Plugin significantly enhances Agent Development Kit @@ -193,6 +193,25 @@ shows the BigQuery view optionally created when } ``` +=== "Kotlin" + + Add the plugin to your agent's `App` object. For prerequisites, see + [Prerequisites](#prerequisites). The plugin ships outside core, in + `com.google.adk:google-adk-kotlin-integrations`, and is JVM-only. + + ```kotlin title="BigQueryAnalyticsExample.kt" + --8<-- "examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt:quickstart" + ``` + + The Kotlin plugin logs a deliberately narrow slice of what the Python and + Java plugins do. It records `INVOCATION_STARTING` and `INVOCATION_COMPLETED` + only — none of the LLM, tool, state or HITL events in the table above — and + populates the identity columns plus `content`, leaving `trace_id`, + `latency_ms`, `attributes` and the rest null. Rows are written one at a time + with the `insertAll` streaming API, synchronously on the invocation path, so + each write adds latency to the turn rather than being batched away by the + Storage Write API. + ### Run and test agent diff --git a/examples/kotlin/build.gradle.kts b/examples/kotlin/build.gradle.kts index b057c5cd7f..bbca101f99 100644 --- a/examples/kotlin/build.gradle.kts +++ b/examples/kotlin/build.gradle.kts @@ -30,6 +30,11 @@ dependencies { // own catalog; the spec and jsonrpc transport arrive transitively. implementation("com.google.adk:google-adk-kotlin-a2a:0.8.0") implementation("org.a2aproject.sdk:a2a-java-sdk-client:1.0.0.Final") + // BigQueryAgentAnalyticsPlugin lives in the integrations module. Unlike the + // a2a artifact above, this one publishes google-cloud-bigquery and + // google-auth on jvmApiElements, so the BigQuery types its constructor + // defaults name arrive on the compile classpath with no second line. + implementation("com.google.adk:google-adk-kotlin-integrations:0.8.0") implementation("com.google.cloud:google-cloud-storage:2.48.2") implementation("io.opentelemetry:opentelemetry-sdk:1.56.0") implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0") diff --git a/examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt b/examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt new file mode 100644 index 0000000000..bce499703c --- /dev/null +++ b/examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt @@ -0,0 +1,62 @@ +/* + * Copyright 2026 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.adk.kt.examples.integrations + +// --8<-- [start:quickstart] +import com.google.adk.kt.agents.Instruction +import com.google.adk.kt.agents.LlmAgent +import com.google.adk.kt.apps.App +import com.google.adk.kt.models.Gemini +import com.google.adk.kt.plugins.agentanalytics.BigQueryAgentAnalyticsPlugin +import com.google.adk.kt.plugins.agentanalytics.BigQueryLoggerConfig + +val analyticsAgent = + LlmAgent( + name = "my_agent", + model = Gemini(name = "gemini-flash-latest"), + instruction = Instruction("You are a helpful assistant."), + ) + +/** + * Wraps [analyticsAgent] in an [App] whose invocations are logged to BigQuery. + * + * The plugin creates the day-partitioned table on first use, so the credentials + * in scope need permission to create a table in the dataset, not only to insert + * rows. Without explicit `credentials`, application default credentials are used. + */ +fun analyticsApp( + projectId: String, + datasetId: String, +): App { + val plugin = + BigQueryAgentAnalyticsPlugin( + config = + BigQueryLoggerConfig( + projectId = projectId, + datasetId = datasetId, + // Optional; defaults to "agent_events". + tableName = "agent_events", + ), + ) + + return App( + appName = "my_agent", + rootAgent = analyticsAgent, + plugins = listOf(plugin), + ) +} +// --8<-- [end:quickstart] diff --git a/tools/kotlin-snippets/files_to_test.txt b/tools/kotlin-snippets/files_to_test.txt index b1902c362c..794f972e9d 100644 --- a/tools/kotlin-snippets/files_to_test.txt +++ b/tools/kotlin-snippets/files_to_test.txt @@ -40,3 +40,4 @@ snippets/tools/overview/UserPreferenceTools.kt snippets/tools/overview/CustomerSupport.kt snippets/tools/overview/DocAnalysisTools.kt snippets/tools/overview/OrderTools.kt +snippets/integrations/BigQueryAnalyticsExample.kt From 8881ac5ed560ecaa1265c4532944aa361e6cddf3 Mon Sep 17 00:00:00 2001 From: Shahin Saadati Date: Wed, 19 Aug 2026 12:33:31 -0700 Subject: [PATCH 2/6] Scope the Kotlin BigQuery claims to what the plugin actually does Review of the branch turned up five over-claims, all of the same kind: the page describes the Python and Java plugins, and adding a Kotlin badge and tab quietly extended every one of those promises to Kotlin. - The page-level badge advertised Kotlin next to Python and Java on a page whose opening promises Auto Schema Upgrade, tool provenance, HITL tracing, view creation, ADK 2.0 workflow events and drop stats. Kotlin implements none of them: BigQueryAgentAnalyticsPlugin overrides two Plugin callbacks. The correction lived only inside the Kotlin tab, which a reader on the Python tab never renders, so it moves to a page-level "Kotlin support" note next to the pricing warning, following the "Java support" note this page already uses. - The page says ingestion goes through the Storage Write API and links its pricing. Kotlin calls tabledata.insertAll, a different billing line: charged per inserted row with a 1 KB minimum and no monthly free tier, so cost tracks invocation count, not bytes. - BigQuerySchema creates no views, so the v_* names in the captured-events table do not exist for Kotlin. A reader would have queried v_invocation_completed and got a not-found. - Configuration options is Python and Java only. Kotlin's whole surface is BigQueryLoggerConfig's six fields, now listed, and `location` (default "US") was undiscoverable - the snippet takes it as a parameter instead of pinning a no-op tableName that already matches the default. - Every logging failure is swallowed: a table that cannot be created or a row that cannot be inserted is logged and the turn continues, so a misconfigured agent looks healthy while writing nothing. A second review pass caught a defect in the first pass's own fix: it told readers to raise the log level for `bigquery_agent_analytics`, which is the plugin's ADK name, not its logger. FloggerLoggingProvider names loggers with kClass.java.name, so the text now gives the class name. Verified: ./tools/kotlin-snippets/runner.sh build and lint both PASS on the snippet (JDK 17), check_kotlin_snippets.sh passes, verify_snippets.py L0-L6 all pass, and the page was rendered with the repo's own markdown extension set to confirm the Kotlin tab joins the Python/Java tabbed set and the note renders as an admonition rather than stray text. --- docs/integrations/bigquery-agent-analytics.md | 50 +++++++++++++++---- .../integrations/BigQueryAnalyticsExample.kt | 8 ++- 2 files changed, 45 insertions(+), 13 deletions(-) diff --git a/docs/integrations/bigquery-agent-analytics.md b/docs/integrations/bigquery-agent-analytics.md index 4da3587673..832c222233 100644 --- a/docs/integrations/bigquery-agent-analytics.md +++ b/docs/integrations/bigquery-agent-analytics.md @@ -7,7 +7,7 @@ catalog_tags: ["observability", "google"] # BigQuery Agent Analytics plugin for ADK -
+
Supported in ADKPython v1.21.0Java v1.5.0Kotlin v0.8.0
@@ -58,6 +58,22 @@ The plugin includes three reliability and observability fixes: For information on costs, see the [BigQuery documentation](https://cloud.google.com/bigquery/pricing?e=48754805&hl=en#data-ingestion-pricing). +!!! note "Kotlin support" + + The **Kotlin** plugin covers a small subset of this page. It logs + `INVOCATION_STARTING` and `INVOCATION_COMPLETED` only; it fills the identity + columns and `content`, leaving `trace_id`, `span_id`, `latency_ms`, + `attributes` and the rest null; and it creates **no views**, so the `v_*` + views in the table below do not exist for Kotlin. Auto Schema Upgrade, tool + provenance, HITL tracing, drop stats and the ADK 2.0 workflow events are not + implemented. + + It also ingests differently: rows go one at a time through + `tabledata.insertAll`, synchronously on the invocation path, not through the + gRPC Storage Write API described above. Those are separate billing lines: + inserted rows are charged with a 1 KB minimum each and no monthly free tier, + so cost scales with invocation count rather than bytes. + ## Use cases - **Agent workflow debugging and analysis:** Capture a wide range of *plugin @@ -196,21 +212,33 @@ shows the BigQuery view optionally created when === "Kotlin" Add the plugin to your agent's `App` object. For prerequisites, see - [Prerequisites](#prerequisites). The plugin ships outside core, in - `com.google.adk:google-adk-kotlin-integrations`, and is JVM-only. + [Prerequisites](#prerequisites). The plugin is JVM-only and ships outside + core, so add the integrations artifact: + + ```kotlin title="build.gradle.kts" + implementation("com.google.adk:google-adk-kotlin-integrations:0.8.0") + ``` ```kotlin title="BigQueryAnalyticsExample.kt" --8<-- "examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt:quickstart" ``` - The Kotlin plugin logs a deliberately narrow slice of what the Python and - Java plugins do. It records `INVOCATION_STARTING` and `INVOCATION_COMPLETED` - only — none of the LLM, tool, state or HITL events in the table above — and - populates the identity columns plus `content`, leaving `trace_id`, - `latency_ms`, `attributes` and the rest null. Rows are written one at a time - with the `insertAll` streaming API, synchronously on the invocation path, so - each write adds latency to the turn rather than being batched away by the - Storage Write API. + `BigQueryLoggerConfig` is the whole Kotlin configuration surface — + `projectId`, `datasetId`, `enabled` (default `true`), `location` (default + `"US"`, passed to the BigQuery client), `tableName` (default + `"agent_events"`) and `credentials` (default: application default + credentials). The options under [Configuration + options](#configuration-options) are Python and Java only. + + **Logging failures are swallowed.** If the table cannot be created or a row + cannot be inserted, the plugin logs and the invocation continues, so a + misconfigured agent looks healthy while writing nothing. When rows are + missing, raise the log level for + `com.google.adk.kt.plugins.agentanalytics.BigQueryAgentAnalyticsPlugin` — + logs are emitted under that class name, not under the plugin's ADK name. + Note also that Kotlin writes `content` as + `{"message": "Invocation started"}` rather than the `{}` shown for these two + event types below. ### Run and test agent diff --git a/examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt b/examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt index bce499703c..eeafd52b9d 100644 --- a/examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt +++ b/examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt @@ -37,10 +37,14 @@ val analyticsAgent = * The plugin creates the day-partitioned table on first use, so the credentials * in scope need permission to create a table in the dataset, not only to insert * rows. Without explicit `credentials`, application default credentials are used. + * + * Logging failures never fail the turn: a table that cannot be created, or a row + * that cannot be inserted, is logged and the invocation carries on. */ fun analyticsApp( projectId: String, datasetId: String, + datasetLocation: String, ): App { val plugin = BigQueryAgentAnalyticsPlugin( @@ -48,8 +52,8 @@ fun analyticsApp( BigQueryLoggerConfig( projectId = projectId, datasetId = datasetId, - // Optional; defaults to "agent_events". - tableName = "agent_events", + // Defaults to "US"; pass your dataset's location instead. + location = datasetLocation, ), ) From 20481cbe07efe855b729d6a55ac11147f62cd992 Mon Sep 17 00:00:00 2001 From: Joe Fernandez <931947+joefernandez@users.noreply.github.com> Date: Tue, 25 Aug 2026 16:31:36 -0700 Subject: [PATCH 3/6] Update bigquery-agent-analytics.md a few minor updates --- docs/integrations/bigquery-agent-analytics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/integrations/bigquery-agent-analytics.md b/docs/integrations/bigquery-agent-analytics.md index 832c222233..de90e646ab 100644 --- a/docs/integrations/bigquery-agent-analytics.md +++ b/docs/integrations/bigquery-agent-analytics.md @@ -7,7 +7,7 @@ catalog_tags: ["observability", "google"] # BigQuery Agent Analytics plugin for ADK -
+
Supported in ADKPython v1.21.0Java v1.5.0Kotlin v0.8.0
@@ -58,9 +58,9 @@ The plugin includes three reliability and observability fixes: For information on costs, see the [BigQuery documentation](https://cloud.google.com/bigquery/pricing?e=48754805&hl=en#data-ingestion-pricing). -!!! note "Kotlin support" +??? note "Kotlin support" - The **Kotlin** plugin covers a small subset of this page. It logs + The **Kotlin** plugin supports subset of available features. It logs `INVOCATION_STARTING` and `INVOCATION_COMPLETED` only; it fills the identity columns and `content`, leaving `trace_id`, `span_id`, `latency_ms`, `attributes` and the rest null; and it creates **no views**, so the `v_*` From 845017f3e10ed45d5adc3a7a5b32e8a2b758d539 Mon Sep 17 00:00:00 2001 From: Joe Fernandez <931947+joefernandez@users.noreply.github.com> Date: Tue, 25 Aug 2026 16:54:01 -0700 Subject: [PATCH 4/6] Update bigquery-agent-analytics.md --- docs/integrations/bigquery-agent-analytics.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/integrations/bigquery-agent-analytics.md b/docs/integrations/bigquery-agent-analytics.md index de90e646ab..1c82c9cc8e 100644 --- a/docs/integrations/bigquery-agent-analytics.md +++ b/docs/integrations/bigquery-agent-analytics.md @@ -60,10 +60,10 @@ The plugin includes three reliability and observability fixes: ??? note "Kotlin support" - The **Kotlin** plugin supports subset of available features. It logs - `INVOCATION_STARTING` and `INVOCATION_COMPLETED` only; it fills the identity - columns and `content`, leaving `trace_id`, `span_id`, `latency_ms`, - `attributes` and the rest null; and it creates **no views**, so the `v_*` + The **Kotlin** plugin supports a subset of the available features. It logs + `INVOCATION_STARTING` and `INVOCATION_COMPLETED` only. The plugin fills the + identity columns and `content`, leaving `trace_id`, `span_id`, `latency_ms`, + `attributes` and the rest null. It creates **no views**, so the `v_*` views in the table below do not exist for Kotlin. Auto Schema Upgrade, tool provenance, HITL tracing, drop stats and the ADK 2.0 workflow events are not implemented. From 8ce83b35d98cb363bab3864de6b855451481e09f Mon Sep 17 00:00:00 2001 From: Shahin Saadati Date: Wed, 26 Aug 2026 09:05:35 -0700 Subject: [PATCH 5/6] Move the Kotlin scoping next to the content it scopes The Kotlin support note described the page's tables as wrong from a separate block, so a reader arriving at a table by anchor link, or reading top to bottom, saw only the unqualified version. Each caveat now sits with what it qualifies: the captured-events table says Kotlin logs two event types and creates no views, the schema reference says which columns are populated, and the lifecycle payload table records the message content Kotlin writes. Configuration options gains a Kotlin tab covering BigQueryLoggerConfig, which is what the quickstart tab was asserting from the outside. With a real section to point at, the quickstart can lead with how to use the plugin rather than with what it cannot do. Drop the BigQuery insert pricing detail; it belongs in the BigQuery docs, not here. --- docs/integrations/bigquery-agent-analytics.md | 102 +++++++++++++----- 1 file changed, 74 insertions(+), 28 deletions(-) diff --git a/docs/integrations/bigquery-agent-analytics.md b/docs/integrations/bigquery-agent-analytics.md index 1c82c9cc8e..9ce4188f66 100644 --- a/docs/integrations/bigquery-agent-analytics.md +++ b/docs/integrations/bigquery-agent-analytics.md @@ -60,19 +60,18 @@ The plugin includes three reliability and observability fixes: ??? note "Kotlin support" - The **Kotlin** plugin supports a subset of the available features. It logs - `INVOCATION_STARTING` and `INVOCATION_COMPLETED` only. The plugin fills the - identity columns and `content`, leaving `trace_id`, `span_id`, `latency_ms`, - `attributes` and the rest null. It creates **no views**, so the `v_*` - views in the table below do not exist for Kotlin. Auto Schema Upgrade, tool - provenance, HITL tracing, drop stats and the ADK 2.0 workflow events are not - implemented. - - It also ingests differently: rows go one at a time through - `tabledata.insertAll`, synchronously on the invocation path, not through the - gRPC Storage Write API described above. Those are separate billing lines: - inserted rows are charged with a 1 KB minimum each and no monthly free tier, - so cost scales with invocation count rather than bytes. + The **Kotlin** plugin logs invocation lifecycle events. It writes an + `INVOCATION_STARTING` row when an invocation begins and an + `INVOCATION_COMPLETED` row when it ends, and creates the partitioned, + clustered events table on first use if it does not already exist. + + Rows are inserted one at a time through `tabledata.insertAll`, synchronously + on the invocation path, rather than through the Storage Write API used by + Python and Java. + + The following are not implemented in Kotlin: LLM, tool, agent, state, HITL + and A2A events; the ADK 2.0 workflow events; automatic view creation; Auto + Schema Upgrade; tool provenance; GCS offloading; and drop statistics. ## Use cases @@ -105,6 +104,10 @@ examples, see [Event types and payloads](#event-types). The **View** column shows the BigQuery view optionally created when [`create_views`](#configuration-options) is enabled (the default). +In **Kotlin**, the plugin logs `INVOCATION_STARTING` and `INVOCATION_COMPLETED` +only and creates no views, so the other rows and the entire **View** column +apply to Python and Java. + | Event Type | Captured When | Key Payload Fields | View | | --- | --- | --- | --- | | `USER_MESSAGE_RECEIVED` | A user message enters the invocation | text summary / content parts | `v_user_message_received` | @@ -223,22 +226,18 @@ shows the BigQuery view optionally created when --8<-- "examples/kotlin/snippets/integrations/BigQueryAnalyticsExample.kt:quickstart" ``` - `BigQueryLoggerConfig` is the whole Kotlin configuration surface — - `projectId`, `datasetId`, `enabled` (default `true`), `location` (default - `"US"`, passed to the BigQuery client), `tableName` (default - `"agent_events"`) and `credentials` (default: application default - credentials). The options under [Configuration - options](#configuration-options) are Python and Java only. - - **Logging failures are swallowed.** If the table cannot be created or a row - cannot be inserted, the plugin logs and the invocation continues, so a - misconfigured agent looks healthy while writing nothing. When rows are - missing, raise the log level for + The plugin creates the events table on first use, so the credentials in + scope need permission to create a table in the dataset, not only to insert + rows. Set `location` to your dataset's location; it defaults to `"US"`. For + the full set of options, see [Configuration + options](#configuration-options). + + Logging never fails the turn: if the table cannot be created or a row cannot + be inserted, the plugin logs the error and the invocation continues. When + rows are missing, enable logging for `com.google.adk.kt.plugins.agentanalytics.BigQueryAgentAnalyticsPlugin` — - logs are emitted under that class name, not under the plugin's ADK name. - Note also that Kotlin writes `content` as - `{"message": "Invocation started"}` rather than the `{}` shown for these two - event types below. + logs are emitted under that class name, not under the plugin's ADK name + (`bigquery_agent_analytics`). ### Run and test agent @@ -755,6 +754,44 @@ account) under which the agent is running needs these Google Cloud roles: BigQueryAgentAnalyticsPlugin plugin = new BigQueryAgentAnalyticsPlugin(config); ``` +=== "Kotlin" + + In Kotlin, all configuration is managed via the `BigQueryLoggerConfig` data + class, which the plugin takes as its only required argument. + + #### BigQueryLoggerConfig properties + + | Option | Type | Default | Use when | + | --- | --- | --- | --- | + | `projectId` | `String` | *(required)* | Select the Google Cloud project | + | `datasetId` | `String` | *(required)* | Select the BigQuery dataset | + | `enabled` | `Boolean` | `true` | Temporarily disable logging | + | `location` | `String` | `"US"` | Match the BigQuery dataset location (for example, `"EU"` or `"us-central1"`) | + | `tableName` | `String` | `"agent_events"` | Use a custom table name | + | `credentials` | `Credentials?` | `null` | Use explicit service-account credentials instead of [ADC](https://cloud.google.com/docs/authentication/application-default-credentials) | + + The following code sample shows how to define a configuration for the + BigQuery Agent Analytics plugin in Kotlin: + + ```kotlin + import com.google.adk.kt.plugins.agentanalytics.BigQueryAgentAnalyticsPlugin + import com.google.adk.kt.plugins.agentanalytics.BigQueryLoggerConfig + + val config = + BigQueryLoggerConfig( + projectId = "my-project", + datasetId = "my_dataset", + location = "EU", + tableName = "agent_events", + ) + + val plugin = BigQueryAgentAnalyticsPlugin(config = config) + ``` + + The options listed under the **Python** and **Java** tabs, such as batching, + content formatting, event allowlists, GCS offloading, and view creation, do + not exist in Kotlin. + ## Schema and production setup @@ -763,6 +800,11 @@ account) under which the agent is running needs these Google Cloud roles: The events table (`agent_events`) uses a flexible schema. The following table provides a comprehensive reference with example values. +In **Kotlin**, the plugin creates the table with these same columns but +populates only `timestamp`, `event_type`, `agent`, `session_id`, +`invocation_id`, `user_id`, and `content`. The remaining columns are always +null. + | Field Name | Type | Mode | Description | Example Value | | --- | --- | --- | --- | --- | | **timestamp** | `TIMESTAMP` | `REQUIRED` | UTC timestamp of event creation. Acts as the primary ordering key and the daily partitioning key. Precision is microsecond. | `2026-02-03 20:52:17 UTC` | @@ -1114,6 +1156,10 @@ updated by tools). | `USER_MESSAGE_RECEIVED` | `{"text_summary": "Help me book a flight."}` | | `AGENT_RESPONSE` | `{"response": "Here are the flights..."}` | +In **Kotlin**, the two invocation events carry a summary message instead of an +empty object: `{"message": "Invocation started"}` and +`{"message": "Invocation completed"}`. + **AGENT_RESPONSE** Logged when the agent yields a final response to the user. The response text is stored in `content`, while the source event metadata is stored in `attributes`. From 96495be2193e07f24c6e091815d508bd913cb3ee Mon Sep 17 00:00:00 2001 From: Joe Fernandez <931947+joefernandez@users.noreply.github.com> Date: Fri, 28 Aug 2026 17:32:42 -0700 Subject: [PATCH 6/6] Update bigquery-agent-analytics.md --- docs/integrations/bigquery-agent-analytics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/integrations/bigquery-agent-analytics.md b/docs/integrations/bigquery-agent-analytics.md index 9ce4188f66..4dc0a0ea4a 100644 --- a/docs/integrations/bigquery-agent-analytics.md +++ b/docs/integrations/bigquery-agent-analytics.md @@ -800,11 +800,6 @@ account) under which the agent is running needs these Google Cloud roles: The events table (`agent_events`) uses a flexible schema. The following table provides a comprehensive reference with example values. -In **Kotlin**, the plugin creates the table with these same columns but -populates only `timestamp`, `event_type`, `agent`, `session_id`, -`invocation_id`, `user_id`, and `content`. The remaining columns are always -null. - | Field Name | Type | Mode | Description | Example Value | | --- | --- | --- | --- | --- | | **timestamp** | `TIMESTAMP` | `REQUIRED` | UTC timestamp of event creation. Acts as the primary ordering key and the daily partitioning key. Precision is microsecond. | `2026-02-03 20:52:17 UTC` | @@ -824,6 +819,11 @@ null. | **is_truncated** | `BOOLEAN` | `NULLABLE` | `true` if `content` or `attributes` exceeded the BigQuery cell size limit (default 10MB) and were partially dropped. | `false` | | **content_parts** | `RECORD` | `REPEATED` | Array of multi-modal segments (Text, Image, Blob). Used when content cannot be serialized as simple JSON (e.g., large binaries or GCS refs). | `[{"mime_type": "text/plain", "text": "hello"}]` | +In **Kotlin**, the plugin creates the table with these same columns but +populates only `timestamp`, `event_type`, `agent`, `session_id`, +`invocation_id`, `user_id`, and `content`. The remaining columns are always +null. + The plugin automatically creates the table if it does not exist. For production, you can optionally create the table manually using the DDL below.