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

PiperOrigin-RevId: 805030050

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,
+    ],
+)