发布时间2026年8月25日版本v3.0.0 Latest定位重大破坏性版本所有 2.x 用户在将 v3.0 投入生产流量前必须完成数据库迁移。agno v3.0.0 正式发布。这是一次覆盖 Agent、Team、Workflow、AgentOS、数据库、工具、知识库、向量数据库、调度器、评测、模型与学习系统的大版本升级。本次更新的核心并不只是增加功能而是对运行记录存储、后台任务执行、用户隔离、Studio 治理、工具调用模式以及数据库迁移流程进行了系统级重构。尤其需要注意的是v3.0.0 是破坏性版本。数据库必须先迁移之后才能让 v3.0 服务正式承接流量。对于正在使用 2.x 的项目升级前应优先阅读 v3 迁移指南、数据库迁移说明以及完整变更日志并严格验证数据迁移结果后再考虑清理旧字段。一、升级前最重要的结论必须先做数据库迁移v3.0.0 中运行记录不再继续以 JSON Blob 的形式保存在 sessions 表中而是被拆分到独立的agno_runs表。过去Session 记录中携带运行数据在运行次数增多时会产生明显的写入放大问题。v3.0.0 将每一次 Run 独立为一行数据从架构层面改变了运行数据的存储方式。升级流程必须遵循以下原则在 v3.0 正式承接服务流量前执行迁移。迁移后验证 Runs 数据已经正确写入新表。确认无误后才可以选择性清理旧的 Runs 字段或列。清理旧字段属于破坏性操作必须显式指定forceTrue。未迁移的旧数据库仍可读取系统会合并新 Runs 表与旧 Blob 中的数据但不应长期依赖这一兼容模式。数据库陈旧或迁移状态不正确时系统会抛出明确的类型化错误而不是继续静默运行。迁移示例如下importasynciofromagno.db.migrations.managerimportMigrationManager# 第一步在 v3.0 服务流量进入前执行迁移asyncio.run(MigrationManager(db).up())# 第二步确认运行记录已经落到新表中再进行任何清理assertlen(db.get_runs(limit5))0,Migration copied nothing - do NOT clean up# 第三步可选且具有破坏性回收旧的运行记录 Blob 列db.cleanup_legacy_runs_column(forceTrue)# SQL 适配器# 文档数据库或 KV 适配器使用# db.cleanup_legacy_runs_field(forceTrue)在 AgentOS 中可以通过以下接口执行全部数据库迁移POST /databases/all/migrate需要强调的是迁移会保留旧的 runs 字段作为备份。只有在确认新表中的运行记录完整可用后才应执行清理操作。二、核心数据库变革Runs 拆分为独立表写入复杂度从 O(N²) 降至 O(N)v3.0.0 最关键的数据库调整是将 Run 从 Session 中剥离出来。每个 Run 将在agno_runs表中以独立行的方式保存并且拥有真实的结构化字段包括session_idrun_typeagent_idteam_idworkflow_iduser_idparent_run_idstatusrun_indexJSON payload这一变化带来了几个直接收益Session 的写入放大从 O(N²) 降为 O(N)。运行记录不再不断膨胀 Session 数据。规避了 DynamoDB、Firestore 等存储系统的单条数据大小上限问题。Run 成为可直接查询、更新、删除的实体。Session 在读取时会重新关联对应 Runs因此既有的读取接口保持兼容。以下接口的使用方式保持不变session.get_messages()get_chat_history()db.get_session()AgentOS Session 路由新增的直接 Run 操作接口包括同步与异步版本db.get_run()db.get_runs(session_id...,status...,limit...,page...)db.upsert_run()db.delete_run()db.delete_runs()此外Session 查询接口也增加了新能力db.get_session(runs_limitN)db.get_sessions(include_runsFalse)迁移管理器提供一行式迁移能力MigrationManager(db).up()该迁移会创建 Runs 存储并复制旧数据具备以下特点非破坏性。幂等执行。支持 12 种同步后端。支持 4 种异步后端。未迁移数据库仍可工作。读取时自动合并新 Runs 表和旧 Blob 数据。每个数据库适配器均会追踪 Schema 版本。v3.0.0 还新增了三个自动创建的数据表agno_runsagno_jobsagno_tool_results其中agno_runs用于独立存储运行记录agno_jobs用于持久化后台任务队列agno_tool_results用于工具结果卸载后的索引。三、工具结果卸载超长工具输出不再撑爆上下文与数据库Agent 在调用工具时工具返回结果可能非常庞大例如搜索结果、数据库查询结果、文件内容、网页抓取内容等。v3.0.0 提供了工具结果卸载能力。当配置以下选项后Agent(offload_tool_resultsTrue)或在 Team 中启用相应配置后任何超过 16,000 个字符的工具结果都会被写入 AgentFS而不再将完整文本直接放入消息记录。消息中只会留下简短的信封信息包括预览内容数据大小result_idAgent 可以通过以下工具按需读取完整结果read_resultsearch_result异步版本的读取与搜索接口这一机制的重要特点是工具结果写入路径不会触发模型调用。超长结果不再直接占用消息历史。有助于减少上下文膨胀。有助于降低大结果持久化的负担。需要时可以通过结果标识再次读取或搜索。开发者还可以使用ResultStore调整卸载策略ResultStore(threshold_chars...,ttl_seconds...)其中threshold_chars用于配置结果卸载的字符阈值。ttl_seconds用于配置结果保存的存活时间。默认情况下超过 16,000 字符的结果会触发卸载。四、媒体卸载图片、音频、视频、文件不再以 Base64 大量写入数据库除工具结果外v3.0.0 同样处理了媒体内容持久化时的膨胀问题。通过为 Agent、Team 或 Workflow 配置媒体存储media_storageS3MediaStorage(bucket...)系统可以在持久化前将图片、音频、视频与文件上传至以下位置本地磁盘S3GCS数据库记录中不再保存完整的 Base64 媒体内容而是保留体积更小的MediaReference。官方示例中一张约 113 KB 的 JPEG 图片如果以 Base64 形式保存字符长度约为 151,000改为媒体引用后记录可降至约 2,897 个字符。这一能力具有以下特征不需要数据库 Schema 变更。支持 Agent、Team、Workflow。可将媒体实际内容与业务数据库行解耦。明显降低媒体消息对存储空间和传输负担的影响。五、CodeMode从宽工具 Schema 转向可编程 IPython Kernelv3.0.0 引入 CodeMode。传统工具调用模式中模型需要面对较宽的工具 Schema并在每一次工具调用后通过对话转录继续下一步推理。CodeMode 则采用不同方式CodeMode(tools[...])它会将大量工具定义替换为一个可编程的 IPython Kernel。该 Kernel 在同一个 Session 中持续存在模型可以编写 Python 代码并将工具作为可await的句柄进行调用。这样模型可以在代码中完成更复杂的组合操作例如保存变量。编写循环。构造辅助函数。组合多个工具的返回值。批量调用工具。基于中间变量继续计算。减少工具调用与对话转录之间的反复往返。CodeMode 的本质是让模型从单次、离散的工具参数调用转向可持续执行的编程式工具编排。六、全新工具与模型能力FinanceTools、AtomicMail、MiniMax 视频工具等v3.0.0 增加了多个新的工具与模型能力。1. FinanceTools新增统一金融工具包FinanceTools。它将金融能力整合为一个工具集并支持替换不同的数据提供方。2. AtomicMail Toolkit新增AtomicMailTools工具包。该工具包能够为 Agno Agent 提供专属电子邮件收件箱使 Agent 可以使用自己的邮箱能力。3. MiniMax 视频生成工具工具体系中加入 MiniMax 视频生成工具扩展了 Agent 在视频生成方向上的可调用能力。4. Toolkit 稳定 ID工具包现在拥有稳定 IDAgentOS 可以基于稳定标识引用工具而不是依赖不稳定的临时引用方式。七、模型更新默认模型变更与 SDK 兼容性调整v3.0.0 对多个模型提供方进行了调整。1. Cerebras 默认模型更新Cerebras 与 CerebrasOpenAI 的默认模型已更新为gpt-oss-120b旧默认值为llama-4-scout-17b-16e-instruct2. Gemini 默认模型更新Gemini 默认模型更新为3.7 Flash3. Groq 默认模型更新Groq 不再使用已废弃的llama-3.3-70b-versatile替换为openai/gpt-oss-120b4. OpenAI 参数类型扩大OpenAI 模型中的以下参数现在支持完整 API 值集合reasoning_effortreasoning_summaryservice_tierverbosity此次属于类型范围扩展不会导致既有调用中断。5. Claude 与新版 SDK 兼容Claude 模型完成 SDK 兼容性更新可以与 anthropic 1.0.0 配合使用。6. RampRouter 模型新增 Ramp Router 模型提供方支持 router.com。7. SuperGrok OAuth新增 SuperGrok 的设备码认证能力可通过 Device Code 完成 xAI 模型授权。八、AgentOS持久化后台执行正式落地AgentOS 在 v3.0.0 中加入了持久化后台执行能力。配置示例AgentOS(queueQueueConfig(durableTrue))开启后已接受的后台运行任务会以已提交的数据行形式保存即使发生以下情况任务仍可恢复进程崩溃。服务重启。应用部署。副本切换。任何副本都可以继续执行这些已持久化的任务。该机制包括以下能力有界并发控制。默认并发数为 32。可通过AGNO_BACKGROUND_MAX_CONCURRENCY调整。任务在排队时可以取消。支持Idempotency-Key去重。队列满时返回 429。Redis 是可选的协调组件但不是事实数据源。后台任务真实状态以数据库中的持久化记录为准。队列 REST 接口包括GET /queue/jobs GET /queue/jobs/{job_id} POST /queue/jobs/{job_id}/requeue GET /queue/stats同时也必须注意以下限制后台执行要求组件配置数据库。如果组件没有数据库后台请求会返回 400。外部框架 Agent例如 LangGraph、Claude、DSPy 等在backgroundtrue时会以内联流式方式执行。这类外部框架 Agent 不具备可恢复能力。九、Studio 3.0从直接可用转向受治理的组件目录Studio 3.0 引入治理式组件目录。在旧模式中创建组件后可能直接对外提供服务。v3.0.0 中使用create_*创建的组件会先处于DRAFT草稿状态不会立即为任何请求提供服务。组件必须经过发布操作publish_component发布后才会生效。Studio 3.0 还支持比较并交换保护。类型化 409 冲突错误。删除墓碑标记。归档。恢复。依赖关系跟踪。StudioTools对约 31 个工具统一返回机器可读信封结构{ok:true,status:...,data:{},error:{...},warnings:[]}这使调用方可以更稳定地处理成功状态、错误信息与警告信息。十、每用户隔离范围扩大不仅是 Sessionv3.0.0 将每用户隔离能力扩展到更多模块。除了 Session 外以下能力也支持用户隔离MetricsSchedulesEvalsKnowledgeComponentsEntity Memory17 种向量数据库指标将按用户、按天聚合。对于没有归属用户的组件与知识内容系统将其视为共享资源所有用户可以读取。管理员可以编辑。启用隔离后不会因为此前创建的无归属构建块而出现 404。这使系统可以在启用用户隔离后保持既有公共组件与知识资源的可访问性。十一、破坏性变更AgentOS 配置与接口调整以下调整会影响现有 AgentOS 项目。1. JWT 配置调整JWTMiddleware与authorization_config中的secret_key已删除。现在应使用verification_keys并且该参数是一个列表。2. 元数据路由调整以下接口行为发生变化GET /models已删除。模型数据迁移到GET /config的available_models中。GET /仅返回最小化落地响应。GET /info成为唯一无需认证的元数据接口。3. MCP Server 配置调整以下旧配置已删除AgentOS(enable_mcp_server...,mcp_config...)现在应传入单个mcp_server...十二、Agent 参数重命名与推理配置变化以下 Agent 参数发生重命名旧参数新参数enable_user_memoriesupdate_memory_on_runsearch_session_historysearch_past_sessionsnum_history_sessionsnum_past_sessions_to_searchnum_past_session_runsnum_past_session_runs_in_search此外reasoningTrue已被删除。现在需要显式指定原生推理模型reasoning_modelnative reasoning model继续运行接口也有变化continue_run acontinue_run其中的updated_tools已删除。现在应从暂停运行的输出中获取RunRequirement列表并将 requirements 传入。十三、Culture 功能移除改用 Knowledge 保存共享信息以下 Culture 相关能力已经移除enable_agentic_cultureadd_culture_to_contextCulturalKnowledgeculture 工具agno_culture表如果需要在用户之间共享信息应使用 Knowledge。十四、Team 与 Workflow 的构造方式调整Workflow 构造器现在只接受关键字参数。旧式位置参数构造方式不再适用应使用Workflow(name...,steps[...])Team 不受此项影响。以下方式仍可使用Team([agent_1,agent_2])但更推荐Team(members[agent_1,agent_2])十五、HITL 平铺参数移除统一迁移到 HumanReview在Step、Steps、Loop、Condition、Router中以下平铺式 HITL 参数已经移除requires_confirmationconfirmation_messageon_rejectrequires_user_inputuser_input_messageuser_input_schemarequires_output_reviewoutput_review_messagerequires_iteration_reviewiteration_review_messageon_errorhitl_max_retrieshitl_timeouton_timeout现在应使用fromagno.workflow.typesimportHumanReview并通过human_reviewHumanReview(...)进行配置。字段名称大多数保持不变但有两项重命名旧名称新名称hitl_max_retriesmax_retrieshitl_timeouttimeout十六、工具层破坏性变更汇总工具系统中有多项旧接口被删除或改名。1. MultiMCPTools 删除MultiMCPTools已删除同时allow_partial_failure也被删除。现在应对每一个 MCP Server 分别使用一个MCPTools。2. MCPToolbox 认证参数调整以下参数已删除auth_tokensauth_headers现在应使用auth_token_getters3. DuckDuckGoTools 方法重命名旧方法新方法duckduckgo_searchweb_searchduckduckgo_newssearch_news新的方法基于WebSearchTools构建。4. Google 平铺工具模块删除以下平铺模块已删除agno.tools.gmailgooglesheetsgooglecalendargoogle_mapsgoogle_drivegoogle_bigquery现在应从以下路径导入agno.tools.google.*5. Google 工具参数重命名旧参数新参数creds_pathcredentials_pathauth_portoauth_portSheets 中类似enable_read_sheet的命名也应改为直接使用裸方法名称。6. FileTools 调整FileTools.check_escape已移除。应使用Toolkit._check_path但LocalFileSystemTools.check_escape不受影响。7. SQLTools 调整以下开关参数已删除enable_list_tablesenable_describe_tableenable_run_sql_query现在应使用对应的裸方法名称。8. Seltz 调整max_documents改为max_results旧版 SDK 路径已删除要求使用seltz1.2.09. StudioTool 别名删除StudioTool别名已删除应改用StudioTools10. 其他工具与向量能力调整BrightData.get_screenshot中未使用的output_path已删除。PgVector.enable_prefix_matching已删除该能力属于无效辅助逻辑。十七、Knowledge 与向量数据库变更Knowledge API 发生调整。以下方法已删除Knowledge.add_contentadd_content_asyncadd_contents_async现在应使用insert()ainsert()ainsert_many()此外GDriveContextProvider已重命名为GoogleDriveContextProviderLanceDB 中use_tantivy已被删除或忽略。需要特别注意向量数据库迁移问题如果对一个 v3 之前创建的向量表使用user_id进行搜索系统会抛出ValueError并指向向量数据库迁移说明。系统不再返回空结果来掩盖表结构不兼容问题。十八、Scheduler 变更更新字段白名单与唯一键调整调度器的update_schedule现在采用严格白名单机制。只允许更新以下字段namedescriptionmethodendpointpayloadcron_exprtimezonetimeout_secondsmax_retriesretry_delay_secondsenablednext_run_atdisabled_reason传入任何其他字段都会抛出ValueError。以下类型的数据不再允许通过通用更新路径写入所有权信息。来源信息。锁状态。v3.0.0 的迁移中也会新增对应的来源字段。此外Schedules 的唯一键发生变化旧唯一键name新唯一键(user_id, name)如果同一个用户下存在重名 Schedule迁移将中止。因此升级前必须先完成重名调度任务的去重处理。十九、Evals 变更eval_id 全面改为 run_id评测系统中eval_id已改为run_id评测类不再携带eval_id每一次运行都拥有自己的run_id。以下调整需要同步处理store_result_in_file的参数从eval_id改为run_id。file_path_to_save_results模板中的{eval_id}不再支持。应使用{run_id}。POST /eval-runs返回数据库中实际保存的 ID即run_id。重复运行不再相互覆盖。二十、Models 与 Learning 的破坏性调整Mistral 的旧兼容层已移除。agno[mistral]现在要求mistralai2.0.0并且 Mistral 已重新包含在 models extra 中。指标模块也发生调整agno.models.metrics以及Metrics别名已删除。现在应使用fromagno.metricsimportRunMetrics模型错误分类接口Model.classify_error已删除。现在应使用ModelProviderError.classify(error)二十一、Entity Memory 用户隔离与别名清理在namespaceuser下Entity Memory 现在按用户隔离。其行键会嵌入user_id的摘要。v3.0.0 迁移会重新生成旧版本中对应的行键迁移函数为agno.learn.migrations.rekey_user_entity_learnings同时在该命名空间下以下方法必须使用关键字形式传入user_idEntityMemoryStore.deleteEntityMemoryStore.get例如user_id...以下 Learning 旧别名已删除旧别名新名称MemoriesConfigUserMemoryConfigMemoriesStoreUserMemoryStoreDecisionDecisionLog二十二、仍可使用但已弃用的能力v3.0.0 仍保留部分兼容能力但建议逐步完成迁移。1. knowledge_retriever旧写法knowledge_retriever(dependencies...)仍可以工作但推荐使用run_context如果 Retriever 的函数签名仍然包含dependencies系统会进入显式的向后兼容分支。如果run_context和dependencies同时出现则以run_context为准。2. Scopes 名称迁移以下 Scope 名称已改名旧名称新名称system:readconfig:readsystem:writeconfig:write旧名称仍作为别名有效已有 Token 也不会立即失效。3. RedisDB 重命名向量数据库中的RedisDB改名为RedisDbRedisVectorDb仍然继续导出用于与agno.db.redis存储适配器进行区分。二十三、分页行为收紧不再接受无边界页码查询v3.0.0 对分页参数进行了更严格的约束。以下情况将抛出ValueError使用page但未指定limit。page 1。旧版本中这些写法可能返回无边界结果或负向结果。v3.0.0 不再允许这类不明确的分页行为。二十四、类型化数据库错误迁移问题不再静默失败v3.0.0 新增类型化错误用于明确区分数据库版本与迁移问题MigrationRequiredErrorSchemaMismatchError这些错误会明确指示相应解决方式。在 AgentOS 中如果出现迁移要求错误JSON 响应体会携带{error_id:migration_required_error}这比旧版本中可能出现的静默异常、空数据、行为不一致更容易定位问题。二十五、完整升级检查清单在升级 agno v3.0.0 前建议逐项检查确认数据库已执行MigrationManager(db).up()。验证agno_runs中已经存在迁移后的运行记录。未验证前不清理旧的 runs Blob 字段。需要回收空间时使用forceTrue清理旧字段。检查 Schedule 是否存在同一用户下重名任务。检查所有Workflow是否改为关键字构造。检查 HITL 配置是否从平铺参数改为HumanReview(...)。检查 JWT 是否已从secret_key迁移到verification_keys。检查 AgentOS 的 MCP Server 是否改为单一mcp_server参数。检查 Agent 参数重命名。检查reasoningTrue是否改为显式reasoning_model。检查 Culture 相关功能是否已迁移到 Knowledge。检查 MultiMCPTools 是否拆分为多个 MCPTools。检查 Google、DuckDuckGo、SQLTools、FileTools 等工具调用名称。检查 Knowledge 写入接口是否改为insert、ainsert、ainsert_many。检查向量表是否已完成面向user_id的迁移。检查 Eval 中的eval_id是否全部改为run_id。检查 Mistral SDK 版本是否满足mistralai2.0.0。检查 Metrics 导入是否迁移到agno.metrics.RunMetrics。检查 Entity Memory 在用户命名空间下是否传递关键字user_id。检查分页调用是否同时提供合法的page与limit。如果使用后台任务确保 AgentOS 组件配置数据库。结语代码地址github.com/agno-agi/agnoagno v3.0.0 并非一次普通版本迭代而是一次围绕数据模型、执行模型、工具调用模型和平台治理模型的全面升级。其中最重要的变化是将 Runs 从 Session Blob 中拆出构建独立的agno_runs表同时引入持久化后台队列、超长工具结果卸载、媒体引用存储、CodeMode 编程式工具调用、Studio 草稿发布机制以及更广泛的用户隔离能力。对于生产环境而言升级的第一原则只有一句话先迁移数据库验证迁移结果再让 v3.0 正式承接流量。如果项目中使用了 AgentOS、Workflow HITL、MCP、Knowledge、向量数据库、Scheduler、Evals 或 Entity Memory则应逐项完成本文列出的 API 与配置迁移避免因破坏性变更导致运行异常。 
长河君 · 2026/8/27 9:42:08 · 阅读 1.2k agno v3.0.0发布：数据库迁移、AgentOS持久化队列、工具结果卸载与全量破坏性变更解读
发布时间2026年8月25日版本v3.0.0 Latest定位重大破坏性版本所有 2.x 用户在将 v3.0 投入生产流量前必须完成数据库迁移。agno v3.0.0 正式发布。这是一次覆盖 Agent、Team、Workflow、AgentOS、数据库、工具、知识库、向量数据库、调度器、评测、模型与学习系统的大版本升级。本次更新的核心并不只是增加功能而是对运行记录存储、后台任务执行、用户隔离、Studio 治理、工具调用模式以及数据库迁移流程进行了系统级重构。尤其需要注意的是v3.0.0 是破坏性版本。数据库必须先迁移之后才能让 v3.0 服务正式承接流量。对于正在使用 2.x 的项目升级前应优先阅读 v3 迁移指南、数据库迁移说明以及完整变更日志并严格验证数据迁移结果后再考虑清理旧字段。一、升级前最重要的结论必须先做数据库迁移v3.0.0 中运行记录不再继续以 JSON Blob 的形式保存在 sessions 表中而是被拆分到独立的agno_runs表。过去Session 记录中携带运行数据在运行次数增多时会产生明显的写入放大问题。v3.0.0 将每一次 Run 独立为一行数据从架构层面改变了运行数据的存储方式。升级流程必须遵循以下原则在 v3.0 正式承接服务流量前执行迁移。迁移后验证 Runs 数据已经正确写入新表。确认无误后才可以选择性清理旧的 Runs 字段或列。清理旧字段属于破坏性操作必须显式指定forceTrue。未迁移的旧数据库仍可读取系统会合并新 Runs 表与旧 Blob 中的数据但不应长期依赖这一兼容模式。数据库陈旧或迁移状态不正确时系统会抛出明确的类型化错误而不是继续静默运行。迁移示例如下importasynciofromagno.db.migrations.managerimportMigrationManager# 第一步在 v3.0 服务流量进入前执行迁移asyncio.run(MigrationManager(db).up())# 第二步确认运行记录已经落到新表中再进行任何清理assertlen(db.get_runs(limit5))0,Migration copied nothing - do NOT clean up# 第三步可选且具有破坏性回收旧的运行记录 Blob 列db.cleanup_legacy_runs_column(forceTrue)# SQL 适配器# 文档数据库或 KV 适配器使用# db.cleanup_legacy_runs_field(forceTrue)在 AgentOS 中可以通过以下接口执行全部数据库迁移POST /databases/all/migrate需要强调的是迁移会保留旧的 runs 字段作为备份。只有在确认新表中的运行记录完整可用后才应执行清理操作。二、核心数据库变革Runs 拆分为独立表写入复杂度从 O(N²) 降至 O(N)v3.0.0 最关键的数据库调整是将 Run 从 Session 中剥离出来。每个 Run 将在agno_runs表中以独立行的方式保存并且拥有真实的结构化字段包括session_idrun_typeagent_idteam_idworkflow_iduser_idparent_run_idstatusrun_indexJSON payload这一变化带来了几个直接收益Session 的写入放大从 O(N²) 降为 O(N)。运行记录不再不断膨胀 Session 数据。规避了 DynamoDB、Firestore 等存储系统的单条数据大小上限问题。Run 成为可直接查询、更新、删除的实体。Session 在读取时会重新关联对应 Runs因此既有的读取接口保持兼容。以下接口的使用方式保持不变session.get_messages()get_chat_history()db.get_session()AgentOS Session 路由新增的直接 Run 操作接口包括同步与异步版本db.get_run()db.get_runs(session_id...,status...,limit...,page...)db.upsert_run()db.delete_run()db.delete_runs()此外Session 查询接口也增加了新能力db.get_session(runs_limitN)db.get_sessions(include_runsFalse)迁移管理器提供一行式迁移能力MigrationManager(db).up()该迁移会创建 Runs 存储并复制旧数据具备以下特点非破坏性。幂等执行。支持 12 种同步后端。支持 4 种异步后端。未迁移数据库仍可工作。读取时自动合并新 Runs 表和旧 Blob 数据。每个数据库适配器均会追踪 Schema 版本。v3.0.0 还新增了三个自动创建的数据表agno_runsagno_jobsagno_tool_results其中agno_runs用于独立存储运行记录agno_jobs用于持久化后台任务队列agno_tool_results用于工具结果卸载后的索引。三、工具结果卸载超长工具输出不再撑爆上下文与数据库Agent 在调用工具时工具返回结果可能非常庞大例如搜索结果、数据库查询结果、文件内容、网页抓取内容等。v3.0.0 提供了工具结果卸载能力。当配置以下选项后Agent(offload_tool_resultsTrue)或在 Team 中启用相应配置后任何超过 16,000 个字符的工具结果都会被写入 AgentFS而不再将完整文本直接放入消息记录。消息中只会留下简短的信封信息包括预览内容数据大小result_idAgent 可以通过以下工具按需读取完整结果read_resultsearch_result异步版本的读取与搜索接口这一机制的重要特点是工具结果写入路径不会触发模型调用。超长结果不再直接占用消息历史。有助于减少上下文膨胀。有助于降低大结果持久化的负担。需要时可以通过结果标识再次读取或搜索。开发者还可以使用ResultStore调整卸载策略ResultStore(threshold_chars...,ttl_seconds...)其中threshold_chars用于配置结果卸载的字符阈值。ttl_seconds用于配置结果保存的存活时间。默认情况下超过 16,000 字符的结果会触发卸载。四、媒体卸载图片、音频、视频、文件不再以 Base64 大量写入数据库除工具结果外v3.0.0 同样处理了媒体内容持久化时的膨胀问题。通过为 Agent、Team 或 Workflow 配置媒体存储media_storageS3MediaStorage(bucket...)系统可以在持久化前将图片、音频、视频与文件上传至以下位置本地磁盘S3GCS数据库记录中不再保存完整的 Base64 媒体内容而是保留体积更小的MediaReference。官方示例中一张约 113 KB 的 JPEG 图片如果以 Base64 形式保存字符长度约为 151,000改为媒体引用后记录可降至约 2,897 个字符。这一能力具有以下特征不需要数据库 Schema 变更。支持 Agent、Team、Workflow。可将媒体实际内容与业务数据库行解耦。明显降低媒体消息对存储空间和传输负担的影响。五、CodeMode从宽工具 Schema 转向可编程 IPython Kernelv3.0.0 引入 CodeMode。传统工具调用模式中模型需要面对较宽的工具 Schema并在每一次工具调用后通过对话转录继续下一步推理。CodeMode 则采用不同方式CodeMode(tools[...])它会将大量工具定义替换为一个可编程的 IPython Kernel。该 Kernel 在同一个 Session 中持续存在模型可以编写 Python 代码并将工具作为可await的句柄进行调用。这样模型可以在代码中完成更复杂的组合操作例如保存变量。编写循环。构造辅助函数。组合多个工具的返回值。批量调用工具。基于中间变量继续计算。减少工具调用与对话转录之间的反复往返。CodeMode 的本质是让模型从单次、离散的工具参数调用转向可持续执行的编程式工具编排。六、全新工具与模型能力FinanceTools、AtomicMail、MiniMax 视频工具等v3.0.0 增加了多个新的工具与模型能力。1. FinanceTools新增统一金融工具包FinanceTools。它将金融能力整合为一个工具集并支持替换不同的数据提供方。2. AtomicMail Toolkit新增AtomicMailTools工具包。该工具包能够为 Agno Agent 提供专属电子邮件收件箱使 Agent 可以使用自己的邮箱能力。3. MiniMax 视频生成工具工具体系中加入 MiniMax 视频生成工具扩展了 Agent 在视频生成方向上的可调用能力。4. Toolkit 稳定 ID工具包现在拥有稳定 IDAgentOS 可以基于稳定标识引用工具而不是依赖不稳定的临时引用方式。七、模型更新默认模型变更与 SDK 兼容性调整v3.0.0 对多个模型提供方进行了调整。1. Cerebras 默认模型更新Cerebras 与 CerebrasOpenAI 的默认模型已更新为gpt-oss-120b旧默认值为llama-4-scout-17b-16e-instruct2. Gemini 默认模型更新Gemini 默认模型更新为3.7 Flash3. Groq 默认模型更新Groq 不再使用已废弃的llama-3.3-70b-versatile替换为openai/gpt-oss-120b4. OpenAI 参数类型扩大OpenAI 模型中的以下参数现在支持完整 API 值集合reasoning_effortreasoning_summaryservice_tierverbosity此次属于类型范围扩展不会导致既有调用中断。5. Claude 与新版 SDK 兼容Claude 模型完成 SDK 兼容性更新可以与 anthropic 1.0.0 配合使用。6. RampRouter 模型新增 Ramp Router 模型提供方支持 router.com。7. SuperGrok OAuth新增 SuperGrok 的设备码认证能力可通过 Device Code 完成 xAI 模型授权。八、AgentOS持久化后台执行正式落地AgentOS 在 v3.0.0 中加入了持久化后台执行能力。配置示例AgentOS(queueQueueConfig(durableTrue))开启后已接受的后台运行任务会以已提交的数据行形式保存即使发生以下情况任务仍可恢复进程崩溃。服务重启。应用部署。副本切换。任何副本都可以继续执行这些已持久化的任务。该机制包括以下能力有界并发控制。默认并发数为 32。可通过AGNO_BACKGROUND_MAX_CONCURRENCY调整。任务在排队时可以取消。支持Idempotency-Key去重。队列满时返回 429。Redis 是可选的协调组件但不是事实数据源。后台任务真实状态以数据库中的持久化记录为准。队列 REST 接口包括GET /queue/jobs GET /queue/jobs/{job_id} POST /queue/jobs/{job_id}/requeue GET /queue/stats同时也必须注意以下限制后台执行要求组件配置数据库。如果组件没有数据库后台请求会返回 400。外部框架 Agent例如 LangGraph、Claude、DSPy 等在backgroundtrue时会以内联流式方式执行。这类外部框架 Agent 不具备可恢复能力。九、Studio 3.0从直接可用转向受治理的组件目录Studio 3.0 引入治理式组件目录。在旧模式中创建组件后可能直接对外提供服务。v3.0.0 中使用create_*创建的组件会先处于DRAFT草稿状态不会立即为任何请求提供服务。组件必须经过发布操作publish_component发布后才会生效。Studio 3.0 还支持比较并交换保护。类型化 409 冲突错误。删除墓碑标记。归档。恢复。依赖关系跟踪。StudioTools对约 31 个工具统一返回机器可读信封结构{ok:true,status:...,data:{},error:{...},warnings:[]}这使调用方可以更稳定地处理成功状态、错误信息与警告信息。十、每用户隔离范围扩大不仅是 Sessionv3.0.0 将每用户隔离能力扩展到更多模块。除了 Session 外以下能力也支持用户隔离MetricsSchedulesEvalsKnowledgeComponentsEntity Memory17 种向量数据库指标将按用户、按天聚合。对于没有归属用户的组件与知识内容系统将其视为共享资源所有用户可以读取。管理员可以编辑。启用隔离后不会因为此前创建的无归属构建块而出现 404。这使系统可以在启用用户隔离后保持既有公共组件与知识资源的可访问性。十一、破坏性变更AgentOS 配置与接口调整以下调整会影响现有 AgentOS 项目。1. JWT 配置调整JWTMiddleware与authorization_config中的secret_key已删除。现在应使用verification_keys并且该参数是一个列表。2. 元数据路由调整以下接口行为发生变化GET /models已删除。模型数据迁移到GET /config的available_models中。GET /仅返回最小化落地响应。GET /info成为唯一无需认证的元数据接口。3. MCP Server 配置调整以下旧配置已删除AgentOS(enable_mcp_server...,mcp_config...)现在应传入单个mcp_server...十二、Agent 参数重命名与推理配置变化以下 Agent 参数发生重命名旧参数新参数enable_user_memoriesupdate_memory_on_runsearch_session_historysearch_past_sessionsnum_history_sessionsnum_past_sessions_to_searchnum_past_session_runsnum_past_session_runs_in_search此外reasoningTrue已被删除。现在需要显式指定原生推理模型reasoning_modelnative reasoning model继续运行接口也有变化continue_run acontinue_run其中的updated_tools已删除。现在应从暂停运行的输出中获取RunRequirement列表并将 requirements 传入。十三、Culture 功能移除改用 Knowledge 保存共享信息以下 Culture 相关能力已经移除enable_agentic_cultureadd_culture_to_contextCulturalKnowledgeculture 工具agno_culture表如果需要在用户之间共享信息应使用 Knowledge。十四、Team 与 Workflow 的构造方式调整Workflow 构造器现在只接受关键字参数。旧式位置参数构造方式不再适用应使用Workflow(name...,steps[...])Team 不受此项影响。以下方式仍可使用Team([agent_1,agent_2])但更推荐Team(members[agent_1,agent_2])十五、HITL 平铺参数移除统一迁移到 HumanReview在Step、Steps、Loop、Condition、Router中以下平铺式 HITL 参数已经移除requires_confirmationconfirmation_messageon_rejectrequires_user_inputuser_input_messageuser_input_schemarequires_output_reviewoutput_review_messagerequires_iteration_reviewiteration_review_messageon_errorhitl_max_retrieshitl_timeouton_timeout现在应使用fromagno.workflow.typesimportHumanReview并通过human_reviewHumanReview(...)进行配置。字段名称大多数保持不变但有两项重命名旧名称新名称hitl_max_retriesmax_retrieshitl_timeouttimeout十六、工具层破坏性变更汇总工具系统中有多项旧接口被删除或改名。1. MultiMCPTools 删除MultiMCPTools已删除同时allow_partial_failure也被删除。现在应对每一个 MCP Server 分别使用一个MCPTools。2. MCPToolbox 认证参数调整以下参数已删除auth_tokensauth_headers现在应使用auth_token_getters3. DuckDuckGoTools 方法重命名旧方法新方法duckduckgo_searchweb_searchduckduckgo_newssearch_news新的方法基于WebSearchTools构建。4. Google 平铺工具模块删除以下平铺模块已删除agno.tools.gmailgooglesheetsgooglecalendargoogle_mapsgoogle_drivegoogle_bigquery现在应从以下路径导入agno.tools.google.*5. Google 工具参数重命名旧参数新参数creds_pathcredentials_pathauth_portoauth_portSheets 中类似enable_read_sheet的命名也应改为直接使用裸方法名称。6. FileTools 调整FileTools.check_escape已移除。应使用Toolkit._check_path但LocalFileSystemTools.check_escape不受影响。7. SQLTools 调整以下开关参数已删除enable_list_tablesenable_describe_tableenable_run_sql_query现在应使用对应的裸方法名称。8. Seltz 调整max_documents改为max_results旧版 SDK 路径已删除要求使用seltz1.2.09. StudioTool 别名删除StudioTool别名已删除应改用StudioTools10. 其他工具与向量能力调整BrightData.get_screenshot中未使用的output_path已删除。PgVector.enable_prefix_matching已删除该能力属于无效辅助逻辑。十七、Knowledge 与向量数据库变更Knowledge API 发生调整。以下方法已删除Knowledge.add_contentadd_content_asyncadd_contents_async现在应使用insert()ainsert()ainsert_many()此外GDriveContextProvider已重命名为GoogleDriveContextProviderLanceDB 中use_tantivy已被删除或忽略。需要特别注意向量数据库迁移问题如果对一个 v3 之前创建的向量表使用user_id进行搜索系统会抛出ValueError并指向向量数据库迁移说明。系统不再返回空结果来掩盖表结构不兼容问题。十八、Scheduler 变更更新字段白名单与唯一键调整调度器的update_schedule现在采用严格白名单机制。只允许更新以下字段namedescriptionmethodendpointpayloadcron_exprtimezonetimeout_secondsmax_retriesretry_delay_secondsenablednext_run_atdisabled_reason传入任何其他字段都会抛出ValueError。以下类型的数据不再允许通过通用更新路径写入所有权信息。来源信息。锁状态。v3.0.0 的迁移中也会新增对应的来源字段。此外Schedules 的唯一键发生变化旧唯一键name新唯一键(user_id, name)如果同一个用户下存在重名 Schedule迁移将中止。因此升级前必须先完成重名调度任务的去重处理。十九、Evals 变更eval_id 全面改为 run_id评测系统中eval_id已改为run_id评测类不再携带eval_id每一次运行都拥有自己的run_id。以下调整需要同步处理store_result_in_file的参数从eval_id改为run_id。file_path_to_save_results模板中的{eval_id}不再支持。应使用{run_id}。POST /eval-runs返回数据库中实际保存的 ID即run_id。重复运行不再相互覆盖。二十、Models 与 Learning 的破坏性调整Mistral 的旧兼容层已移除。agno[mistral]现在要求mistralai2.0.0并且 Mistral 已重新包含在 models extra 中。指标模块也发生调整agno.models.metrics以及Metrics别名已删除。现在应使用fromagno.metricsimportRunMetrics模型错误分类接口Model.classify_error已删除。现在应使用ModelProviderError.classify(error)二十一、Entity Memory 用户隔离与别名清理在namespaceuser下Entity Memory 现在按用户隔离。其行键会嵌入user_id的摘要。v3.0.0 迁移会重新生成旧版本中对应的行键迁移函数为agno.learn.migrations.rekey_user_entity_learnings同时在该命名空间下以下方法必须使用关键字形式传入user_idEntityMemoryStore.deleteEntityMemoryStore.get例如user_id...以下 Learning 旧别名已删除旧别名新名称MemoriesConfigUserMemoryConfigMemoriesStoreUserMemoryStoreDecisionDecisionLog二十二、仍可使用但已弃用的能力v3.0.0 仍保留部分兼容能力但建议逐步完成迁移。1. knowledge_retriever旧写法knowledge_retriever(dependencies...)仍可以工作但推荐使用run_context如果 Retriever 的函数签名仍然包含dependencies系统会进入显式的向后兼容分支。如果run_context和dependencies同时出现则以run_context为准。2. Scopes 名称迁移以下 Scope 名称已改名旧名称新名称system:readconfig:readsystem:writeconfig:write旧名称仍作为别名有效已有 Token 也不会立即失效。3. RedisDB 重命名向量数据库中的RedisDB改名为RedisDbRedisVectorDb仍然继续导出用于与agno.db.redis存储适配器进行区分。二十三、分页行为收紧不再接受无边界页码查询v3.0.0 对分页参数进行了更严格的约束。以下情况将抛出ValueError使用page但未指定limit。page 1。旧版本中这些写法可能返回无边界结果或负向结果。v3.0.0 不再允许这类不明确的分页行为。二十四、类型化数据库错误迁移问题不再静默失败v3.0.0 新增类型化错误用于明确区分数据库版本与迁移问题MigrationRequiredErrorSchemaMismatchError这些错误会明确指示相应解决方式。在 AgentOS 中如果出现迁移要求错误JSON 响应体会携带{error_id:migration_required_error}这比旧版本中可能出现的静默异常、空数据、行为不一致更容易定位问题。二十五、完整升级检查清单在升级 agno v3.0.0 前建议逐项检查确认数据库已执行MigrationManager(db).up()。验证agno_runs中已经存在迁移后的运行记录。未验证前不清理旧的 runs Blob 字段。需要回收空间时使用forceTrue清理旧字段。检查 Schedule 是否存在同一用户下重名任务。检查所有Workflow是否改为关键字构造。检查 HITL 配置是否从平铺参数改为HumanReview(...)。检查 JWT 是否已从secret_key迁移到verification_keys。检查 AgentOS 的 MCP Server 是否改为单一mcp_server参数。检查 Agent 参数重命名。检查reasoningTrue是否改为显式reasoning_model。检查 Culture 相关功能是否已迁移到 Knowledge。检查 MultiMCPTools 是否拆分为多个 MCPTools。检查 Google、DuckDuckGo、SQLTools、FileTools 等工具调用名称。检查 Knowledge 写入接口是否改为insert、ainsert、ainsert_many。检查向量表是否已完成面向user_id的迁移。检查 Eval 中的eval_id是否全部改为run_id。检查 Mistral SDK 版本是否满足mistralai2.0.0。检查 Metrics 导入是否迁移到agno.metrics.RunMetrics。检查 Entity Memory 在用户命名空间下是否传递关键字user_id。检查分页调用是否同时提供合法的page与limit。如果使用后台任务确保 AgentOS 组件配置数据库。结语代码地址github.com/agno-agi/agnoagno v3.0.0 并非一次普通版本迭代而是一次围绕数据模型、执行模型、工具调用模型和平台治理模型的全面升级。其中最重要的变化是将 Runs 从 Session Blob 中拆出构建独立的agno_runs表同时引入持久化后台队列、超长工具结果卸载、媒体引用存储、CodeMode 编程式工具调用、Studio 草稿发布机制以及更广泛的用户隔离能力。对于生产环境而言升级的第一原则只有一句话先迁移数据库验证迁移结果再让 v3.0 正式承接流量。如果项目中使用了 AgentOS、Workflow HITL、MCP、Knowledge、向量数据库、Scheduler、Evals 或 Entity Memory则应逐项完成本文列出的 API 与配置迁移避免因破坏性变更导致运行异常。