Agno 多智能体团队 Cookbook（03_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/tasks（02_modes/）、团队知识（05_knowledge/）、会话持久化（07_session/）、上下文压缩（10_context_compression/）、学习（12_learning/）、分布式 RAG（15_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/）依赖 pgvector；hooks/示例的输出只出现在钩子回调中，因此验收标准是"运行无报错即视为通过"。
执行要求：先读全文，再并行验证
文档对执行流程做了四点硬约束，核心思想是先理解、后修改、最小化改动：
- 改动前必须逐字通读目标目录下的每个
.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("...", stream=True)模式检查器：结构合规的机器闸门
第 3.a 步调用的 cookbook/scripts/check_cookbook_pattern.py 是整个验证体系的自动化基石。从源码看，该脚本通过ast.parse解析文件并实施五类结构校验，每条违规对应一个稳定错误码：
| 违规码 | 含义 | 触发条件 |
|---|---|---|
syntax_error | 语法错误 | 文件无法通过ast.parse，附带具体行号与错误信息 |
missing_docstring | 缺模块 docstring | ast.get_docstring(tree, clean=False)返回空 |
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# (?P<title>.+?)\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.md（Quickstart 版验证契约，明确写出 "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 format+ruff check --select I --fix（import 排序），目标覆盖libs/agno、libs/agnoctl、libs/agno_infra与cookbook四个代码域，任意失败即非零退出。
scripts/validate.sh 的职责划分更细：libs/agno与libs/agnoctl走ruff check+mypy（后者使用各自的pyproject.toml），而cookbook域只做ruff check+ 一次针对cookbook/00_quickstart的模式检查。可以推断：由于validate.sh无法覆盖所有 cookbook 子目录，03_teams等目录的模式检查正是在前述 a 步按子目录逐一完成的——两级校验互补，而非互相替代。
交付格式：结果必须可追溯
文档要求最终报告固定包含四部分，这保证了验证过程的可审计性：
- Findings（不一致、失败、风险清单，须带文件引用）；
- 执行的测试/验证命令及结果；
- 遗留缺口或需人工跟进的事项；
- 结果表，固定为"子目录 / 文件 / 状态 / 备注"四列格式，例如：
| Subdirectory | File | Status | Notes |
|---|---|---|---|
01_quickstart | 01_basic_coordination.py | PASS | Team coordinated response from both members |
guardrails | pii_detection.py | FAIL | Missing 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_GUIDE"import 位于 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），仅供参考
