Agno Cookbook 测试与文档框架
Agno Cookbook 测试与文档框架
学习目标
本章将分析 Agno 的 Cookbook 测试和文档框架：
- 分级目录结构与章节组织
- TEST_LOG.md / TEST_PROMPT.md 标准化测试记录
- 双虚拟环境隔离（开发 vs Cookbook 运行）
- 格式化与验证脚本的 CI 集成
项目实践
分级目录结构
Agno 的 Cookbook 采用分级目录组织：
cookbook/├── 00_quickstart/ # 快速入门（必读）├── 01_demo/ # 演示项目├── 02_agents/ # Agent 教程├── 03_teams/ # Team 教程├── 04_workflows/ # Workflow 教程├── 05_agent_os/ # AgentOS 教程├── 06_storage/ # 存储教程├── 07_knowledge/ # 知识库教程├── 08_learning/ # 学习系统教程（黄金标准）├── 09_evals/ # 评估教程├── 10_reasoning/ # 推理教程├── 11_memory/ # 记忆教程├── 12_context/ # 上下文教程├── 90_models/ # 模型专题├── 91_tools/ # 工具专题├── 92_integrations/ # 集成专题├── 93_components/ # 组件示例└── 99_docs/ # 文档相关编号规则：
00-12：核心教程，按学习顺序排列90-99：专题/参考，不按顺序学习- 每个章节目录包含多个
.py示例文件
标准化测试记录
每个章节目录包含：
cookbook/08_learning/├── 01_basics/│ ├── 1a_user_profile_always.py│ ├── 1b_user_profile_agentic.py│ ├── ...├── README.md # 章节说明├── TEST_LOG.md # 测试结果记录├── TEST_PROMPT.md # 测试提示模板├── requirements.txt # 依赖└── requirements.in # 依赖源（pip-compile）TEST_LOG.md 格式：
### 1a_user_profile_always.py
**Status:** PASS
**Description:** 测试用户画像的 always 模式，验证 Agent 能自动捕获和更新用户信息。
**Result:** 成功捕获用户姓名和偏好，数据库中有对应记录。
---双虚拟环境隔离
Agno 使用两个独立的虚拟环境：
| 环境 | 用途 | 设置脚本 |
|---|---|---|
.venv/ | 开发：测试、格式化、验证 | ./scripts/dev_setup.sh |
.venvs/demo/ | Cookbook 运行：所有演示依赖 | ./scripts/demo_setup.sh |
为什么隔离？
- 开发环境只包含测试和 linting 依赖
- Cookbook 环境包含所有模型 API 和工具集成的演示依赖
- 避免依赖冲突（如测试框架与演示框架）
运行 Cookbook
# 使用 Cookbook 环境.venvs/demo/bin/python cookbook/08_learning/01_basics/1a_user_profile_always.py
# 长时间运行的测试，实时查看输出.venvs/demo/bin/python cookbook/08_learning/.../file.py 2>&1 | tail -100pgvector 本地测试环境
# 启动本地 PostgreSQL + pgvector./cookbook/scripts/run_pgvector.sh提供 Docker 容器运行 pgvector，用于测试向量搜索功能。
格式化与验证脚本
# 格式化所有代码（ruff format）./scripts/format.sh
# 验证所有代码（ruff check + mypy）./scripts/validate.shCI 集成：两个脚本必须在 push 前通过。PR 的 GitHub Actions 自动运行验证。
CLAUDE.md 开发规范
Agno 的 CLAUDE.md 文件定义了严格的开发规范：
- 不在循环中创建 Agent（复用）
- 使用
output_schema进行结构化响应 - PostgreSQL 用于生产，SQLite 用于开发
- 先单 Agent 后多 Agent 扩展
- 所有公开方法需要 sync 和 async 双版本
- 禁止在 cookbook 中使用
OpenAIChat（用OpenAIResponses） - 禁止使用
gpt-4o或gpt-4o-mini（用gpt-5.4）
问题与规避
1. Cookbook 过时
框架更新后，Cookbook 示例可能不再工作。
规避：
- TEST_LOG.md 记录测试结果和日期
- CI 定期运行所有 Cookbook
generate_requirements.sh更新依赖锁定
2. 模型 API Key 管理
Cookbook 示例需要各种模型的 API Key。
规避：
- 使用环境变量（
os.getenv("OPENAI_API_KEY")） .env文件（在.gitignore中）- CI 使用 GitHub Secrets
3. 环境搭建成本
两个虚拟环境 + pgvector 容器，新贡献者需要时间搭建。
规避：
- 脚本自动化（
dev_setup.sh/demo_setup.sh） - CLAUDE.md 中的快速参考表
- Docker Compose 一键启动
设计取舍
为什么用 Markdown 测试记录而非自动化测试框架？
优势：人类可读，包含描述性结果和观察 代价：无法自动化验证 替代方案：pytest 自动化测试——可以 CI 集成但缺少定性描述
为什么核心教程和专题分开编号？
优势：核心教程按学习顺序排列，专题按需查阅 代价：文件分散在不同目录 替代方案：扁平目录——简单但难以导航