API Reference Audit

ADK API reference doc auditor (api-ref-audit)

This skill audits the API reference documentation in the

adk-docs repository across every language

SDK and reports what is out of date. It is a reporting and guidance skill:

it detects drift, recommends the correct per-surface release process, and emits

an executable plan only when the user explicitly asks. It does not edit

files, run generators, or open PRs by default.

The audit covers three kinds of drift:

• Generated API reference docs under docs/api-reference/ that lag behind

the latest SDK release.

• Hardcoded version strings in prose and examples (dependency coordinates,

pom.xml versions) that must be bumped with each Java/Kotlin release.

• Code-sample drift (light flagging only): samples that reference pinned

versions or obviously deprecated APIs. Deep sample verification is out of

scope of this skill.

> [!IMPORTANT]

> The maps below are hints, not ground truth. File layouts, script paths,

> and team processes change. At each step, verify the path or marker exists and

> re-derive it if a lookup fails, rather than trusting the table blindly.

Version map (in-repo version vs. upstream truth)

Each surface is one API reference output this repo ships: Python API, Python

CLI, Python REST API, Python Agent Config, TypeScript, Go, Java, and Kotlin.

For each surface, read the in-repo version from the file listed, then compare it

against the latest upstream release and package registry.

| Surface | In-repo version marker | Upstream repo | Package registry |

| --- | --- | --- | --- |

| Python API | docs/api-reference/python/_static/documentation_options.js (VERSION:) | google/adk-python | PyPI google-adk |

| Python CLI | docs/api-reference/cli/_static/documentation_options.js (VERSION:) and docs/api-reference/cli/index.html ("ADK X.Y.Z") | google/adk-python | PyPI google-adk |

| Python REST API | docs/api-reference/rest/openapi.json (info.version) | google/adk-python | PyPI google-adk |

| Python Agent Config | no version marker; diff the type set in agentconfig/index.html against upstream AgentConfig.json | google/adk-python (same release as Python API/CLI/REST) | n/a |

| TypeScript | docs/api-reference/typescript/variables/version.html (the version const); cross-check docs/api-reference/typescript/index.html (<title> "... - vX.Y.Z") | google/adk-js (monorepo; see note) | npm @google/adk (authoritative) |

| Go | external, hosted on pkg.go.dev; verify links in docs/api-reference/index.md | google/adk-go | pkg.go.dev |

| Java | docs/api-reference/java/index.html (<title> "Maven Parent POM X.Y.Z API") | google/adk-java (authoritative) | Maven Central com.google.adk:google-adk (lags; cross-check only) |

| Kotlin | docs/api-reference/kotlin/index.html (version string near the header) | google/adk-kotlin (authoritative) | Maven Central com.google.adk:google-adk-kotlin-core (lags; cross-check only) |

Notes:

• Python API, CLI, and REST all track the same adk-python release, so they

usually move together. Flag it when they diverge.

• Python Agent Config has no version field. Parse the **keys of the $defs

object** (plus top-level oneOf variants) from the upstream

AgentConfig.json at the target tag, e.g. jq '."$defs" | keys'. Do not

substring-grep for *Config: that mixes property names (camelCase, e.g.

imageConfig) with type names (PascalCase, e.g. ImageConfig) and produces

false drift. Check each $defs key as a whole word against

agentconfig/index.html; a key present upstream but missing in the page (or

vice versa) is drift.

• TypeScript: use npm @google/adk dist-tags.latest as the authoritative

version. adk-js is a monorepo with package-prefixed tags (e.g. main-v1.4.0,

integrations-v1.4.0), so gh ... releases/latest can return a release for a

different package instead of @google/adk. The in-repo version const tracks

the same @google/adk package npm publishes and releases together with it, so

compare the two directly: any version difference means the docs are behind.

The generate script clones the adk-v<version> tag (the core @google/adk

package tag).

• Go docs are not built into this repo. Confirm the release version and that the

index.md links point at the correct major versions (e.g. v2.x and v1.x). Go

versions are also pinned in examples/go/go.mod / go.sum and appear as

/adk/v2 import paths in prose (e.g. docs/events/index.md, docs/2.0/), so

check those too.

Hardcoded version references

These version-pinned strings are intentional and useful: they show developers

the exact dependency versions to use. The audit's job is to keep them current,

not remove them. They drift with each Java/Kotlin release and are bumped in a

separate PR (see the process map). Discover current occurrences by grep; do not

trust the file list alone, as new pages might appear over time.

• Grep targets:
• com.google.adk:google-adk and com.google.adk:google-adk-kotlin across

docs/**/*.md

• <google-adk.version> across docs//*.md and examples/java//pom.xml
• bare google-adk>=X.Y.Z pins in integration pages (report only; these are

minimum-version pins, not doc-version bumps)

• Known files that carry these (verify, do not assume complete):
• docs/get-started/installation.md
• docs/get-started/java.md
• docs/get-started/kotlin.md
• docs/get-started/streaming/quickstart-streaming-java.md
• docs/deploy/cloud-run.md
• docs/agents/models/litert-lm.md
• docs/integrations/firestore-session-service.md
• examples/java/**/pom.xml

• Never flag or bump language support tags. Versions that are inside of

language-support-tag spans (e.g. `<span class="lst-python">Python

v1.32.0</span>`) mark the release a feature was *introduced* in, not the

latest published version. Leave them untouched; bumping them misrepresents

when the feature became available.

Per-surface process map (owner, tooling, steps)

Treat each entry as a starting hint. Before recommending it, confirm the script

still exists and inspect the most recent matching bump PR to confirm the current

process.

• Python API: self-serve. Run `bash tools/python-api-docs/generate.sh

<version>`, then open a PR (the script injects the Google Analytics tag via

Sphinx).

• Python CLI: self-serve. Run `bash tools/python-cli-docs/generate.sh

<version>`, then open a PR. The GA tag is injected via a Sphinx layout

template in the script.

• Python REST API: self-serve. Run `bash

tools/python-rest-api-docs/generate.sh <version>`, then open a PR. GA tag is

baked into the generated index.html.

• Python Agent Config: regenerated from the adk-python schema with

json-schema-for-humans; no tools/ generate script exists yet, so treat the

update as manual.

• TypeScript: self-serve, one PR. Run `bash

tools/typescript-api-docs/generate.sh <version> (where <version>` is the npm

@google/adk version from the audit), then open a PR. The script clones the

adk-js adk-v<version> tag, adds the version to the page title via TypeDoc's

--includeVersion, and injects the Google Analytics tag into every HTML file

(awk post-processing).

• Java: two separate PRs per release. The adk-java team pushes the built

Javadoc assets (title chore: update ADK Java doc to version <X>); the docs

maintainer bumps the hardcoded dependency versions and pom.xml values (title

Update ADK Java dependency versions to <X>). The two can lag each other; the

assets PR is not self-serve, the dependency bump is.

• Kotlin: self-serve, one PR. Run `bash tools/kotlin-api-docs/generate.sh

<version>`, then open a PR that bundles the generated assets and the hardcoded

Kotlin refs (installation.md, get-started/kotlin.md, litert-lm.md). The

GA tag is auto-injected into every HTML file.

Verify the process

• Confirm each referenced script exists under tools/ before recommending it.
• Inspect the last matching bump to confirm the real, current process and the

files it touched, for example:

• gh pr list --repo google/adk-docs --state merged --search "Kotlin"
• gh pr list --repo google/adk-docs --state merged --search "CLI reference"
• gh pr list --repo google/adk-docs --state merged --search "Java"
• gh pr list --repo google/adk-docs --state merged --search "TypeScript"

Audit workflow

Step 1: Read in-repo versions

For every surface in the version map, read the marker file and record the

current version. Use grep/Read for the JS and HTML markers and parse

info.version from rest/openapi.json. If a marker path does not resolve,

re-derive it (search the generated output) and note the discrepancy.

Step 2: Fetch upstream releases and registry versions

For each SDK, get the latest release and the latest published package:

• GitHub latest release and tags:
• gh api repos/google/adk-python/releases/latest --jq .tag_name
• Repeat for adk-go, adk-kotlin, adk-java.
• For adk-js, do not use releases/latest (monorepo tags are

package-prefixed, e.g. main-v1.4.0); use npm @google/adk as the source

of truth.

• Package registries:
• PyPI: fetch https://pypi.org/pypi/google-adk/json and read info.version.
• npm: fetch https://registry.npmjs.org/@google/adk and read

dist-tags.latest.

• Maven Central: query

https://search.maven.org/solrsearch/select?q=g:com.google.adk+AND+a:google-adk&rows=1&wt=json

and read latestVersion (use a:google-adk-kotlin-core for Kotlin).

• For Java and Kotlin, treat the GitHub release/tag as authoritative. The

Maven Central search index frequently lags real releases (it has returned

versions older than what is already shipped in this repo). Use the registry

only as a cross-check, and when it disagrees with the GitHub tag, trust the

tag and note the lag.

• Note when a GitHub tag and its registry version disagree (a release may be

tagged but not yet published, or vice versa); report both.

Step 3: Classify each surface

Mark each surface as one of:

• Up to date: in-repo version equals the latest upstream release.
• Behind: in-repo version is older than the latest release (report the gap,

e.g. 2.3.0 -> 2.4.1).

• Unknown / manual: upstream lookup failed, or a surface with no automatable

check. Agent Config is not "unknown"; classify it via the type-set diff

(Behind if types were added or removed upstream).

Call out the common case where Python API, CLI, and REST should share the same

adk-python version but do not.

For Agent Config, run the type-set diff described in the version map Notes to

decide Up to date vs. Behind.

Step 4: Check hardcoded version references

Grep the targets in "Hardcoded version references" and compare each pinned

version to the latest Java and Kotlin releases. List every file and line that

needs a bump. Keep minimum-version pins (google-adk>=X.Y.Z) separate; only

flag them if they reference a version newer than what is released or are clearly

stale.

Step 5: Light code-sample drift flag

Do a quick scan (not a deep audit): note samples with hardcoded model or package

versions, obviously deprecated imports, or patterns superseded by a new

release's changelog. Report these as hints and recommend a dedicated

sample-audit pass for deep verification. Do not attempt to rewrite samples here.

Step 6: Verify Go links

Confirm docs/api-reference/index.md links point at the correct Go major

versions on pkg.go.dev and that the latest adk-go release is represented.

Also check the pinned versions in examples/go/go.mod / go.sum and the

/adk/v2 import paths in prose (e.g. docs/events/index.md, docs/2.0/).

Report format

Produce a Markdown report. Lead with a status table, then prioritized findings.

Status table (one row per surface):

| Surface | In-repo | Latest upstream | Status | Recommended action |

| --- | --- | --- | --- | --- |

Prioritized findings after the table. List only items that require action; do

not emit "no action" or "confirmed correct" lines anywhere, including inside an

otherwise-actionable finding. If a surface needs nothing, its table row already

says so.

• 🔴 Out of date / broken: a surface multiple releases behind, a

broken/incorrect API-reference link, or version markers that disagree with

each other (e.g. Python API/CLI/REST on different versions).

• 🟠 Stale hardcoded versions: file:line list of dependency coordinates and

pom.xml values to bump, with old -> new.

• 🟡 Sample-drift hints: samples that likely need updating; recommend the

deep sample-audit pass.

For each stale surface, name the recommended process from the process map

(self-serve script, wait on team, or manual) so the user knows how to proceed.

After the report, stop. Do not modify files, run generators, or open PRs

unless the user explicitly asks.

Executable plan (only when asked)

When the user asks you to proceed, output concrete next actions per stale

surface:

• The exact command to run, when self-serve, for example:
• bash tools/python-cli-docs/generate.sh <new-version>
• bash tools/python-rest-api-docs/generate.sh <new-version>
• bash tools/kotlin-api-docs/generate.sh <new-version>
• bash tools/typescript-api-docs/generate.sh <new-version>
• For team-owned surfaces (Java), state that the update is blocked on the owning

team's asset PR and what to request or wait for.

• For hardcoded versions, the precise file:line edits (old -> new), including

examples/java/**/pom.xml.

• Which surfaces move together (Python API, CLI, and REST share one adk-python

version) so they ship as separate PRs, one per surface, bumped in the same

sitting.

• A PR description per stale surface, following the repo convention:
• a short bullet summary of what changed
• Rendered page: <preview link, where applicable>
• upstream release link and version
• A final note telling the user how to proceed: self-run the commands, wait on

the owning team, or have the agent execute the plan.

PR title conventions

Match the established titles so history stays searchable:

• Python API: Update API reference docs for ADK Python <X.Y.Z>
• Python CLI: Update CLI reference docs for ADK Python <X.Y.Z>
• Python REST API: Update REST API reference docs for ADK Python <X.Y.Z>
• TypeScript: Update API reference docs for ADK TypeScript <X.Y.Z>
• Java dependency bump: Update ADK Java dependency versions to <X.Y.Z>
• Kotlin: Update ADK Kotlin to <X.Y.Z>

Style rules to bake in

• Report versions precisely as old -> new; never guess a version you did not

read from a marker or fetch from upstream.

• Do not invent links; use only markers you read and releases you fetched.
• No em dashes or verbose AI-generated content.
• The canonical source repositories are listed in

docs/community/contributing-guide.md.