api-reference-audit

name

api-reference-audit

description

Audits whether ADK API reference docs and version-pinned strings are up to date across all language SDKs. Compares in-repo versions against upstream releases and package registries, then reports what needs bumping and which process to follow, and emits an executable plan only when asked. Triggers on "audit API reference", "check API ref docs", "are API docs up to date", "bump API doc versions", "check SDK doc versions".

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:

1. Generated API reference docs under docs/api-reference/ that lag behind the latest SDK release.
2. Hardcoded version strings in prose and examples (dependency coordinates, pom.xml versions) that must be bumped with each Java/Kotlin release.
3. 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/live/get-started/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.