使用 ADK Release Analyzer Agent 自动分析 adk-python 版本差异并生成文档更新任务【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python导读本文基于 adk-python 开源仓库中的adk_release_analyzer示例深入讲解一个由 ADKAgent Development Kit构建的多 Agent 文档版本分析系统它能够在google/adk-python两个版本之间自动对比代码差异、定位google/adk-docs文档仓库中需要同步更新的内容并自动创建带详细修改指引的 GitHub Issue。读完本文你将掌握该 Agent 的交互式与自动化两种运行模式、完整的环境变量与依赖配置、三层多 Agent 流水线的内部实现原理以及如何把 release 分析接入 CI/CD 工作流。一、项目背景为什么需要一个版本分析 Agent开源项目在持续迭代过程中代码变更新 API、新 CLI 参数、行为变化与文档更新之间往往存在滞后。adk-python 仓库的contributing/samples/adk_team/adk_documentation目录就为此提供了一个自动化解决方案adk_release_analyzer——一个基于 Python 的 Agent专门负责分析google/adk-python仓库两个 release 之间的差异识别google/adk-docs文档仓库中需要更新的内容并自动生成包含详细修改指令的 GitHub Issue。从仓库结构看该示例与同目录下的adk_docs_updater负责根据 Issue 指令实际修改文档并创建 PR形成分析 → 执行的闭环Release Analyzer 负责发现问题Docs Updater 负责解决问题。本文聚焦前者。Agent 支持两种运行模式交互模式本地运行通过adk web在浏览器中实时查看推荐结果创建 Issue 前征求用户确认并支持对版本与代码变更进行问答自动化模式以脚本main.py方式无人值守运行适合集成到 CI/CD 流水线直接创建 Issue 而无需用户审批。二、交互模式在浏览器中实时审查分析结果交互模式适合在正式创建 Issue 前人工审阅 Agent 的推荐。其核心特性包括Web 界面通过 ADK 的adk web命令在浏览器中渲染 Agent 交互界面用户确认交互模式下 Agent 被明确指示在创建 GitHub Issue 前必须征求用户确认对应源码 agent.py 中的APPROVAL_INSTRUCTION交互模式下为 Ask for user approval or confirmation for creating or updating the issue.问答能力你可以直接向 Agent 提问关于 release 与代码变更的任何问题它会基于相关仓库信息给出回答。运行交互模式首先设置必需的环境变量确保INTERACTIVE设为1或保持未设置状态然后在终端执行adk web contributing/samples/adk_team/adk_documentation该命令会启动一个本地服务器并提供一个 URL供你在浏览器中打开 Agent 的 Web 界面。从源码看交互模式的判定逻辑在 settings.pyIS_INTERACTIVE os.getenv(INTERACTIVE, 1).lower() in [true, 1]即默认就是交互模式只有显式设置为0或false才会进入自动化模式。三、自动化模式接入 CI/CD 的无人值守分析对于完全自动化的分析Agent 以脚本main.py方式运行例如作为 CI/CD 流水线的一部分。工作流配置在.github/workflows/analyze-releases-for-adk-docs-updates.yml中会自动检查最近两个 release 是否需要文档更新。工作流触发方式该 GitHub Workflow 配置了两种触发机制Release 事件每当有新 release 被published发布时自动执行手动调度也支持手动触发便于测试与重试。自动创建 Issue自动化模式下Agent 以非交互方式运行直接创建包含文档更新指令的 GitHub Issue不要求用户确认。该行为由将INTERACTIVE环境变量设为0配置。对应源码 agent.py 中非交互模式的指令为 Do notwait or ask for user approval or confirmation for creating or updating the issue.脚本入口的额外能力自动化模式的主脚本 main.py 还提供了三个命令行参数让分析范围更加可控python -m adk_documentation.adk_release_analyzer.main \ --start-tag v1.26.0 \ --end-tag v1.27.0 \ --resume参数说明默认行为--start-tag比较的旧 release tagbase如v1.26.0未指定时比较最近两个 release--end-tag比较的新 release taghead如v1.27.0同上--resume从最近一次会话继续跳过规划阶段不指定则全新分析--resume的实现值得一提脚本通过DatabaseSessionServiceSQLite位于sessions.db持久化会话状态恢复时从 state 中读取current_group_index、file_groups、recommendations等进度信息并使用跳过 planner 的resume_pipelineagent.py从中断的分组继续分析。当未同时指定两个 tag 时脚本会自动构造合适的提示词仅给--end-tag则对比其与上一版本否则默认分析最近两个 release。四、安装依赖与环境变量配置无论交互模式还是自动化模式都需要完成以下配置。依赖安装Agent 需要以下 Python 库pip install --upgrade pip pip install google-adk[db]其中google-adk[db]提供数据库会话服务DatabaseSessionService用于持久化会话状态以支持--resume断点续跑。环境变量以下环境变量用于连接所需服务变量必填默认值说明GITHUB_TOKEN是无GitHub Personal Access Token需对文档仓库拥有issues:write权限GOOGLE_API_KEY是无Gemini API 的 API KeyDOC_OWNER否google拥有文档仓库的 GitHub 组织或用户名CODE_OWNER否google拥有代码仓库的 GitHub 组织或用户名DOC_REPO否adk-docs文档仓库名称CODE_REPO否adk-python代码仓库名称LOCAL_REPOS_DIR_PATH否/tmp本地克隆仓库的目录INTERACTIVE否1控制交互模式1为交互模式默认0为自动化模式从 settings.py 源码可以看到两点实现细节GITHUB_TOKEN在导入时就被校验未设置会直接抛出ValueError因此运行时它实际上是强制项配置文件通过dotenv的load_dotenv(overrideTrue)加载环境变量因此本地执行时可以将这些变量放入项目根目录的.env文件中而自动化工作流中则应配置为环境变量或 Secrets。五、多 Agent 架构如何避免大规模 release 分析的上下文溢出该 Agent 的核心设计亮点是采用SequentialAgent LoopAgent组合模式将大型 release 分析拆解为增量处理避免上下文溢出。整体架构在 agent.py 中有清晰实现由三个角色组成1. PlannerAgent规划者收集变更文件并创建分析分组release_planner负责分析前的准备其工作流程为调用clone_or_pull_repo克隆/更新代码仓库与文档仓库若已存在则执行git pull调用list_releases获取 release tag默认比较最近两个 release调用get_changed_files_summary获取变更文件列表不带完整 patch以节省上下文空间。这里有两个关键参数local_repo_path指向本地克隆路径可避免 GitHub API 的 300 文件限制path_filtersrc/google/adk/只保留 ADK 源码文件减少 token 消耗进一步过滤排除测试文件与__init__.py但不因改动行数少而排除文件即使是公共 API 的单行改动也需要文档更新按重要性排序新增文件added CLI 文件cli/ 工具文件tools/ 核心模块agents/、models/、sessions/、memory/、a2a/、flows/、plugins/、evaluation/ 改动量大的文件生成高层次的 release 摘要识别主题、相关文件将文件分组每组最多MAX_FILES_PER_GROUP 5个相关文件放在同一组调用save_release_info保存状态。2. LoopAgent FileGroupAnalyzer分组分析器逐个分组处理file_analysis_loop是一个LoopAgentagent.pymax_iterations50作为安全上限其子代理file_group_analyzer使用动态指令file_analyzer_instruction函数从ReadonlyContext读取当前状态逐组分析调用get_next_file_group获取下一组文件若全部处理完则调用exit_loop退出循环首先调用get_release_context获取全局上下文release 主题、其他变更文件、已有推荐避免重复推荐对组内每个文件调用get_file_diff_for_release获取 patch并深入分析API 变更新增函数/类/方法、新增参数、新 CLI 参数查找 argparse、click 装饰器、新环境变量查找os.environ/getenv、新工具或特性、重命名或弃用行为变更即使 API 签名不变默认值变化、错误处理或异常类型变化、返回值格式变化、副作用增减、性能特性变化、边界情况处理变化、校验规则变化对每处重要变更调用search_local_git_repo在文档仓库的docs/目录搜索相关文档始终传入ignored_dirs[api-reference]因为 API 参考文档由代码自动生成无需手动维护调用read_local_git_repo_file_content阅读相关文档判断是否需要更新同样跳过docs/api-reference/为每处需要更新的文档创建推荐包含summary变更摘要、doc_file文档相对路径、current_state文档当前内容、proposed_change应改为的内容、reasoning理由、reference源码文件路径、related_files相关联的其他变更文件调用save_group_recommendations保存推荐并仅在保存成功后才推进分组索引——这样中断的分组在恢复时会重试而非跳过。3. SummaryAgent汇总者汇编推荐并创建 GitHub Issuesummary_agent负责收尾调用get_all_recommendations取回全部累积的推荐按重要性组织特性变更 Bug 修复 其他组内按影响文件数排序去重或合并相似推荐按固定模板格式化 Issue 正文见下文调用create_issue在文档仓库创建 Issue标题格式为Found docs updates needed from ADK python release {start_tag} to {end_tag}正文顶部包含 compare 链接并附带docs updates标签tools.py。流水线编排与断点续跑三个角色通过analysis_pipeline SequentialAgent(...)串成完整流水线。为支持断点续跑仓库还通过copy.deepcopy复制 Loop 与 Summary AgentADK 中一个 Agent 只能有一个父节点构建了跳过规划阶段的resume_pipeline。根 Agentadk_release_analyzer则负责理解用户意图完整分析请求 → 委托给analysis_pipeline针对单文件/模块的快速查询 → 直接使用工具应答。Issue 正文中的每条推荐使用如下模板摘自 agent.py 的指令### N. **Summary of the change** **Doc file**: path/to/doc.md **Current state**: Current content in the doc **Proposed Change**: What it should say instead **Reasoning**: Explanation of why this change is necessary. **Reference**: src/google/adk/path/to/file.py六、底层工具链与安全性设计所有 Agent 共享的工具定义在 tools.py底层通过 GitHub REST APIapi.github.com配合GITHUB_TOKEN与本地git命令实现工具功能实现要点list_releases列出仓库全部 release分页拉取per_page100返回 id/tag/时间get_changed_files_summary获取变更文件摘要不含 patch优先用本地git diff --name-status--numstat规避 300 文件限制失败回退 GitHub APIget_file_diff_for_release获取单个文件的 patch调用 compare API 后按文件名筛选clone_or_pull_repo克隆或更新仓库目录存在则git pull否则git clone返回 head commit SHAsearch_local_git_repo在本地仓库搜索基于git grep -n -I -E支持扩展名过滤与排除目录read_local_git_repo_file_content读取本地文件返回带行号内容与 head commit SHAlist_directory_contents递归列出目录自动过滤隐藏文件/目录create_issue/update_issue/get_issueIssue 管理创建时自动附加docs updates标签值得特别强调的是路径沙箱安全设计这些工具由 LLM 驱动会处理不可信输入Issue 正文、release diff因此 tools.py 中的_confine_path会先解析符号链接与..段再校验路径必须位于LOCAL_REPOS_DIR_PATH之内防止恶意指令读取/proc/self/environ、凭据文件或写出仓库之外。这一安全边界由 test_tools.py 的PathConfinementTest测试用例覆盖验证包括越界读取拒绝/etc/passwd、/proc/self/environ、符号链接逃逸拒绝、目录列举/搜索越界拒绝、clone 路径越界拒绝以及 PR 变更键的路径穿越../../../../tmp/evil.txt拒绝。七、模型配置与容错Agent 统一使用Gemini模型并配置了精细的重试策略agent.py_RETRY_OPTIONS types.HttpRetryOptions( initial_delay10, attempts8, exp_base2, max_delay300, http_status_codes[429, 503], ) GEMINI_PRO_WITH_RETRY Gemini( modelgemini-3.1-pro-preview, retry_options_RETRY_OPTIONS, )规划与汇总阶段使用gemini-3.1-pro-preview追求更高质量的输出针对 429限流与 503过载状态码采用指数退避重试初始延迟 10 秒、最多 8 次、最大延迟 300 秒以适配长时间批量分析场景分组分析 Agent 设置了include_contentsnoneagent.py避免把历史消息内容重复注入进一步控制上下文占用。八、端到端运行流程总结将以上内容串联起来一次完整的 release 分析流程为配置环境变量GITHUB_TOKEN、GOOGLE_API_KEY为必填其余可保持默认或按需定制安装google-adk[db]本地交互执行adk web contributing/samples/adk_team/adk_documentation在浏览器中审查并确认 Issue 创建自动化在 CI/CD 中运行main.py可在 workflow 中配置 release published 与手动触发Agent 自动完成克隆仓库 → 枚举 release → 汇总变更 → 分组分析 → 生成推荐 → 创建 Issue全流程若分析中断可用--resume从上次会话继续跳过规划阶段直接完成剩余分组分析。通过这一套设计adk-python 的每次发布都能被自动审查一遍文档同步需求且分析过程可审计、可中断恢复、可人工确认为开源项目代码与文档同步这一常见痛点提供了可直接复用的工程化模板。相关资源adk_release_analyzer README本文对应的原始文档Agent 多角色实现Planner / File Group Analyzer / Summary 三层架构与流水线编排脚本入口--start-tag/--end-tag/--resume命令行参数配置与工具 与 tools.py环境变量加载、GitHub API 与本地 git 工具链、路径沙箱安全测试路径越界与符号链接逃逸防护测试同目录的 adk_docs_updater负责根据 Issue 指令实际修改文档并创建 PR 的配套 Agent。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
