Agno Team 会话Session管理实战持久化、历史传递、摘要与共享完整指南【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agnoAgno 的 Team 是多 Agent 协作的核心载体而 Session会话决定了 Team 在多次交互之间能否记住自己说过什么、做过什么。本文基于 cookbook/03_teams/07_session 目录下的全部示例系统讲解 Team 会话的持久化存储、聊天历史注入、会话命名与缓存、自动摘要、历史会话搜索、跨 Agent 共享会话以及嵌套团队之间的历史传递并深入 Team 源码 验证每个参数的底层语义。读完本文你将掌握用 Agno Team 搭建有记忆、可追溯、可跨会话延续的多 Agent 应用的完整方案。前置准备与运行环境官方示例的 README 明确了三条运行前提与仓库内其余 cookbook 保持一致加载环境变量示例默认使用 OpenAI 模型OpenAIResponses需要先通过direnv allow加载.envrc中的密钥如OPENAI_API_KEY使用项目虚拟环境推荐用.venvs/demo/bin/python来运行 cookbook 示例例如.venvs/demo/bin/python cookbook/03_teams/07_session/persistent_session.py按需启动外部服务部分示例依赖外部基础设施——persistent_session.py、chat_history.py、session_summary.py、session_options.py使用 PostgreSQL连接串形如postgresqlpsycopg://ai:ailocalhost:5532/ai而search_past_sessions.py、custom_session_summary.py、nested_team_history.py等使用 SQLite 或InMemoryDb。README 明确指出这些额外依赖以文件 docstring 中的说明为准。会话基础持久化 Session 与聊天历史持久化会话让 Team 跨运行活下来一个 Team 默认是无状态的但如果给它挂上数据库会话就能跨进程、跨时间保存。persistent_session.py 演示了最基础的用法from agno.agent import Agent from agno.db.postgres import PostgresDb from agno.models.openai import OpenAIResponses from agno.team import Team db_url postgresqlpsycopg://ai:ailocalhost:5532/ai db PostgresDb(db_urldb_url, session_tablesessions) agent Agent(modelOpenAIResponses(idgpt-5-mini)) basic_team Team( modelOpenAIResponses(idgpt-5-mini), members[agent], dbdb, ) history_team Team( modelOpenAIResponses(idgpt-5-mini), members[agent], dbdb, add_history_to_contextTrue, num_history_runs3, )这里的两个关键参数在 team.py 中有明确定义参数默认值作用dbNone会话存储后端BaseDb/AsyncBaseDb类型不设置则运行结束即丢失add_history_to_contextFalse为True时把聊天历史中的消息加入发送给模型的消息列表源码注释add_history_to_contexttrue adds messages from the chat history to the messages list sent to the Modelnum_history_runsNone注入上下文的最近运行run次数上限num_history_messagesNone注入上下文的最近消息条数上限与num_history_runs二选一或配合使用basic_team与history_team的区别是验证重点前者虽然也把会话写入了数据库但没有把历史注入上下文所以第三轮提问What have we been talking about?无法唤起前两轮的记忆后者通过add_history_to_contextTrue与num_history_runs3让 Team 能主动回顾过去三轮对话。这揭示了一个重要设计持久化与记忆是两个独立的开关——db决定能否保存add_history_to_context决定是否回填。读取聊天历史get_chat_historychat_history.py 展示了存取分离的完整闭环除了用add_history_to_context把历史喂给模型还可以通过team.get_chat_history()把历史取出来自己处理history_team Team( modelOpenAIResponses(idgpt-5-mini), members[agent], dbdb, ) if __name__ __main__: history_team.print_response(Tell me a new interesting fact about space) print(history_team.get_chat_history()) history_team.print_response(Tell me a new interesting fact about oceans) print(history_team.get_chat_history())同时它还演示了num_history_messages的限量注入模式limited_history_team Team( modelOpenAIResponses(idgpt-5.2), members[Agent(modelOpenAIResponses(idgpt-5.2))], dbdb, add_history_to_contextTrue, num_history_messages1, # 只把最近 1 条消息放进上下文 )这样即使会话很长模型每次也只看到最近 N 条消息是控制上下文长度、降低 token 开销的实用手段。在源码层面get_chat_history(session_id, last_n_runs)与异步版本aget_chat_history()均在 team.py 中定义返回List[Message]last_n_runs可进一步限定只取最近几次运行的对话。会话选项命名、内存数据库与会话缓存session_options.py 集中演示了三个高频会话能力。会话命名与自动命名renamable_team Team( modelOpenAIResponses(idgpt-5-mini), members[agent], dbpostgres_db, ) renamable_team.print_response(Tell me a new interesting fact about space) renamable_team.set_session_name(session_nameInteresting Space Facts) print(renamable_team.get_session_name()) renamable_team.set_session_name(autogenerateTrue) # 让模型根据对话内容自动起名 print(renamable_team.get_session_name())set_session_name支持两种用法显式传入session_name固定名称或传入autogenerateTrue由模型根据会话内容自动生成随后用get_session_name()读取。对应实现位于 team.py并同时提供异步版本aset_session_name/aget_session_name。在数据库层面这是通过 team.py 的会话模块 的generate_session_name调用模型完成的。内存数据库与会话 IDin_memory_db InMemoryDb() in_memory_team Team( modelOpenAIResponses(idgpt-5-mini), members[research_agent], dbin_memory_db, add_history_to_contextTrue, num_history_runs3, session_idtest_session, # 显式固定会话 ID )InMemoryDb适合原型验证与单进程短生命周期场景——会话仅存在内存中进程退出即消失。显式指定session_id后后续调用get_chat_history(session_idtest_session)就能取回同一会话内的消息。示例中用pprint打印[m.model_dump(include{role, content}) for m in chat_history]来观察第一轮、第二轮之后的会话累积情况是排查会话是否真正落库的便捷手段。会话缓存cached_team Team( modelOpenAIResponses(idgpt-5-mini), members[research_agent], dbsessions_db, session_idteam_session_cache, add_history_to_contextTrue, cache_sessionTrue, )cache_sessionTrue会把当前 Team 会话缓存在内存中以加速访问适用于高频往返同一会话的场景。该参数在 team.py 中的注释为If True, cache the current Team session in memory for faster access。会话摘要压缩长对话延续上下文长会话直接把全部历史注入上下文既贵又容易超限Agno 提供了摘要机制把过去的对话压缩成结构化摘要。自动摘要与异步读取session_summary.py 演示了同步、异步两套摘要流程sync_db PostgresDb(db_urlsync_db_url, session_tablesessions) async_db AsyncPostgresDb(db_urlasync_db_url, session_tablesessions) summary_team Team( modelOpenAIResponses(idgpt-5-mini), members[sync_agent], dbsync_db, enable_session_summariesTrue, # 每轮运行结束后自动生成摘要 ) context_summary_team Team( modelOpenAIResponses(idgpt-5-mini), dbsync_db, session_idsession_summary, add_session_summary_to_contextTrue, # 把摘要注入上下文 members[sync_agent], )异步版本通过AsyncPostgresDb连接串改用postgresqlpsycopg_async://配合aprint_response并在运行结束后调用aget_session_summary(session_id...)拉取摘要返回的SessionSummary对象同时包含summary文本与topics主题列表summary await async_summary_team.aget_session_summary(session_idasync_team_session_summary) if summary: print(f\nSession Summary: {summary.summary}) if summary.topics: print(fTopics: {, .join(summary.topics)})对应参数在 team.pyenable_session_summaries每轮运行结束创建/更新会话摘要、add_session_summary_to_context是否把摘要注入上下文、session_summary_manager自定义摘要管理器。读取方法为get_session_summary/aget_session_summaryteam.py。自定义摘要管理器custom_session_summary.py 进一步演示了用SessionSummaryManager定制摘要行为from agno.session import SessionSummaryManager db SqliteDb( db_filetmp/team_session_summary.db, session_tableteam_summary_sessions, ) summary_manager SessionSummaryManager(modelOpenAIResponses(idgpt-5-mini)) sprint_team Team( nameSprint Team, modelOpenAIResponses(idgpt-5-mini), members[planner], dbdb, session_summary_managersummary_manager, # 替换默认摘要生成器 add_session_summary_to_contextTrue, )配合agent.instructions可以引导摘要风格。示例中为规划 Agent 设置了Build concise, sequenced plan summaries.、Keep recommendations practical.等指令从而让两周期 Sprint 计划这类业务摘要更贴合领域。运行三轮后通过sprint_team.get_session_summary(session_idsprint-planning-session)取回摘要并让 Team 基于摘要回答下一步最重要动作展示了摘要压缩 → 上下文复用 → 延续对话的完整链路。搜索历史会话两步模式list-then-read当团队需要回想用户更早的会话而不只是当前会话时search_past_sessions.py 展示了官方推荐的两步模式先列出预览、再按需读取全文。db AsyncSqliteDb(db_fileDB_FILE) team Team( modelOpenAIResponses(idgpt-5.6-luna), members[], dbdb, search_past_sessionsTrue, num_past_sessions_to_search10, # 控制搜索最近多少条历史会话 )启用search_past_sessionsTrue后Team 会获得两个内置工具见 team.py 参数注释search_past_sessions()返回若干历史会话的轻量逐轮预览read_past_session(session_id)读取某个具体会话的完整对话。配套的粒度控制参数源码注释明确给出默认值参数默认值作用search_past_sessionsFalse是否给 Team 注入历史会话搜索工具num_past_sessions_to_searchNone约 20最多搜索多少条历史会话num_past_session_runs_in_searchNone约 3每条预览里展示几次运行的摘要示例还演示了按用户隔离的会话访问用户 1 建立user1_session_1..3、用户 2 建立user2_session_1..2随后通过aprint_response(..., session_id..., user_id...)让每个用户只能浏览并阅读自己的历史会话例如What did I discuss in my previous conversations?与Read the full conversation from the session where we discussed China。这正是多租户场景下会话归属 越权隔离的参考实现。与单 Agent 共享会话share_session_with_agent.py 展示了一个独特的用例同一个session_id在独立 Agent 与 Team 之间来回流转。db InMemoryDb() agent Agent( nameCity Planner Agent, idcity-planner-agent-id, modelOpenAIResponses(idgpt-5.2), dbdb, # 与 Team 共享同一个数据库 tools[get_weather, get_activities], add_history_to_contextTrue, ) team Team( nameCity Planner Team, idcity-planner-team-id, modelOpenAIResponses(idgpt-5.2), dbdb, # 同一个数据库 members[weather_agent, activities_agent], add_history_to_contextTrue, ) session_id str(uuid.uuid4()) agent.print_response(What is the weather like in Tokyo?, session_idsession_id) team.print_response(What activities can I do there?, session_idsession_id) agent.print_response(What else can you tell me about the city? Should I visit?, session_idsession_id)会话的归属以数据库为锚点只要 Agent 与 Team 使用同一个db实例并传入相同的session_id就能在单 Agent 模式与多 Agent 团队模式之间无缝切换交替继续同一段对话。这一模式非常适用于先由个人助理收集信息再升级到专家团队深度处理再回到个人助理汇报的产品形态。嵌套团队的历史传递当 Team 的成员本身是 Team子团队时历史如何传递是关键问题。该目录下有三个层层递进的示例。子团队自行维护对话历史nested_team_history.py 展示父团队把任务委托给嵌套子团队时子团队通过add_history_to_contextTrue携带它自己的上一轮对话继续工作。示例用moderoute的main_team包含 Writer 与 Research Team三轮追问中 Research Team 必须记得第一轮的研究结论才能回答后续问题。research_team Team( nameResearch Team, modelOpenAIResponses(idgpt-5.6-sol), members[analyst], add_history_to_contextTrue, roleConduct research and analysis, ) main_team Team( nameMain Team, modelOpenAIResponses(idgpt-5.6-sol), members[writer, research_team], dbdb, add_history_to_contextTrue, moderoute, show_members_responsesTrue, )add_team_history_to_members把团队级历史发给成员nested_team_history_to_members.py 演示的add_team_history_to_membersTrue语义更精细父团队委托任务时会向被委托的成员注入过去运行的文本摘要对嵌套子团队而言这份摘要按子团队自己的 id 过滤因此子团队能回忆起它自己处理过的事情而不是根团队领导的对话。main_team Team( nameMain Team, modelOpenAIResponses(idgpt-5.5), members[research_team], dbdb, add_team_history_to_membersTrue, # 把团队历史共享给成员 num_team_history_runs5, instructions[ You coordinate sub-teams. Delegate every request to the member with id research_team (the Research Team)., Delegate to the team as a whole using member_idresearch_team. Never delegate to an individual agent inside a sub-team., ], )源码注释点明了本意This means sending the team-level history to the members, not the agent-level historyteam.py并配套num_team_history_runs默认 3此处调为 5控制发送的历史运行条数team.py。示例特意用指令约束必须把整个子团队作为单元委托因为只有走委托给子团队这条路子团队才能拿到自己的历史——如果父团队直接委托到子团队内部的叶子 Agent就绕过了这条路径。三层深度嵌套客服升级场景nested_team_deep_history.py 把模式推到三层Support TeamTriage Agent→ Escalation TeamTechnical Support Expert Team→ Expert TeamDatabase Expert Security Expert。每层都开启add_history_to_contextTrue模拟一次数据库故障的完整工单客户报障 → 补充昨天部署新功能后开始超时 → 询问目前发现了什么、建议如何修复要求每一层都能回忆起自己的历史处理过程。这是嵌套团队会话在真实客服系统中的一个可直接借鉴的架构蓝本。会话元数据的三层解析规则除 README 列出的示例外同目录的 metadata_resolution.py 补充了会话元数据的合并规则可视为会话体系的一部分team.metadata session.metadata call-site metadata即调用现场run/arun时传入的metadata优先级最高其次为会话中存储的metadata最低为 Team 构造时的metadata默认值。示例通过预置TeamSession(metadata{user_tier: premium, ...})、构造 Team 默认元数据{user_tier: free, ...}、再在调用时传{user_tier: enterprise}来验证同一把键依次被会话覆盖、再被调用现场覆盖而仅在某一层出现的键如会话的dark_mode、Team 的team_env会保留到最终结果中。这为按租户、按请求注入上下文变量提供了确定的优先级语义。会话 API 速查表综合 Team 源码 与会话示例以下是最常用的会话相关参数与方法构造参数Team 实例化参数默认值说明session_idNone自动生成指定会话 ID跨调用复用同一会话user_idNone会话归属用户用于多用户隔离dbNone会话落库后端Postgres/SQLite/InMemory 等cache_sessionFalse内存缓存当前会话以加速访问add_history_to_contextFalse把历史消息注入模型上下文num_history_runs/num_history_messagesNone控制注入历史的运行数/消息数上限add_team_history_to_membersFalse委托成员时附带团队级历史摘要num_team_history_runs3附带给成员的团队历史运行条数search_past_sessionsFalse注入历史会话搜索工具两步模式num_past_sessions_to_search/num_past_session_runs_in_searchNone搜索范围与预览条数默认约 20 / 3enable_session_summariesFalse每轮结束后自动生成会话摘要session_summary_managerNone自定义摘要管理器SessionSummaryManageradd_session_summary_to_contextNone是否把摘要注入上下文常用方法同步 / 异步方法作用set_session_name/aset_session_name手动命名或autogenerateTrue自动命名会话get_session_name/aget_session_name读取会话名称get_chat_history/aget_chat_history读取会话的聊天历史Message列表get_session_summary/aget_session_summary读取会话摘要含summary与topicsdelete_session/adelete_session删除会话可指定是否删除媒体总结Agno Team 的会话体系由三个层次构成存储层dbsession_id/user_id决定会话存哪里、归属谁、记忆层add_history_to_context、num_history_runs/messages、add_team_history_to_members决定把多少历史喂给模型以及enable_session_summaries用摘要替代长历史、检索层search_past_sessions两步模式支持跨会话回溯share_session_with_agent支持 Agent 与 Team 共享同一会话。嵌套团队场景下历史按子团队 id 作用域隔离保证每层都能回忆自己的专属上下文。所有参数与 API 均可在 Team 源码 及其 会话示例目录 中找到完整可运行的对照实现可直接基于这些示例搭建具备持久记忆与多轮协作能力的生产级多 Agent 系统。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考