[実践ADK] コードとドキュメントの差異を検出・自動更新する adk_documentationエージェント
こんにちは、ドキュメントファーストよりコードファーストが好きな、サントリーこと大橋です。
Agent Development Kit (ADK)のリポジトリでは、開発・運用をサポートするために様々なAIエージェントが稼働しています。以前の記事では、GitHubのDiscussionに寄せられた質問に自動で回答する「ADK Answering Agent」を紹介しました。
今回は、ADKリポジトリで稼働するもう一つの興味深いエージェント、「adk_documentation」について、その仕組みと役割を深掘りしていきます。
課題: ソースコードとドキュメントの乖離
ドキュメントの更新はしんどい。
ソフトウェア開発において、「ソースコードは常に正しいが、ドキュメントはそうとは限らない」という言葉を耳にしたことがある方は多いのではないでしょうか。
開発が進むにつれて機能追加や仕様変更が繰り返される中で、ソースコードの修正は行われても、それに追従するドキュメントの更新は後回しにされがちです。結果として、コードとドキュメントの間に差異（乖離）が生まれ、ドキュメントが陳腐化してしまう、というのは多くのプロジェクトが抱える根深い課題です。
この課題は、特にADKのように迅速なリリースサイクルを持つオープンソースソフトウェア（OSS）にとっては、より深刻な問題となり得ます。
adk_documentationエージェントとは
この「コードとドキュメントの乖離」という課題に、AIエージェント自身が立ち向かうのが、今回紹介するadk_documentationエージェントです。
このエージェントは、実際にはadk_release_analyzerとadk_docs_updaterという2つのサブエージェントから構成されるマルチエージェントシステムです。
-
adk_release_analyzer: 2つのリリース間のコード変更をすべて分析し、ドキュメント（adk-docsリポジトリ）にその変更が反映されているかを確認します。もし未反映の変更があれば、どのようなドキュメント修正が必要かを提案するGitHub Issueを自動で作成します。 -
adk_docs_updater:adk_release_analyzerが作成したIssueの指示に基づき、実際にドキュメントファイルを修正し、Pull Requestを自動で作成します。
まさに、AIエージェントが自身のプロジェクトの健康状態を維持するために働く、自己言及的な仕組みと言えるでしょう。
実際にこのエージェントによって作成されたIssueがこちらです。リリースの変更点と、それに対応するドキュメントの更新案が詳細に記述されていることがわかります。
adk_documentationエージェントの仕組み
では、このエージェントはどのようにして動作しているのでしょうか。コードやGitHub Actionsのワークフローを読み解くと、その仕組みが見えてきます。
エージェントの動作フロー全体を図にすると、以下のようになります。
フェーズ1: 変更の分析とIssue作成 (adk_release_analyzer)
-
トリガー:
adk-pythonリポジトリで新しいリリースが公開されると、GitHub Actionsのワークフロー (analyze-releases-for-adk-docs-updates.yml) が自動的にトリガーされます。 -
エージェント実行: ワークフローは
adk_release_analyzerエージェントを実行します。 -
リリース情報取得:
list_releasesツールを使い、最新の2つのリリースタグを取得します。 -
差分ファイル取得:
get_changed_files_between_releasesツールを使い、2つのリリース間のすべてのコード変更（追加、修正、削除されたファイルとそれらの差分）を取得します。 -
関連ドキュメント検索: コードの変更内容を基に、関連する可能性のあるドキュメントファイルを
adk-docsリポジトリ内からsearch_local_git_repoツールで検索します。 -
ファイル内容読み込み: 変更されたコードと、関連するドキュメントファイルの内容を
read_local_git_repo_file_contentツールで読み込みます。 - 分析と比較: LLMの能力を最大限に活用し、コードの変更点と現在のドキュメント内容を比較分析し、ドキュメントが古い、または情報が不足している箇所を特定します。
-
Issueの作成: 分析結果を基に、具体的な修正指示をMarkdown形式で記述し、
create_issueツールを使ってadk-docsリポジトリに新しいIssueを作成します。
フェーズ2: ドキュメントの更新とPull Request作成 (adk_docs_updater)
-
トリガー: （将来的には）開発者が
adk_release_analyzerによって作成されたIssueを確認し、手動またはコメント経由でadk_docs_updaterエージェントを実行する想定です。 -
Issue情報取得:
get_issueツールを使い、指示が書かれたIssueの詳細を取得します。 -
ファイル読み込み: 指示に基づき、更新対象のドキュメントファイルを
read_local_git_repo_file_contentツールで読み込みます。 - ドキュメント修正: LLMがIssueの指示と現在のドキュメント内容を理解し、インメモリでドキュメントを修正します。
-
Pull Request作成:
create_pull_request_from_changesツールを使い、修正内容をコミットし、adk-docsリポジトリにPull Requestを作成します。
このように、2つの専門エージェントが連携し、ツールを駆使してドキュメントのメンテナンスを自動化しているのです。
まとめ
今回はADKリポジトリで実際に稼働しているadk_documentationエージェントについて解説しました。
ソフトウェア開発における普遍的な課題である「コードとドキュメントの乖離」に対して、AIエージェント自身がリリース間の差分を理解し、ドキュメントの更新を提案・実行するというアプローチは非常に先進的です。
ドキュメント更新ってめちゃ面倒ですしね。
このような仕組みによって、開発者はドキュメント更新という手間のかかる作業から解放され、より創造的な開発作業に集中できるようになります。
この仕組みは、ADKというOSSプロジェクトだけでなく、多くの企業における社内ドキュメントやAPI仕様書のメンテナンスなど、様々な場面で応用が可能です。単にテキストを生成するだけでなく、各種ツールと連携して具体的なタスクを実行するAIエージェントの実践的な活用例として、非常に参考になるのではないでしょうか。
個人的にはチャットボットのようなインターフェースのAIエージェントよりも、こういった密かに業務を助けるようなAIエージェントは非常に好ましいです。
最後にお知らせ/宣伝
先日、ADKユーザー向けのイベント「ADK UG #0」が開催され、ADK開発者が集う日本語のDiscordコミュニティが誕生しました。ADKに関する情報交換や議論に興味がある方は、ぜひご参加ください！
また、ADKの最新のコミットログやリリースノートを分かりやすく解説するPodcastを、月・水・金に配信しています。ADKの動向を追いかけたい方は、ぜひ聴いてみてください。
Discussion