Document the BigQuery agent analytics plugin for Kotlin - #2147
Open
happyhuman wants to merge 2 commits into
Open
Document the BigQuery agent analytics plugin for Kotlin#2147happyhuman wants to merge 2 commits into
happyhuman wants to merge 2 commits into
Conversation
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.
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.
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/integrations/bigquery-agent-analytics.mdhad no Kotlin content.adk-kotlin 0.8.0 ships
BigQueryAgentAnalyticsPlugin, so the Quickstart'ssetup group now carries a Kotlin tab beside Python and Java, backed by a
transcluded snippet that CI compiles and lints.
Only the setup group gets Kotlin. The page's six other tab groups document event
payloads and configuration surface the Kotlin plugin does not have.
The interesting part: saying what Kotlin doesn't do
This page describes the Python and Java plugins, and a Kotlin badge silently
extends every one of its promises to Kotlin. It shouldn't. At the pin,
BigQueryAgentAnalyticsPluginoverrides exactly twoPlugincallbacks, so thepage's opening — Auto Schema Upgrade, tool provenance, HITL tracing, automatic
view creation, ADK 2.0 workflow events, drop stats — describes nothing Kotlin
implements.
Rather than bury that inside the Kotlin tab, where a reader on the Python tab
never renders it, there is a page-level "Kotlin support" note next to the
pricing warning, following the
!!! note "Java support"idiom this page alreadyuses further down. It records four things a reader would otherwise get wrong:
INVOCATION_STARTINGandINVOCATION_COMPLETEDonly;identity columns plus
contentpopulated, withtrace_id,span_id,latency_msandattributesleft null.BigQuerySchemahas onlygetEventsSchema()andgetDefaultClusteringFields(). Thev_*names in the captured-events tabledo not exist for Kotlin, so
SELECT … FROM v_invocation_completedwould havereturned a not-found.
tabledata.insertAll, one row at a time, synchronously on the invocationpath — not the gRPC Storage Write API the page describes and links pricing
for. That is a separate SKU: charged per inserted row with a 1 KB minimum and
no monthly free tier, so cost tracks invocation count rather than bytes.
cannot be inserted, is logged and the turn continues — a misconfigured agent
looks perfectly healthy while writing nothing.
The Kotlin tab adds the artifact coordinate, the full
BigQueryLoggerConfigsurface (the Configurationoptions section is Python and Java only), and the class
name to raise the log level on when rows go missing.
locationdeserves a specific mention: it defaults to"US"and is passedstraight to the BigQuery client, and nothing in the page would have told a
Kotlin reader with an
EUdataset that the parameter exists. The snippet takesit as an argument instead of pinning a
tableNamethat already matches its owndefault.
Build change
One line:
com.google.adk:google-adk-kotlin-integrations:0.8.0. Unlike the a2aartifact, this one publishes
google-cloud-bigqueryandgoogle-authonjvmApiElements, so the BigQuery types named by the plugin constructor'sdefaults land on the compile classpath without a second dependency. Confirmed by
a real compile, not just by reading the module metadata.
Verification
Everything below was actually run:
./tools/kotlin-snippets/runner.sh build …/BigQueryAnalyticsExample.kt→PASS (JDK 17). Same command CI runs.
./tools/kotlin-snippets/runner.sh lint …→ PASS.check_kotlin_snippets.sh→ all Kotlin files registered.verify_snippets.py→ L0 symbols, L1 compile, L2 ktlint, L3 transclusions,L5 registration, L6 badge all PASS. L4 skips: this project registers no
runSnippetstask.python-markdownwith the extension list parsed outof
mkdocs.yml: the Quickstart set's labels come back['Python', 'Java', 'Kotlin']andKotlin supportrenders as an admonition,so neither the tab nor the note leaks raw markdown.
Every API claim is grounded in the
v0.8.0tag ofgoogle/adk-kotlin, never theworking tree, which runs ahead of the pin.
Not fixed here
The IAM permissions step grants
roles/bigquery.dataEditorat Table Level, which cannot create a table that does not exist yet — while
Prerequisites says the plugin creates the events table for you. That is wrong for
all three languages and predates this change, so I left it alone. Happy to fix it
in a follow-up.