Agno AgentOS 数据库与外部媒体存储实战指南02_databases 示例的端到端验证与源码解析【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno本文基于 Agno 仓库 cookbook/05_agent_os/02_databases 目录下的示例脚本及其 TEST_LOG.md 实测记录系统讲解 AgentOS 的默认数据库继承机制、SQLite/Postgres/SurrealDB 三种数据库后端、S3/GCS 外部媒体存储以及会话媒体的读取与级联删除。读者完成后将掌握如何为 AgentOS 配置持久化存储、如何让数据库只存元数据而把文件字节交给对象存储、如何用GET /config、GET /sessions与媒体路由验证全链路是否真正落盘。一、02_databases 目录概览一套存储示例两层职责AgentOS 的存储设计可以拆成两个正交问题会话与状态数据放在哪张数据库里以及文件字节放在哪个对象存储里。cookbook/05_agent_os/02_databases下的六个示例脚本恰好覆盖这两层文件演示主题验证方式basic.pySQLite 默认数据库继承与自动建表LIVE 实测postgres.py同步/异步 Postgres 生产级持久化LIVE 实测surreal.pySurrealDB 客户端/凭证/命名空间构造LIVE 实测s3_media_storage.py媒体字节卸载到 S3库中只留MediaReferenceLIVE 实测gcs_media_storage.py媒体字节卸载到 GCS库中只留MediaReferenceSTATIC 静态验证media_storage_delete.py会话媒体回读与随会话删除对象LIVE 实测根据 TEST_LOG.md这批示例于2026-07-24针对 Agno 源码提交64129408633bb3f4837b2a09a0eb087eddbed86a全部测试通过其中五个为 LIVE连接真实服务模式、一个为 STATIC不发起云请求的静态检查模式。测试的核心方法论贯穿始终启动 AgentOS 服务后逐一调用health健康检查、configuration/config、session-writePOST /sessions、session-listGET /sessions四类端点验证数据真实写入并读出。二、核心机制一默认数据库继承与自动建表2.1 继承规则README 明确了两条规则AgentOS(db...)会把该数据库下发给所有未显式声明db的 agent、team 与 workflow成为它们的默认数据库组件自身声明的db永远优先于 AgentOS 的默认值。basic.py正是为验证这条规则而设计的创建了一个故意不写db参数的database-agent再把 SQLite 数据库传给 AgentOSdb SqliteDb( idagent-os-default-db, db_filetmp/databases.db, ) database_agent Agent( iddatabase-agent, nameDatabase Agent, modelOpenAIResponses(idgpt-5.5), instructionsAnswer questions concisely., markdownTrue, # 注意此 agent 刻意省略 db由 AgentOS 注入默认数据库 ) agent_os AgentOS( iddatabase-basics-os, descriptionAgentOS default-database inheritance with SQLite., dbdb, agents[database_agent], auto_provision_dbsTrue, ) app agent_os.get_app()2.2 测试证据继承确实生效TEST_LOG 对basic.py的记录如下LIVE 模式PASS启动时自动创建了 AgentOS 所需的全部表即 provisioning 生效访问/config时OS 与database-agent报告的数据库 ID 都是agent-os-default-db——这直接证明没有自带数据库的 agent 继承了 AgentOS 的默认数据库通过POST /sessions创建会话后再从GET /sessions读回数据往返一致。这里的自证闭环很有价值/config同时暴露 OS 级与组件级数据库 ID是排查某个 agent 到底落在哪个库的第一现场。你也可以按basic.py文件头部的提示自行打开http://localhost:7777/config对比 OS 与 agent 的 db ID。2.3 源码印证auto_provision_dbs 的默认行为auto_provision_dbsTrue是 AgentOS 的默认值libs/agno/agno/os/app.py 中AgentOS.__init__的参数定义。从源码结构看其生命周期大致如下构建应用时通过_auto_discover_databases()收集所有注册的数据库实例服务启动时db_lifespan执行_initialize_sync_databases()与_initialize_async_databases()在事件循环内完成建表关闭时统一释放连接。因此本地开发最常见的做法就是什么都不配给个 SQLite 路径直接启动表会自动就位。只有当你用外部迁移流程如 Alembic托管 schema 时才应该把auto_provision_dbs关掉避免 AgentOS 与迁移工具争抢建表职责。三、核心机制二同步与异步 Postgres 生产持久化3.1 两种适配器的选择README 给出的选型建议是本地开发用 SQLite生产用 Postgres。postgres.py则更进一步展示了同一份代码如何在同步与异步适配器之间切换sync_db PostgresDb( idagent-os-postgres-sync, db_urlpostgresqlpsycopg://ai:ailocalhost:5532/ai, ) async_db AsyncPostgresDb( idagent-os-postgres-async, db_urlpostgresqlpsycopg_async://ai:ailocalhost:5532/ai, ) use_async getenv(AGENTOS_USE_ASYNC_POSTGRES, false).lower() true db async_db if use_async else sync_db注意两个关键差异导入路径PostgresDb同步与AsyncPostgresDb异步都来自agno.db.postgres连接串驱动同步用postgresqlpsycopg://...异步必须换postgresqlpsycopg_async://...不能混用。启动方式也随之区分。同步.venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.py异步通过环境变量切换无需改代码AGENTOS_USE_ASYNC_POSTGREStrue \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.py3.2 测试证据两种模式各自建表、各自持久化TEST_LOG 对postgres.py的记录LIVE 模式PASS在端口5532的 Postgres 服务上分别以同步、异步两种适配器运行同一套 AgentOS 服务各自执行 health、config、session-write、session-list 端点。结果同步运行成功 provision 了自己的 schema/config报告数据库agent-os-postgres-sync异步运行报告agent-os-postgres-async每个适配器都持久化并读回了各自的测试会话互不串扰。这组实验同时验证了三件事环境变量切换机制有效、两种驱动连接串正确、AgentOS 能在同一库实例上为不同数据库 ID 各自建表。3.3 生产延伸Neon、Supabase 等托管库怎么接仓库 README 特别提醒Neon 与 Supabase 走的是 Postgres 线协议直接把它们的连接串传给PostgresDb即可不需要独立适配器。这是把生产持久化落到云托管服务时最省事的路径——你只需要准备好连接串AgentOS 侧完全无感。四、核心机制三SurrealDB 的构造形态不是所有数据库都接受 SQL 连接串。surreal.py展示了 SurrealDB 的特殊构造形状client、URL、凭证、命名空间、数据库名五个维度分开传入db SurrealDb( clientNone, db_urlgetenv(SURREALDB_URL, ws://localhost:8000), db_creds{ username: getenv(SURREALDB_USER, root), password: getenv(SURREALDB_PASSWORD, root), }, db_nsgetenv(SURREALDB_NAMESPACE, agno), db_dbgetenv(SURREALDB_DATABASE, agent_os), idagent-os-surreal, )所有连接参数都支持环境变量覆盖默认值与仓库里的 run_surrealdb.sh 启动脚本保持一致因此本地起服务后开箱即用。运行前置条件安装扩展pip install agno[surrealdb]启动服务./cookbook/scripts/run_surrealdb.sh。测试证据LIVE 模式PASSTEST_LOG 记录了启动一个隔离的 SurrealDB 服务通过SURREALDB_URL配置示例然后执行四类端点。/config报告 OS 侧数据库agent-os-surreal、组件侧surreal-agent通过POST /sessions创建的会话成功从 SurrealDB 读回。一个值得记录的运维细节隔离服务最终使用端口8001因为 8000 已被本机另一个 AgentOS 容器占用——端口冲突在微服务化部署中很常见SURREALDB_URL环境变量让示例可以灵活换端口而不改代码。五、核心机制四把媒体字节卸载到对象存储5.1 为什么需要 media_storage如果对话中包含图片、CSV、生成的文档把这些字节以 base64 塞进数据库会迅速膨胀表体积、拖慢查询。AgentOS 的解法是双通道存储数据库只存会话文本与元数据media_storage决定文件字节去向上传与生成的文件写入对象存储会话行里只留一个轻量的MediaReference。配置方式是在AgentOS(media_storage...)传入后端媒体随后通过GET /sessions/{session_id}/media/{storage_key}对外提供。s3_media_storage.py的完整形态storage AsyncS3MediaStorage( bucketbucket, # 来自 AGNO_FILE_OUTPUT_S3_BUCKET regionos.getenv(AWS_REGION), # 缺省时回退 AWS_DEFAULT_REGION 或 ~/.aws/config prefixagno/agentos/files/, # 桶内统一前缀 presigned_url_expiry3600, # 预签名 URL 有效期秒 ) file_agent Agent( idmedia-storage-agent, modelOpenAIResponses(idgpt-5.5), dbdb, media_storagestorage, store_mediaTrue, # 开启媒体落盘 add_history_to_contextTrue, tools[FileGenerationTools(allTrue)], # 支持 agent 生成文件 ... ) agent_os AgentOS( idagentos-media-storage, agents[file_agent], dbdb, media_storagestorage, # 媒体路由经由此实例解析 storage_key )GCS 版本gcs_media_storage.py结构完全对称只是换用AsyncGCSMediaStorage并通过GCP_PROJECT与GOOGLE_APPLICATION_CREDENTIALS或 Application Default Credentials认证。5.2 测试证据S3 全链路真实验证LIVETEST_LOG 对s3_media_storage.py的记录是目前目录里最完整的一条链路验证对真实 S3 桶启动 AgentOS通过POST /agents/media-storage-agent/runs上传一个 CSV 并让 agent 生成另一个 CSV两个 run 都成功完成且每条agno_runs行携带的是MediaReference而非 base64引用大小分别为 3590 与 6867 字节上传与生成的 CSV 都写入 S3 默认前缀agno/agentos/files/下对象本体 77 与 82 字节ContentType: text/csvGET /sessions/{session_id}/media/{storage_key}返回200Content-Type为text/csv; charsetutf-8内容与对象逐字节一致追加redirecttrue时返回307指向一个新签发的预签名 URL。这套断言直接坐实了 README 中上传和生成的文件写入对象存储、数据库只留引用、媒体经由路由流式回读的全部承诺。5.3 测试证据GCS 静态验证STATICGCS 版本没有连接真实桶而是采用 STATIC 模式用占位桶构造 AgentOS 应用但不发任何 Google Cloud 请求。TEST_LOG 验证了三点agent 与 AgentOS 共享同一个AsyncGCSMediaStorage实例应用同时暴露了agent run 路由与会话媒体路由Ruff 格式化、lint 与 Python 编译全部通过。并如实注明GCS 的 live 上传与回读需要配置好的凭证与真实桶。STATIC 模式的价值在于——在没有云凭证的 CI 或离线环境里依然可以验证装配正确性共享实例、路由挂载、代码质量把需要真实云资源的风险留到部署阶段。5.4 一个容易踩的坑region 配置README 专门提醒了 region 的坑当桶不在默认区域时必须传region。原因是上传阶段 AgentOS 会自动定位区域但媒体 URL 的签名里携带 region若不显式配置媒体能存得上去却读不出来——保存成功、加载失败问题极其隐蔽。S3 示例中region取自AWS_REGION未设置时回退到AWS_DEFAULT_REGION或本地~/.aws/config这一点在 s3_media_storage.py 的注释中有明确交代。六、核心机制五会话媒体的回读与级联删除media_storage_delete.py回答最后一个生命周期问题媒体随会话删除吗6.1 默认行为媒体比会话活得久文件头部的 docstring 说得很清楚媒体默认比会话存活得更久。run 上的MediaReference是哪个对象属于哪个会话的唯一记录。因此delete_mediatrue的实现逻辑是删除前先从行里读出所有 storage_key再在行被删掉之后统一清扫对象——先取钥匙、后拆房子。示例配置S3 变体db SqliteDb(db_filetmp/agentos_media_delete.db) storage AsyncS3MediaStorage( bucketbucket, regionos.getenv(AWS_REGION), prefixagno/agentos/files/, presigned_url_expiry3600, ) file_agent Agent( idmedia-delete-agent, modelOpenAIResponses(idgpt-5.5), dbdb, media_storagestorage, store_mediaTrue, ... ) agent_os AgentOS( idagentos-media-delete, agents[file_agent], dbdb, media_storagestorage, # 读与删路由都通过这个实例解析 storage_key )6.2 测试证据删除语义的完整矩阵LIVETEST_LOG 对media_storage_delete.py的记录构成了一张清晰的删除语义表步骤请求结果挂载文本文件并运行POST /agents/media-delete-agent/runs200S3 下agno/agentos/files/新增 1 个对象检查会话行GET /sessions/{session_id}行内是media_reference无 base64流式回读GET /sessions/{session_id}/media/{storage_key}200text/plain; charsetutf-8与原始 21 字节完全一致预签名跳转同上加redirecttrue307仅删会话DELETE /sessions/{session_id}204对象保留在 S3级联删除DELETE /sessions/{session_id}?delete_mediatrue204对象一并移除测试后桶内容恢复原状避免污染共享环境。这张表给出明确的操作语义想要保留用户生成物就只删会话需要彻底清除数据如隐私合规、测试清理就必须显式带delete_mediatrue。七、后端选型参考与运行手册7.1 数据库后端速查表README 给出的完整参考表同一套 AgentOS 写法仅换后端可以直接作为选型清单后端导入连接示例所需服务SQLitefrom agno.db.sqlite import SqliteDbSqliteDb(db_filetmp/agent_os.db)无JSONfrom agno.db.json import JsonDbJsonDb(db_pathtmp/agent_os_json)无Postgresfrom agno.db.postgres import PostgresDbPostgresDb(db_urlpostgresqlpsycopg://user:passhost:5432/db)PostgreSQLMySQLfrom agno.db.mysql import MySQLDbMySQLDb(db_urlmysqlpymysql://user:passhost:3306/db)MySQLMongoDBfrom agno.db.mongo import MongoDbMongoDb(db_urlmongodb://localhost:27017, db_nameagno)MongoDBRedisfrom agno.db.redis import RedisDbRedisDb(db_urlredis://localhost:6379/0)RedisValkeyfrom agno.db.valkey import ValkeyDbValkeyDb(hostlocalhost, port6379)ValkeyDynamoDBfrom agno.db.dynamo import DynamoDbDynamoDb()AWS DynamoDB 及AWS_REGION、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEYFirestorefrom agno.db.firestore import FirestoreDbFirestoreDb(project_idmy-project)Firestore 与应用默认凭证GCS JSONfrom agno.db.gcs_json import GcsJsonDbGcsJsonDb(bucket_namemy-bucket)GCS 与应用默认凭证SingleStorefrom agno.db.singlestore import SingleStoreDbSingleStoreDb(db_urlmysqlpymysql://user:passhost:3306/db)SingleStoreSurrealDBfrom agno.db.surrealdb import SurrealDbSurrealDb(clientNone, db_url..., db_creds..., db_ns..., db_db...)SurrealDBClickHousefrom agno.db.clickhouse import ClickhouseDbClickhouseDb(hostlocalhost, databaseagno)仅用于 trace/span不是通用持久化后端内存from agno.db.in_memory import InMemoryDbInMemoryDb()无进程内、不持久两条需要重点记住的注意事项ClickHouse 在 AgentOS 中只实现 trace 与 span 接口会话、记忆、知识、评估与组件数据请使用 Postgres 这类行存储Neon/Supabase 走 Postgres 线协议直接把连接串交给PostgresDb即可。7.2 媒体存储后端速查表后端导入连接示例所需服务本地from agno.media.storage.local import LocalMediaStorageLocalMediaStorage(base_pathtmp/media)无S3from agno.media.storage.s3 import S3MediaStorageS3MediaStorage(bucketmy-bucket)S3 与agno[s3]GCSfrom agno.media.storage.gcs import GCSMediaStorageGCSMediaStorage(bucketmy-bucket)GCS 与agno[gcs]每个后端都有对应的Async变体供异步应用使用。7.3 运行与环境变量按 README.md 的说明各示例的运行命令与前置条件为# SQLite无需任何外部服务 .venvs/demo/bin/python cookbook/05_agent_os/02_databases/basic.py # 同步 Postgres先跑 ./cookbook/scripts/run_pgvector.sh .venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.py # 异步 Postgres AGENTOS_USE_ASYNC_POSTGREStrue \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.py # SurrealDBpip install agno[surrealdb] 后先跑 run_surrealdb.sh .venvs/demo/bin/python cookbook/05_agent_os/02_databases/surreal.py # S3 媒体存储pip install agno[s3] AWS 凭证 AGNO_FILE_OUTPUT_S3_BUCKETmy-bucket \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/s3_media_storage.py # GCS 媒体存储pip install agno[gcs] Google Cloud 凭证 AGNO_FILE_OUTPUT_GCS_BUCKETmy-bucket \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/gcs_media_storage.py # 媒体回读与删除 AGNO_FILE_OUTPUT_S3_BUCKETmy-bucket \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/media_storage_delete.py所有服务默认监听7777 端口。环境变量约定汇总AGNO_FILE_OUTPUT_S3_BUCKET/AGNO_FILE_OUTPUT_GCS_BUCKET媒体落桶的目标桶AGENTOS_USE_ASYNC_POSTGREStrue切换到异步 PostgresSURREALDB_URL/SURREALDB_USER/SURREALDB_PASSWORD/SURREALDB_NAMESPACE/SURREALDB_DATABASE覆盖 SurrealDB 连接参数AWS_REGION/GCP_PROJECT/GOOGLE_APPLICATION_CREDENTIALS云凭证相关OPENAI_API_KEY仅当 agent 真正调用模型时才需要纯建表与路由验证不需要。7.4 用 curl 复现测试步骤TEST_LOG 中的验证动作全部可以通过 HTTP 端点复现启动任意示例后# 1. 健康检查 curl http://localhost:7777/health # 2. 读取配置找到 os_database 与组件级 db ID验证默认数据库继承 curl http://localhost:7777/config # 3. 创建会话并读回验证 session-write / session-list curl -X POST http://localhost:7777/sessions curl http://localhost:7777/sessions # 4. 需要迁移 schema 时用 config 返回的 db ID 触发迁移 curl -X POST http://localhost:7777/databases/db-id/migrate # 迁移到指定 schema 版本 curl -X POST http://localhost:7777/databases/db-id/migrate?target_versionversion八、测试方法论总结从示例到可复用的验收清单回看 TEST_LOG.md 的整体结构它本身就是一个高质量的 AgentOS 存储验收模板可以抽象为四步清单装配检查/config返回的数据库 ID 必须符合预期——basic.py中 OS 与 agent 都指向agent-os-default-db即证明默认数据库继承生效写入检查POST /sessions后GET /sessions能读回证明持久化路径含异步驱动真实工作媒体落盘检查run 行里是MediaReference而非 base64对象出现在指定 prefix 下媒体路由 200 且内容逐字节一致redirecttrue返回 307 到新签 URL删除语义检查不带参数删会话只删行、带delete_mediatrue连对象一起清据此确定你的数据留存策略。当无法连接真实云服务时gcs_media_storage.py的 STATIC 验证方式给出了降级方案用占位配置验证实例共享与路由挂载把真实云资源的验证推迟到有凭证的环境同时保证代码质量门禁Ruff、lint、编译不缺席。九、结语02_databases 这套示例用六个脚本、一个测试日志把 AgentOS 的存储全景串联成一条可验证的链路选型SQLite→Postgres→SurrealDB→ 装配默认数据库继承→ 建表auto_provision_dbs→ 落盘对象存储 MediaReference→ 回读与清理媒体路由 delete_media。测试日志中的每一项 PASS 都不是空泛的能跑而是对着真实服务、真实桶、真实字节逐一断言的验收证据——这正是把示例代码变成生产决策时最值得借鉴的部分。后续若需要深挖某类后端如 DynamoDB、Firestore、SingleStore或某个端点如记忆、学习、组件路由的行为可以回到 05_agent_os 目录下的对应子目录继续展开。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考