* 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>
* Show maxLlmCalls in the RunConfig Kotlin tabs
Two groups on the RunConfig page had a Kotlin tab that set only
streamingMode while the Python, TypeScript and Java siblings also set
max_llm_calls. The tab existed and every symbol in it was valid, so
neither a symbol diff nor a missing-tab scan could see the gap - only
comparing a tab's contents against its siblings.
Also corrects the runtime-limits prose, which described the overflow
error purely in Python terms. Kotlin rejects Int.MAX_VALUE the same way.
The audio and speech group is deliberately left without a Kotlin tab:
Kotlin's RunConfig carries only streamingMode, maxLlmCalls and
customMetadata, so there is no speechConfig or responseModalities to
show.
* Update examples/kotlin/snippets/runtime/RunConfigExample.kt
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Name FileArtifactService in the artifact service list
Two prose lines enumerated only the in-memory and GCS services, both
attributed to Python. Kotlin has had FileArtifactService, which persists
artifacts to a local directory, since v0.4.0.
The page already has a Kotlin tab and badge, so this is an omission in
the enumeration rather than a missing snippet group. The androidMain
FileArtifactServiceAndroid and its fromInternalFilesDir /
fromExternalFilesDir factories are left out on purpose: this page is not
Android-scoped and naming them would imply availability the JVM artifact
does not have.
* Apply suggestion from @joefernandez
* Apply suggestion from @joefernandez
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Add Kotlin tabs for grounding with Agent Search
Both tab groups on the page showed Python and Java only, though
VertexAiSearchTool has existed in adk-kotlin since v0.1.0.
Kotlin uses the constructor directly rather than the builder the Java tab
reaches for, since dataStoreId is a named parameter. The citation snippet
collects from the event Flow instead of iterating a list, and reads
isFinalResponse as a property.
Both tabs are inline, matching their siblings: the snippets elide
surrounding setup and carry placeholder datastore ids, so there is
nothing here that could compile standalone.
* Badge the grounding page with the version VertexAiSearchTool shipped in
The badge said Kotlin v0.8.0, the version adk-docs compiles against,
rather than the introducing release. VertexAiSearchTool has been present
since v0.1.0, matching the Python v0.1.0 and Java v0.1.0 badges already
on this page.
* Cover Kotlin in the Agent Search authentication setup
Kotlin reads the same Google Cloud credentials and env vars as Java from
the application environment, so the auth bullet now names both. Also
corrects the Kotlin support tag: VertexAiSearchTool landed in v0.2.0, not
v0.1.0.
* Apply suggestion from @joefernandez
---------
Co-authored-by: Shahin Saadati <3443249+happyhuman@users.noreply.github.com>
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Add Kotlin safety settings and includeContents to the agent docs
Three related parity gaps, all on the same two types.
docs/safety/index.md had no Kotlin tab at all in the built-in Gemini
safety section. docs/agents/llm-agents.md had a Kotlin tab for
generateContentConfig that set only temperature and maxOutputTokens
while its Python sibling also set safety settings, and no Kotlin tab at
all for includeContents. None of these are new API: safety settings
landed in adk-kotlin 0.5.0 and includeContents has been on LlmAgent
since 0.1.0.
The under-showing tab is the interesting case. A missing-tab scan cannot
see it and neither can a symbol diff, because the tab exists and every
symbol it names is present - only comparing a tab's contents against its
siblings reveals it.
The safety page tab is inline because its siblings are, and because the
snippet elides the required name and model parameters the same way they
do, so there is nothing there that could compile on its own.
* Restore the Go tab's indentation on the safety page
Adding the Kotlin tab accidentally reindented a line inside the Go
sample, which mixes tabs and spaces. The Go tab is a sibling and should
not appear in this diff at all; the page's only non-additive change is
now the badge line.
* Add the Kotlin tab for input and output schemas
The structured-data section of agents/llm-agents had Python, TypeScript, Go and
Java but no Kotlin, and adk-kotlin 0.8.0 is what makes the tab worth writing:
Schema gained the twelve JSON Schema constraint fields, so a constraint can be
declared rather than described in the property's description and hoped for. The
snippet uses two of them, pattern and minLength, on the capital string.
Two conditions come with those fields, both from the upstream KDoc rather than
from guessing, and both easy to hit:
- Gemini rejects a schema whose `format` is anything but int32/int64 on a
number or enum/date-time on a string.
- `default` must hold a JSON-native value, and serializing a Schema that sets
one needs a Json whose serializersModule has a contextual serializer for
`Any`; a plain Json throws.
The tab also names the type, because `Schema` is ambiguous in this codebase:
`com.google.adk.kt.types.Schema` is the data class LlmAgent takes, while
`com.google.adk.kt.tools.Schema` is an unrelated annotation, and the GenAI SDK
has a third. `kotlin_api.py sig Schema` prints two of them.
Written as a region in CapitalAgent.kt rather than inline as the backlog row
proposed. Every other Kotlin tab on this page transcludes from that file even
though its Python and Java siblings are inline, so inline Kotlin here would
break the page's own convention and give up CI compile coverage.
Verified: runner.sh build and lint both PASS (JDK 17), verify_snippets L0-L6
pass, and rendering the page with the repo's markdown extensions shows the
target group as [Python, TypeScript, Go, Java, Kotlin].
* Correct what the schema tab promises about enforcement and outputKey
Review against the v0.8.0 sources found four claims a Kotlin reader would have
acted on and been wrong, and one example that taught the wrong thing.
- "Cannot use tools effectively here", carried over from the Python and Java
tabs, is false for adk-kotlin. LlmAgent.kt:100-107 documents the opposite:
with tools present the schema is applied directly on models that support
both, and models that do not get a set_model_response fallback. The comment is
gone and the tab says what actually happens.
- The pattern in the example was the wrong constraint for the data. Under
full-match semantics `^[A-Z][A-Za-z .'-]*` rejects Bogota, Brasilia,
Reykjavik, San Jose and "Washington, D.C." - correct answers the model would
be marked down for - and under JSON Schema's partial-match default it rejects
nothing at all, since the tail may match zero characters. It now constrains a
countryCode field with ^[A-Z]{2}$, where a pattern is genuinely the right
tool, and the capital carries minLength/maxLength instead. The instruction was
updated to ask for both fields, since it previously disagreed with the schema
it was paired with.
- "A constraint can be declared instead of described" implied ADK enforces the
constraints. It does not: SchemaUtils reads none of the twelve fields, and its
validation covers type, required, nullable, anyOf and items only. They are
forwarded to the model, and the tab now says so.
- With outputSchema set, outputKey does not hold text. LlmAgent.kt:360-374
stores the parsed Map, and on a validation failure logs and stores the raw
string under the same key - so `state["found_capital"] as String` throws on
the happy path, and nothing but the runtime type distinguishes the two
outcomes. The page's bullets above the group say the text content is saved.
- Only a top-level object schema is accepted, so the list of new fields, which
includes minItems and maxItems, could have led a reader to a top-level array
that silently fails validation.
Also scoped the format note to Type.INTEGER as well as Type.NUMBER, and the
default note to a hand-rolled Json, since ADK's own registers a contextual Any
serializer (Serializers.kt:138).
Verified: runner.sh build and lint both PASS (JDK 17), verify_snippets L0-L6
pass, and the rendered page shows the group as [Python, TypeScript, Go, Java,
Kotlin] with the new bullets inside the Kotlin tab.
* Move the schema behaviour out of the Kotlin tab
Checking the other SDKs showed most of what the Kotlin tab explained was
not Kotlin's. Python, Java, Go and Kotlin all fall back to a
set_model_response tool when a model cannot take a schema alongside
tools, so the warning's advice to restructure into sub-agents was
describing a limitation none of them has. All three of Python, Java and
Kotlin store the parsed object under output_key once an output schema is
set, so the bullet promising the text content was wrong before this
change and wrong for every reader, not just Kotlin ones.
What is left is a Java and Kotlin trait rather than a Kotlin one: both
validate structure only and leave the constraint fields to the model,
both accept only a top-level object, and both log and fall back to the
raw string. Python enforces its Pydantic constraints and accepts list
and primitive schemas, so a note naming the two JVM SDKs says it without
implying Kotlin is the odd one out. Each claim now links the source it
came from, pinned at v0.8.0.
Drop the account of which format values Gemini accepts and link the
Schema reference, which stays right on its own schedule.
* Apply suggestion from @joefernandez
* Apply suggestion from @joefernandez
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Add Kotlin tabs to the Skills page
The Skills page documented Python, TypeScript and Go but not Kotlin, even
though SkillToolset has existed since adk-kotlin v0.1.0. This was missed
because every earlier coverage audit diffed one release tag against the
next, so symbols that already existed at v0.1.0 were never checked.
Kotlin's shape differs from Python's in two ways the tabs need to show.
SkillToolset takes a single SkillSource rather than a list of loaded
skills, so NewFileSystemSource discovers every skill under a base
directory instead of loading them one by one. And like ADK Go, Kotlin
ships no built-in source for skills defined in code, so the inline-skills
tab implements SkillSource directly rather than pretending a Python-style
model class exists.
* Badge the Skills page with the version SkillToolset shipped in
The badge said Kotlin v0.8.0, which is the version adk-docs compiles
against, not the version the feature landed in. Every other badge on the
page and across the site names the introducing release - SkillToolset has
been present since v0.1.0.
* Point Kotlin readers at the adk-kotlin repo for Skills feedback
The Experimental callout invites feedback per SDK but listed only
Python, TypeScript and Go, which is now inconsistent with the Kotlin
badge this branch adds.
The link has no template parameter, unlike its three siblings, because
adk-kotlin has no issue templates - its .github directory holds only
workflows, so ?template=feature_request.md would silently fall back to a
blank issue.
* Add Kotlin tabs to the tool confirmation page
All three tab groups showed Python, TypeScript, Go and Java but not
Kotlin, even though the API has existed since adk-kotlin v0.1.0.
Kotlin turns out to sit closer to Python than to TypeScript here: the
@Tool annotation carries a requireConfirmation flag, so the boolean case
is a direct equivalent of FunctionTool(require_confirmation=True) rather
than something callers hand-roll. The flag is a compile-time constant,
though, so dynamic thresholds are evaluated inside the tool through
ToolContext, the way ADK Java does it. The prose that previously singled
out TypeScript for that now names Kotlin too.
The advanced example reads the returned payload through Number rather
than casting straight to Int, because the payload arrives decoded from
JSON and its numeric type is not guaranteed - the same trap the Go tab
calls out for float64.
* Badge the confirmation page with the version the API shipped in
The badge said Kotlin v0.8.0, the version adk-docs compiles against,
rather than the introducing release. ToolConfirmation,
ToolContext.requestConfirmation and the @Tool requireConfirmation flag
were all present at v0.1.0.
* Update confirmation.md
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
Zyan