* docs(runtime): correct TypeScript claims in RunConfig streaming docs
The streaming sections of runtime/runconfig.md told TypeScript readers three
things that are not true of the TypeScript SDK.
- The BIDI bullet directed readers to `runner.run_live()`. That entry point
does not exist in TypeScript: `Runner` exposes no `runLive()` and
`LlmAgent.runLiveFlow` throws. The bullet also omitted that passing BIDI
degrades to non-streaming with no error and no warning.
- The TypeScript tab recommended `supportCfc: true`. Copying it yields a
single event with `errorCode: 'UNKNOWN_ERROR'` and
`errorMessage: 'CFC is not yet supported in callLlmAsync'` and no response
text at all. Removed from the snippet and documented in the existing
experimental admonition.
- "Configure live agents" carried a TypeScript support tag and a TypeScript
snippet, but the whole section describes `run_live()` parameters. The three
fields the TypeScript `RunConfig` declares feed only `liveConnectConfig`,
which nothing reachable consumes. Tag and snippet removed, with a note
explaining why the fields exist but do nothing.
Verified against @google/adk 1.6.0 and adk-js at HEAD; `mkdocs build --strict`
is clean.
* docs(runtime): name the streaming mode property per language
The prose said "set the `streaming_mode` parameter" in a language-neutral
sentence, but the TypeScript property is `streamingMode` (as the TypeScript
code tab below it already shows).
* docs(runtime): apply review feedback on the streaming sections
Addresses @joefernandez's review of #2101 and the staleness the technical
review report found in three of the four original changes.
Two adk-js merges landed after this PR was written and invalidated its
TypeScript claims: adk-js#692 (2026-08-13) makes StreamingMode.BIDI throw
instead of silently degrading, and adk-js#523 (2026-08-18) implements
Runner.runLive and the LlmAgent live flow. Rather than re-state per-SDK
behavior that is still moving, the TypeScript-specific claims are dropped
entirely, per the review direction not to document what a feature does not do.
- Rename "Enable streaming" to "Text response options" and reword the intro so
it cannot be confused with the Live and voice path. The #enable-streaming
anchor is preserved via attr_list, since docs/live/configuration.md links to
it and external links may too.
- Drop the per-language property-name parenthetical. The snippets below already
show the syntax, and it was wrong for Go, Java and Kotlin.
- Replace the StreamingMode.BIDI bullet with a paragraph pointing at Live and
Voice Agents, instead of listing BIDI as a parallel option to NONE and SSE.
- Drop the "run_live() is not available in the TypeScript SDK" warning; both
Runner.runLive and LlmAgent.runLiveFlow exist at adk-js HEAD.
- Drop the TypeScript detail from the CFC "Experimental" admonition. Removing
supportCfc: true from the TypeScript snippet stands: it still throws at
llm_agent.ts and surfaces as an error event with no response text.
- Restore the TypeScript language tag and snippet under "Configure live agents"
and add the Java tag. The three TypeScript fields are in LIVE_KEYS and are
applied by the now-working live flow; Java has Runner.runLive and implements
avatar_config.
- Lead "Configure live agents" with a pointer to Live and Voice Agents.
* docs(runtime): add Java live RunConfig example
* Apply batched suggestions from code review
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Apply batched suggestions from code review
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Upgrade Kotlin docs to adk-kotlin 0.9.0 and move off AdkWebServer
adk-kotlin 0.9.0 split the web server into AdkApiServer, which serves the agent
runtime contract headlessly, and AdkDevServer, which adds the development UI.
AdkWebServer is deprecated in that release and goes away at 1.0, so WebMain.kt
as written here stops compiling the day 1.0 ships.
The quickstart snippet now builds an AdkDevServer from an AdkServerConfig. That
drops three imports: AdkServerConfig.inMemory() supplies the agent loader and
the in-memory session and artifact services the old constructor took one by one.
Two behaviour notes come with the split. AdkWebServer pinned host to 0.0.0.0;
the new classes bind loopback, which is a visible change for anyone reaching the
server from a container or a remote box, so the page now says so and names the
host parameter in prose. It prints no worked example on purpose: the only value
such a snippet could carry is either 127.0.0.1, which overrides the default with
itself, or 0.0.0.0, which is a copyable way to publish an unauthenticated server
on every interface, and AdkDevServer construction is already shown in full
earlier on the page. And AdkApiServer is the headless half of the same config,
so it gets a short section rather than a bare mention - the bundled Kotlin API
reference is still generated at 0.5.0 and documents none of these classes, so a
link there would not have helped. The "not meant for production" warning now
sits directly after the screenshot, where go.md, java.md and python.md put it.
The dependency blocks readers copy from still pinned 0.8.0, and so did the
examples project. Verified on Maven Central that 0.9.0 is published for every
artifact named across these pages: -core, -processor, -webserver, -litertlm,
-a2a and -integrations. Checked the 0.9.0 POMs before bumping: Ktor still
resolves to 2.3.13 and a2a-java-sdk-client to 1.0.0.Final, so the explicit pins
stay correct and the two comments citing them only needed their version
reference moved. The `Kotlin v0.x` support badges are deliberately left alone:
they record the release a feature landed in, not the current version.
Verified by compiling: every snippet added here was compiled verbatim against
the published 0.9.0 artifacts on JDK 17, and the whole examples project still
builds at 0.9.0. As a negative control, the old snippet still compiles at 0.9.0
but emits the deprecation warning, which is what makes this a 1.0 break rather
than a present-day one. Note the Kotlin snippet check only builds .kt files
changed in the PR, so it will not cover a markdown-only change like this.
* Apply suggestion from @joefernandez
* Apply suggestion from @joefernandez
* Removing information bloat from the Get Started
see comments for where to locate this information
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* docs(live): decompose the development guide into capability pages
Split dev-guide/part1-5 into Sessions, Events, Tools, Workflows, Audio and
video, Configuration, Voice, Supported models, and Build a custom server.
Rewrite index.md as the section Overview with a streaming-type decision table.
Implements Phase 2 of the Live Interactions<>ADK documentation revamp.
* docs(live): drop half-cascade model coverage
Half-cascade models are no longer supported for live agents. Remove the
Native Audio vs Half-Cascade architecture framing from Supported models and
the half-cascade caveats from Voice configuration. The eight prebuilt Live
API voices are kept, relabeled as native-audio voices alongside the extended
Text-to-Speech list.
* docs(live): retire the five-part dev guide and rewire navigation
Delete live/dev-guide/ and live/streaming-tools.md now that their content
lives in the capability pages. Regroup the Live nav into Get started / Build /
Ship / Reference, repoint every partN.md cross-link at its new page and
anchor, and add direct redirects for the removed paths (mkdocs-redirects does
not chain, so streaming/* keys point at final destinations).
* docs(live): point at the API reference instead of pinned source
Swap the RunConfig, Event, SequentialAgent, LiveRequestQueue and
Runner.run_live source-reference notes for Python API reference links.
Implementation pointers with line ranges are left as source links, since they
document internals with no public reference equivalent.
* docs(live): fix docs against adk-python main and drop the bidi-demo links
The bidi-demo sample was removed from adk-samples, so all the source links in
docs/live/ were dead. The sample is not shipped here either, so remove every
reference to it instead of repointing the links.
The code snippets themselves are unchanged. What goes away is only the
scaffolding that pointed at the sample:
- 32 code fences lose their linked 'Demo implementation: file.py:NN-MM' title
and become plain language-tagged fences.
- The 'Complete Demo Implementation' note in custom-server.md and the 'Demo
Implementation' note in events.md are dropped; both existed only to link out.
- The 'Learn More' note in tools.md and the model setup step in models.md keep
their guidance but no longer cite the sample's files.
- Prose that named the demo ('The bidi-demo demonstrates how to...') is
rewritten to describe the pattern directly.
- The Bidi Demo card and its screenshot are removed from the Live demos section
of index.md; LensMosaic remains.
Staleness fixes verified against adk-python main:
- StreamingMode.BIDI is inert. Only run_async() reads RunConfig.streaming_mode;
run_live() never does. Remove it from every run_live()-facing sample and
rewrite the 'StreamingMode: BIDI or SSE' section around the Runner method you
call. Keeps the old anchor via attr_list.
- configuration.md: run_live(session=...) is gone; use user_id/session_id.
- tools.md: streaming tools are registered lazily on first model call, not
scanned up front; the input_stream queue is created only for tools annotated
with LiveRequestQueue, and stop_streaming resets it to None. The old
runners.py / function_tool.py line references pointed at unrelated code.
- sessions.md: document DEFAULT_MAX_RECONNECT_ATTEMPTS = 5 and the go_away
reconnect trigger; correct 'automatic closure in SSE mode', which really only
happens for the internal queue under support_cfc.
- events.md: audio artifacts require RunConfig.save_live_blob=True;
get_author_for_event() also keys off llm_response.input_transcription.
- configuration.md: document history_config and the
initial_history_in_client_content=True that ADK sets when seeding history.
Not changed: get-started/streaming-java.md still sets StreamingMode.BIDI, which
could not be verified without an adk-java checkout.
* Refresh the Live API supported-model list
Checked against the Gemini Live API and Agent Platform model docs:
- models.md: replace the model list with a platform/model/stage table covering
gemini-3.1-flash-live-preview (Preview, Gemini Live API only),
gemini-2.5-flash-native-audio-preview-12-2025 (Preview), and
gemini-live-2.5-flash-native-audio (now GA, not "public preview").
- Document what Gemini 3.1 Live does not support: proactivity, affective
dialog, async function calling, thinking_budget (it uses thinking_level),
plus multi-part server events and the turn-coverage default change.
- Note that no Gemini 3.x Live model exists on Agent Platform, and that Live
API models are unavailable in the `global` location.
- voice.md: replace the Platform Compatibility text, which wrongly said
proactivity and affective dialog are unavailable on Agent Platform, with a
per-model support table.
- configuration.md: CFC's model check is a literal `gemini-2` prefix match, so
it rejects Gemini 3.x; refresh the runners.py line anchor.
- bidi-demo: same model table in the README, the 3.1 option and the regional
location requirement in .env.example, and an expanded model comment in
agent.py. The default stays on 2.5 native audio because the demo exposes
proactivity and affective dialog toggles. Re-anchored the agent.py line
links in models.md, tools.md, and sessions.md.
* docs(live): align docs with current Live API model capabilities
Verified docs/live/ and docs/runtime/runconfig.md against the Gemini Live
API capabilities guide, the Agent Platform Live API docs, and ADK 2.6.3.
Model consistency:
- response_modalities=["TEXT"] was presented as a valid live configuration
in configuration.md, events.md and sessions.md. Every Live API model ADK
supports is a native audio model, and those accept AUDIO only. Reframed
around AUDIO plus output audio transcription, and kept TEXT where it is
actually correct: the run_async() / SSE path.
- docs/runtime/runconfig.md configured response_modalities=["AUDIO","TEXT"]
in all three language samples. A session accepts exactly one modality.
- events.md snippets read event.content.parts[0], which drops content on
gemini-3.1-flash-live-preview because it sends multiple parts per server
event -- the failure models.md already warns about. All four snippets now
iterate over parts.
- tools.md gave the streaming-tools root agent model="gemini-flash-latest",
which has no Live API support, so the example could not run under
run_live() on either platform. That alias is still used for the one-shot
generate_content call inside the tool, where it is correct.
- configuration.md "Standard Gemini Models (1.5 Series) Accessed via SSE"
described a retired model family and labelled gemini-pro-latest /
gemini-flash-latest as 1.5 with 2M context.
- sessions.md: document that send_client_content is seeding-only on Gemini
3.x Live, and that ADK reroutes single-part text to send_realtime_input.
- models.md: gemini-live-2.5-flash-native-audio is the only GA Live API
model on Agent Platform, not the only one.
Coverage and links:
- configuration.md: document explicit_vad_signal, translation_config,
avatar_config and model_input_context.
- voice.md: note that ADK picks the live API version (v1alpha / v1beta1),
so proactivity and affective dialog need no http_options.
- Replace redirecting upstream URLs with their current targets:
live-guide -> live-api/capabilities, live-session ->
live-api/session-management, live -> live-api, and
cloud.google.com/vertex-ai -> the Agent Platform equivalents.
Verified correct, left alone: session and context limits, audio and video
specs, the proactivity / affective dialog model matrix, thinking_level vs
thinking_budget, the support_cfc gemini-2 prefix check, and ADK's AUDIO
default in run_live().
* docs(live): trim the response-modality and SSE material
Every Live API model ADK supports is a native audio model, so a live
session's response modality is always AUDIO and there is nothing to
choose. Shrink the section to the one thing that still matters --
reading text off event.output_transcription.
StreamingMode is only read by run_async(); the SSE tutorial that grew
around it here (protocol diagrams, progressive-streaming walkthrough,
mode-selection table, 1.5-series model list) duplicates
runtime/runconfig.md and describes models that no longer exist. Keep
the inert-BIDI warning and the run_live()/run_async() split, drop the
rest.
Document explicit_vad_signal, translation_config, avatar_config and
model_input_context, which had no coverage at all.
* docs(live): cut duplicated and non-ADK material
Six sections carried weight that did not belong to them:
- sessions.md 'Best Practices for Live API Connection and Session
Management' restated the Session Resumption and Context Window
Compression sections verbatim, down to the RunConfig snippets.
Deleted.
- sessions.md 'Concurrency and Thread Safety' + 'Message Ordering
Guarantees' explained asyncio.Queue at length and reproduced the
upstream task already in custom-server.md. Condensed to the three
properties that actually affect calling code, with a pointer to
the private _queue attribute dropped.
- sessions.md 'Architectural Patterns for Managing Quotas' was an
ASCII decision tree and a comparison table for two patterns that
reduce to one sentence each.
- index.md 'Real-world applications' spent five industry vignettes
making one point.
- events.md 'Deserializing on the Client' pasted 80 lines of the
bidi-demo's UI code, calling helpers that no longer exist anywhere
in these docs. Reduced to the event-shape handling it was meant to
show.
- audio-video.md 'Handling Image Input at the Client' was 130 lines
of getUserMedia/canvas/FileReader boilerplate plus a seven-point
recap of it.
Also fix two dead absolute links: /agents/multi-agents/#workflow-agents-as-orchestrators
(the page now redirects to workflows/index.md and the anchor is gone)
and /live/streaming-tools/ (no such page; the content is in tools.md).
* docs(live): restructure the live docs around ADK ownership
The live section had accumulated content it did not own: backend limits
restated on capability pages, Web Audio API implementation presented as
ADK guidance, and shared concepts re-explained rather than linked.
Applies one rule throughout: if a fact would still be true with the ADK
source deleted, it belongs on models.md or behind an upstream link, not
on a capability page.
- audio-video.md is now the format contract only (505 -> 121). The
browser mic-capture, ring-buffer playback, and camera-frame code was
Web Audio API with no ADK in it, had no counterpart in adk-python, and
no test anywhere. Deleted rather than relocated. The twelve numbered
'Key Implementation Details' lists restated the code comments directly
above them; deleted. The streaming-tool lifecycle section duplicated
tools.md; replaced with a link.
- custom-server.md gains 'Connect a client': what adk web handles
(16 kHz capture, 24 kHz playback, 1 fps JPEG, transcripts, barge-in),
where it stops, and the /run_live wire protocol, which was previously
undocumented. Keeps the one JS snippet that shows ADK's event shape.
Drops 'Client-side patterns'.
- sessions.md hands its platform-limits table and quota numbers to
models.md, keeping the session-pool design guidance. The same figures
had been stated in three places across two pages.
- models.md gains 'Platform limits and quotas' as the single source, and
loses the 'Key characteristics' list that restated configuration.md.
- configuration.md drops the 'Platform Support' column, which read
'Both' on 13 of 15 rows and labelled the two exceptions as platform
constraints when they are model constraints.
- tools.md compresses 'Tool execution context' to the one fact that is
live-specific: an InvocationContext spans the whole run_live() loop,
not a single turn.
- workflows.md points at graphs/index.md, the ADK 2.0 graph workflow
page, rather than the v0.1.0 multi-agent umbrella.
- Six internal links used absolute paths, which mkdocs does not
validate, so --strict had been silently ignoring them. Now relative.
- Fixes class.="grid cards" in get-started/index.md, which was breaking
the card grid.
* docs(live): standardize page leads and cut duplicated RunConfig prose
Every live page opened by narrating its own table of contents ("This page
covers X, Y, and Z"), which duplicates the rendered TOC, ages badly when
a heading changes, and spends a paragraph before the reader gets a fact.
evaluation.md already did the better thing: state the shared baseline,
link the canonical page, then cover only the delta. That is now the
convention across the section.
- sessions.md, events.md, configuration.md, audio-video.md,
workflows.md, tools.md, models.md and get-started/index.md now name
their non-live counterpart in the lead instead of listing their own
headings. Three pages had no outbound link to the shared concept at
all: tools.md to Custom Tools, models.md to Models for agents, and
workflows.md pointed at the v0.1.0 umbrella rather than graph
workflows.
- configuration.md drops the custom_metadata section (85 lines) for a
pointer plus the one live-specific consequence: a run_live() call is a
single invocation, so metadata is stamped on the whole session rather
than one turn. runtime/runconfig.md already owns the field.
- configuration.md trims max_llm_calls and save_live_blob to the facts
that are live-specific — max_llm_calls does not apply to run_live() at
all, and save_live_blob writes ~1.92 MB per minute per session to two
services — and drops the generic use-case and best-practice lists.
- custom-server.md replaces 'Key concepts', which re-pasted all three
code blocks from the complete example directly above it, with prose
explaining why the two tasks must run concurrently.
Live section: 2820 -> 2211 lines.
* docs(live): reframe pages around capabilities, fix eval config key
* Apply batched suggestions from code review
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Apply suggestion from @joefernandez
* Apply batched suggestions from code review
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
---------
Co-authored-by: Stephen Allen <stephenaallen@google.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Document the `enable_spreadsheet_parsing` parameter added to `LoadArtifactsTool`
in adk-python:
https://github.com/google/adk-python/commit/370027a770b413ab7991afa3395dbf8be1eb89e5
- Keep the standard `LoadArtifactsTool()` example in the main Python snippet for the default behavior.
- Add a dedicated "Parsing spreadsheet artifacts (Python only)" section explaining that spreadsheet files (.xlsx, .xls) cannot be read inline by default and can be parsed into Markdown tables by enabling `enable_spreadsheet_parsing=True`.
- Document behavior details: rendering each sheet as a separate Markdown table and capping output at the first 100 rows per sheet to prevent context window exhaustion.
The page covered upgrading from 1.x for Python and Go but not TypeScript,
even though ADK TypeScript 2.0 is published. Adds a section in the same shape
as the other two, covering the four changes that affect a project upgrading
from @google/adk 1.6.0:
- Four optional fields added to the Event interface (`output`, `route`,
`nodeInfo`, `isolationScope`), and what that means for a custom session
service backed by a rigid schema.
- `BaseAgent` now extends `BaseNode`, so subclasses inherit seven members that
can collide with their own fields, and `description` defaults to an empty
string rather than `undefined`.
- `InvocationContext.agent` is now optional, with `requireAgent(ctx)` as the
replacement inside an agent's own execution.
- `SequentialAgent`, `ParallelAgent` and `LoopAgent` warn once per class but
still work.
Deliberately omits the `LLMAgentWrapper` removal and the dynamic
`ctx.runNode()` resume change listed in the 2.0.0 changelog. Neither shipped
in a released 1.x, so neither can affect an upgrade; both were churn within
the 2.0 development line.
Also marks TypeScript as supported in the page header, adds the GA note, links
the TypeScript workflow samples under Next steps, and adds adk-js to the
closing feedback line.
The claims are checked against `adk-v2.0.0`: the Event field list comes from a
diff of `events/event.ts` between the 1.6.0 and 2.0.0 tags, and the code
sample compiles under `strict` against the published `@google/adk@2.0.0`.
* Show how a Kotlin client answers a long-running tool call
The function-tools page documents long-running tools in two halves: defining one
(which Kotlin already covered) and driving it from the client, which Kotlin did
not. Nothing in the docs showed a Kotlin reader how the deferred result gets
back to the model - the only Kotlin mention of longRunningToolIds in the repo is
a commented-out field listing in events/index.md.
The new region continues the reimbursement scenario the Kotlin tab above it
already sets up, rather than importing the nav-agent scenario the upstream demos
use. It shows the two things that are easy to get wrong:
- A pending call is one whose id the event also lists in `longRunningToolIds`;
the FunctionResponse must reuse that id or the model cannot match the answer
to the request it is waiting on.
- A resumable app must pass `invocationId` to the second `runAsync`. Without it
the response opens a new invocation instead of resuming the paused one, which
the page's own resume note warns about for Python. Grounded in
ResumableLongRunningToolDemoAgent.kt:84-99 at the v0.8.0 tag.
Appended to the existing, already-registered LongRunningTool.kt instead of the
new file the backlog row proposed: this page already owns that snippet, and a
second file elsewhere would split one page's Kotlin across two directories.
Also added a bullet to "Key aspects of this example", which explains the group
purely in terms of `LongRunningFunctionTool` - a class Kotlin does not have. The
Kotlin form is `@Tool(isLongRunning = true)` or a `BaseTool` subclass, and a
long-running tool returning `Unit` suppresses even the placeholder response
(InvocationContext.kt:447).
Verified: runner.sh build and lint both PASS on the snippet (JDK 17),
check_kotlin_snippets.sh passes, L0/L5/L6 pass. L3 reports two orphaned-tab
problems at lines 123 and 227; both pre-date this change and are false
positives - rendering the page with the repo's own markdown extensions shows
every group, including the one edited here, as a single tabbed set with Kotlin
among its labels.
* Correct the long-running snippet's account of resume and turn count
Review against the v0.8.0 sources found three claims in this branch that a
reader would have acted on and been wrong.
The invocationId argument was the worst of them. The snippet took an
`appIsResumable` flag and passed `invocationId` on the second `runAsync`,
commenting that a resumable app must do so or the response opens a new
invocation. The runner does not work that way: `resolveInvocationId`
(AbstractRunner.kt:468-483) looks the id up from the function-call event that
matches the response's own id and discards whatever the caller passed. The flag
was inert, and anyone plumbing it through their call sites would have got
nothing for it. Both are gone; the comment now says what actually resumes the
invocation - the response id itself.
"Returns a placeholder and the turn ends" was wrong for the snippet's own
default. This tool returns a data class, not `Unit`, so a non-resumable app
emits the placeholder as a function response and calls the model again:
LongRunningToolIntegrationTest's scenario table records two model calls and a
trailing text event for that combination, and asserts it in
runAsync_longRunningToolReturnsDict_propagatesPayloadAndAcknowledges. A reader
building a HITL flow would have budgeted one model call and been surprised by an
interim reply. The KDoc and the page bullet now describe both modes.
Reusing the call id was described as something the model needs to match the
answer to its request. The model never gets that far: an unknown id throws from
HistoryRewriterProcessor.findMatchingFunctionCallEvent, and a null one throws
too, because the id set is built with mapNotNull and an empty set matches no
event. The comment now says it throws.
Also prints turn 1, which is where the interim reply appears, and says so when
the model answers without calling the tool instead of returning silently.
Verified: runner.sh build and lint both PASS (JDK 17), L0/L1/L2/L5/L6 pass, and
rendering the page with the repo's markdown extensions puts Kotlin in the target
group's tab set. L3's two orphaned-tab reports are pre-existing on main and are
false positives - the render shows those groups whole.
* Update function-tools.md
* Say that Kotlin resolves the invocation from the response itself
Adding a Kotlin tab to this section quietly extended the Resume note to
Kotlin, where it does not hold: resolveInvocationId matches the function
response's own call ID against the session and ignores the invocationId
the caller passes, so requiring one sends readers looking for a
parameter that changes nothing. An ID matching no call throws rather
than starting a fresh invocation.
Also fix subject-verb agreement in the turn-count bullet.
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* 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>
Zyan