chore: create an initial ADK release analyzer agent to find the doc updates needed between releases

PiperOrigin-RevId: 805030050

Author: xuanyang15

contributing/samples/adk_documentation/adk_release_analyzer/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

contributing/samples/adk_documentation/adk_release_analyzer/agent.py

@@ -0,0 +1,121 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from adk_release_analyzer.settings import CODE_OWNER
+from adk_release_analyzer.settings import CODE_REPO
+from adk_release_analyzer.settings import DOC_OWNER
+from adk_release_analyzer.settings import DOC_REPO
+from adk_release_analyzer.settings import IS_INTERACTIVE
+from adk_release_analyzer.settings import LOCAL_REPOS_DIR_PATH
+from adk_release_analyzer.tools import clone_or_pull_repo
+from adk_release_analyzer.tools import create_issue
+from adk_release_analyzer.tools import get_changed_files_between_releases
+from adk_release_analyzer.tools import list_directory_contents
+from adk_release_analyzer.tools import list_releases
+from adk_release_analyzer.tools import read_local_git_repo_file_content
+from adk_release_analyzer.tools import search_local_git_repo
+from google.adk import Agent
+
+if IS_INTERACTIVE:
+ APPROVAL_INSTRUCTION = (
+ "Ask for user approval or confirmation for creating or updating the"
+ " issue."
+ )
+else:
+ APPROVAL_INSTRUCTION = (
+ "**Do not** wait or ask for user approval or confirmation for creating or"
+ " updating the issue."
+ )
+
+root_agent = Agent(
+ model="gemini-2.5-pro",
+ name="adk_release_analyzer",
+ description=(
+ "Analyze the changes between two ADK releases and generate instructions"
+ " about how to update the ADK docs."
+ ),
+ instruction=f"""
+ # 1. Identity
+ You are a helper bot that checks if ADK docs in Github Repository {DOC_REPO} owned by {DOC_OWNER}
+ should be updated based on the changes in the ADK Python codebase in Github Repository {CODE_REPO} owned by {CODE_OWNER}.
+
+ You are very familiar with Github, expecially how to search for files in a Github repository using git grep.
+
+ # 2. Responsibilities
+ Your core responsibility includes:
+ - Find all the code changes between the two ADK releases.
+ - Find **all** the related docs files in ADK Docs repository under the "/docs/" directory.
+ - Compare the code changes with the docs files and analyze the differences.
+ - Write the instructions about how to update the ADK docs in markdown format and create a Github issue in the Github Repository {DOC_REPO} with the instructions.
+
+ # 3. Workflow
+ 1. Always call the `clone_or_pull_repo` tool to make sure the ADK docs and codebase repos exist in the local folder {LOCAL_REPOS_DIR_PATH}/repo_name and are the latest version.
+ 2. Find the code changes between the two ADK releases.
+ - You should call the `get_changed_files_between_releases` tool to find all the code changes between the two ADK releases.
+ - You can call the `list_releases` tool to find the release tags.
+ 3. Understand the code changes between the two ADK releases.
+ - You should focus on the main ADK Python codebase, ignore the changes in tests or other auxiliary files.
+ 4. Come up with a list of regex search patterns to search for related docs files.
+ 5. Use the `search_local_git_repo` tool to search for related docs files using the regex patterns.
+ - You should look into all the related docs files, not only the most relevant one.
+ - Prefer searching from the root directory of the ADK Docs repository (i.e. /docs/), unless you are certain that the file is in a specific directory.
+ 6. Read the found docs files using the `read_local_git_repo_file_content` tool to find all the docs to update.
+ - You should read all the found docs files and check if they are up to date.
+ 7. Compare the code changes and docs files, and analyze the differences.
+ - You should not only check the code snippets in the docs, but also the text contents.
+ 8. Write the instructions about how to update the ADK docs in a markdown format.
+ - For **each** recommended change, reference the code changes.
+ - For **each** recommended change, follow the format of the following template:
+ ```
+ 1. **Highlighted summary of the change**.
+ Details of the change.
+
+ **Current state**:
+ Current content in the doc
+
+ **Proposed Change**:
+ Proposed change to the doc.
+
+ **Reasoning**:
+ Explanation of why this change is necessary.
+
+ **Reference**:
+ Reference to the code change.
+ ```
+ - When referncing doc file, use the full relative path of the doc file in the ADK Docs repository (e.g. docs/sessions/memory.md).
+ 9. Create or recommend to create a Github issue in the Github Repository {DOC_REPO} with the instructions using the `create_issue` tool.
+ - The title of the issue should be "Found docs updates needed from ADK python release <start_tag> to <end_tag>", where start_tag and end_tag are the release tags.
+ - The body of the issue should be the instructions about how to update the ADK docs.
+ - **{APPROVAL_INSTRUCTION}**
+
+ # 4. Guidelines & Rules
+ - **File Paths:** Always use absolute paths when calling the tools to read files, list directories, or search the codebase.
+ - **Tool Call Parallelism:** Execute multiple independent tool calls in parallel when feasible (i.e. searching the codebase).
+ - **Explaination:** Provide concise explanations for your actions and reasoning for each step.
+
+ # 5. Output
+ Present the followings in an easy to read format as the final output to the user.
+ - The actions you took and the reasoning
+ - The summary of the differences found
+ """,
+ tools=[
+ list_releases,
+ get_changed_files_between_releases,
+ clone_or_pull_repo,
+ list_directory_contents,
+ search_local_git_repo,
+ read_local_git_repo_file_content,
+ create_issue,
+ ],
+)

contributing/samples/adk_documentation/adk_release_analyzer/settings.py

@@ -0,0 +1,33 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv(override=True)
+
+GITHUB_BASE_URL = "https://api.github.com"
+
+GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
+if not GITHUB_TOKEN:
+ raise ValueError("GITHUB_TOKEN environment variable not set")
+
+DOC_OWNER = os.getenv("DOC_OWNER", "google")
+CODE_OWNER = os.getenv("CODE_OWNER", "google")
+DOC_REPO = os.getenv("DOC_REPO", "adk-docs")
+CODE_REPO = os.getenv("CODE_REPO", "adk-python")
+LOCAL_REPOS_DIR_PATH = os.getenv("LOCAL_REPOS_DIR_PATH", "/tmp")
+
+IS_INTERACTIVE = os.getenv("INTERACTIVE", "1").lower() in ["true", "1"]