Add Kotlin snippet for VertexAiSessionService - #2102
Merged
Conversation
The VertexAiSessionService section showed Python, Go and Java. Kotlin gained
the service in adk-kotlin 0.7.0, so add a Kotlin tab and Kotlin to that
section's language-support badge.
Kotlin addresses the reasoning engine differently from every sibling tab on
the page, so the snippet says so at the point of use:
- The engine is fixed at construction via `reasoningEngineId`. The 0.7.0 KDoc
is explicit that, unlike the Python and Java ADK, `SessionKey.appName` is
never parsed to derive the engine -- it is only a label. The Python tab
above passes the engine through `app_name` on each call.
- `reasoningEngineId` must be the bare numeric id. The constructor rejects a
full resource name outright (`require(reasoningEngineId.all { it.isDigit() })`),
while the Python tab passes
`projects/.../locations/.../reasoningEngines/...`.
A reader copying the adjacent Python idiom would therefore fail twice over.
Written inline to match the two existing Kotlin tabs on this page. Inline
snippets never reach Gradle, so this one was additionally compiled against the
0.7.0 pin in a scratch file that is not part of the commit.
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Five fixes from self-review against the 0.7.0 sources and upstream's own VertexAiSessionServiceExample.kt, which I should have consulted before writing the first version: - State that the service is JVM-only. It lives in core/src/jvmMain, so it does not exist on Android. Kotlin is the only language on this page where that distinction applies, so if the Kotlin tab omits it, nothing carries it. - Show the service actually being used. The snippet stopped at an uncalled `suspend fun`; it now hands the service to an InMemoryRunner, which is what the section is about and what the upstream example does. - Use `runBlocking` in a `main`, matching upstream, instead of a suspend function nothing calls. - Drop `state = mapOf(...)`. It defaults to null, upstream omits it, and the Java tab explicitly notes no initial state is needed, so it introduced a concept the sibling tabs deliberately avoid. - Widen the comparison from "the Python and Java tabs" to all the other tabs. The KDoc phrasing names Python and Java, but this page also has a Go tab. The added LlmAgent needs an explicit `model`; the first draft would not have compiled without it, which the scratch compile caught.
The previous revision added an LlmAgent, a Gemini model and an InMemoryRunner, taking the tab to 30 code lines against Python's 5, Go's 8 and Java's 12. No sibling tab on this page constructs a runner or an agent, and this section's prose never mentions one -- it is a characteristics list, not a wiring guide. That change came from misapplying a review finding. On sessions/memory the equivalent note was right: the prose there says "instantiating the VertexAiMemoryBankService and passing it to the Runner" and the Python tab shows exactly that. Neither holds here, so the runner was answering a question this page does not ask. Now scoped like the Java tab, the closest analogue: construct the service, then create one session. That is still enough to demonstrate both divergences -- the engine pinned at construction as a bare numeric id, and appName being only a label -- since showing the second requires a SessionKey. `runBlocking` stays, because createSession is a suspend function; it is the direct counterpart of the Java tab's `.blockingGet()`, and the comment now says so. Recompiled against the 0.7.0 pin in a scratch file.
…hing documentation note
wikaaaaa
approved these changes
Aug 11, 2026
joefernandez
approved these changes
Aug 17, 2026
joefernandez
left a comment
joefernandez
left a comment
Collaborator
There was a problem hiding this comment.
thanks for the update!
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
3 participants
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
The
VertexAiSessionServicesection ofdocs/sessions/session/index.mdshowedPython, Go and Java. Kotlin gained the service in adk-kotlin 0.7.0, so this adds
a Kotlin tab and adds Kotlin to that section's language-support badge.
Why this snippet carries so much comment
Kotlin addresses the reasoning engine differently from every sibling tab on
the page, in two independent ways. Both are enforced at runtime, so getting it
wrong fails at the first call rather than at compile time.
app_nameon each callprojects/…/reasoningEngines/…app_nameon each call"123456789"VertexAIService(ctx, modelName)reasoningEngineIdat constructionFrom the 0.7.0 KDoc:
and the constructor:
require(reasoningEngineId.all { it.isDigit() }) { "reasoningEngineId must be the numeric reasoning engine id ..., not a resource name" }A reader copying the Python idiom directly above would fail twice: passing a
resource name where a numeric id is required, and expecting
appNameto selectthe engine when it is inert. The snippet calls both out inline rather than
burying them here.
Notes for reviewers
VertexAiSessionServiceis incore/src/jvmMain, so it doesnot exist on Android. Kotlin is the only language on this page where that
distinction applies, so the tab says so above the code.
then create one session. No runner or agent — no sibling tab on this page
builds one, and this section's prose is a characteristics list rather than a
wiring guide. An earlier revision added an
LlmAgent+Gemini+InMemoryRunnerand ran to 30 code lines against Python's 5 and Java's 12;that was misapplying a note that was correct on
sessions/memory, where theprose does promise a Runner and the Python tab shows one.
runBlockingis the counterpart of the Java tab's.blockingGet()—createSessionis a suspend function, so some bridge is unavoidable.internal. The snippet uses the publicsecondary one,
(project, location, reasoningEngineId, credentials, httpClient).kotlin_api.py sigshows only the primary, so checking thesignature alone suggests a constructor callers cannot invoke.
id = nullinSessionKeyis deliberate.toAdk(appName, userId, fallbackId)prefers the server-assigned id from the responsenameandfalls back to
key.idonly when absent, so null is the correct way to letthe service assign one. Upstream does the same.
createSession(key, state = null)defaults it and theJava tab notes none is needed, so passing one would add a concept the
siblings avoid.
Kotlin v0.1.0and stays there — it marks when Kotlin support for the pagewas introduced. This
###section has its own badge, which had no Kotlin atall; it gets
v0.7.0, when the service landed.Verification
verify_snippets.py: L0/L2/L3/L5/L6 pass.against the 0.7.0 pin in a scratch file, which is not part of the commit.
That caught a missing required
modelargument onLlmAgentthat L0 alonedid not.
Pre-existing issue found while reviewing, not fixed here
The page's first Kotlin tab (the
InMemorySessionServiceexample, aroundL142) does not compile: it calls the suspend
createSessionoutside acoroutine and has top-level statements. Out of scope for this PR, but it should
be fixed — happy to file or follow up.