mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Shahin Saadati
109b278c0b
* 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. * 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. * Update bigquery-agent-analytics.md a few minor updates * Update bigquery-agent-analytics.md * 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. * Update bigquery-agent-analytics.md --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>