Agno 存储 Cookbook 测试验证实战：数据库集成与媒体存储示例的系统化质检工作流-北京尧图网络

Agno 存储 Cookbook 测试验证实战数据库集成与媒体存储示例的系统化质检工作流【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文围绕 agno 仓库中cookbook/06_storage的测试验证工作流TEST_PROMPT.md展开系统讲解如何对一个覆盖 12 种数据库集成、会话持久化与媒体卸载的示例目录执行逐文件、逐子目录的标准化验证。读完本文你将掌握 agno cookbook 的代码规范检查、依赖感知的运行策略、验证命令链与结果报告格式并能基于06_storage的实际示例深入理解 Agent/Team/Workflow 的持久化与媒体存储原理。一、测试对象cookbook/06_storage 目录全景cookbook/06_storage是 agno 仓库中专门演示「将 Agent、Team、Workflow 与会话、媒体数据持久化到外部存储」的示例集。其目录结构分为三大类1. 根级会话管理示例目录根文件主题01_persistent_session_storage.py使用 PostgresDb 对 Team 做持久化会话存储02_session_summary.py会话摘要session summary配置03_chat_history.py从数据库会话中读取聊天历史04_session_summary_limits.py用last_n_runs/conversation_limit限制摘要输入05~11 系列媒体存储本地 / S3 / GCS 卸载与读取、删除、Workflow 场景、文件生成2. 数据库集成子目录postgres含async_postgres、sqlite含async_sqlite、mongo含async_mongo、mysql含async_mysql、redis、valkey、singlestore、firestore、dynamodb、json_db、gcs、in_memory、surrealdb、examples每个子目录内都包含README.md、TEST_LOG.md、__init__.py及针对 Agent/Team/Workflow 的示例脚本。3. 非 Python 文件各子目录的README.md与TEST_LOG.md同样属于检查范围重点是排查过时的OpenAIChat引用等历史遗留问题。该目录的覆盖面在 README.md 中有完整清单PostgreSQL、SQLite、MongoDB、MySQL、Redis、Valkey、SingleStore、Firestore、DynamoDB、JSON 文件存储、GCS、内存存储共 12 种后端。二、测试前置条件与运行环境TEST_PROMPT 明确规定了一套统一的执行环境任何验证工作开始前都必须就位Python 解释器使用项目专用的.venvs/demo/bin/python而不是系统默认 Python——这是 agno 仓库的约定详见根目录 AGENTS.md其中记录了项目规范、虚拟环境与测试工作流。API Keys通过direnv allow加载避免在脚本中硬编码密钥。数据库依赖PostgreSQL 相关示例需要先启动实例仓库提供了一键脚本 cookbook/scripts/run_pgvector.sh启动带 pgvector 扩展的 Postgres供postgres与postgres_async子目录使用。代码风格基准cookbook/STYLE_GUIDE.md 定义了所有 Python 示例的文件结构规则。以根级示例为例实际运行命令形如.venvs/demo/bin/python cookbook/06_storage/01_persistent_session_storage.py .venvs/demo/bin/python cookbook/06_storage/03_chat_history.py其中 01_persistent_session_storage.py 演示了最基础的持久化接入——用PostgresDb(db_url..., session_tablesessions)建库对象Team 通过dbdb、session_idteam_session_storage、add_history_to_contextTrue三个参数把会话写入数据库并在后续轮次注入上下文。三、核心执行要求六步标准验证流程TEST_PROMPT 将整个验证工作拆解为六个明确步骤这是整份文档的骨架第 1 步通读全部源码禁止只靠 grep在改动任何文件之前必须逐个打开、阅读目标目录下的每一个.py文件理解完整内容。文档特别强调不要只依赖 grep 或结构检查器因为自动检查会漏掉「section 内的 import、注释中过时的模型引用、不一致的模式」这类问题。第 2 步按子目录并行派发 agent为cookbook/06_storage/下的每个子目录各派一个并行 agent每个 agent 独立处理一个子目录互不干扰。这种并行结构设计是为了让多后端验证Postgres、Mongo、Redis 等可以在不同 agent 中同时推进缩短整体耗时。第 3 步每个 agent 的强制动作清单每个 agent 必须依次完成a. 运行结构检查器并修复违规执行.venvs/demo/bin/python cookbook/scripts/check_cookbook_pattern.py --base-dir cookbook/06_storage/SUBDIR修复所有报告的问题。b. 运行该子目录下所有*.py文件使用.venvs/demo/bin/python逐一执行跳过__init__.py记录每个文件的运行结果。c. 确保示例符合 STYLE_GUIDE模块 docstring 使用下划线章节横幅使用# ---------------------------------------------------------------------------import 位于 docstring 与第一个横幅之间必须有if __name__ __main__:执行门不允许出现 emoji 字符。d. 同步检查非 Python 文件子目录内的README.md等文件若残留过时的OpenAIChat引用一并更新。e. 最小化、行为保持的修改仅在为满足风格合规时才做必要的修改且必须是「最小、不改变行为」的编辑。f. 更新 TEST_LOG把该子目录每个文件的 PASS/FAIL 结果以最新条目写回cookbook/06_storage/SUBDIR/TEST_LOG.md。第 4 步根级文件测试01_persistent_session_storage.py、02_session_summary.py、03_chat_history.py等根级文件也需要同样测试并更新cookbook/06_storage/TEST_LOG.md。第 5 步合并结果所有并行 agent 完成后汇总合并所有子目录与根级文件的验证结果。第 6 步最终响应按规定的四段格式输出详见第六节。四、依赖感知的运行策略各后端的跳过条件这是 TEST_PROMPT 中极具工程价值的部分——不是所有示例都必须在本地跑通而是根据外部依赖是否可用做「运行 / 跳过」决策。完整矩阵如下子目录 / 后端前置依赖不可用时的策略postgres/postgres_async运行中的 PostgreSQL用run_pgvector.sh启动依赖未就绪则无法运行mysql/mysql_async运行中的 MySQL直接跳过mongo/mongo_async运行中的 MongoDB直接跳过redis运行中的 Redis直接跳过dynamodbAWS DynamoDB本地或云端直接跳过firestore/gcsGoogle Cloud 凭证直接跳过surrealdb运行中的 SurrealDB直接跳过sqlite/json_db/in_memory无外部依赖必须始终通过其中sqlite、json_db、in_memory三类无外部依赖、应当稳定 PASS 的子目录构成了验证的「基线锚点」如果它们都失败说明环境本身有问题反之它们全部通过才能把失败归因于特定后端。五、验证命令链与结构检查器原理所有验证必须在以下命令全部通过后才能宣告完成# 1. 结构模式检查逐子目录 .venvs/demo/bin/python cookbook/scripts/check_cookbook_pattern.py --base-dir cookbook/06_storage/SUBDIR # 2. 全量格式化ruff format source .venv/bin/activate ./scripts/format.sh # 3. 全量校验ruff check mypy source .venv/bin/activate ./scripts/validate.sh其中第一条命令的背后是 cookbook/scripts/check_cookbook_pattern.py它用 AST 解析而非正则匹配来校验示例结构。从其源码第 72-120 行可以确认五条硬性规则模块 docstring 必须存在缺失即报missing_docstring必须有主执行门非下划线前缀的.py文件必须包含if __name__ __main__:否则报missing_main_gate必须使用横幅分节通过SECTION_RE# ---或# 样式识别章节无章节报missing_sections章节顺序必须存在「Create…」章节在前、「Run…」章节在后禁止 emojiEMOJI_RE[\U0001F300-\U0001FAFF]扫描整个源码。检查器还会自动跳过__init__.py、__main__.py以及__pycache__、.git、.context目录避免误报。以 03_chat_history.py 为正面范例可以看到它完整符合上述规范docstring →# ---横幅分节Setup / Create Agent / Run Agent→if __name__ __main__:执行门。而 02_session_summary.py 则展示了「方法一enable_session_summariesTrue注释形式保留」与「方法二显式传入SessionSummaryManager」两种配置路径验证时需确认注释示例与实际激活的代码不互相矛盾。六、最终响应格式结构化的测试报告TEST_PROMPT 要求验证结束后按固定四段格式输出这在多 agent 协作场景下保证了报告的可合并性Findings发现列出不一致、失败项与风险必须带文件引用Test/validation commands run with results执行的测试与结果Remaining gaps or manual follow-ups剩余缺口与人工跟进项Results table结果表格式如下SubdirectoryFileStatusNotespostgressession_storage.pyPASSSession persisted and retrieveddynamodbdynamodb_storage.pySKIPDynamoDB not available locally结果表通过Status列PASS / FAIL / SKIP一目了然地呈现每个文件的验证结论Notes列则记录「持久化成功并取回」「本地无 DynamoDB 故跳过」等补充事实便于后续审计与回归对比。七、从测试视角理解 Storage 功能的纵深设计理解验证工作流之后值得把06_storage示例背后的设计意图串起来——这正是测试时最容易踩坑、也最值得深入的地方。7.1 会话持久化的三种能力三个根级示例共同勾勒出会话管理的完整能力持久化与上下文注入01_persistent_session_storage.py 通过add_history_to_contextTrue让数据库中的历史在每轮自动拼入上下文会话摘要02_session_summary.py 将长对话浓缩为摘要04_session_summary_limits.py 进一步用last_n_runs5只看最近 5 轮和conversation_limit20最多 20 条消息控制送入摘要模型的输入量防止长会话撑爆摘要模型的上下文窗口历史读取03_chat_history.py 演示agent.get_chat_history()直接从数据库取回全部历史并打印。7.2 媒体存储数据库里只放指针05~11系列示例展示的是「媒体卸载media offload」模式图片、音频、文件等大体积内容存入对象存储本地文件系统 / S3 / GCS数据库行只保留一个轻量MediaReference指针。测试时需要注意几个关键行为URL-only 媒体默认跳过仅传Image(url...)时默认不落盘需persist_remote_urlsTrue才会自动下载见 05_media_storage_local.py多轮复用07_media_storage_multiturn.py 中第 1 轮上传图片后第 2 轮无需重新附加存储的引用会在读取时重新签名re-signed模型直接从 S3 拉取字节Workflow 场景10_media_storage_workflow.py 证明workflow.run(images...)传入的媒体与步骤内 Agent 产出的媒体都会被卸载且步骤输入会在执行前从存储重新水合rehydrate生成文件的卸载11_media_storage_file_generation.py 让FileGenerationTools生成的文件同样走卸载通道通过file.get_content_bytes(storage...)读取字节、file.get_url(storage...)获取重新签名的链接删除语义09_media_storage_delete.py 演示默认情况下删除会话行后对象会残留指针是找到对象的唯一线索必须传delete_mediaTrue才会先读键再清扫对象——该标志在 Agent、Team、Workflow 的同步与异步版本上同时存在。7.3 单向门媒体存储的升级约束README.md 中有一条重要的生产运维警示第 78-90 行开启媒体存储是「单向门one-way door」。虽然无 schema 变更但媒体列的数据形态会变化——卸载后的图片携带media_reference而不再有content。旧版读取器会因媒体三者url/filepath/content皆无而直接抛异常导致包含一条卸载行的get_sessions()整体失败新版代码读取旧行则安全。因此在验证时这也意味着升级方向单向安全回滚方向不安全——发布顺序必须先全量升级再开启media_storage。八、可复用的验证流程总结把 TEST_PROMPT 提炼成一套可复用的方法论适用于任何大型 cookbook 目录的质量保障环境先行固定解释器版本、密钥加载方式、外部服务启动脚本如run_pgvector.sh分级派发按子目录并行天然适配多后端测试静态动态双验证结构检查器AST 级保证规范实跑保证可运行依赖矩阵管理明确「必须 PASS / 可 SKIP」边界避免环境差异污染结果格式化类型检查收尾format.shruff format与validate.shruff check mypy做全局兜底结构化报告Findings / Commands / Gaps / Results table 四段式保证多 agent 结果的合并性与可追溯性。这套工作流同时适用于cookbook/02_agents、03_teams、04_workflows等所有 cookbook 目录的同类验证是理解 agno 示例工程质量与贡献规范的直接入口。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Agno 存储 Cookbook 测试验证实战：数据库集成与媒体存储示例的系统化质检工作流

相关推荐

lib60870-2.2.0源码深度解析：IEC 60870-104协议栈分层实现与故障调试

心电图分类识别：CNN、RNN与SVM模型对比详解

从登录到鉴权：前端用户认证模块的完整设计与避坑指南

更多资讯

PCIe Switch芯片怎么选？ACP系列国产替代方案全解析

impeccable 之 onboard 设计指南：如何打造直达“顿悟时刻“的首次使用体验、空状态与激活路径

昇腾GE动态shape功能指南

Nginx Proxy Manager 重定向主机（Redirection Host）完整指南：域名迁移与 301/302 跳转实战

Code Review Graph VS Code 扩展使用指南：在编辑器中可视化代码依赖图、爆炸半径与审查上下文

Dubbo负载均衡全解析：内置策略源码与权重预热细节

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？