mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
main
1197 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Saloni Gupta
|
a7dbbcf986 | Removed the incompatible output_schema=str from graph samples (#2228) | ||
|
Markus Ecker
|
0a75ee1214 |
docs(integrations): use transparent kite icon for CopilotKit catalog card (#2221)
Replace the CopilotKit catalog icon with the kite mark on a transparent background so it matches the other integration cards instead of showing a dark square. |
||
|
wolo
|
9b01c6f526 |
docs(integrations): document Go support for the Postman MCP server (#2211)
* docs(integrations): document Go support for the Postman MCP server The Postman page carried Python and TypeScript tabs only, so Go users had no documented way to reach the Postman MCP server even though adk-go needs no new code for it. Both transports the page describes are already covered by google.golang.org/adk/v2/tool/mcptoolset: mcp.CommandTransport for the local npx server, and Config.Endpoint plus Config.Auth for the remote streamable HTTP server, where auth.StaticToken produces the same Authorization: Bearer header the Python and TypeScript samples set by hand. Add the lst-go language-support span and a Go tab with the same Local and Remote sub-tabs as the other two languages, following the pattern used by agent-registry.md and mcp-toolbox-for-databases.md. The optional server flags are held in an args slice so the Configuration section's "add --full or --code to the args list" reads correctly for Go as well. * docs(integrations): scope the env passed to the Postman MCP server The Go sample forwarded the whole parent environment to a package fetched from npm at run time, including the GOOGLE_API_KEY it reads a few lines earlier. Pass an allowlist instead: the Postman key plus the variables npx needs on POSIX and Windows. --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Ali Adnan
|
9ce0e98b5e |
fix: await create_session in agent_search example (#2053)
create_session is async; calling it without await at module scope produces an un-awaited coroutine. Wrap with asyncio.run, matching the pattern used in other built-in tool examples. |
||
|
Ali Adnan
|
911869c6de |
fix: remove broken relative import in rag_engine example (#2052)
* fix: remove broken relative import in rag_engine example The snippet imported from a non-existent .prompts module and used an undefined return_instructions_root(). Replaced with a self-contained instruction string so the knowledge-engine example runs standalone. * Apply suggestion from @joefernandez --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Ali Adnan
|
3b350ea25b |
docs: add missing Apache 2.0 license headers to python snippets (#2054)
Three example files were missing the required Google license header, which fails the License Header Lint CI check. Prepend the standard header. |
||
|
Ali Adnan
|
36ef9871e2 |
fix: await create_session and add license header in agent_cli example (#2055)
* fix: await create_session and add license header in agent_cli example create_session is async; the un-awaited coroutine caused a RuntimeError when session.id was accessed. Also added the missing Apache 2.0 header. * Apply suggestion from @joefernandez --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Amaad Martin
|
9f21af3c0c |
chore(examples): bump @google/adk to 1.5.0 in five TypeScript examples (#2080)
Three of these five examples do not type-check against the version they
pin, so anyone who copies them gets compile errors before they get an
agent. Bumping to the current 1.5.0 release fixes all three.
Verified by running `npm install` and `tsc --noEmit` in each directory
against the pinned version and against 1.5.0:
example pinned before after
agents/custom-agent ^0.2.0 pass pass
agents/llm-agent ^0.2.0 FAIL pass
get-started/multi_tool_agent ^0.2.0 FAIL pass
sessions ^0.6.1 pass pass
skills ^0.6.1 FAIL pass
The two 0.2.x failures are the zod v3 -> v4 change in `ToolInputParameters`
(TS2322); the `skills` failure is that `Skill`, `SkillToolset` and
`loadSkillFromDir` were not exported until after 0.6.1 (TS2305).
`@google/adk-devtools` is bumped alongside `@google/adk` in the same five
files. The two packages are released together from the adk-js monorepo and
share a version line, so leaving devtools on 0.2.x/0.6.x while the runtime
moves to 1.5.0 would pin a combination that is never published or tested
together. This is a three-major bump and is called out here deliberately
rather than being buried in the diff.
Four other examples stay pinned at ^0.2.0 and are deliberately not bumped:
agents/workflow-agents tsconfig `include` points at a nonexistent src/,
plus an invalid --ignoreDeprecations value
callbacks invalid --ignoreDeprecations value
tools/function-tools unused locals/parameters (TS6133)
tools/overview unchecked `m.content.parts` (TS18048)
All four fail `tsc --noEmit` at 1.5.0 as well as at 0.2.x, and none of the
failures is an ADK API incompatibility -- they are tsconfig mistakes and
bugs in the sample sources. Bumping them would add churn without making a
single one of them work, and would put unverified entries in a change whose
whole claim is that every bump was type-checked. Repairing those four
examples is a separate change.
Co-authored-by: Amaad Martin <amaadmartin@google.com>
|
||
|
Akshit Sharma
|
66b0cbca8d | Update agent name in multi-tool agent tutorial (#2213) | ||
|
Kathy Wu
|
fb23822335 |
Update outdated BigQuery integration sample code (#2214)
The BigQuery integration page still imports from google.adk.tools.bigquery, which now raises a DeprecationWarning pointing at google.adk.integrations.bigquery. Update all five auth snippets and the included sample to the new path. The sample also wrapped session_service.create_session() in asyncio.run(), which blows up in Colab and other notebooks where a loop is already running. Restructure it around an async main() that awaits create_session() and iterates runner.run_async(), matching the pattern the other built-in tool snippets already use. Bug: b/559149787 Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
eliasecchig
|
2743c90a7f |
docs(get-started): add migrate to ADK guide (#2197)
* docs(get-started): add migrate to ADK guide * docs(get-started): address review feedback on migration guide * Apply batched suggestions from review Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> * Update migrate.md * Update migrate.md --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
George Weale
|
c21cd63918 |
Fix code samples that do not compile against the shipped SDKs (#2194)
* Fix code samples that do not compile against the shipped SDKs Checked the code samples against the real published libraries and corrected what does not compile or resolve. Verified against google-adk 2.8.0 for Python, @google/adk 2.0.0 for TypeScript, google-adk 1.6.0 for Java, adk-kotlin 0.8.0 for Kotlin, and adk/v2 2.3.0 for Go. Go: tool.Context does not exist in the v2 line and never has. The type is agent.Context, which this repository's own Go examples already use. Nine sites. Four import blocks also omitted the fmt they call. Java: two imports naming packages that do not exist, com.google.adk.agent (the package is agents) and com.google.adk.agents.Content (it is a genai type). Four wrong types, each confirmed against the jar with javap: EventActions.stateDelta returns Map not ConcurrentMap, artifactDelta returns Map<String, Integer> rather than ConcurrentMap<String, Part>, FunctionResponse.response yields Map<String, Object>, and loadArtifact takes the version as an int so the Optional argument matched no overload. Python: four coroutines used without await, which also masked a SearchMemoryResponse.results field that does not exist. The field is memories, holding MemoryEntry objects; the TypeScript and Java tabs of the same example had the same mistake. Also CodeExecutionInput imported from the wrong module, a calendar_tool_set object that does not exist in place of CalendarToolset, two positional Part.from_text calls against a keyword-only signature, five LlmAgent samples missing the required name, and an external access token sample built on an enum member and a field that the package does not define. Also corrects samples that could not parse at all: an unindented plugin class body, bracket and text block typos, a truncated call, an await in a non-async function, an await dedented out of the condition meant to guard it, a mid-file Java import, and a fence that opened at six spaces and closed at eight, which made a page render a literal code fence as body text. * Yield the workflow node's result instead of returning it code_workflow yields, which makes it an async generator, and returning a value from one is a syntax error. A generator node conveys its result by yielding an event whose output the runner copies to the context, which is the form the data handling page already uses. * docs(tools): simplify the toolset headings per review Drop the parenthetical class lists from the two toolset headings in the authentication page. Nothing links to either anchor. --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Shahin Saadati
|
290bf4e05e |
Regenerate Kotlin API reference for adk-kotlin 1.0.0 (#2212)
The published Kotlin API reference was still generated from adk-kotlin 0.5.0, so it described an API several releases behind what the docs tell people to depend on. Regenerating it required repairing the generator first. adk-kotlin now runs Dokka in V2 mode, where the V1 `dokkaHtmlMultiModule` task refuses to run at all, and V2 has no implicit multi-module aggregation: the root project only collects modules that are declared as `dokka` dependencies, which adk-kotlin does not do for itself. The script therefore appends those declarations to its throwaway clone before invoking `dokkaGenerateHtml`, and copies from the V2 output path. The regenerated site adds four modules that did not exist at 0.5.0: firebase, mlkit, examples-android and examples-java. |
||
|
Shahin Saadati
|
4505cb7e13 |
Fix the Kotlin API reference generator for Dokka 2 and regenerate at 0.9.0 (#2204)
## Summary
The published Kotlin API reference has rendered **0.5.0** since it was
last
generated — four releases behind `main`, which is on 0.9.0. This
regenerates it
and fixes the generator that made it impossible.
It is not a forgotten manual step. `tools/kotlin-api-docs/generate.sh`
cannot
run against any adk-kotlin newer than **v0.6.0**.
## Why it was stuck
adk-kotlin moved from Dokka **1.9.20** to **2.2.0** at **v0.7.0**, and
Dokka 2
changed three things the script depends on:
1. **The task is gone.** `dokkaHtmlMultiModule` survives only as a
disabled
stub. Against a v0.9.0 clone, `./gradlew tasks --all` lists it verbatim
as:
```
dokkaHtmlMultiModule - [⚠ V1 tasks disabled] Runs all subprojects …
```
The build fails before generating anything.
2. **The output path moved** from `build/dokka/htmlMultiModule` to
`build/dokka/html`.
3. **Root aggregation is gone.** Dokka 1 inferred the unified
multi-module site
from the subprojects; Dokka 2 requires an explicit
`dependencies { dokka(project(...)) }` block, and adk-kotlin's root
build has
none. So even with the task name fixed there is no combined site to copy
—
only a dozen disconnected per-module ones.
## What this changes
**`tools/kotlin-api-docs/generate.sh`** — the three fixes above, plus a
post-generation check that `index.html` actually renders the requested
version.
Nothing verified that before, which is exactly how a 0.5.0 site sat in
the repo
looking freshly built.
The aggregation block is injected into the throwaway clone the script
already
makes, rather than sent upstream to adk-kotlin. That keeps the whole fix
inside
adk-docs — no second repo, no second review — and makes the module list
a docs
decision rather than an SDK one.
**`docs/api-reference/kotlin/`** — regenerated at 0.9.0. 2,462 files.
## Module coverage changes, and not purely additively
Please review this part specifically; it is the only judgement call
here.
| Module | Before | After | |
|---|---|---|---|
| `core`, `a2a`, `litertlm`, `processor`, `webserver` | ✅ | ✅ |
unchanged |
| `integrations` | ❌ | ✅ | **added** |
| `testing` | ❌ | ✅ | **added** |
| `examples` | ✅ | ❌ | **dropped** |
| `firebase`, `mlkit` | ❌ | ❌ | attempted, produce nothing |
- **`integrations` matters most.** It hosts
`BigQueryAgentAnalyticsPlugin`,
which `docs/integrations/bigquery-agent-analytics.md` documents and the
API
reference has never covered.
- **`examples` is dropped** because it is sample code rather than API
surface,
and it declares a JDK 21 toolchain that fails to auto-provision and
takes the
entire build down with it. Happy to restore it if you disagree, but it
needs
the toolchain problem solved first.
- **`firebase` and `mlkit` aggregate but emit empty directories** —
Dokka 2
generates no pages for their androidMain source sets. I left them out
rather
than shipping empty modules that imply coverage that is not there.
Making them
work needs a Dokka source-set fix in adk-kotlin, so it is out of scope
here.
## Verification
- A clean run of the committed script reproduces this exact tree.
- `index.html` renders `0.9.0`, and no file under
`docs/api-reference/kotlin/`
still contains `0.5.0`.
- The one deep link into the reference —
`docs/runtime/runconfig.md:364`, into
`google-adk-kotlin-core/com.google.adk.kt.agents/-run-config/` — still
resolves.
- The GA tag is injected exactly once per page. Eight files are skipped:
the
`navigation.html` fragments, which have no `<head>` to inject into.
- No temp-clone paths leaked into the generated HTML.
Built with **JDK 26** and Android SDK **platform 34**. adk-kotlin
declares a JDK
17 toolchain, but Dokka never needed to launch it for the aggregated
modules.
## Reviewing 2,462 files
Almost all of it is generated HTML. The only hand-written change is
`tools/kotlin-api-docs/generate.sh` (+57/-13); everything else is Dokka
output.
Reviewing the script and spot-checking a couple of rendered pages is the
useful
version of this review.
## Relationship to #2152
#2152 pins adk-docs to adk-kotlin 1.0.0 and lists regenerating this
reference on
its pre-merge checklist, blocked on a `v1.0.0` tag that does not exist
yet.
This PR deliberately does **not** wait for that. Doing it at 0.9.0 now
clears
four releases of staleness immediately and proves the toolchain works
while
there is no deadline, instead of discovering the generator is broken on
release
day. Once 1.0.0 ships, #2152 re-runs the same script with a different
argument.
|
||
|
Kaz Sato
|
77ac9368c6 |
docs(live): restore Gemini 3.1 Flash Live and fix broken anchors (#2208)
* docs(live): restore Gemini 3.1 Flash Live and fix broken anchors Verify the models and limits content merged in #2086 against upstream documentation. The platform limits table is correct as merged and stays as is: audio-only sessions cap at 15 minutes and audio+video at 2 minutes on both backends, a connection lasts ~10 minutes, and Agent Platform additionally defaults a conversation session to 10 minutes. The earlier claim that Agent Platform capped every session at 10 minutes conflated the connection limit with the session limit. Restore the coverage that was dropped: - `gemini-3.1-flash-live-preview` is a real model, released 2026-03-26 and documented on AI Studio. It is not available on Agent Platform, which supports no Gemini Live 3.x model. - Mark launch stages. `gemini-live-2.5-flash-native-audio` is the only GA Live model; the AI Studio IDs are all preview. - Give the per-model feature table a second column, since with one column it said nothing. 3.1 supports neither proactivity/affective dialog nor non-blocking tools, and configures thinking with `thinking_level` rather than `thinking_budget`. - State the `global` location restriction as fact rather than as something to go check: Live 2.5 models are not served there. Also fix two anchors that do not resolve, and a deprecated model ID: - `live/configuration.md` linked to `#response-modalities`; the heading is `## Response modes`. - `live/evaluation.md` linked to `#audio-user-simulation-live-agents`; the heading is `## Audio user simulation for live agents`. - `tutorials/multi-tool-agent.md` suggested `gemini-2.0-flash-live-001`, which was shut down on 2025-12-09. * Apply suggestion from @joefernandez --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Markus Ecker
|
cf135fc7e6 |
docs(integrations): add CopilotKit integration page (#2203)
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Shahin Saadati
|
e040a94029 |
Bump adk-docs to adk-kotlin 1.0.0 (#2152)
* Bump adk-docs to adk-kotlin 1.0.0
KT-23. adk-docs compiles its Kotlin snippets against the pinned SDK, so no 1.0
feature can be documented until this pin moves. Prerequisite only - no snippets,
no prose about 1.0 features.
Moves the examples pin (core, webserver, processor, a2a) and the install
instructions readers copy from, which track the pin for the same reason they did
at 0.8.0: leaving them behind hands newcomers an SDK older than the snippets on
the same page.
THIS DOES NOT BUILD YET, and cannot until the artifacts are published:
> Could not find com.google.adk:google-adk-kotlin-core:1.0.0.
> Could not find com.google.adk:google-adk-kotlin-webserver:1.0.0.
> Could not find com.google.adk:google-adk-kotlin-a2a:1.0.0.
Maven Central carries 0.8.0 as the newest release for every artifact today, and
google/adk-kotlin has no v1.0.0 tag. The PR is a draft until the release lands.
Two comments that pinned third-party versions against adk-kotlin 0.8.0's
catalog - Ktor 2.3.13 and a2a-java-sdk-client 1.0.0.Final - now say the match
was made against 0.8.0 and needs re-checking, rather than restating it as though
it still held. A major release is exactly where a transitive version moves.
Also note the version string is assumed to be `1.0.0`. If the release is cut as
`1.0.0-rc.1` or similar, these five coordinates need to match it.
* Bump the A2A quickstart's dependency to 1.0.0 as well
Missed on the first pass, and the reason is worth recording: the sweep used
`google-adk-kotlin[a-z-]*:0\.8\.0`, whose character class has no digits, so it
silently skipped `google-adk-kotlin-a2a` - the one artifact with a digit in its
name. Every other coordinate matched, so the search looked exhaustive and was
not.
The corrected pattern is `google-adk-kotlin[a-z0-9-]*:[0-9]+\.[0-9]+\.[0-9]+`.
Run repo-wide it now finds five live coordinates in the examples build file and
seventeen in the docs, all at 1.0.0, and nothing left below it.
* Bump every adk-kotlin coordinate to 1.0.0
main moved to 0.9.0 (#2191) after this branch was cut, so the merge above
took main wholesale and this re-applies the 1.0 pin on top. Two coordinates
are new since the branch was opened and were never in the original bump:
- `google-adk-kotlin-litertlm` in `docs/agents/models/litert-lm.md`
- `google-adk-kotlin-integrations` in
`docs/integrations/bigquery-agent-analytics.md` (arrived with #2147, the
reconciliation the original PR description flagged as owed)
Also bumps the two tag-pinned `adk-kotlin/blob/v0.8.0` source links in
`docs/agents/llm-agents.md`. Those point at `SchemaUtils` and `LlmAgent` to
back a claim about how Kotlin validates output schemas; pinned to a tag five
releases behind, they document what 0.8 did, not what a reader on 1.0 runs.
19 coordinates and 2 permalinks. No `com.google.adk:google-adk-kotlin-*`
coordinate below 1.0.0 remains anywhere in the repo.
Deliberately untouched, because they record history rather than a pin:
the ~42 `Kotlin vX.Y.Z` support badges (bumping them would assert that e.g.
artifacts first shipped in Kotlin 1.0), and the "added in adk-kotlin 0.8.0"
/ "Since adk-kotlin 0.7.0" comments in CapitalAgent.kt and
CountInvocationPlugin.kt.
Still unbuildable and still a draft: Maven Central's newest
google-adk-kotlin-core is 0.9.0 and google/adk-kotlin's newest tag is v0.9.0,
so there is no 1.0.0 to resolve. `verify_snippets.py --fast` passes L3, L5 and
L6 and refuses L0 for exactly that reason -- no grounding source exists at the
target version. The bundled Dokka API reference under docs/api-reference/kotlin
still renders 0.5.0 across 1,674 files and cannot be regenerated until the tag
exists; it remains on the pre-merge checklist.
|
||
|
Maurizio Ipsale
|
f85bf69487 |
docs(community): add ADK: From Zero to Hero course (#2173)
* docs(community): add ADK: From Zero to Hero course A 40-module, hands-on ADK 2.0 training course by a Google Cloud Authorized Trainer and GDE, built around real challenge labs (theory -> lab with TODOs -> hidden solution) rather than copy-paste tutorials. Currently Python-only. https://mauripsale.github.io/doc-adk-training/ * docs(community): use evergreen '40+ module' wording for the course card |
||
|
Zoe Steinkamp
|
4983b6974a |
Integration page for clickhouse (#2133)
* Create clickhouse.md Adding file * 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> |
||
|
Dat Daryl Ngo
|
9dea50349c |
Clarify Arize AX and Phoenix integration guidance (#2142)
* docs: refresh Arize integration links * docs: address Arize integration review --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Kaz Sato
|
e1c5d8b780 |
docs(runtime): correct TypeScript claims in RunConfig streaming docs (#2101)
* 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> |
||
|
JuanCa
|
63a9b510da |
Cloud Trace Data Capture Update (#1179) (#2168)
Details added on data capture and privacy settings for Cloud Trace. |
||
|
Daria Wieliczko
|
eb989519a7 |
Upgrade Kotlin docs to adk-kotlin 0.9.0 and move off AdkWebServer (#2191)
* 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> |
||
|
Joe Fernandez
|
f7c7d41e5c | Update main.html (#2192) | ||
|
Kaz Sato
|
03eccf55e0 |
docs(live): decompose the dev guide and fix staleness vs adk-python main (#2086)
* 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>
|
||
|
isseink
|
a3959cf125 |
docs(artifacts): document enable_spreadsheet_parsing in LoadArtifactsTool (#2134)
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. |
||
|
Alexey Kalenkevich
|
cab6ef918b |
Add the ADK TypeScript 1.x compatibility section to the ADK 2.0 page (#2190)
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`. |
||
|
Shahin Saadati
|
674851324e |
Add the Kotlin tab for answering a long-running tool call (#2149)
* 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> |
||
|
Shahin Saadati
|
109b278c0b |
Document the BigQuery agent analytics plugin for Kotlin (#2147)
* 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> |
||
|
Shahin Saadati
|
57869ca730 |
Show maxLlmCalls in the RunConfig Kotlin tabs (#2163)
* 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> |
||
|
Shahin Saadati
|
f27b98d8b3 |
Name FileArtifactService in the artifact service list (#2162)
* 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> |
||
|
Shahin Saadati
|
bae192e3d4 |
Add Kotlin tabs for grounding with Agent Search (#2160)
* 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> |
||
|
Shahin Saadati
|
5682576053 |
Add Kotlin safety settings and includeContents to the agent docs (#2158)
* 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. |
||
|
Shahin Saadati
|
3e9b83db71 |
Add the Kotlin tab for structured input and output schemas (#2151)
* 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>
|
||
|
Shahin Saadati
|
3583210a0d |
Add Kotlin tabs to the Skills page (#2156)
* 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. |
||
|
Shahin Saadati
|
fb99006173 |
Add Kotlin tabs to the tool confirmation page (#2157)
* 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> |
||
|
Shahin Saadati
|
e59783b904 |
Add the Kotlin tab for driving a long-running tool to completion (#2159)
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. |
||
|
Shahin Saadati
|
66d062035e |
Extend the compaction summarizer section to Kotlin (#2161)
* Extend the compaction summarizer section to Kotlin The Define a Summarizer group showed Python, Java and TypeScript but not Kotlin, and two lines of surrounding prose understated Kotlin as a result: one attributed LlmEventSummarizer to Python and Java only, the other said only Python and Java can customize the prompt template. Kotlin has had LlmEventSummarizer since v0.3.0 and exposes promptTemplate as a constructor parameter. This is partial coverage rather than an untouched page - the page is already Kotlin-badged and has a Kotlin tab for the token-threshold config. That tab is inline, as are all four siblings in this group, so the new tab is inline too rather than the new .kt file the backlog suggested; mixing forms between two Kotlin tabs on one page would be worse than either choice on its own. * Correct the Java summarizer property name to promptTemplate adk-java's LlmEventSummarizer exposes promptTemplate, not prompt_template; only Python uses the snake_case name. --------- Co-authored-by: Shahin Saadati <3443249+happyhuman@users.noreply.github.com> |
||
|
Shahin Saadati
|
b39decfcfe |
Add Kotlin to the session rewind page (#2164)
* 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. |
||
|
Alexey Kalenkevich
|
1203686bb4 |
Add TypeScript tabs to the graph workflow pages (#2167)
* 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> |
||
|
wolo
|
6c8fd32fea |
docs(integrations): document Go support for Agent Registry (#2123)
The Agent Registry page was Python-only, even though the Go client shipped in ADK Go v2.1.0 as google.golang.org/adk/v2/agentregistry, so Go users had no documented way to discover registered agents and MCP servers. Add the Go language-support tag and a Go tab alongside Python in Installation, Use with Agent, both authentication sections, API Reference, and Configuration Options, following the tabbed pattern used by the other multi-language integration pages. Also repoint the Python RemoteA2aAgent link at the Python A2A quickstart, which the Go quickstart had replaced. |
||
|
Hande Kafkas
|
27b0aa84cf |
Add Langfuse observability integration (#2112)
* Add Langfuse observability integration page Document OpenInference-based tracing setup for ADK agents so Langfuse appears in the integrations catalog. * add updates --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
eliasecchig
|
979a8fa9db |
Add Agents CLI quickstart to Get Started (#2095)
* Add Agents CLI quickstart to Get Started Agents CLI is currently explained only under Deploy > Agent Runtime and in the Coding with AI tutorial, so readers reach it either not at all or with the impression that it only configures AI coding assistants. Add a quickstart alongside the language quickstarts, and a card on the Get Started index so the choice is made up front. * Rework the quickstart around the coding agent path Lead with the coding agent as the intended way to use Agents CLI, add the lifecycle diagram and the seven skills, and say the CLI has more than 25 commands so the skills do not read as the whole product. Name the real Phase 0 questions (tools, inputs and outputs, success criteria) and close the loop in Next steps, where evaluation grades against those criteria. Drop the manual command section in favour of the upstream manual workflow tutorial, drop the playground production warning, and use Antigravity rather than Antigravity CLI to match the rest of the docs. * Address review feedback on Agents CLI quickstart - Tighten intro to 3-4 sentences; drop the coding-agent-path paragraph, the "optional / ordinary ADK agents" paragraph, and the seven-skills table (kept the lifecycle diagram) - Installation: state clearly that setup also installs the ADK Python packages, not just the CLI - Authenticate: swap the default to the Gemini API key path; move Google Cloud into a linked note pointing to the Google Cloud setup guide - Build your agent: replace prose in each tab with a command block containing verification steps as comments; move "Any other agent" out of the tabs into a note; "tell it" -> "tell the coding agent" - Add explanatory sentence before the scaffold command block clarifying that the coding agent runs the commands (and the reader can too) - Get Started index: drop the language-quickstarts-vs-Agents-CLI framing paragraph (unlikely to be read in that position) * Update agents-cli.md * Update agents-cli.md * Delete docs/assets/agents-cli-lifecycle.png --------- Co-authored-by: pierpaolo28 <pierpaolo28@users.noreply.github.com> Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
danyang-google
|
9db1fe2440 |
docs: move get_bucket to admin toolset and simplify GCS IAM permissions (#2056)
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Haran Rajkumar
|
64a9449cf2 |
Replace site search with Pagefind (#2096)
* feat(search): replace the built-in search with Pagefind Material's search ranked identifier queries badly, split one page across a row per heading, and showed only the first handful of matches. Pagefind indexes at build time, groups sub-results under their page, and pages through the whole result set. hooks/pagefind.py marks each page's content <article> with data-pagefind-body and runs the indexer over the built site. It fails the build on six conditions: the anchor missing, nothing marked, marked and indexed counts disagreeing, an exclude selector matching no page, a UI asset not emitted, and the ranking API gone from the bundle. MKDOCS_PAGEFIND_SKIP=1 skips indexing for a faster `mkdocs serve`, warns so that --strict fails pull requests, and is refused under gh-deploy, which publishes without --strict. The header hosts Pagefind's own modal and trigger components, so there is little UI to own. overrides/main.html raises termSimilarity so "LlmAgent" beats pages that merely say "agent" often, mirrors Material's colour scheme onto data-pf-theme, clears the search input on close around an upstream bug, and restores the / and s shortcuts that left with the old plugin. The lunr-specific CSS is gone. * Update header.html * Update custom.css * Update custom.css --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Shahin Saadati
|
8da5856bc5 |
Add Kotlin snippets to the custom tools page, including toolset filtering (#2114)
* 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).
|
||
|
Joe Fernandez
|
8c4074329d |
docs: correct nonexistent google-adk[vertexai] extra to [gcp] (#2132)
The `vertexai` extra does not exist in google-adk's pyproject.toml, so `pip install google-adk[vertexai]` silently installs the base package without the Agent Platform dependencies. Readers following these snippets hit an ImportError when constructing VertexAiSessionService or VertexAiMemoryBankService. The correct extra is `gcp`, which pulls in google-cloud-aiplatform[agent-engines]. Follow-up to review feedback on #2031, which flagged the two occurrences in express-mode.md. The same stale extra appears once in sessions/session/index.md, fixed here too. Co-authored-by: Shahin Saadati <happyhuman@users.noreply.github.com> |
||
|
Shahin Saadati
|
2570332640 |
Add A2A consuming quickstart for Kotlin (#2118)
* 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.
|
||
|
Liang Wu
|
fa05dbaf6b |
docs(graphs): remove live streaming from known limitations (#2139)
Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com> |
||
|
Shahin Saadati
|
d49c698bc6 |
Upgrade Kotlin examples and install docs to adk-kotlin 0.8.0 (#2143)
* 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. |