Agno 多智能体团队 Cookbook03_teams的测试驱动质量验证工作流【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技术指南围绕仓库内 cookbook/03_teams/TEST_PROMPT.md 展开系统讲解 Agno 项目如何以并行验证代理 结构检查器 静态校验脚本三层手段对cookbook/03_teams全部 28 个子目录的多智能体团队Agent Team示例进行端到端测试与质量把关。读完本文你将掌握 Agno cookbook 质量验证的完整工作流环境准备、模式检查器规则、逐子目录运行策略、交互式与依赖型示例的特判处理以及format.sh/validate.sh两类门禁命令的底层实现可直接在真实仓库中复现与延伸。定位这份文档驱动什么任务在 Agno 仓库中每个 cookbook 目录都同时存在README.md内容说明、TEST_PROMPT.md验证任务书与TEST_LOG.md验证结果日志三个配套文件。cookbook/03_teams/TEST_PROMPT.md 的标题自述其目标非常明确Thoroughly test and validatecookbook/03_teamsso it aligns with our cookbook standards——即对03_teams目录做全面测试与校验使其对齐项目统一的 cookbook 标准。它与面向用户的功能文档不同是一份可执行的验证契约既约束了执行主体AI 编码代理必须先读全量源文件、再改代码也划定了环境、命令、验收口径与结果交付格式。它和 cookbook/03_teams/README.md团队功能教学、cookbook/03_teams/TEST_LOG.md逐文件 PASS/FAIL 档案三者互补共同构成编写 → 校验 → 留档的闭环。参照 AGENTS.md 的说明测试与维护 cookbook 是该项目除功能开发外最重要的任务而cookbook/08_learning/被标注为该项工作的golden standard参照。验证对象03_teams本身覆盖了 Agno 多智能体团队的完整能力面。据其 README.md子目录主题包括核心协调模式01_quickstart/、执行模式 coordinate/route/broadcast/tasks02_modes/、团队知识05_knowledge/、会话持久化07_session/、上下文压缩10_context_compression/、学习12_learning/、分布式 RAG15_distributed_rag/、安全护栏18_guardrails/、时间旅行与分支25_time_travel/、26_fork_session/等贯穿本文后续提及的多数特判场景。执行前的环境准备文档在 Environment 一节给出三条硬性前提这也是在仓库内运行任何03_teams示例的必要条件解释器统一使用.venvs/demo/bin/python运行示例。这与仓库的双虚拟环境策略一致——见 AGENTS.md.venv/用于开发pytest、format、validate由./scripts/dev_setup.sh搭建.venvs/demo/用于运行 cookbook含全部 demo 依赖由./scripts/demo_setup.sh搭建。切勿混用。API 密钥通过direnv allow加载例如OPENAI_API_KEY示例脚本本身不硬编码密钥。外部数据库知识、会话、分布式 RAG 等示例需要 PostgreSQL/PgVector先启动 cookbook/scripts/run_pgvector.sh。文档同时给出环境提示human_in_the_loop/示例需要交互输入验证策略是验证启动与首次工具调用成功后即终止某些子目录knowledge/、session/、distributed_rag/、memory/依赖 pgvectorhooks/示例的输出只出现在钩子回调中因此验收标准是运行无报错即视为通过。执行要求先读全文再并行验证文档对执行流程做了四点硬约束核心思想是先理解、后修改、最小化改动改动前必须逐字通读目标目录下的每个.py文件不能只依赖 grep 或结构检查器。理由是自动化检查器会漏掉诸如函数体内局部 import注释中的过期模型引用风格前后不一致等问题——这些只有人/代理真正阅读全文才能发现。为cookbook/03_teams/下每个子目录派发一个并行子代理各子代理独立负责一个子目录互不干扰。每个子代理承担六项职责详见下节。全部子代理完成后汇总合并结果形成最终报告。子代理的六项职责文档用 a–f 六条定义了每个子代理的最小工作集步骤动作说明a运行模式检查器执行check_cookbook_pattern.py --base-dir cookbook/03_teams/SUBDIR并修复违规b运行全部示例用.venvs/demo/bin/python逐个运行该子目录下所有*.py跳过__init__.py记录结果c对齐样式规范对照 cookbook/STYLE_GUIDE.md 检查每个 Python 示例d检查非 Python 文件排查目录内README.md等文件是否残留过时的OpenAIChat引用并更新e最小化修复仅在必要时做保持行为的最小风格修复禁止大改f更新测试日志在cookbook/03_teams/SUBDIR/TEST_LOG.md中按文件追加 PASS/FAIL 记录其中 c 步要求的样式合规项来自 cookbook/STYLE_GUIDE.md共五条模块 docstring且用下划线分隔分区横幅注释# ---------------------------------------------------------------------------import 语句位于 docstring 与第一个横幅之间必须存在if __name__ __main__:执行门Python 源文件中不允许出现 emoji 字符。推荐骨架模板STYLE_GUIDE.md 给出的可运行示例标准骨架如下也是check_cookbook_pattern.py校验规则的直接来源 Title What this demonstrates # --------------------------------------------------------------------------- # Config / Setup # --------------------------------------------------------------------------- # --------------------------------------------------------------------------- # Agent Instructions # --------------------------------------------------------------------------- instructions ... # --------------------------------------------------------------------------- # Create the Agent # --------------------------------------------------------------------------- example_agent Agent(...) # --------------------------------------------------------------------------- # Run the Agent # --------------------------------------------------------------------------- if __name__ __main__: example_agent.print_response(..., streamTrue)模式检查器结构合规的机器闸门第 3.a 步调用的 cookbook/scripts/check_cookbook_pattern.py 是整个验证体系的自动化基石。从源码看该脚本通过ast.parse解析文件并实施五类结构校验每条违规对应一个稳定错误码违规码含义触发条件syntax_error语法错误文件无法通过ast.parse附带具体行号与错误信息missing_docstring缺模块 docstringast.get_docstring(tree, cleanFalse)返回空missing_main_gate缺主执行门文件名不以_开头且找不到if __name__ __main__:__init__.py、__main__.py及下划线前缀的支撑模块豁免missing_sections缺分区横幅全文找不到# ---或# 风格的横幅分区missing_create_section缺 Create 分区所有分区标题中无含单词 Create 者missing_run_section缺 Run 分区所有分区标题中无含单词 Run 者section_order分区顺序错误Create 分区出现在 Run 分区之后emoji_not_allowed含 emoji命中[\U0001F300-\U0001FAFF]范围的字符值得注意的实现细节均可在 check_cookbook_pattern.py 源码中确认分区标题用正则^# [-]\n# (?Ptitle.?)\n# [-]$多行匹配行号按字符偏移换算关键词匹配不区分大小写re.IGNORECASE因此 Create/Run 写成小写也能命中跳过名单文件名__init__.py、__main__.py目录名__pycache__、.git、.context支持--recursive递归扫描与--output-format text|json两种输出便于接入 CI 或代理工具存在任一违规即退出码为 1。对03_teams场景实际执行按子目录粒度进行即文档规定的--base-dir cookbook/03_teams/SUBDIR。全量执行与特殊场景特判b 步要求运行子目录下每个*.py。文档特别强调两类例外human_in_the_loop/与交互型示例需要人工输入如输入y/n或交互式确认不能放进无人值守的批量运行器验证到启动成功 首次工具调用触发即终止进程。依赖外部服务的示例knowledge/、session/、distributed_rag/、memory/需要 pgvector 已就绪否则应先运行run_pgvector.sh再执行。这类边界处理正是从 cookbook/03_teams/TEST_LOG.md含各子目录实测记录与 cookbook/00_quickstart/TEST_PROMPT.mdQuickstart 版验证契约明确写出 human_in_the_loop.pyis interactive andrun.pystarts a server, so neither belongs in an unattended folder runner等同类文档中沉淀下来的方法论。最终门禁format 与 validate全部子目录验证通过后文档要求在仓库根目录跑两组收尾命令必须在.venv开发环境激活状态下执行source .venv/bin/activate ./scripts/format.sh source .venv/bin/activate ./scripts/validate.sh从 scripts/format.sh 源码看format 实际执行的是ruff formatruff check --select I --fiximport 排序目标覆盖libs/agno、libs/agnoctl、libs/agno_infra与cookbook四个代码域任意失败即非零退出。scripts/validate.sh 的职责划分更细libs/agno与libs/agnoctl走ruff checkmypy后者使用各自的pyproject.toml而cookbook域只做ruff check 一次针对cookbook/00_quickstart的模式检查。可以推断由于validate.sh无法覆盖所有 cookbook 子目录03_teams等目录的模式检查正是在前述 a 步按子目录逐一完成的——两级校验互补而非互相替代。交付格式结果必须可追溯文档要求最终报告固定包含四部分这保证了验证过程的可审计性Findings不一致、失败、风险清单须带文件引用执行的测试/验证命令及结果遗留缺口或需人工跟进的事项结果表固定为子目录 / 文件 / 状态 / 备注四列格式例如SubdirectoryFileStatusNotes01_quickstart01_basic_coordination.pyPASSTeam coordinated response from both membersguardrailspii_detection.pyFAILMissing presidio dependency这种统一表格式样还承担历史留档职责新验证只做追加绝不覆盖旧记录。仓库现存日志也印证了这一点——例如 cookbook/03_teams/01_quickstart/TEST_LOG.md 记录了02_respond_directly_router_team.py、03_delegate_to_all_members.py、04_respond_directly_with_history.py的 PASS同时记录了01_basic_coordination.py的样式违规code_before_first_section_banner与05_team_history.py的运行时 Traceback失败样本被完整保留以供回归对照。从真实失败日志反推验证要点结合 cookbook/03_teams/TEST_LOG.md 的实测数据可以归纳出文档验证体系实际拦截到的高频问题类型这些也应作为你复现验证时的重点观察项风格类如01_quickstart/01_basic_coordination.py出现code_before_first_section_banner——首个分区横幅前存在代码违反 STYLE_GUIDEimport 位于 docstring 与首个横幅之间的布局要求运行时类如05_team_history.py执行中抛出 Traceback需要结合具体异常定位可能是模型调用、会话初始化或依赖缺失超时类01_quickstart 早期验证中出现多例 Timeout after 30s多由真实 LLM 调用引起需要在有限时间内权衡是否延长超时或改用确定性断言。这些日志同时展示了健康示例的运行输出形态——例如06_history_of_members.py的 PASS 记录中包含 Team IDmulti-lingual-q-and-a-team、TeamSession 的创建日志、delegate_task_to_member工具注入等关键过程信息可作为行为性验收验证实际发生了成员委托而非只检查进程退出码的对照样本。小结把测试本身工程化03_teams/TEST_PROMPT.md揭示的是 Agno 将测试 cookbook这件事本身工程化的方法先通读再动手、按子目录并行分治、机器检查器守住结构底线、人工/代理逐文件核对行为与风格、特殊场景特判、统一日志留档、全库门禁收尾。这套流程不仅适用于03_teams也以 cookbook/00_quickstart/TEST_PROMPT.md 等同类文档的形式贯穿整个cookbook/目录。若你想为某个新示例补做验证只需照此清单逐条执行激活.venvs/demo、启动 pgvector、跑子目录模式检查、运行示例、按四段格式在 cookbook/03_teams/TEST_LOG.md 中追加记录最后用format.sh/validate.sh收口即可。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
