agno AgentOS 数据库与媒体存储配置指南从 SQLite 到生产级 Postgres 与 S3/GCS【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技术指南围绕 agno AgentOS 的持久化配置展开核心讲解如何通过AgentOS(db...)注入默认数据库、通过AgentOS(media_storage...)将媒体文件字节外置到对象存储以及如何启动服务、执行数据库迁移与删除会话媒体。读完本篇你将掌握 AgentOS 默认数据库继承机制、SQLite/Postgres/SurrealDB 等十余种存储后端的接入方式、外部媒体存储的完整读写与删除链路以及生产环境下的 schema 迁移命令。文中所有配置与命令均可在当前仓库的 cookbook/05_agent_os/02_databases 目录中直接运行验证。AgentOS 数据库设计一次注入全局继承AgentOS 的持久化设计遵循默认值 组件级覆盖原则。将数据库传给AgentOS(db...)后该数据库会成为所有未显式指定自身数据库的 agent、team 和 workflow 的默认存储后端任何组件级db配置始终优先于默认值。这一行为在示例 basic.py 中有直接体现database_agent在构造时刻意省略db参数由AgentOS将注入的SqliteDb自动分配给它。from agno.agent import Agent from agno.db.sqlite import SqliteDb from agno.models.openai import OpenAIResponses from agno.os import AgentOS db SqliteDb( idagent-os-default-db, db_filetmp/databases.db, ) # 该 agent 故意不设置 dbAgentOS 会注入默认数据库 database_agent Agent( iddatabase-agent, nameDatabase Agent, modelOpenAIResponses(idgpt-5.5), instructionsAnswer questions concisely., markdownTrue, ) agent_os AgentOS( iddatabase-basics-os, descriptionAgentOS default-database inheritance with SQLite., dbdb, agents[database_agent], auto_provision_dbsTrue, ) app agent_os.get_app()从源码看auto_provision_dbs是AgentOS构造函数的显式参数默认值为True见 libs/agno/agno/os/app.py。当服务启动时若该参数为真FastAPI 的 lifespan 钩子会依次调用_initialize_sync_databases()与_initialize_async_databases()在事件循环中创建所需的数据表只有当你使用外部迁移流程接管 schema 管理时才应将其关闭。asynccontextmanager async def db_lifespan(app: FastAPI, agent_os: AgentOS): Initializes databases in the event loop and closes them on shutdown. if agent_os.auto_provision_dbs: agent_os._initialize_sync_databases() await agent_os._initialize_async_databases()一个实用的验证技巧服务启动后访问http://localhost:7777/config对比OS 数据库 ID与各 agent 的数据库 ID即可确认默认数据库是否正确继承到了所有组件。文件清单本目录六个示例的职责划分本目录下的示例文件按照数据库后端与媒体存储两个主题组织文件说明basic.py演示默认数据库继承与 SQLite 自动建表auto_provision_dbspostgres.py演示同步 / 异步 Postgres 适配器的生产级持久化选择surreal.py展示 SurrealDB 的 client、凭据、namespace、database 构造形态s3_media_storage.py将媒体字节外置到 S3数据库仅保留 MediaReferencegcs_media_storage.py将媒体字节外置到 GCS数据库仅保留 MediaReferencemedia_storage_delete.py通过媒体路由读回会话媒体并在删除会话时一并清理对象后端参考支持的存储适配器一览README 提供了一张完整的后端参考表涵盖导入路径、连接方式与所需服务。以下按类别整理并补充必要的使用说明后端导入连接示例所需服务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 与 Application Default CredentialsGCS JSONfrom agno.db.gcs_json import GcsJsonDbGcsJsonDb(bucket_namemy-bucket)GCS 与 Application Default CredentialsSingleStorefrom 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)仅用于 traces不是通用 AgentOS 持久化后端In-memoryfrom agno.db.in_memory import InMemoryDbInMemoryDb()无进程内存储、不持久化几条值得注意的边界说明均来自原文档Neon 与 Supabase使用 Postgres wire 协议因此应把它们的连接串直接传给PostgresDb无需独立适配器。异步 Postgres需导入AsyncPostgresDb并使用postgresqlpsycopg_async://...形式的 URL。ClickHouse只实现了 trace 与 span 数据面。会话、记忆、知识、评估与组件等业务数据应使用行存储如 Postgres。生产持久化示例同步与异步 Postgrespostgres.py 展示了如何在同一份代码中按环境变量切换同步与异步适配器from os import getenv from agno.agent import Agent from agno.db.postgres import AsyncPostgresDb, PostgresDb from agno.models.openai import OpenAIResponses from agno.os import AgentOS 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 postgres_agent Agent( idpostgres-agent, namePostgres Agent, modelOpenAIResponses(idgpt-5.5), instructionsAnswer questions concisely., markdownTrue, ) agent_os AgentOS( idpostgres-agent-os, descriptionAgentOS backed by sync or async Postgres., dbdb, agents[postgres_agent], ) app agent_os.get_app()同步适配器是默认且最简单的方式当数据库操作必须在异步应用中保持非阻塞时再通过AGENTOS_USE_ASYNC_POSTGREStrue切换到异步变体。示例中的连接串默认指向本地 pgvector 容器localhost:5532对应仓库脚本 scripts/run_pgvector.sh。SurrealDB以构造参数代替连接串surreal.py 展示了 SurrealDB 与众不同的接入方式——不使用 SQL 连接串而是显式传入 client、URL、凭据、namespace 与 database且所有值均可通过环境变量覆盖from os import getenv from agno.agent import Agent from agno.db.surrealdb import SurrealDb from agno.models.openai import OpenAIResponses from agno.os import AgentOS 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, )默认值ws://localhost:8000与root/root与仓库脚本 scripts/run_surrealdb.sh 中的本地启动配置保持一致。外部媒体存储数据库只存引用字节交给对象存储数据库负责存储会话文本而media_storage决定文件字节的去向。将后端传给AgentOS(media_storage...)后上传与生成的媒体文件会被写入对象存储会话行中只保留一个MediaReference而非 base64 内联数据。媒体随后通过GET /sessions/{session_id}/media/{storage_key}路由对外提供该路由定义见 libs/agno/agno/os/routers/media/media.py。后端导入连接示例所需服务Localfrom 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变体供异步应用使用。S3 媒体存储示例s3_media_storage.py 将媒体字节送往 S3并同时把数据库、媒体存储、文件生成工具绑定到同一 Agentimport os from agno.agent import Agent from agno.db.sqlite import SqliteDb from agno.media.storage.s3 import AsyncS3MediaStorage from agno.models.openai import OpenAIResponses from agno.os import AgentOS from agno.tools.file import FileGenerationTools from dotenv import load_dotenv load_dotenv() bucket os.getenv(AGNO_FILE_OUTPUT_S3_BUCKET) if not bucket: raise ValueError( AGNO_FILE_OUTPUT_S3_BUCKET must be set to the destination S3 bucket ) db SqliteDb(db_filetmp/agentos_media_storage.db) storage AsyncS3MediaStorage( bucketbucket, regionos.getenv(AWS_REGION), # 未设置时回退到 AWS_DEFAULT_REGION 或 ~/.aws/config prefixagno/agentos/files/, presigned_url_expiry3600, ) file_agent Agent( idmedia-storage-agent, nameMedia Storage Agent, modelOpenAIResponses(idgpt-5.5), dbdb, media_storagestorage, store_mediaTrue, add_history_to_contextTrue, tools[FileGenerationTools(allTrue)], descriptionAnalyze uploaded media and generate files stored in S3., instructions[ Read and answer questions about attached media and files., Use the appropriate file-generation tool when the user requests an output file., Always use a descriptive filename with the correct extension., Briefly explain what you read or generated., ], markdownTrue, ) agent_os AgentOS( idagentos-media-storage, nameAgentOS Media Storage, agents[file_agent], dbdb, media_storagestorage, ) app agent_os.get_app()示例通过store_mediaTrue开启媒体持久化AsyncS3MediaStorage还支持prefix对象前缀便于统一管理目录与presigned_url_expiry预签名 URL 有效期秒两个实用参数。运行时可附加图片或 CSV 提问再要求 Agent 生成 CSV观察文件落桶而数据库仅存引用。GCS 媒体存储示例gcs_media_storage.py 与 S3 版本结构完全对称仅更换存储后端与凭据方式db SqliteDb(db_filetmp/agentos_gcs_media_storage.db) storage AsyncGCSMediaStorage( bucketbucket, projectos.getenv(GCP_PROJECT), credentials_pathos.getenv(GOOGLE_APPLICATION_CREDENTIALS), prefixagno/agentos/files/, presigned_url_expiry3600, )GCS 的认证使用 Google Cloud Application Default Credentials也可通过GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON 文件。若未设置AGNO_FILE_OUTPUT_GCS_BUCKET示例会直接抛出ValueError提示。region 参数容易被忽略的保存成功但加载失败陷阱原文档特别提醒当桶不在默认区域时务必传入region。上传操作会自行找到正确的区域但媒体 URL 的签名中携带 region 信息——如果不传 region媒体会成功保存随后却因签名区域不匹配而加载失败。这是 S3/GCS 媒体存储最典型的隐蔽故障点。读取与删除会话媒体完整的生命周期管理media_storage_delete.py 演示了媒体从写入到删除的完整链路。默认情况下媒体对象的生命周期长于会话——run 上的引用是记录哪个对象属于哪个会话的唯一凭据因此删除时必须先读取行中的 storage key再清理底层对象。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, nameMedia Delete Agent, modelOpenAIResponses(idgpt-5.5), dbdb, media_storagestorage, store_mediaTrue, descriptionAnswer questions about attached files., markdownTrue, ) agent_os AgentOS( idagentos-media-delete, nameAgentOS Media Delete, agents[file_agent], dbdb, media_storagestorage, # 读与删路由都通过它解析 storage key ) app agent_os.get_app()从源码看libs/agno/agno/os/routers/session/session.py删除会话时传入delete_mediatrue服务端会先从会话行中收集所有关联的 storage key再调用adelete_media_keys批量清除对象该清理是 best-effort 的——行已删除存储失败不应导致整个删除请求失败。媒体 key 的收集还做了会话作用域限定另一会话的引用不属于本会话可删除的范围。运行方式与前置条件环境准备所有示例仅在 agent 运行并调用模型时需要OPENAI_API_KEYPostgres 示例需先启动本地服务./cookbook/scripts/run_pgvector.shSurrealDB 示例需安装agno[surrealdb]并运行./cookbook/scripts/run_surrealdb.shS3 相关示例需安装agno[s3]设置AGNO_FILE_OUTPUT_S3_BUCKET与 AWS 凭据GCS 示例需安装agno[gcs]设置AGNO_FILE_OUTPUT_GCS_BUCKET并使用 Google Cloud Application Default Credentials 认证。启动命令SQLite 默认数据库.venvs/demo/bin/python cookbook/05_agent_os/02_databases/basic.py同步 Postgres.venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.py异步 PostgresAGENTOS_USE_ASYNC_POSTGREStrue \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.pySurrealDB.venvs/demo/bin/python cookbook/05_agent_os/02_databases/surreal.pyS3 媒体存储AGNO_FILE_OUTPUT_S3_BUCKETmy-bucket \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/s3_media_storage.pyGCS 媒体存储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 端口。运行时 API 验证与数据库迁移服务启动后可以按如下顺序做端到端验证以媒体删除示例为例向一次 run 附加文件GET /sessions/{session_id}查看会话中的MediaReferenceGET /sessions/{session_id}/media/{storage_key}流式读回媒体DELETE /sessions/{session_id}?delete_mediatrue同时删除行记录与底层对象。数据库迁移方面AgentOS 暴露了迁移 API实现见 libs/agno/agno/os/routers/database.py。先从GET /config读取该服务的数据库 ID然后触发迁移curl -X POST http://localhost:7777/databases/db-id/migrate如需迁移到指定 schema 版本在 URL 后追加?target_versionversion即可。从源码可以看出迁移管理器会根据目标版本与当前版本的高低自动选择升级up或降级down远程数据库RemoteDb会被拒绝迁移——它归属另一个 AgentOS 实例应由其所有者执行迁移。小结AgentOS 的持久化架构将会话数据与媒体字节清晰地分层db决定结构化数据的落点本地开发用 SQLite生产用 Postgresmedia_storage决定文件的去向S3/GCS 等对象存储MediaReference则作为二者之间的桥梁。配合auto_provision_dbs自动建表与/databases/{db_id}/migrate版本化迁移开发者可以从本地 SQLite 无缝过渡到生产级 Postgres同时将媒体负载安全地卸载到对象存储。相关示例与测试可直接在 cookbook/05_agent_os/02_databases 目录下运行验证完整数据库适配器实现位于 libs/agno/agno/db媒体存储实现位于 libs/agno/agno/media/storage。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agno AgentOS 数据库与媒体存储配置指南：从 SQLite 到生产级 Postgres 与 S3/GCS
agno AgentOS 数据库与媒体存储配置指南从 SQLite 到生产级 Postgres 与 S3/GCS【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技术指南围绕 agno AgentOS 的持久化配置展开核心讲解如何通过AgentOS(db...)注入默认数据库、通过AgentOS(media_storage...)将媒体文件字节外置到对象存储以及如何启动服务、执行数据库迁移与删除会话媒体。读完本篇你将掌握 AgentOS 默认数据库继承机制、SQLite/Postgres/SurrealDB 等十余种存储后端的接入方式、外部媒体存储的完整读写与删除链路以及生产环境下的 schema 迁移命令。文中所有配置与命令均可在当前仓库的 cookbook/05_agent_os/02_databases 目录中直接运行验证。AgentOS 数据库设计一次注入全局继承AgentOS 的持久化设计遵循默认值 组件级覆盖原则。将数据库传给AgentOS(db...)后该数据库会成为所有未显式指定自身数据库的 agent、team 和 workflow 的默认存储后端任何组件级db配置始终优先于默认值。这一行为在示例 basic.py 中有直接体现database_agent在构造时刻意省略db参数由AgentOS将注入的SqliteDb自动分配给它。from agno.agent import Agent from agno.db.sqlite import SqliteDb from agno.models.openai import OpenAIResponses from agno.os import AgentOS db SqliteDb( idagent-os-default-db, db_filetmp/databases.db, ) # 该 agent 故意不设置 dbAgentOS 会注入默认数据库 database_agent Agent( iddatabase-agent, nameDatabase Agent, modelOpenAIResponses(idgpt-5.5), instructionsAnswer questions concisely., markdownTrue, ) agent_os AgentOS( iddatabase-basics-os, descriptionAgentOS default-database inheritance with SQLite., dbdb, agents[database_agent], auto_provision_dbsTrue, ) app agent_os.get_app()从源码看auto_provision_dbs是AgentOS构造函数的显式参数默认值为True见 libs/agno/agno/os/app.py。当服务启动时若该参数为真FastAPI 的 lifespan 钩子会依次调用_initialize_sync_databases()与_initialize_async_databases()在事件循环中创建所需的数据表只有当你使用外部迁移流程接管 schema 管理时才应将其关闭。asynccontextmanager async def db_lifespan(app: FastAPI, agent_os: AgentOS): Initializes databases in the event loop and closes them on shutdown. if agent_os.auto_provision_dbs: agent_os._initialize_sync_databases() await agent_os._initialize_async_databases()一个实用的验证技巧服务启动后访问http://localhost:7777/config对比OS 数据库 ID与各 agent 的数据库 ID即可确认默认数据库是否正确继承到了所有组件。文件清单本目录六个示例的职责划分本目录下的示例文件按照数据库后端与媒体存储两个主题组织文件说明basic.py演示默认数据库继承与 SQLite 自动建表auto_provision_dbspostgres.py演示同步 / 异步 Postgres 适配器的生产级持久化选择surreal.py展示 SurrealDB 的 client、凭据、namespace、database 构造形态s3_media_storage.py将媒体字节外置到 S3数据库仅保留 MediaReferencegcs_media_storage.py将媒体字节外置到 GCS数据库仅保留 MediaReferencemedia_storage_delete.py通过媒体路由读回会话媒体并在删除会话时一并清理对象后端参考支持的存储适配器一览README 提供了一张完整的后端参考表涵盖导入路径、连接方式与所需服务。以下按类别整理并补充必要的使用说明后端导入连接示例所需服务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 与 Application Default CredentialsGCS JSONfrom agno.db.gcs_json import GcsJsonDbGcsJsonDb(bucket_namemy-bucket)GCS 与 Application Default CredentialsSingleStorefrom 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)仅用于 traces不是通用 AgentOS 持久化后端In-memoryfrom agno.db.in_memory import InMemoryDbInMemoryDb()无进程内存储、不持久化几条值得注意的边界说明均来自原文档Neon 与 Supabase使用 Postgres wire 协议因此应把它们的连接串直接传给PostgresDb无需独立适配器。异步 Postgres需导入AsyncPostgresDb并使用postgresqlpsycopg_async://...形式的 URL。ClickHouse只实现了 trace 与 span 数据面。会话、记忆、知识、评估与组件等业务数据应使用行存储如 Postgres。生产持久化示例同步与异步 Postgrespostgres.py 展示了如何在同一份代码中按环境变量切换同步与异步适配器from os import getenv from agno.agent import Agent from agno.db.postgres import AsyncPostgresDb, PostgresDb from agno.models.openai import OpenAIResponses from agno.os import AgentOS 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 postgres_agent Agent( idpostgres-agent, namePostgres Agent, modelOpenAIResponses(idgpt-5.5), instructionsAnswer questions concisely., markdownTrue, ) agent_os AgentOS( idpostgres-agent-os, descriptionAgentOS backed by sync or async Postgres., dbdb, agents[postgres_agent], ) app agent_os.get_app()同步适配器是默认且最简单的方式当数据库操作必须在异步应用中保持非阻塞时再通过AGENTOS_USE_ASYNC_POSTGREStrue切换到异步变体。示例中的连接串默认指向本地 pgvector 容器localhost:5532对应仓库脚本 scripts/run_pgvector.sh。SurrealDB以构造参数代替连接串surreal.py 展示了 SurrealDB 与众不同的接入方式——不使用 SQL 连接串而是显式传入 client、URL、凭据、namespace 与 database且所有值均可通过环境变量覆盖from os import getenv from agno.agent import Agent from agno.db.surrealdb import SurrealDb from agno.models.openai import OpenAIResponses from agno.os import AgentOS 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, )默认值ws://localhost:8000与root/root与仓库脚本 scripts/run_surrealdb.sh 中的本地启动配置保持一致。外部媒体存储数据库只存引用字节交给对象存储数据库负责存储会话文本而media_storage决定文件字节的去向。将后端传给AgentOS(media_storage...)后上传与生成的媒体文件会被写入对象存储会话行中只保留一个MediaReference而非 base64 内联数据。媒体随后通过GET /sessions/{session_id}/media/{storage_key}路由对外提供该路由定义见 libs/agno/agno/os/routers/media/media.py。后端导入连接示例所需服务Localfrom 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变体供异步应用使用。S3 媒体存储示例s3_media_storage.py 将媒体字节送往 S3并同时把数据库、媒体存储、文件生成工具绑定到同一 Agentimport os from agno.agent import Agent from agno.db.sqlite import SqliteDb from agno.media.storage.s3 import AsyncS3MediaStorage from agno.models.openai import OpenAIResponses from agno.os import AgentOS from agno.tools.file import FileGenerationTools from dotenv import load_dotenv load_dotenv() bucket os.getenv(AGNO_FILE_OUTPUT_S3_BUCKET) if not bucket: raise ValueError( AGNO_FILE_OUTPUT_S3_BUCKET must be set to the destination S3 bucket ) db SqliteDb(db_filetmp/agentos_media_storage.db) storage AsyncS3MediaStorage( bucketbucket, regionos.getenv(AWS_REGION), # 未设置时回退到 AWS_DEFAULT_REGION 或 ~/.aws/config prefixagno/agentos/files/, presigned_url_expiry3600, ) file_agent Agent( idmedia-storage-agent, nameMedia Storage Agent, modelOpenAIResponses(idgpt-5.5), dbdb, media_storagestorage, store_mediaTrue, add_history_to_contextTrue, tools[FileGenerationTools(allTrue)], descriptionAnalyze uploaded media and generate files stored in S3., instructions[ Read and answer questions about attached media and files., Use the appropriate file-generation tool when the user requests an output file., Always use a descriptive filename with the correct extension., Briefly explain what you read or generated., ], markdownTrue, ) agent_os AgentOS( idagentos-media-storage, nameAgentOS Media Storage, agents[file_agent], dbdb, media_storagestorage, ) app agent_os.get_app()示例通过store_mediaTrue开启媒体持久化AsyncS3MediaStorage还支持prefix对象前缀便于统一管理目录与presigned_url_expiry预签名 URL 有效期秒两个实用参数。运行时可附加图片或 CSV 提问再要求 Agent 生成 CSV观察文件落桶而数据库仅存引用。GCS 媒体存储示例gcs_media_storage.py 与 S3 版本结构完全对称仅更换存储后端与凭据方式db SqliteDb(db_filetmp/agentos_gcs_media_storage.db) storage AsyncGCSMediaStorage( bucketbucket, projectos.getenv(GCP_PROJECT), credentials_pathos.getenv(GOOGLE_APPLICATION_CREDENTIALS), prefixagno/agentos/files/, presigned_url_expiry3600, )GCS 的认证使用 Google Cloud Application Default Credentials也可通过GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON 文件。若未设置AGNO_FILE_OUTPUT_GCS_BUCKET示例会直接抛出ValueError提示。region 参数容易被忽略的保存成功但加载失败陷阱原文档特别提醒当桶不在默认区域时务必传入region。上传操作会自行找到正确的区域但媒体 URL 的签名中携带 region 信息——如果不传 region媒体会成功保存随后却因签名区域不匹配而加载失败。这是 S3/GCS 媒体存储最典型的隐蔽故障点。读取与删除会话媒体完整的生命周期管理media_storage_delete.py 演示了媒体从写入到删除的完整链路。默认情况下媒体对象的生命周期长于会话——run 上的引用是记录哪个对象属于哪个会话的唯一凭据因此删除时必须先读取行中的 storage key再清理底层对象。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, nameMedia Delete Agent, modelOpenAIResponses(idgpt-5.5), dbdb, media_storagestorage, store_mediaTrue, descriptionAnswer questions about attached files., markdownTrue, ) agent_os AgentOS( idagentos-media-delete, nameAgentOS Media Delete, agents[file_agent], dbdb, media_storagestorage, # 读与删路由都通过它解析 storage key ) app agent_os.get_app()从源码看libs/agno/agno/os/routers/session/session.py删除会话时传入delete_mediatrue服务端会先从会话行中收集所有关联的 storage key再调用adelete_media_keys批量清除对象该清理是 best-effort 的——行已删除存储失败不应导致整个删除请求失败。媒体 key 的收集还做了会话作用域限定另一会话的引用不属于本会话可删除的范围。运行方式与前置条件环境准备所有示例仅在 agent 运行并调用模型时需要OPENAI_API_KEYPostgres 示例需先启动本地服务./cookbook/scripts/run_pgvector.shSurrealDB 示例需安装agno[surrealdb]并运行./cookbook/scripts/run_surrealdb.shS3 相关示例需安装agno[s3]设置AGNO_FILE_OUTPUT_S3_BUCKET与 AWS 凭据GCS 示例需安装agno[gcs]设置AGNO_FILE_OUTPUT_GCS_BUCKET并使用 Google Cloud Application Default Credentials 认证。启动命令SQLite 默认数据库.venvs/demo/bin/python cookbook/05_agent_os/02_databases/basic.py同步 Postgres.venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.py异步 PostgresAGENTOS_USE_ASYNC_POSTGREStrue \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/postgres.pySurrealDB.venvs/demo/bin/python cookbook/05_agent_os/02_databases/surreal.pyS3 媒体存储AGNO_FILE_OUTPUT_S3_BUCKETmy-bucket \ .venvs/demo/bin/python cookbook/05_agent_os/02_databases/s3_media_storage.pyGCS 媒体存储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 端口。运行时 API 验证与数据库迁移服务启动后可以按如下顺序做端到端验证以媒体删除示例为例向一次 run 附加文件GET /sessions/{session_id}查看会话中的MediaReferenceGET /sessions/{session_id}/media/{storage_key}流式读回媒体DELETE /sessions/{session_id}?delete_mediatrue同时删除行记录与底层对象。数据库迁移方面AgentOS 暴露了迁移 API实现见 libs/agno/agno/os/routers/database.py。先从GET /config读取该服务的数据库 ID然后触发迁移curl -X POST http://localhost:7777/databases/db-id/migrate如需迁移到指定 schema 版本在 URL 后追加?target_versionversion即可。从源码可以看出迁移管理器会根据目标版本与当前版本的高低自动选择升级up或降级down远程数据库RemoteDb会被拒绝迁移——它归属另一个 AgentOS 实例应由其所有者执行迁移。小结AgentOS 的持久化架构将会话数据与媒体字节清晰地分层db决定结构化数据的落点本地开发用 SQLite生产用 Postgresmedia_storage决定文件的去向S3/GCS 等对象存储MediaReference则作为二者之间的桥梁。配合auto_provision_dbs自动建表与/databases/{db_id}/migrate版本化迁移开发者可以从本地 SQLite 无缝过渡到生产级 Postgres同时将媒体负载安全地卸载到对象存储。相关示例与测试可直接在 cookbook/05_agent_os/02_databases 目录下运行验证完整数据库适配器实现位于 libs/agno/agno/db媒体存储实现位于 libs/agno/agno/media/storage。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考