fix: Enhance ADK release analyzer with resume functionality and better session management

Co-authored-by: Xuan Yang <xygoogle@google.com>
PiperOrigin-RevId: 890127075

Author: xuanyang15

.github/workflows/analyze-releases-for-adk-docs-updates.yml

@@ -6,6 +6,20 @@ on:
     types: [published]
   # Manual trigger for testing and retrying.
   workflow_dispatch:
+    inputs:
+      resume:
+        description: 'Resume from the last failed/interrupted run'
+        required: false
+        type: boolean
+        default: false
+      start_tag:
+        description: 'Older release tag (base), e.g. v1.26.0'
+        required: false
+        type: string
+      end_tag:
+        description: 'Newer release tag (head), e.g. v1.27.0'
+        required: false
+        type: string
 
 jobs:
   analyze-new-release-for-adk-docs-updates:
@@ -33,6 +47,13 @@ jobs:
           python -m pip install --upgrade pip
           pip install requests google-adk
 
+      - name: Restore session DB from cache
+        if: ${{ github.event.inputs.resume == 'true' }}
+        uses: actions/cache/restore@v4
+        with:
+          path: contributing/samples/adk_documentation/adk_release_analyzer/sessions.db
+          key: analyzer-session-db
+
       - name: Run Analyzing Script
         env:
           GITHUB_TOKEN: ${{ secrets.ADK_TRIAGE_AGENT }}
@@ -44,4 +65,15 @@ jobs:
           CODE_REPO: 'adk-python'
           INTERACTIVE: 0
           PYTHONPATH: contributing/samples/adk_documentation
-        run: python -m adk_release_analyzer.main
+        run: >-
+          python -m adk_release_analyzer.main
+          ${{ github.event.inputs.resume == 'true' && '--resume' || '' }}
+          ${{ github.event.inputs.start_tag && format('--start-tag {0}', github.event.inputs.start_tag) || '' }}
+          ${{ github.event.inputs.end_tag && format('--end-tag {0}', github.event.inputs.end_tag) || '' }}
+
+      - name: Save session DB to cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: contributing/samples/adk_documentation/adk_release_analyzer/sessions.db
+          key: analyzer-session-db

contributing/samples/adk_documentation/adk_release_analyzer/agent.py

@@ -29,6 +29,7 @@
 - recommendations: Accumulated recommendations from all groups
 """
 
+import copy
 import os
 import sys
 from typing import Any
@@ -114,6 +115,7 @@ def get_next_file_group(tool_context: ToolContext) -> dict[str, Any]:
   current_index = tool_context.state.get("current_group_index", 0)
 
   if current_index >= len(file_groups):
+    print(f"[Progress] All {len(file_groups)} groups processed.")
     return {
         "status": "complete",
         "message": "All file groups have been processed.",
@@ -122,7 +124,11 @@ def get_next_file_group(tool_context: ToolContext) -> dict[str, Any]:
     }
 
   current_group = file_groups[current_index]
-  tool_context.state["current_group_index"] = current_index + 1
+  file_paths = [f.get("relative_path", "?") for f in current_group]
+  print(
+      f"[Progress] Starting group {current_index + 1}/{len(file_groups)}:"
+      f" {file_paths}"
+  )
 
   return {
       "status": "success",
@@ -157,6 +163,16 @@ def save_group_recommendations(
   all_recommendations = tool_context.state.get("recommendations", [])
   all_recommendations.extend(recommendations)
   tool_context.state["recommendations"] = all_recommendations
+  # Advance index only after recommendations are saved, so interrupted
+  # groups get retried on resume instead of being skipped.
+  tool_context.state["current_group_index"] = group_index + 1
+
+  total_groups = len(tool_context.state.get("file_groups", []))
+  print(
+      f"[Progress] Group {group_index + 1}/{total_groups} done."
+      f" +{len(recommendations)} recommendations"
+      f" ({len(all_recommendations)} total)"
+  )
 
   return {
       "status": "success",
@@ -180,6 +196,11 @@ def get_all_recommendations(tool_context: ToolContext) -> dict[str, Any]:
   end_tag = tool_context.state.get("end_tag", "unknown")
   compare_url = tool_context.state.get("compare_url", "")
 
+  print(
+      f"[Summary] Retrieving recommendations: {len(recommendations)} total,"
+      f" release {start_tag} → {end_tag}"
+  )
+
   return {
       "status": "success",
       "start_tag": start_tag,
@@ -226,6 +247,12 @@ def save_release_info(
   tool_context.state["release_summary"] = release_summary
   tool_context.state["all_changed_files"] = all_changed_files
 
+  total_files = sum(len(group) for group in file_groups)
+  print(
+      f"[Planning] Release {start_tag} → {end_tag}:"
+      f" {total_files} files in {len(file_groups)} groups"
+  )
+
   return {
       "status": "success",
       "start_tag": start_tag,
@@ -404,10 +431,13 @@ def file_analyzer_instruction(readonly_context: ReadonlyContext) -> str:
 4. For EACH significant change, call `search_local_git_repo` to find related docs
    in {LOCAL_REPOS_DIR_PATH}/{DOC_REPO}/docs/
    - Search for the feature name, class name, or related keywords
+   - **ALWAYS** pass `ignored_dirs=["api-reference"]` to skip auto-generated API
+     reference docs (they are updated automatically by code, not manually)
    - If no docs found, recommend creating new documentation
 
 5. Call `read_local_git_repo_file_content` to read the relevant doc files
    and check if they need updating.
+   - **SKIP** any files under `docs/api-reference/` — these are auto-generated.
 
 6. For each documentation update needed, create a recommendation with:
    - summary: Brief summary of what needs to change
@@ -446,6 +476,7 @@ def file_analyzer_instruction(readonly_context: ReadonlyContext) -> str:
         "Analyzes a group of changed files and generates recommendations."
     ),
     instruction=file_analyzer_instruction,
+    include_contents="none",
     tools=[
         get_next_file_group,
         get_release_context,  # Get global context to avoid duplicates
@@ -554,6 +585,26 @@ def summary_instruction(readonly_context: ReadonlyContext) -> str:
 )
 
 
+# Resume pipeline: skips planner, continues from where loop left off.
+# Deep copy agents since ADK agents can only have one parent.
+_resume_loop = copy.deepcopy(file_analysis_loop)
+_resume_loop.parent_agent = None
+_resume_summary = copy.deepcopy(summary_agent)
+_resume_summary.parent_agent = None
+
+resume_pipeline = SequentialAgent(
+    name="resume_pipeline",
+    description=(
+        "Resumes the release analysis pipeline from the file analysis loop,"
+        " skipping the planning phase."
+    ),
+    sub_agents=[
+        _resume_loop,
+        _resume_summary,
+    ],
+)
+
+
 # =============================================================================
 # Root Agent: Entry point that understands user requests
 # =============================================================================

contributing/samples/adk_documentation/adk_release_analyzer/main.py

@@ -12,8 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import argparse
 import asyncio
 import logging
+import os
 import time
 
 from adk_documentation.adk_release_analyzer import agent
@@ -23,30 +25,105 @@
 from adk_documentation.settings import DOC_REPO
 from adk_documentation.utils import call_agent_async
 from google.adk.cli.utils import logs
-from google.adk.runners import InMemoryRunner
+from google.adk.runners import Runner
+from google.adk.sessions import DatabaseSessionService
 
 APP_NAME = "adk_release_analyzer"
 USER_ID = "adk_release_analyzer_user"
+DB_PATH = os.path.join(os.path.dirname(__file__), "sessions.db")
+DB_URL = f"sqlite+aiosqlite:///{DB_PATH}"
 
-logs.setup_adk_logger(level=logging.DEBUG)
+logs.setup_adk_logger(level=logging.INFO)
 
 
 async def main():
-  runner = InMemoryRunner(
-      agent=agent.root_agent,
-      app_name=APP_NAME,
+  parser = argparse.ArgumentParser(description="ADK Release Analyzer")
+  parser.add_argument(
+      "--resume",
+      action="store_true",
+      help="Resume from the last session instead of starting fresh.",
   )
-  session = await runner.session_service.create_session(
-      app_name=APP_NAME,
-      user_id=USER_ID,
+  parser.add_argument(
+      "--start-tag",
+      type=str,
+      default=None,
+      help="The older release tag (base) for comparison, e.g. v1.26.0.",
   )
-
-  response = await call_agent_async(
-      runner,
-      USER_ID,
-      session.id,
-      "Please analyze the most recent two releases of ADK Python!",
+  parser.add_argument(
+      "--end-tag",
+      type=str,
+      default=None,
+      help="The newer release tag (head) for comparison, e.g. v1.27.0.",
   )
+  args = parser.parse_args()
+
+  session_service = DatabaseSessionService(db_url=DB_URL)
+
+  if args.resume:
+    # Find the most recent session to resume
+    sessions_response = await session_service.list_sessions(
+        app_name=APP_NAME, user_id=USER_ID
+    )
+    if not sessions_response.sessions:
+      print("No previous session found. Starting fresh.")
+      args.resume = False
+
+  if args.resume:
+    # Resume: use existing session with resume_pipeline (skip planner)
+    last_session = sessions_response.sessions[-1]
+    session_id = last_session.id
+    session = await session_service.get_session(
+        app_name=APP_NAME, user_id=USER_ID, session_id=session_id
+    )
+    state = session.state
+    group_index = state.get("current_group_index", 0)
+    total_groups = len(state.get("file_groups", []))
+    num_recs = len(state.get("recommendations", []))
+    print(f"Resuming session {session_id}")
+    print(
+        f"  Progress: group {group_index + 1}/{total_groups},"
+        f" {num_recs} recommendations so far"
+    )
+    print(
+        f"  Release: {state.get('start_tag', '?')} →"
+        f" {state.get('end_tag', '?')}"
+    )
+
+    runner = Runner(
+        agent=agent.resume_pipeline,
+        app_name=APP_NAME,
+        session_service=session_service,
+    )
+    prompt = "Resume analyzing the remaining file groups."
+  else:
+    # Fresh run
+    runner = Runner(
+        agent=agent.root_agent,
+        app_name=APP_NAME,
+        session_service=session_service,
+    )
+    session = await session_service.create_session(
+        app_name=APP_NAME,
+        user_id=USER_ID,
+    )
+    session_id = session.id
+    if args.start_tag and args.end_tag:
+      prompt = (
+          f"Please analyze ADK Python releases from {args.start_tag} to"
+          f" {args.end_tag}!"
+      )
+    elif args.end_tag:
+      prompt = (
+          f"Please analyze the ADK Python release {args.end_tag} against its"
+          " previous release!"
+      )
+    else:
+      prompt = "Please analyze the most recent two releases of ADK Python!"
+
+  print(f"Session ID: {session_id}")
+  print("-" * 80)
+
+  response = await call_agent_async(runner, USER_ID, session_id, prompt)
   print(f"<<<< Agent Final Output: {response}\n")
 
 

contributing/samples/adk_documentation/tools.py

@@ -183,18 +183,24 @@ def read_local_git_repo_file_content(file_path: str) -> Dict[str, Any]:
       commit hash.
   """
   print(f"Attempting to read file from path: {file_path}")
-  dir_path = os.path.dirname(file_path)
-  head_commit_sha = _find_head_commit_sha(dir_path)
+  if not os.path.isabs(file_path):
+    return error_response(
+        f"file_path must be an absolute path, got: {file_path}"
+    )
+
+  try:
+    dir_path = os.path.dirname(file_path)
+    head_commit_sha = _find_head_commit_sha(dir_path)
+  except (FileNotFoundError, subprocess.CalledProcessError):
+    head_commit_sha = "unknown"
 
   try:
-    # Open and read the file content
     with open(file_path, "r", encoding="utf-8") as f:
       content = f.read()
 
-      # Add line numbers to the content
-      lines = content.splitlines()
-      numbered_lines = [f"{i + 1}: {line}" for i, line in enumerate(lines)]
-      numbered_content = "\n".join(numbered_lines)
+    lines = content.splitlines()
+    numbered_lines = [f"{i + 1}: {line}" for i, line in enumerate(lines)]
+    numbered_content = "\n".join(numbered_lines)
 
     return {
         "status": "success",
@@ -204,7 +210,7 @@ def read_local_git_repo_file_content(file_path: str) -> Dict[str, Any]:
     }
   except FileNotFoundError:
     return error_response(f"Error: File not found at {file_path}")
-  except IOError as e:
+  except (IOError, OSError) as e:
     return error_response(f"An unexpected error occurred: {e}")