Agno Cookbook 集成模块测试与验证全指南：从环境搭建到代码规范校验

导读

本文基于 cookbook/integrations/TEST_PROMPT.md 给出的测试工作流，系统讲解如何为 Agno 仓库中的 cookbook/integrations（Parallel 网络研究集成、SurrealDB 记忆后端集成）执行一次端到端的质量验证：包括测试环境准备、逐文件结构校验、示例脚本运行、代码风格对齐与 TEST_LOG 结果登记。读完本文，你将掌握一套可复用的"文档化测试协议"，能够使用 check_cookbook_pattern.py、format.sh、validate.sh 等工具对 cookbook 示例进行自动化与人工结合的验证，并按要求输出包含 Findings、测试命令与结果表格的验收报告。

---

一、验证目标：让集成示例对齐 Cookbook 标准

cookbook/integrations/TEST_PROMPT.md 的既定目标非常明确：彻底测试并验证 cookbook/integrations 目录，使其与 Agno cookbook 标准对齐。这份文档本质上是写给测试执行者的"任务书"，它要求：

• 在动手修改前，逐一阅读目标目录中的每一个 .py 文件，而不是仅依赖 grep 或结构检查器——因为自动检查可能漏掉"函数内部 import、注释里过期的模型引用、不一致的写法"等问题；
• 对 cookbook/integrations/ 下的每个子目录（parallel/、surrealdb/）独立处理，包括嵌套子目录；
• 每个子目录需要依次完成：运行结构检查器并修复违规、运行全部 *.py 示例并记录结果、核对代码是否符合 cookbook/STYLE_GUIDE.md、在目录内 TEST_LOG.md 中更新每个文件的 PASS/FAIL 记录。

从当前仓库看，cookbook/integrations/ 下实际包含三个子目录（discord/、parallel/、surrealdb/），其中 TEST_PROMPT 明确点名的是 parallel/ 与 surrealdb/ 两个：

• parallel/：基于 Parallel（parallel.ai）构建的 Web 研究 Agent 示例，覆盖 Search、Extract、Task、Monitor 四类 API；
• surrealdb/：以 SurrealDB 作为 Agno Memory 管理后端的集成示例。

两个子目录的用途在 cookbook/integrations/README.md 中有概括：前者是"面向 Agent 的 Web 研究 API"（Search 秒级查证、Extract 抓取指定 URL、Task 深度研究带引用、Monitor 定时追踪主题），后者是"SurrealDB 支撑的记忆管理集成"。

---

二、测试环境准备：虚拟环境、密钥与数据库

TEST_PROMPT 明确给出了测试运行所依赖的环境约定，这是整份工作流能否执行的前提：

环境要素	约定值	用途说明
Python 解释器	.venvs/demo/bin/python	所有示例脚本与校验脚本均使用 demo 虚拟环境执行
API 密钥加载	direnv allow	加载环境变量；Parallel 示例需要 PARALLEL_API_KEY
数据库	./cookbook/scripts/run_pgvector.sh	供"持久化记忆或知识"类示例使用

其中 PARALLEL_API_KEY 是运行 parallel/ 下所有示例的硬前提；而 SurrealDB 示例则需要本地启动 SurrealDB 实例（surrealdb/README.md 中示例连接的是 ws://localhost:8000）。

测试协议还强调：这些上下文文件应优先阅读——CLAUDE.md / AGENTS.md 记录项目约定、虚拟环境与测试工作流；cookbook/STYLE_GUIDE.md 规定 Python 文件结构规则。也就是说，执行测试前必须先建立"项目规范是什么"的完整认知，再动手检查代码。

---

三、执行要求：四步走的标准测试流程

TEST_PROMPT 对每个子目录规定了四步操作，本文逐一拆解并结合仓库源码说明其含义。

第 1 步：逐个通读 .py 文件

要求"读取目标目录中的每个 .py 文件后再做任何改动"，且明确警告：不要只依赖 grep 或结构检查器。理由是自动化检查器存在盲区，例如：

• import 语句出现在函数内部（延迟导入）而非模块顶部；
• 注释中残留已过期的模型引用（如旧模型名）；
• 各示例间风格不一致。

以 parallel/01_quickstart.py 为例，其完整结构是一个标准的 cookbook 示例：模块 docstring 用 ===== 下划线装饰、用 # ----... 横幅注释划分"Create the Agent"与"Run the Agent"两个区块、执行逻辑放在 if __name__ == "__main__": 门控内。人工阅读正是为了确认这类模式是否在每个文件里被一致遵循。

第 2 步：运行结构检查器并修复违规

对每个子目录执行：

.venvs/demo/bin/python cookbook/scripts/check_cookbook_pattern.py --base-dir cookbook/integrations/<SUBDIR> --recursive

该脚本是校验的核心工具，位于 cookbook/scripts/check_cookbook_pattern.py，其实现细节在本文第五节展开。执行后需修复全部违规项（violations），直至脚本退出码为 0。

第 3 步：运行全部示例脚本

用 .venvs/demo/bin/python 运行子目录下所有 *.py 文件并记录结果，__init__.py 除外。运行输出即"功能是否可用"的直接证据——例如 Parallel 示例能否真实返回搜索结果、SurrealDB 示例能否真实写入并读回记忆。

第 4 步：核对风格规范并更新测试日志

示例代码须符合 cookbook/STYLE_GUIDE.md 的 5 条硬性规则：

1. 模块 docstring 置于文件顶部，且以 ===== 下划线装饰标题行；
2. 使用横幅注释（# ----- 或 # ===== 风格）划分区块；
3. import 语句位于 docstring 与第一个横幅之间；
4. 必须存在 if __name__ == "__main__": 执行门控；
5. Python 文件中不得出现 emoji 字符。

随后在每个目录自己的 TEST_LOG.md 中登记每个文件的新鲜 PASS/FAIL 记录。例如 cookbook/integrations/parallel/TEST_LOG.md 与 cookbook/integrations/surrealdb/TEST_LOG.md，而 cookbook/integrations/TEST_LOG.md 则作为总览，指向各子目录的日志并记录 check_cookbook_pattern.py 的整体状态。

---

四、特殊场景：两类需要"跳过或延长时间"的集成

TEST_PROMPT 专门为两个子目录标注了运行前提与风险，这是测试执行中最容易踩坑的部分。

Parallel：需要 API 密钥，Task/Monitor 示例耗时极长

• parallel/ 需要 PARALLEL_API_KEY 环境变量，且需 pip install parallel-web 安装 SDK；
• Task 与 Monitor 示例可能非常慢（深度研究最长可达约 25 分钟），测试时应设置长超时，或明确以 SKIP 状态跳过并附注原因；
• parallel/09_agent_os_app.py 会启动一个 AgentOS 服务——验证它成功启动后即可终止进程，不必等待完整业务闭环。

从源码看，这些耗时点确实存在：parallel/03_deep_research.py 使用 Task API 启动深度研究（create_task() 后 get_task_result() 轮询结果），其 docstring 明确说明处理器（processor）是在"深度"与"时间"之间做权衡："base" 快、适合大多数问题（几秒到几分钟）；"pro" 更深、且是 "auto" 输出模式的必需项；"ultra" 深度最大、可能运行数分钟以上。而 parallel/08_competitive_intel_monitor.py 则使用 Monitor API——监控器在服务端按自身调度运行，因此新建的监控器当下没有事件，需要重跑脚本才能看到检测到的变化。

SurrealDB：必须有运行中的实例

surrealdb/ 下所有示例都依赖一个可连接的 SurrealDB 实例（连接参数如 ws://localhost:8000、用户 root、密码 root、namespace agno、database memories，见 standalone_memory_surreal.py）。如果本地未启动该服务，测试应标记为 SKIP 而不是伪造 PASS。

---

五、校验工具的源码级解析：check_cookbook_pattern.py 到底检查什么

cookbook/scripts/check_cookbook_pattern.py 是整个验证流程的自动化核心。读懂它的检查逻辑，才能理解"为什么 TEST_PROMPT 要求修复违规"。该脚本以 ast 解析 Python 源码，对每个文件依次做如下检查：

1. 语法检查（ast.parse）：语法错误直接记为 syntax_error 违规并跳过后续检查；
2. 模块 docstring（ast.get_docstring）：缺失则记为 missing_docstring；
3. 主执行门控：文件名不以 _ 开头时必须匹配 if __name__ == "__main__":，否则记为 missing_main_gate（下划线前缀的支撑模块除外）；
4. 区块横幅：通过正则 ^# [-=]+\n# (?P<title>.+?)\n# [-=]+$ 识别 # --- / # === 风格的区块标题；没有区块记为 missing_sections；
5. Create / Run 区块及其顺序：必须存在标题含 "Create" 的区块（missing_create_section）和含 "Run" 的区块（missing_run_section），且 Create 必须出现在 Run 之前（section_order 违规）；
6. emoji 检查：用 Unicode 区间 [\U0001F300-\U0001FAFF] 扫描所有字符，命中记为 emoji_not_allowed；
7. 扫描范围控制：跳过 __init__.py、__main__.py、__pycache__、.git、.context 等。

从实现看，脚本还支持 --output-format json 输出结构化违规报告，便于接入 CI 或脚本化处理；退出码非 0 即代表存在违规。也就是说，TEST_PROMPT 中的 --recursive 扫描实质上是对"docstring → 区块 → 执行门控 → 无 emoji"这套 cookbook 可教学模式的机器化验证，人工通读的价值则在于发现这些规则覆盖不到的内容质量问题。

与之配套的还有两条全局验证命令：

source .venv/bin/activate && ./scripts/format.sh      # 用 ruff format 统一格式化
source .venv/bin/activate && ./scripts/validate.sh    # 用 ruff check + mypy 做静态校验

这两条命令作用于整个仓库（scripts/format.sh、scripts/validate.sh），在子目录级结构检查全部通过后执行，属于测试协议的最后一道关。

---

六、把示例跑起来：两类集成的真实代码形态

为了让"验证什么"更具体，下面结合测试对象本身的源码，展示两类集成的核心形态——这正是测试执行时需要逐行核对的内容。

Parallel：一个最小研究 Agent

parallel/01_quickstart.py 是"最小的 Parallel 驱动 Agent"：给 Agent 挂上 ParallelTools()（默认启用 Search 与 Extract 两个 API），即可用一句自然语言问题触发联网研究：

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.parallel import ParallelTools

agent = Agent(
    model=OpenAIResponses(id="gpt-5.4"),
    tools=[ParallelTools()],
    markdown=True,
)

if __name__ == "__main__":
    agent.print_response(
        "What did Parallel (parallel.ai) launch most recently, and when?",
        stream=True,
    )

需要启用更深层 API 时通过开关完成（parallel/README.md）：

ParallelTools(enable_task=True)       # 深度研究，带引用
ParallelTools(enable_monitor=True)    # 定时追踪主题变化

更完整的形态是 parallel/04_research_assistant.py：它把 Search + Extract + Task 三套 API 与 Agno 持久化（SQLite 会话 db = SqliteDb(db_file="tmp/parallel_assistant.db")）组合成"可回访"的研究助手，通过 add_history_to_context=True、num_history_runs=5、update_memory_on_run=True 实现跨轮记忆，并用固定的 user_id / session_id 串联多轮对话。测试时这类示例除了验证工具调用，还要验证会话持久化是否真正生效（第一轮建立主题后，第二轮追问时助手是否还记得上下文）。

SurrealDB：记忆管理的增删改查

surrealdb/standalone_memory_surreal.py 展示了用 SurrealDB 做记忆后端的完整 CRUD 流程：

from agno.db.surrealdb import SurrealDb
from agno.memory import MemoryManager, UserMemory

SURREALDB_URL = "ws://localhost:8000"
SURREALDB_USER = "root"
SURREALDB_PASSWORD = "root"
SURREALDB_NAMESPACE = "agno"
SURREALDB_DATABASE = "memories"

creds = {"username": SURREALDB_USER, "password": SURREALDB_PASSWORD}
db = SurrealDb(None, SURREALDB_URL, creds, SURREALDB_NAMESPACE, SURREALDB_DATABASE)
memory = MemoryManager(db=db)

随后通过 MemoryManager 的 add_user_memory（写入，支持按 user_id 隔离用户）、get_user_memories（读取）、delete_user_memory（删除）、replace_user_memory（替换）完成对用户记忆的全生命周期管理。测试时需确认每次操作后读回的结果与预期一致（示例中直接使用 assert 断言来守护这一正确性）。该子目录其他示例还覆盖了从文本/对话历史自动创建记忆、自定义提取指令、多检索方式搜索记忆、以及用数据库工具精细控制增删改查等场景（见 surrealdb/README.md）。

---

七、最终验收报告：Test Prompt 规定的输出格式

测试协议对最终交付物也有明确格式要求，共四部分，其中最后一项是结构化结果表：

1. Findings：列出发现的不一致、失败与风险，并附带文件引用；
2. Test/validation commands run with results：实际执行过的测试/验证命令及结果；
3. Any remaining gaps or manual follow-ups：遗留缺口或需要人工跟进的事项；
4. 结果表格：

Subdirectory	File	Status	Notes
parallel	01_quickstart.py	PASS	Search returned results
surrealdb	memory_creation.py	SKIP	SurrealDB not running

从这个表格可以看出状态值约定：PASS 表示运行通过、SKIP 表示因外部依赖不可用而跳过（并附原因）。这与 cookbook/integrations/TEST_LOG.md 的登记习惯一致——该文件目前将 check_cookbook_pattern.py 的整体状态记为 PENDING，并注明"待 Parallel showcase 落地后重跑"，体现了"测试状态必须是当下事实"的记录原则。

---

八、把测试协议沉淀为可复用流程

回顾整份 TEST_PROMPT，其价值不只是针对 cookbook/integrations 的一次性验收，更是一套可复用的 cookbook 质量流程模板。将其提炼为通用步骤，任何新增的集成示例目录都可以套用：

1. 先读规范，再读代码：CLAUDE.md / AGENTS.md 建立项目约定，cookbook/STYLE_GUIDE.md 建立代码形态预期；
2. 自动化结构校验打底：check_cookbook_pattern.py --base-dir <dir> --recursive 负责 docstring、区块顺序、主门控、无 emoji 等机械规则；
3. 人工通读补盲：专查自动检查覆盖不到的 import 位置、过期注释、风格漂移；
4. 真实运行验证：在约定虚拟环境 .venvs/demo/bin/python 下逐个执行示例，区分"外部依赖缺失导致的 SKIP"与"代码缺陷导致的 FAIL"；
5. 全局格式化与静态检查收尾：format.sh（ruff format）与 validate.sh（ruff check + mypy）；
6. 如实登记：在每个目录的 TEST_LOG.md 更新逐文件状态，在最终报告中给出 Findings、命令清单、遗留事项与结果表。

按此流程执行，既能保证 cookbook 示例"可读、可教、可运行"，又能让每个集成模块的验证过程可追踪、可复现——这正是 Agno 仓库在 cookbook/integrations/TEST_PROMPT.md 中想要沉淀的工程习惯。