* 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>
* 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>
* 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>
The call_reimbursement_tool group showed Python, TypeScript, Go and Java
but not Kotlin, even though the page already carries a Kotlin tab for
defining the tool a few sections earlier. Defining a long-running tool
without showing how to resume it leaves the Kotlin reader at the point
where the invocation pauses.
The new region extends the file that already backs this page rather than
adding a second one. It mirrors the Python flow: watch for the call whose
id appears in Event.longRunningToolIds, keep the matching
FunctionResponse, then send a copy of it back with the final status to
resume the paused invocation.
Scoped deliberately to that group. RequestInputTool and GetUserChoiceTool
were also on this backlog row, but they have no host page in ANY language
- they appear nowhere in the narrative docs, only in generated API
reference - so adding a Kotlin-only section for them would invent
structure rather than close a gap. Recorded for a product-docs request
instead.
* Add Kotlin to the session rewind page
The page was single-language: one bare Python fence, no tab structure,
and a badge div listing Python only. Kotlin has had Runner.rewindAsync
with matching semantics, so the code block is converted into a
Python/Kotlin tab group with the Python content kept verbatim.
Semantics were checked against the implementation rather than inferred
from the method name, since the page makes specific promises. Two hold:
AbstractRunner.rewindAsync appends a synthetic user event carrying
reversing state and artifact deltas, so rewound requests stay in the log
as the "How it works" section describes; and keys prefixed app: or user:
are skipped when the delta is computed, which is exactly the
"Global agent resources" limitation.
Worth knowing for anyone reading the interface: Runner.rewindAsync has a
default implementation that throws NotImplementedError. AbstractRunner
overrides it and InMemoryRunner extends AbstractRunner, so the documented
path works, but a custom Runner built straight on the interface would
not.
Runner.close was on the same backlog row and is left out: it is a
lifecycle concern with nothing to do with rewinding.
* Badge the rewind page with the version rewindAsync shipped in
The badge said Kotlin v0.8.0, the version adk-docs compiles against,
rather than the introducing release. Checking the tags, rewindAsync is
absent at v0.1.0 and v0.2.0 and first appears in AbstractRunner at
v0.3.0 - so the backlog row that recorded it as a v0.1.0 member was
wrong as well.
* Add TypeScript tabs to the graph workflow pages
The five /graphs/ pages documented graph workflows for Python and Go only,
so a TypeScript reader had to infer the API from the Python tab — which
does not translate: TypeScript has no `@node` decorator, schemas are Zod
objects rather than pydantic models, state is written through `ctx.state`
instead of returned on an event, and a user-facing message is the event's
`content` rather than a `message` field.
Every section that has a Python tab now has a TypeScript tab before the Go
one, backed by 26 snippet files under examples/typescript/snippets/graphs/.
The snippets are ported from the runnable samples in adk-js
(samples/workflows/), which already map 1:1 to these section anchors, and
they all type-check against the adk-js workflow API.
The tabs also call out the behaviours that are easy to get wrong and have
no Python equivalent: `ctx.runNode()` resolves to a node result rather than
the output, and does not throw when a child interrupts; a second event
carrying `output` silently overwrites the first; `LlmAgent.inputSchema` is
not the node's input contract inside a graph.
* Drop inline comments from the graph workflow snippets
The `//` annotations inside the snippet regions duplicated the prose that
already introduces each tab, and they were the first thing a reader saw in a
rendered sample rather than the API itself.
Removes the 83 `//` comments inside the `--8<--` regions across all 26 files.
JSDoc blocks stay, since they document what a function or schema is rather
than annotating a line; the Apache headers and the per-file orientation
comments above each region are untouched, and neither renders on the docs
site anyway.
Verified comment-only: compiling every file before and after with
`tsc --removeComments` produces byte-identical `.js` and `.d.ts` output
across all 52 emitted files.
* Use single-quoted strings in the graph workflow snippets
The 26 files landed double-quoted, which reads as a deliberate choice next to
the existing TypeScript snippets under examples/typescript/snippets/ — those
are predominantly single-quoted (49 of 68 imports). The repo has no prettier
config, so nothing enforces either style; this just stops the new directory
looking different from its neighbours.
Formatting only: `prettier --no-config --single-quote`, and every changed line
differs from the original by a quote character alone. Compiling before and
after with `tsc --removeComments` produces output whose only differences are
the same quote swaps, since tsc preserves the source quote style.
* Restore the upstream titleCase guard in the nested workflow snippet
Porting samples/workflows/routes/nested_workflow inlined the `titleCase`
helper and dropped the check that a character's uppercase form is a single
code point, along with the comment explaining why it is there. That changed
behaviour for word-initial characters whose uppercase expands: "first draft"
became "FIrst Draft" and "ßeta test" became "SSeta Test", where upstream
leaves both alone.
Restores the helper, the guard and the rationale. Because the helper sits
inside the --8<-- region, the explanation now renders on the page as well, so
the next person to touch it can see what the guard is for.
Also restores an unused `_ctx` parameter in the user_message snippet, the only
other place the port had drifted from upstream.
Verified by compiling each of the 26 snippets and its upstream counterpart at
adk-v2.0.0 with `tsc --removeComments` and comparing the emitted JavaScript:
all 26 are now semantically identical to samples/workflows/.
* Address review: plainer wording, and lift shared cautions out of the tabs
Wording, across all TypeScript tabs:
- No sentence starts with code syntax. "`route` is independent of..." becomes
"The `route` value is independent of...", and the same for the other cases.
- Removed informal and editorial phrasing: "earn their keep", "dropped
straight into", "reach for", "hands you", "two things to know going in",
"kick the children off", "fails loudly".
- Spelled out "/" as "and" in the `inputSchema` and `outputSchema` sentence.
- Described the `ctx.runNode()` interrupt behaviour in full rather than only
as "does not throw": it returns normally with `interruptIds` populated and
`output` undefined, and an orchestrator that skips the check continues with
a value the user never supplied.
- Explained what a JoinNode waits for instead of referring to "the barrier".
- Tied the `rerunOnResume` option back to the code sample it follows, and
introduced the two orchestrator details by saying when they matter.
Structure:
- The "Response schema input limitations" note appeared in both the Python
and TypeScript tabs. Replaced both with one language-neutral note after the
code examples.
- The "Stuck JoinNode" caution appeared in all three tabs. Replaced them with
one caution after the code examples, stating the rule that every node
feeding a join must produce an output.
- Moved the unbounded-cycle caution out of the TypeScript tab to the end of
the section, since it is not language specific.
Snippet header comments got the same wording pass. Verified afterwards: the
26 snippets still type-check, all 53 snippet includes resolve, and every
snippet is still semantically identical to samples/workflows/ at adk-v2.0.0.
* Apply suggestion from @joefernandez
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Add Kotlin snippet for filtering a toolset's tools
The Toolsets section had no Kotlin. ToolFilter and ToolPredicate arrived in
adk-kotlin 0.7.0 and give Kotlin something the other languages do not have: a
filter that receives the ReadonlyContext, so a toolset's tool list can depend on
session state or the current user.
The Python tab in the Simple Math Toolset example only gestures at this, in a
commented-out branch inside get_tools(). This snippet implements it, showing all
three states: no filter selects everything, allowList selects by name, and a
Predicate decides per invocation.
Placed in its own subsection rather than as a fourth tab on the Simple Math
Toolset example. That group is one worked example explained by five bullets --
an agent, a greet tool, name prefixing, a tool_context.state write and close() --
and a filtering snippet satisfies none of them. Kotlin cannot satisfy the prefix
bullet at all, since BaseTool.name is a val and adk-kotlin has no prefix
mechanism. A tab there would have left readers with four bullets that do not
describe the code above them.
Transcluded, so CI compiles and lints it. Verified beyond compiling: the tools
are generated by KSP, filtering returns the expected sets for all three cases,
and the tool bodies run -- addNumbers(7,3) -> {result=10}.
* feat: add Kotlin code snippets for tool definition and usage examples to ADK documentation
* refactor: move doc snippet markers above imports in Kotlin tool examples
* Match ExternalApprovalTool to the 0.8.0 BaseTool.run signature
adk-kotlin 0.8.0 widened `BaseTool.run`'s args from `Map<String, Any>` to
`Map<String, Any?>`, so the override in this snippet overrides nothing and the
class no longer implements its abstract member. `compileKotlin` fails with
"'run' overrides nothing" at MultiAgentExample.kt:61.
The break arrived on main with the 0.8.0 bump in #2143, not from this branch.
It surfaces here because the snippet runner builds the whole examples project,
while that PR's own check only compiled the files it changed - and it changed
no .kt files at all. Fixing it here because it blocks this PR; it is one
character and unrelated to the toolset filtering content.
* Correct the tool badges and drop the exclusivity from the filter heading
Four things from joefernandez's review:
- Heading shortened to "Filter tools in toolsets" as suggested.
- That shorter heading is conceptual, and the subsection carries a Kotlin-only
badge, which would repeat the exclusivity claim his b/548652184 is about.
Python, Java and TypeScript all filter toolsets by name or by a
context-aware predicate on BaseToolset, so the section now says so in a
sentence and the badge's title scopes the version to the Kotlin ToolFilter
API rather than to filtering as a concept.
- Page badge Kotlin v0.7.0 -> v0.1.0, and the Toolsets badge likewise. @Tool,
ToolContext and Toolset all exist at the v0.1.0 tag; only ToolFilter is new
in v0.7.0, and function-tools.md already carries v0.1.0.
- The Toolsets badge's bare "Java" span now reads v0.3.0, the first adk-java
release containing BaseToolset (added in a211ac4c, tagged v0.3.0).
* Add A2A consuming quickstart for Kotlin
adk-kotlin has been able to consume remote A2A agents since 0.6.0, and the docs
had no Kotlin page for it. This adds one alongside the Python, Go and Java
quickstarts, plus its nav entry.
A new page rather than a tab: docs/a2a has no tab groups at all, it is one page
per language, so this follows the section's own shape.
Two dependencies are needed, not one. The a2a artifact publishes the A2A SDK as
runtime-only, and A2AAgent's httpClient parameter defaults to JdkA2AHttpClient(),
so a2a-java-sdk-client has to be on the compile classpath as well. That number
was established by compiling, not by reading module metadata: the a2a artifact
alone fails with "Cannot access class 'A2AHttpClient'", and adding the client
artifact is sufficient -- spec and the jsonrpc transport arrive transitively.
Only the consuming side is documented, because that is all that exists: no
webserver source at v0.7.0 mentions a2a, so there is no Kotlin equivalent of the
exposing quickstarts. The page says so and links to the Python and Java ones.
A2AAgent is a suspending factory, and the implementation class behind it is
internal, so the factory is the only way to construct one. The snippet notes it.
Verified end to end rather than by compiling alone: served a real agent card
from a local server and ran the snippet, which fetched it, parsed it and wired
the remote agent in as a sub-agent --
"Root agent root_agent delegates to prime_agent".
* Correct the agent card claims and make the server step usable
A2AAgent does not read the remote's name from the card: the name is the
caller's, and independent of what the card advertises. It does not read the
transport either, which is hardcoded to JSON-RPC. What the card supplies is
the description and the streaming capability.
The server step told readers to start a server without saying how, and the
two obvious candidates do not work: adk-kotlin parses A2A 1.0 cards, which
require supportedInterfaces with a protocolBinding, and the adk-java and
adk-python samples both publish 0.3-style cards that A2AAgent rejects with
AgentCardResolutionError. State that, and give a minimal card verified by
running the snippet against it.
Also fix the root agent instruction, which referenced dice-rolling the agent
cannot do; match the Java snippet's prime-delegation wording.
* Point the A2A quickstart at the adk-python sample server
The page claimed neither the adk-java nor the adk-python sample works as the
server for this quickstart. The adk-python half is wrong. adk-python does not
serve its `agent.json` verbatim: `fast_api.py` parses it through
`_compat.parse_agent_card`, and under a2a-sdk 1.x that parse promotes the
legacy `url` and `preferredTransport` into `supportedInterfaces`. The dependency
is `a2a-sdk>=0.3.4,<2`, so a fresh install resolves to 1.x and the card on the
wire is A2A 1.0 - exactly what the Kotlin client requires.
So the page now names a server a reader can actually start, instead of asking
them to hand-write a card:
adk api_server --a2a --port 8001 \
contributing/samples/a2a/a2a_basic/remote_a2a
Its card is served under the agent's own prefix, and the snippet's agentCardUrl
follows it to http://localhost:8001/a2a/check_prime_agent. Confirmed the route
prefix in `attach_a2a_routes_to_app` and that the sample card's own `url`
already points there.
The adk-java half of the claim was correct and stays: `a2a_server` is pinned to
the 0.3.x A2A SDK and serves a 0.3 card. That, and the A2A 1.0 requirement it
illustrates, move into a note. The hand-written card survives as a collapsible
fallback for readers bringing their own server.
Reported by joefernandez in review of #2118.
* Upgrade Kotlin examples to adk-kotlin 0.8.0
The Kotlin examples project is pinned to adk-kotlin 0.7.0, which predates the
BigQuery agent analytics plugin and the JSON Schema constraint fields on
`Schema`. Bump the pin to 0.8.0 so snippets for those features can be written.
Only the three version strings change. Checked the 0.8.0 POM before bumping:
it still resolves Ktor 2.3.13 and kotlin-stdlib 2.1.20, so the explicit Ktor
pins and the 2.1.20 Kotlin/KSP plugin versions stay correct, and 0.8.0 removes
no API that the current snippets use.
Not compile-verified locally - no JDK 17 on hand, and the Gradle wrapper
rejects the JDK 26 that is. The PR check only builds .kt files changed in the
PR, so it will not cover this either; the first snippet PR on top of this one
is what will actually exercise the new version.
* Bump the Kotlin install instructions to 0.8.0
The dependency blocks readers copy from still pinned 0.5.0 - three releases
behind, and behind the examples project itself. Anyone following the quickstart
got an SDK without context caching, the Vertex AI memory and session services,
or the BigQuery analytics plugin, while the snippets on those same pages are
written against a newer API.
Verified on Maven Central that 0.8.0 is published for every artifact named
here: -core, -processor, -webserver, and -litertlm.
Only install instructions change. The `Kotlin v0.x` support badges are
deliberately left alone: they record the release a feature landed in, not the
current version.
* Add Kotlin snippet for the CallbackContext memory-write helpers
adk-kotlin 0.7.0 added addEventsToMemory and addMemory to CallbackContext,
alongside the addSessionToMemory the page already shows in Kotlin. They cover
the cases addSessionToMemory cannot: a chosen subset of events, and facts you
construct yourself rather than letting the service derive them.
Compiling changed the shape of this snippet. The obvious version read the
current turn's events off context.invocationContext, but that property is
internal -- CallbackContext exposes no way to reach the session. So
addEventsToMemory takes events the caller already holds, and the snippet says
so rather than quietly implying otherwise.
Both helpers, and addSessionToMemory, throw IllegalStateException when the
runner has no memory service. That is a runtime failure with nothing at compile
time to warn you, so the page states it. Verified by running both paths:
"Cannot add events to memory: memory service is not available." and
"Cannot add memory: memory service is not available."
Badged Kotlin v0.7.0, verified rather than assumed: neither helper exists on
CallbackContext at v0.6.0.
Appended to the existing MemoryExample.kt, already registered, so CI compiles
and lints it.
* docs: clarify CallbackContext memory methods and their default behavior
* Add Kotlin snippet for DebugLoggingPlugin
The Kotlin logging page covered LoggingPlugin's console output but not
DebugLoggingPlugin, available since adk-kotlin 0.6.0, which records the same
activity in full to a YAML file instead of truncated console summaries. Both
plugins override the same twelve callbacks, so the difference really is only
fidelity and destination.
Transcluded from the existing LoggingExamples.kt rather than written inline,
matching the rest of the page and keeping it in the compile regression suite --
the file is already registered in files_to_test.txt.
The sample passes includeSystemInstruction = false, since the plugin's KDoc
cautions that it writes raw prompts, tool arguments and session state to disk.
Verified against the upstream test that the flag records has_system_instruction
in place of the instruction text rather than dropping the field, and the
comment names that field so it can be found in the output.
outputPath is left at its default rather than passed explicitly; the default
filename is given in the prose instead, so the snippet does not imply the
parameter is required.
Page badge left at Kotlin v0.1.0: the other snippets on the page have worked
since then, so the version requirement for this one is noted in the prose.
* docs: add Kotlin version support tag to debug logging documentation
* Document how to check whether the context cache was used
The caching page explained how to turn caching on and never how to tell whether
it is working. CacheMetadata has been available since adk-kotlin 0.6.0 and is
undocumented: adk-python has fourteen code references to cache_metadata, while
adk-docs mentions it twice, both incidental -- a BigQuery schema table and a
bullet in the Live dev guide.
The snippet reads it from Event.cacheMetadata and covers both states the type
can be in, because the constructor enforces the split: cacheName, expireTime and
invocationsUsed must either all be set (an active cache) or all be null (the
fingerprint-only state used for prefix matching before a cache exists).
Notes that token counts live on LlmResponse.usageMetadata rather than here,
which the KDoc calls out to avoid duplication and a reader would otherwise
reasonably look for on CacheMetadata.
Badged Kotlin v0.6.0 and verified rather than assumed: the snippet compiles
against a temporary 0.6.0 pin as well as the current 0.7.0 one.
Transcluded and registered, so CI compiles and lints it. Exercised all four
paths with synthetic events: no metadata, fingerprint-only, active, and active
with expireSoon true.
* Correct when CacheMetadata is present on an event
The section claimed every event backed by an LLM response carries a
CacheMetadata. It does not: LlmResponse.cacheMetadata is null when caching
is disabled and also when the call produced no cache information, so the
claim was wrong even with caching on.
Say "can carry", name both null cases, and explain why the snippet checks
before reading. The snippet's own comment made the same overstatement.
* docs: clarify the behavior of expireSoon and cache status in documentation and snippets
adk-kotlin 0.7.0 added a plugins parameter to the agent-based InMemoryRunner
constructor. App.plugins already existed at 0.6.0, so this is an ergonomic
shorthand rather than a new capability, but it is the form a Kotlin reader
should see and the plugins page had no Kotlin at all.
Two tab groups rather than one. The Register group's prose refers to
"the CountInvocationPlugin plugin defined in the previous section", so a Kotlin
tab there alone would point at a class the page never defines in Kotlin. Adding
the Create group as well makes the pair self-contained.
Kotlin now appears in two of the page's nine groups; the remaining seven are
per-callback detail. Whether to finish the page is a separate decision.
Plugin declares exactly one abstract member, name -- all twelve callbacks and
close() have defaults -- so a custom plugin only overrides what it needs. The
snippet overrides beforeAgent and beforeModel, matching the callbacks the
surrounding prose describes.
Transcluded and registered, so CI compiles and lints it. Also run: the runner is
constructed with the plugin wired, and invoking beforeAgent twice prints
"[Plugin] Agent run count: 1" then 2, so the counter callbacks work.
* Upgrade Kotlin examples to adk-kotlin 0.7.0
The Kotlin examples were pinned to adk-kotlin 0.5.0, which predates the
context caching, Vertex AI memory, and RAG retrieval APIs. Bump the pin to
0.7.0 so snippets for those features can be added.
Three consequences of the bump are handled here:
- `ExperimentalResumabilityFeature` was removed in 0.7.0, so RunConfigExample
no longer opts into it. The annotation class is gone, not merely deprecated,
so this is a hard compile break rather than a warning that could be deferred.
- The Vertex AI session and memory services expose Ktor's `HttpClient` as a
defaulted constructor parameter, so any snippet naming them needs Ktor on the
compile classpath, not just at runtime.
- The `resolutionStrategy` block forcing kotlin-stdlib 2.1.20 is now dead. It
worked around 0.5.0 publishing a stdlib newer than this project's compiler;
0.6.0 fixed that upstream. Verified that the highest stdlib on the compile
classpath is still 2.1.20 without it.
Also fixes two unrelated snags found while validating the above:
- `check_kotlin_snippets.sh` walked `examples/kotlin` without pruning build
output, so after any local build it reported every generated KSP file as an
unregistered snippet. CI only ever ran it against a clean checkout, so the
bug was invisible there.
- A transclusion path in logging.md was split across two lines, so the include
never resolved and the code block rendered empty.
* Fix broken links to adk-python plugin samples
The three plugin sample links 404. adk-python renamed
`contributing/samples/plugin/` to `contributing/samples/plugins/`; the
directory contents are otherwise unchanged, so only the path segment moves.
This is what the repo-wide `link-check` job has been failing on. It is
unrelated to the 0.7.0 upgrade in this PR, but the check gates the merge and
the fix is confined to the three URLs.
Verified all three targets return 200.
* Add Kotlin snippets for Memory Bank and RAG memory
The memory page documented `VertexAiMemoryBankService` and
`VertexAiRagMemoryService` for Python and Java only; the Kotlin tab stopped at
the in-memory service. Both are available in adk-kotlin as of 0.7.0, so add
the two missing tabs.
Both services declare an `internal` primary constructor, so the snippets use
the public secondary one that takes project/location plus the engine or corpus
id -- reading the primary signature alone gives a constructor callers cannot
invoke.
The page's language-support badge stays at Kotlin v0.1.0: it marks when Kotlin
support for the page was introduced, and the other six Kotlin snippets on it
have worked since then.
The remaining diff in MemoryExample.kt is ktlint bringing pre-existing lines
into line with the repo style, which the linter now gates on because the file
is touched here.
* Correct the ragCorpus contract and wire both services to a Runner
Three fixes from review:
- The `rag_memory` KDoc claimed `ragCorpus` accepts a bare id or a full
resource name. It is the opposite: `normalizeCorpusName` does
`require(!ragCorpus.startsWith("projects/"))` and throws on a full name. The
Python tab directly above this snippet passes a full resource name, so a
reader switching tabs would have hit an IllegalArgumentException with a
comment telling them it was fine. The note now states the bare-id rule and
calls out the divergence from Python explicitly.
- Dropped "the primary constructor is internal" from the rendered snippet. It
is a note for reviewers, not for readers, who cannot see that constructor.
It stays in the PR description.
- Both snippets stopped at a factory function while the surrounding prose says
"instantiating the service and passing it to the Runner" and the Python tab
shows exactly that. They now build the service and pass it to a Runner.
* Upgrade Kotlin examples to adk-kotlin 0.7.0
The Kotlin examples were pinned to adk-kotlin 0.5.0, which predates the
context caching, Vertex AI memory, and RAG retrieval APIs. Bump the pin to
0.7.0 so snippets for those features can be added.
Three consequences of the bump are handled here:
- `ExperimentalResumabilityFeature` was removed in 0.7.0, so RunConfigExample
no longer opts into it. The annotation class is gone, not merely deprecated,
so this is a hard compile break rather than a warning that could be deferred.
- The Vertex AI session and memory services expose Ktor's `HttpClient` as a
defaulted constructor parameter, so any snippet naming them needs Ktor on the
compile classpath, not just at runtime.
- The `resolutionStrategy` block forcing kotlin-stdlib 2.1.20 is now dead. It
worked around 0.5.0 publishing a stdlib newer than this project's compiler;
0.6.0 fixed that upstream. Verified that the highest stdlib on the compile
classpath is still 2.1.20 without it.
Also fixes two unrelated snags found while validating the above:
- `check_kotlin_snippets.sh` walked `examples/kotlin` without pruning build
output, so after any local build it reported every generated KSP file as an
unregistered snippet. CI only ever ran it against a clean checkout, so the
bug was invisible there.
- A transclusion path in logging.md was split across two lines, so the include
never resolved and the code block rendered empty.
* Fix broken links to adk-python plugin samples
The three plugin sample links 404. adk-python renamed
`contributing/samples/plugin/` to `contributing/samples/plugins/`; the
directory contents are otherwise unchanged, so only the path segment moves.
This is what the repo-wide `link-check` job has been failing on. It is
unrelated to the 0.7.0 upgrade in this PR, but the check gates the merge and
the fix is confined to the three URLs.
Verified all three targets return 200.
* Add Kotlin snippet for the Knowledge Engine retrieval tool
The Knowledge Engine integration page only showed Python. `VertexAiRagRetrieval`
landed in adk-kotlin 0.7.0, so add a Kotlin tab and advertise Kotlin support in
the page badge.
Retrieval runs inside the model through the Gemini-native `vertexRagStore` kind
rather than as a locally executed tool, so the snippet configures the corpus via
`VertexRagStoreRagResource` and leaves invocation to the model.
Registers the new file in files_to_test.txt so it stays in the compile
regression suite.
* Use the conventional package for the RAG retrieval snippet
RagEngine.kt declared `package integrations`. Every other snippet in the tree
uses `com.google.adk.kt.examples.<area>`. It compiled either way because the
source root is `snippets/` and Kotlin does not require the directory to match
the package, so nothing would have caught it.
Also worth flagging for anyone reading this alongside the memory snippets: the
two APIs take opposite corpus formats. `VertexAiRagRetrieval` here wants the
full `projects/.../ragCorpora/...` resource name, while
`VertexAiRagMemoryService` wants a bare corpus id and rejects the full name.
That is the library's doing, not a docs inconsistency.
- Add pip install "google-adk[gcp]" step to Eventarc Prerequisites.
- Clarify datacontenttype inference defaults and specify application/json in snippet prompt.
- Update Runtime Lambda table entry to use ctx.session_id and note support for payload and Context.
- Update OMIT table entry to list all mandatory attributes (type, source, bus, id, specversion).
Addresses feedback in https://github.com/google/adk-docs/pull/2045#issuecomment-5184438669
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* Upgrade Kotlin examples to adk-kotlin 0.7.0
The Kotlin examples were pinned to adk-kotlin 0.5.0, which predates the
context caching, Vertex AI memory, and RAG retrieval APIs. Bump the pin to
0.7.0 so snippets for those features can be added.
Three consequences of the bump are handled here:
- `ExperimentalResumabilityFeature` was removed in 0.7.0, so RunConfigExample
no longer opts into it. The annotation class is gone, not merely deprecated,
so this is a hard compile break rather than a warning that could be deferred.
- The Vertex AI session and memory services expose Ktor's `HttpClient` as a
defaulted constructor parameter, so any snippet naming them needs Ktor on the
compile classpath, not just at runtime.
- The `resolutionStrategy` block forcing kotlin-stdlib 2.1.20 is now dead. It
worked around 0.5.0 publishing a stdlib newer than this project's compiler;
0.6.0 fixed that upstream. Verified that the highest stdlib on the compile
classpath is still 2.1.20 without it.
Also fixes two unrelated snags found while validating the above:
- `check_kotlin_snippets.sh` walked `examples/kotlin` without pruning build
output, so after any local build it reported every generated KSP file as an
unregistered snippet. CI only ever ran it against a clean checkout, so the
bug was invisible there.
- A transclusion path in logging.md was split across two lines, so the include
never resolved and the code block rendered empty.
* Fix broken links to adk-python plugin samples
The three plugin sample links 404. adk-python renamed
`contributing/samples/plugin/` to `contributing/samples/plugins/`; the
directory contents are otherwise unchanged, so only the path segment moves.
This is what the repo-wide `link-check` job has been failing on. It is
unrelated to the 0.7.0 upgrade in this PR, but the check gates the merge and
the fix is confined to the three URLs.
Verified all three targets return 200.
InMemorySessionService.create_session is async, so calls without await
return unawaited coroutines and the sessions are never created, causing
SessionNotFoundError on subsequent runner.run_async() calls.
Co-authored-by: Kristopher Overholt <koverholt@google.com>
* docs: Document new add_memory method for direct memory management
* 1350-6Memoryupdate.md
* Update on memory.md according to issue #1350 - 6
Simplified dense sections, corrected markdown formatting errors, and fixed typos to align with documentation standards. Corrected some sections from the original page and the agent's PR that were a little clunky. Erased sentences inside paragraph's ,Joe's request, and included commas instead. All this while including the necessary update.
* Update memory.md
-Worked on feedback, fixed errors, changed wording slightly, and reviewed format.
-Some changes were lost when I tried to resolve conflicts between branches in my last commit. I added them back here.
* Fix add_memory example and memory operations list in memory.md
* Format memory.md: line wrapping, snippet cleanup, and Java example
---------
Co-authored-by: adk-bot <adk-bot@google.com>
Co-authored-by: Kristopher Overholt <koverholt@google.com>
* #1029 - 8 vector_store_similarity_search and SpannerVectorStoreSettings
Added vector_store_similarity_search to SpannerToolset. SpannerVectorStoreSettings is introduced to support this feature.
* Update spanner.md
* Update spanner.md
Applied feedback. Additionally, reviewed the phrasing in the intro for clarity and concision and did some minor formatting edits.
* Fix wrapping, missing import, trailing whitespace, formatting fixes
* Restructure Spanner page: add intro, section headings, reorder vector search
* Add experimental tags/notes to corresponding integration pages
---------
Co-authored-by: Kristopher Overholt <koverholt@google.com>
* Fix Go multi-tool tutorial snippet to include two tools
* Update model string in multi-tool snippets to gemini-flash-latest in Python, TS, Java
---------
Co-authored-by: Kristopher Overholt <koverholt@google.com>
The memory docs and the express-mode weather agent notebook referenced
`adk.tools.preload_memory_tool.PreloadMemoryTool()`, which raises
`AttributeError: module 'google.adk.tools' has no attribute
'preload_memory_tool'` because the submodule is not exposed via the
package's lazy `__getattr__`.
Use the documented public API `from google.adk.tools import preload_memory`
and pass the `preload_memory` instance directly, consistent with how the
sibling `load_memory` tool is shown in the same page.
Fixes#1771
Co-authored-by: Kristopher Overholt <koverholt@google.com>
* Format localhost URLs as inline code in quickstarts
* Correct module paths and stale notes in snippet comments
* Reword "and later" to "and higher" in snippet notes
* docs: update GOOGLE_GENAI_USE_VERTEXAI to GOOGLE_GENAI_USE_ENTERPRISE in configs and models
* docs: update GOOGLE_GENAI_USE_VERTEXAI in deployment and setup guides
* docs: update GOOGLE_GENAI_USE_VERTEXAI and Client parameter in integrations and streaming docs
* docs: update GOOGLE_GENAI_USE_VERTEXAI in tutorials and examples
---------
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
* adding go getting started to 2.0 docs
* updating graphs docs for go; adding in workflow example go snippets
* Updating HiTL docs for Go 2.0
* updating Go getting started guide for v2
* Updating Routes docs for Go v2
* Updating data handling docs for Go 2.0
* Updating dynamic workflows docs for Go 2.0
* fix(docs): set ADK Go 2.0 GA date on the 2.0 landing page
* fix(docs): standardize ADK Go 2.0 install/import on /v2 @ v2.0.0
* updating announcement banner
* routes snippets updates
* 2.0 install instructions clean-up
* updating collaboration docs for go v2 + new example snippet
---------
Co-authored-by: Karol Piotrowicz <kpiotrowicz@google.com>
* Update version for ADK Kotlin to 0.2.0
* Update version for ADK Kotlin examples to 0.2.0
* Update install steps on multi-tool-agent page
* Update ADK Kotlin API reference docs to 0.2.0
* Remove runner parameter from AdkWebServer constructor
Daria Wieliczko