api-reference-audit

ADK API リファレンスドキュメント監査ツール（api-ref-audit）

このスキルは、adk-docs リポジトリのすべての言語 SDK にわたって API リファレンスドキュメントを監査し、古くなっている箇所を報告します。これは報告とガイダンスを行うスキルです。差異を検出し、対象ごとに適切なリリースプロセスを推奨します。実行可能な計画を提示するのは、ユーザーから明示的に求められた場合に限ります。デフォルトでは、ファイルの編集、ジェネレーターの実行、プルリクエストの作成は行いません。

監査では、次の3種類の差異を対象にします。

1. 最新の SDK リリースより遅れている、docs/api-reference/ 以下の生成済み API リファレンスドキュメント。
2. Java/Kotlin のリリースごとに更新する必要がある、説明文やサンプル内のハードコードされたバージョン文字列（依存関係の座標、pom.xml のバージョン）。
3. コードサンプルの差異（簡易的なフラグ付けのみ）：固定バージョンを参照しているサンプルや、明らかに非推奨の API を使っているサンプル。このスキルでは、サンプルの詳細な検証は対象外です。

重要

以下のマップは手がかりであり、絶対的な正解ではありません。ファイル構成、スクリプトのパス、チームのプロセスは変わることがあります。各ステップでパスや目印の存在を確認し、参照に失敗した場合は表をそのまま信頼せず、改めて特定してください。

バージョン一覧（リポジトリ内のバージョンと上流の正確なバージョン）

各対象は、このリポジトリが提供する API リファレンス出力の 1 つです。Python API、Python CLI、Python REST API、Python Agent Config、TypeScript、Go、Java、Kotlin が含まれます。

各対象について、記載されたファイルからリポジトリ内のバージョンを確認し、上流の最新リリースおよびパッケージレジストリと比較します。

対象	リポジトリ内のバージョンの目印	上流リポジトリ	パッケージレジストリ
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:）および 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	バージョンの目印なし。agentconfig/index.html の型セットを上流の AgentConfig.json と比較	google/adk-python（Python API／CLI／REST と同じリリース）	該当なし
TypeScript	docs/api-reference/typescript/variables/version.html（version 定数）。docs/api-reference/typescript/index.html（<title> の「... - vX.Y.Z」）とも照合	google/adk-js（モノレポ。注を参照）	npm @google/adk（正式な基準）
Go	外部ホストの pkg.go.dev。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（正式な基準）	Maven Central com.google.adk:google-adk（反映が遅れるため、照合用のみ）
Kotlin	docs/api-reference/kotlin/index.html（ヘッダー付近のバージョン文字列）	google/adk-kotlin（正式な基準）	Maven Central com.google.adk:google-adk-kotlin-core（反映が遅れるため、照合用のみ）

注：

• Python API、CLI、REST はすべて同じ adk-python リリースを追跡するため、通常は一緒に更新されます。バージョンが異なる場合は指摘してください。
• Python Agent Config にはバージョンフィールドがありません。対象のタグにある上流の AgentConfig.json から、$defs オブジェクトのキー（およびトップレベルの oneOf バリアント）を解析します。例：jq '."$defs" | keys'。*Config を部分文字列で検索しないでください。プロパティ名（キャメルケース。例：imageConfig）と型名（パスカルケース。例：ImageConfig）が混在し、誤った差分が生じます。各 $defs キーを完全な単語として agentconfig/index.html 内で確認します。上流に存在するキーがページにない場合（またはその逆）は、差分があります。
• TypeScript：正式なバージョンには、npm @google/adk の dist-tags.latest を使用します。adk-js はパッケージ別のタグ（例：main-v1.4.0、integrations-v1.4.0）を持つモノレポのため、gh ... releases/latest では @google/adk とは別のパッケージのリリースが返されることがあります。リポジトリ内の version 定数は、npm が公開し、同時にリリースする @google/adk パッケージと同じバージョンを示すため、両者を直接比較します。バージョンが異なれば、ドキュメントが古くなっています。生成スクリプトは adk-v<version> タグ（コアの @google/adk パッケージタグ）をクローンします。
• Go のドキュメントはこのリポジトリ内でビルドされません。リリースバージョンと、index.md のリンクが正しいメジャーバージョン（例：v2.x、v1.x）を指していることを確認してください。Go のバージョンは examples/go/go.mod／go.sum にも固定され、文章中（例：docs/events/index.md、docs/2.0/）に /adk/v2 のインポートパスとして記載されているため、それらも確認してください。

ハードコードされたバージョン参照

これらのバージョンを固定した文字列は意図的なものであり、役に立ちます。開発者が使用すべき正確な依存関係のバージョンを示しています。監査の目的は、これらを削除することではなく、最新の状態に保つことです。Java/Kotlin のリリースごとにずれが生じるため、別の PR で更新します（プロセスマップを参照）。grep で現在の該当箇所を見つけてください。時間の経過とともに新しいページが追加される可能性があるため、ファイル一覧だけを信頼しないでください。

• grep の対象:

  • com.google.adk:google-adk および com.google.adk:google-adk-kotlin（docs/**/*.md 全体）
  • <google-adk.version>（docs/**/*.md および examples/java/**/pom.xml）
  • インテグレーションページ内の、バージョンを指定した裸の google-adk>=X.Y.Z（報告のみ。これは最小バージョンの指定であり、ドキュメントのバージョン更新ではありません）

• 該当箇所がある既知のファイル（必ず確認し、すべて網羅されていると思い込まないでください）:

  • 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

• 言語サポートタグには、決して警告を出したりバージョンを更新したりしないでください。 language-support-tag スパン内のバージョン（例：<span class="lst-python">Python v1.32.0</span>）は、機能が最初に導入されたリリースを示すものであり、最新の公開バージョンを示すものではありません。そのままにしてください。更新すると、機能が利用可能になった時期を誤って伝えることになります。

サーフェスごとのプロセスマップ（担当者、ツール、手順）

各項目は、あくまで出発点として扱ってください。推奨する前に、スクリプトが現在も存在することを確認し、直近の該当する更新 PR を調べて現在のプロセスを確認してください。

• Python API：セルフサービスです。bash tools/python-api-docs/generate.sh <version> を実行し、PR を作成します（スクリプトが Sphinx 経由で Google Analytics タグを挿入します）。
• Python CLI：セルフサービスです。bash tools/python-cli-docs/generate.sh <version> を実行し、PR を作成します。GA タグは、スクリプト内の Sphinx レイアウトテンプレート経由で挿入されます。
• Python REST API：セルフサービスです。bash tools/python-rest-api-docs/generate.sh <version> を実行し、PR を作成します。GA タグは、生成された index.html に埋め込まれます。
• Python Agent Config：json-schema-for-humans を使い、adk-python のスキーマから再生成します。現時点では tools/ に生成スクリプトがないため、手動で更新するものとして扱ってください。
• TypeScript：セルフサービスで、PR は 1 件です。bash tools/typescript-api-docs/generate.sh <version> を実行します（<version> には監査で確認した npm の @google/adk バージョンを指定）。その後、PR を作成します。スクリプトは adk-js の adk-v<version> タグをクローンし、TypeDoc の --includeVersion によってページタイトルにバージョンを追加し、awk による後処理で、すべての HTML ファイルに Google Analytics タグを挿入します。
• Java：セルフサービスです。bash tools/java-api-docs/generate.sh <version> を実行し、docs/api-reference/java/ 以下の Javadoc アセットを再生成します（GA タグはすべての HTML ファイルに自動挿入されます）。また、ハードコードされた依存関係のバージョンと pom.xml の値も更新します。これらは 2 件の別々の PR（Javadoc アセットの場合は chore: update ADK Java doc to version <X>、依存関係のバージョン指定の場合は Update ADK Java dependency versions to <X>）として公開することも、まとめて公開することもできます。
• Kotlin：セルフサービスで、PR は 1 件です。bash tools/kotlin-api-docs/generate.sh <version> を実行し、生成されたアセットとハードコードされた Kotlin の参照箇所（installation.md、get-started/kotlin.md、litert-lm.md）をまとめた PR を作成します。GA タグはすべての HTML ファイルに自動挿入されます。

プロセスを確認する

• 推奨する前に、参照されている各スクリプトが tools/ の下に存在することを確認します。
• 直近の該当するバージョン更新を調べ、実際の現在のプロセスと変更されたファイルを確認します。例：
  • 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"

監査ワークフロー

ステップ 1：リポジトリ内のバージョンを読む

バージョンマップにあるすべての対象について、マーカーファイルを読み、現在のバージョンを記録します。JS と HTML のマーカーには grep／Read を使い、rest/openapi.json から info.version を解析します。マーカーのパスが解決できない場合は、生成された出力を検索してパスを再導出し、その不一致を記録します。

ステップ 2：上流のリリースとレジストリのバージョンを取得する

各 SDK について、最新リリースと最新の公開パッケージを取得します。

• GitHub の最新リリースとタグ：
  • gh api repos/google/adk-python/releases/latest --jq .tag_name
  • adk-go、adk-kotlin、adk-java についても同様に実行します。
  • adk-js では releases/latest を使わないでください（モノレポのタグには main-v1.4.0 のようにパッケージ名が付くため）。正しい情報源として npm の @google/adk を使います。
• パッケージレジストリ：
  • PyPI：https://pypi.org/pypi/google-adk/json を取得し、info.version を読み取ります。
  • npm：https://registry.npmjs.org/@google/adk を取得し、dist-tags.latest を読み取ります。
  • Maven Central：https://search.maven.org/solrsearch/select?q=g:com.google.adk+AND+a:google-adk&rows=1&wt=json を照会し、latestVersion を読み取ります（Kotlin では a:google-adk-kotlin-core を使います）。
• Java と Kotlin では、GitHub のリリース／タグを正とします。 Maven Central の検索インデックスは実際のリリースに遅れることが頻繁にあります（このリポジトリですでに公開されているバージョンより古いバージョンが返されたことがあります）。レジストリの情報は照合にのみ使い、GitHub のタグと異なる場合は、タグを優先して遅れを記録します。
• GitHub のタグとレジストリのバージョンが異なる場合は記録します（リリースにタグが付いていても未公開の場合や、その逆の場合があります）。両方のバージョンを報告します。

ステップ 3：各対象を分類する

各対象を次のいずれかに分類します。

• 最新：リポジトリ内のバージョンが最新の上流リリースと一致しています。
• 遅れ：リポジトリ内のバージョンが最新リリースより古い状態です（例：2.3.0 -> 2.4.1 のように差分を報告します）。
• 不明／手動：上流の情報を取得できなかった場合、または自動チェックできない対象です。Agent Config は「不明」ではありません。型セットの差分で分類します（上流で型が追加または削除されていれば「遅れ」です）。

Python API、CLI、REST では同じ adk-python のバージョンを共有するのが一般的ですが、実際には一致していないことがある点を指摘します。

Agent Config については、バージョンマップの Notes に記載された型セットの差分を実行し、「最新」か「遅れ」かを判断します。

ステップ 4：ハードコードされたバージョン参照を確認する

「ハードコードされたバージョン参照」の対象を grep し、固定されている各バージョンを Java と Kotlin の最新リリースと比較します。更新が必要なファイルと行をすべて列挙します。最小バージョンの指定（google-adk>=X.Y.Z）は別に扱い、リリース済みのバージョンより新しいものを参照している場合、または明らかに古い場合にのみ指摘します。

ステップ 5：コードサンプルの軽い差分確認

簡単に確認します（詳細な監査ではありません）。モデルやパッケージのバージョンがハードコードされたサンプル、明らかに非推奨になったインポート、新しいリリースの変更履歴で置き換えられたパターンを見つけたら記録します。これらは参考情報として報告し、詳細な検証には専用のサンプル監査を推奨します。ここではサンプルを書き換えないでください。

ステップ 6：Go のリンクを確認する

docs/api-reference/index.md のリンクが pkg.go.dev の正しい Go メジャーバージョンを指していることと、最新の adk-go リリースが反映されていることを確認します。また、examples/go/go.mod／go.sum の固定バージョンと、本文（例：docs/events/index.md、docs/2.0/）の /adk/v2 インポートパスも確認します。

レポート形式

Markdown 形式のレポートを作成します。最初にステータステーブルを置き、その後に優先度順の指摘事項を記載します。

ステータステーブル（対象ごとに 1 行）：

対象	リポジトリ内	最新のアップストリーム	ステータス	推奨アクション

テーブルの後に、優先度順の指摘事項を記載します。対応が必要な項目のみを列挙してください。「対応不要」や「正しいことを確認済み」といった行は、対応が必要な指摘事項の中も含め、どこにも出力しないでください。対応が不要な対象については、テーブルの行にその旨が示されています。

• 🔴 最新でない／壊れている：複数リリース分遅れている対象、壊れている／誤った API リファレンスへのリンク、または互いに一致しないバージョン表記（例：Python API／CLI／REST のバージョンが異なる）。
• 🟠 ハードコードされたバージョンが古い：更新が必要な依存関係の座標と pom.xml の値を、file:line の一覧と旧バージョン -> 新バージョンで示します。
• 🟡 サンプルのずれに関するヒント：更新が必要と思われるサンプルを示し、詳細なサンプル監査の実施を推奨します。

古い対象ごとに、プロセスマップにある推奨プロセス（セルフサービススクリプト、チームの対応を待つ、または手動）を明記し、ユーザーが次の進め方を把握できるようにします。

レポートの後はそこで終了します。ユーザーから明示的に依頼されない限り、ファイルの変更、ジェネレーターの実行、プルリクエストの作成は行わないでください。

実行可能な計画（依頼された場合のみ）

ユーザーから作業を進めるよう依頼された場合は、古い対象ごとに具体的な次のアクションを提示します。

• セルフサービスの場合は、実行する正確なコマンドを示します。例：
  • bash tools/python-api-docs/generate.sh <new-version>
  • bash tools/python-cli-docs/generate.sh <new-version>
  • bash tools/python-rest-api-docs/generate.sh <new-version>
  • bash tools/java-api-docs/generate.sh <new-version>
  • bash tools/kotlin-api-docs/generate.sh <new-version>
  • bash tools/typescript-api-docs/generate.sh <new-version>
• ハードコードされたバージョンについて、変更箇所を正確な file:line と旧バージョン -> 新バージョンで示します。examples/java/**/pom.xml も含めます。
• 連動して更新する対象を示します（Python API、CLI、REST は同じ adk-python のバージョンを共有するため、それぞれ別のプルリクエストとして、同じタイミングで更新します）。
• リポジトリの慣例に沿った、対象ごとのプルリクエストの説明を作成します。
  • 変更内容の簡潔な箇条書き
  • Rendered page: <該当する場合はプレビューリンク>
  • アップストリームのリリースリンクとバージョン
• 最後に、次の進め方をユーザーに伝えます。コマンドを自分で実行する、担当チームの対応を待つ、またはエージェントに計画を実行させる、のいずれかです。

プルリクエストのタイトル規則

履歴を検索しやすく保つため、既存のタイトルに合わせます。

• 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 API：chore: update ADK Java doc to version <X.Y.Z>
• Java の依存関係の更新：Update ADK Java dependency versions to <X.Y.Z>
• Kotlin：Update ADK Kotlin to <X.Y.Z>

取り入れるスタイルルール

• バージョンは正確に 旧バージョン -> 新バージョン の形式で記載します。マーカーから読み取ったか、アップストリームから取得したバージョン以外を推測してはいけません。
• リンクを捏造してはいけません。読み取ったマーカーと取得したリリースにあるものだけを使用します。
• 全角ダッシュは使用せず、AI が生成したような冗長な文章も避けます。
• 正規のソースリポジトリは docs/community/contributing-guide.md に記載されています。