Agno 团队上下文管理实战从系统提示词、历史消息到工具调用的多维控制指南【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno在 Agno 中Team与单Agent的本质差异不仅在于多个成员协作更在于上下文context的编排复杂度协调者coordinator如何理解团队使命、记住用户身份与地理时区、参考历史会话中的关键结果同时又不被陈旧的工具调用细节淹没。本文围绕 cookbook/03_teams/09_context_management 目录下的 7 个示例展开系统讲解 Agno Team 上下文管理的全部常用手段自定义系统消息、团队介绍语、额外上下文占位符解析、少样本示例注入、日期时间/位置上下文以及历史消息与工具调用的过滤策略。读完你将能针对不同业务场景为多 Agent 团队配置出懂时机、懂分工、懂分寸的上下文策略。一、能力总览Team 上下文管理要解决哪些问题多 Agent 团队的每一次运行协调者模型都会收到由系统提示词、成员信息、历史消息、当前请求拼接而成的上下文。上下文质量直接决定团队是否会把简单请求错误地下派给成员、是否忘记用户所处时区或者是否在第十轮对话后把前九轮的大量工具返回塞爆窗口。下表汇总了本目录 7 个示例分别演示的上下文控制维度也是全文的阅读索引示例文件核心关键词解决的上下文问题additional_context.pyadditional_context、resolve_in_context、dependencies注入含占位符的补充上下文并在运行时解析few_shot_learning.pyadditional_input用问题—标准回复示例约束团队行为模式custom_system_message.pysystem_message、system_message_role、add_name_to_context覆盖默认系统消息并定制其角色datetime_format.pyadd_datetime_to_context、datetime_format、timezone_identifier以指定格式与时区注入当前时间location_context.pyadd_location_to_context注入地理位置与本地时区上下文introduction.pyintroduction、add_history_to_context设置会话可复用的开场介绍语filter_tool_calls_from_history.pynum_history_runs、max_tool_calls_from_history限制回灌的历史轮次与工具调用数量所有示例均调用team.print_response(...)触发团队运行多数示例还支持streamTrue的流式输出。运行方式遵循本 cookbook 的通用规范通过.venvs/demo/bin/python执行参见 README 的 Prerequisites 一节并预先通过direnv allow加载OPENAI_API_KEY等环境变量个别示例依赖额外的本地服务具体以脚本 docstring 中的说明为准。二、搭建最小可运行环境在运行任一示例前先完成如下准备加载环境变量在仓库根目录执行direnv allow使OPENAI_API_KEY等密钥自动注入当前 shell使用项目虚拟环境统一使用.venvs/demo/bin/python来运行 cookbook 脚本避免依赖污染确认额外服务filter_tool_calls_from_history.py使用 SQLite 存储会话通过 SqliteDb无需外部数据库few_shot_learning.py与location_context.py等示例则可能要求联网调用模型或搜索工具。本目录所有示例的成员与协调者模型均使用agno.models.openai.OpenAIResponses例如OpenAIResponses(idgpt-5-mini)。若你希望替换成其他厂商模型只需把model换成 Agno 支持的任意模型封装如agno.models.anthropic、agno.models.google等上下文相关的所有参数均与模型无关。三、向团队注入运营规则additional_context 与占位符运行时解析additional_context.py 演示了一个非常有代表性的场景团队需要在每次运行时都携带一条组织政策但政策文本中的角色、区域等信息是运行时才确定的。示例的做法是把上下文写成含{role}、{region}占位符的模板再用dependencies提供变量字典最后开启resolve_in_contextTrue让 Team 在运行时完成解析from agno.agent import Agent from agno.models.openai import OpenAIResponses from agno.team import Team ops_agent Agent( nameOps Copilot, modelOpenAIResponses(idgpt-5-mini), instructions[Follow operational policy and include ownership guidance.], ) policy_team Team( namePolicy Team, modelOpenAIResponses(idgpt-5-mini), members[ops_agent], additional_context( The requester is a {role} in the {region}. Use language suitable for an internal process update and include owner timeline whenever possible. ), resolve_in_contextTrue, dependencies{role: support lead, region: EMEA}, instructions[Answer as a practical operational policy assistant.], markdownTrue, ) policy_team.print_response( A partner asked for a temporary extension on compliance docs., streamTrue, )运行后会看到协调者在实际回答中采用支持主管、EMEA 区域的口吻与措辞。从 Team 源码 可以看到这些参数的默认语义additional_context: Optional[str]默认Noneteam.pyresolve_in_context: bool默认Trueteam.py即默认开启占位符解析dependencies为解析提供键值来源。需要说明的是占位符解析最终由底层的上下文解析逻辑Agent 层同样具备该能力完成模板中未被dependencies覆盖的键将无法被正确替换。因此**约定上下文模板中出现的每个{key}都必须在dependencies中提供**是保证稳定的最佳实践。若业务上希望在个别请求中临时覆盖也可以把同样的键放在当次请求的上下文里优先级由框架的解析顺序决定。四、用 few-shot 约束团队输出范式additional_inputadditional_context注入的是描述性规则而 few_shot_learning.py 演示的是少样本学习直接给团队一组用户问题 → 理想回复的示例让模型模仿示例中的处理范式。该示例构造了一个客服团队support_examples其中每个样本都是agno.models.message.Message构成的两轮对话用户抱怨roleuser与标准的处理回复roleassistant。例如密码找回类问题示例回复不仅给出话术还明确标注转交 Support Specialist、列出处理步骤与预期结果重复扣款类问题则示范转交 Escalation Manager以及补偿、安抚与跟进要点support_examples [ Message(roleuser, contentI forgot my password and cant log in), Message( roleassistant, content Ill help you reset your password right away. **Transferring to Support Specialist**: Please assist this customer with password reset: - Guide them through the password reset process - Verify their identity if needed - Ensure they can successfully log in - Provide tips for creating a secure password Expected outcome: Customer successfully logs in with new password. .strip(), ), # ... 更多样例重复扣款转 Escalation Manager、上传崩溃转 Support Specialist ]随后团队通过additional_inputsupport_examples把示例列表注入上下文见 few_shot_learning.pyteam Team( nameCustomer Support Team, members[support_agent, escalation_agent], modelOpenAIResponses(idgpt-5-mini), add_name_to_contextTrue, additional_inputsupport_examples, instructions[ You coordinate customer support with excellence and empathy., Follow established patterns for proper issue resolution., Always prioritize customer satisfaction and clear communication., ], markdownTrue, )从源码的类型定义可以确认additional_input是一个宽松的列表元素既可以是字符串、Message也可以是Dict或BaseModel见 team.py 中Optional[List[Union[str, Dict, BaseModel, Message]]]的声明也就是说你可以用 Pydantic 模型批量传入结构化示例。测试脚本的主流程一次性提交三类新场景——找不到确认邮件、收到损坏商品、无法取消订阅——用来检验团队是否学会按问题类型自动选择 Support Specialist / Escalation Manager的分诊范式。设计示例时建议遵循如下要点场景覆盖要正交每类问题至少一组样本明确各自应由哪位成员接手示例中显式给出处理步骤与 Expected outcome模型会沿袭这一结构化输出习惯若示例包含敏感流程应保证与真实业务 SOP 一致避免模型学到错误模式。五、接管团队人设system_message 与 system_message_role默认情况下Team 会为协调者生成一段通用的系统消息大致语义是你协调一组专业 AI Agent 完成用户请求必要时将任务下派给成员……TEST_LOG 中可以看到系统消息原文与默认介绍。当业务需要团队拥有更强的自定义人设时可像 custom_system_message.py 一样通过system_message完全覆盖默认消息并通过system_message_role指定该消息在对话中的角色coaching_team Team( nameTeam Coach, modelOpenAIResponses(idgpt-5-mini), members[coach], instructions[Focus on high-leverage behavior changes.], system_message( You are a performance coach for remote teams. Every answer must end with one concrete next action. ), system_message_rolesystem, add_name_to_contextTrue, )运行后协调者的 system prompt 就变成了自定义文案你是一位远程团队绩效教练每个回答必须以一个具体下一步行动收尾——TEST_LOG 中记录的真实请求体佐证了这一点DEBUG system 后紧跟的正是这段自定义文本而不是框架默认的团队协调介绍。这里的两个参数各司其职参数作用注意事项system_message替换默认系统提示词设置后框架不再拼接通用协调者人设需自行确保它包含必要的团队协调说明system_message_role指定该消息以何种 role 注入常见取值为system若设为developer部分模型支持则对应模型的开发者指令通道add_name_to_context将团队name如 Team Coach写入上下文让模型知道我是谁便于消息中自我介绍或签名风险提示自定义system_message是全量替换而非追加。如果你完全覆盖默认消息务必在自定义文案里交代清楚成员与委派机制否则协调者可能忘记自己身处多 Agent 团队、不会调用delegate_task_to_member工具。一个稳妥做法是在system_message中保留必要的协调语义再用instructions追加业务规则。六、让团队知道现在几点datetime_format 与时区时间感知是多 Agent 团队处理排期、提醒、日报类任务的前提。框架可以把当前时间自动注入系统上下文但格式与时区必须可控否则会出现机器可读时间戳 UTC 时刻让模型换算困难的尴尬。datetime_format.py 给出了完整解法开启add_datetime_to_contextTrue后通过datetime_format指定 strftime 风格格式并用timezone_identifier指定 IANA 时区scheduling_team Team( nameScheduling Team, modelOpenAIResponses(idgpt-5-mini), members[scheduler], add_datetime_to_contextTrue, datetime_format%B %d, %Y %I:%M %p %Z, # e.g. March 09, 2026 02:30 PM UTC timezone_identifierUS/Eastern, )各参数要点add_datetime_to_context默认关闭False开启后才会向上下文注入时间datetime_formatPythonstrftime格式串。示例%B %d, %Y %I:%M %p %Z输出人类可读的长格式如March 09, 2026 02:30 PM UTC想给模型更紧凑的表示可用%Y-%m-%d %H:%M %Z等timezone_identifierIANA 时区标识符如US/Eastern、America/Chicago。默认不指定时遵循环境本地时区。示例中成员是 Scheduler测试问题为为 30 分钟后安排一个站会。若缺少正确的本地时间注入模型会把30 分钟后换算到错误的基准时刻因此该配置在日程编排 Agent 中几乎是必选项。七、让团队知道你在哪location_context与时间上下文配套的是位置上下文。location_context.py 展示了面向旅行规划场景的用法——开启add_location_to_contextTrue后团队在规划周末短途游带什么、去哪里时会参考当地气候、季节与昼夜情况trip_planner_team Team( nameTrip Planner, modelOpenAIResponses(idgpt-5-mini), members[planner], add_location_to_contextTrue, timezone_identifierAmerica/Chicago, instructions[ Plan recommendations around local time and season., Mention when local timing may affect itinerary decisions., ], )这里可以看到一个参数复用的设计timezone_identifier不仅在add_datetime_to_context时生效也服务于位置上下文——同一套时区设定同时影响当前几点和当前所处位置的季节/时段推断。从 Team 源码 可见add_datetime_to_context、add_location_to_context、datetime_format、timezone_identifier是并列的独立配置项可以按需自由组合排期类团队add_datetime_to_contextTruedatetime_formattimezone_identifier出行/本地生活类团队add_location_to_contextTruetimezone_identifier两者都开启同时获得时间与位置信息适合本地化运营实时执行的复合场景。八、定制会话开场白introduction很多业务希望团队在每轮会话开始时先用一句固定介绍语自报家门例如限定回答范围而不是让模型每次都自由发挥。introduction.py 用登山助手场景做了示范团队只回答与登山相关的问题并把这句介绍语作为会话期可复用的固定上下文from agno.db.sqlite import SqliteDb db SqliteDb(db_filetmp/teams.db, session_tableteam_sessions) INTRODUCTION ( Hello, Im your personal assistant. I can help you only with questions related to mountain climbing. ) team Team( modelOpenAIResponses(idgpt-5.2), dbdb, members[agent], introductionINTRODUCTION, session_idintroduction_session_mountain_climbing, add_history_to_contextTrue, )理解该示例需要抓住三个配合点introduction作为会话的介绍消息注入模型会在开场使用它把它限定为仅回答登山相关问题实际上起到了轻量级对话护栏的作用持久化会话示例使用 SqliteDbdb_filetmp/teams.db并固定session_idintroduction_session_mountain_climbing确保多次调用落在同一会话、历史得以回灌。TEST_LOG 显示运行时确实执行了 Getting messages from previous runs: 6 / Adding 6 messages from history 的取回流程add_history_to_contextTrue开启历史注入后第二轮问题如Is K2 harder to climb than Everest?会参考第一轮Easiest 14er in USA?的对话语境。会话存储是多次追问类应用的标配。若未设置dbTeam 默认只在内存中保留当次会话上下文进程结束后历史即丢失。更多会话与存储配置可参考 06_storage 与 03_teams/07_session 系列示例。九、控制记忆的体量历史轮次与工具调用过滤多轮对话与长期会话必然引入一个工程问题上下文窗口有限历史越长越贵、越容易淹没关键信息尤其当历史中充斥着大段 Web 搜索结果工具调用的输出时。这是 filter_tool_calls_from_history.py 的核心场景一个同时配备技术研究员 Alex与商业分析师 Sarah的调研团队协调者自己持有WebSearchTools连续执行 4 个调研任务每个任务都会产生大量搜索与工具返回。团队配置如下关键参数已标注research_team Team( nameResearch Team, modelOpenAIResponses(idgpt-5.2), members[tech_researcher, business_analyst], tools[WebSearchTools()], # Team 自己用 DuckDuckGo 做初步检索 descriptionResearch team that investigates topics and provides analysis., instructionsdedent( You are a research coordinator that investigates topics comprehensively. Your Process: 1. Use DuckDuckGo to search for a lot of information on the topic. 2. Delegate detailed analysis to the appropriate specialist 3. Synthesize research findings with specialist insights ... ).strip(), dbSqliteDb(db_filetmp/research_team.db), session_idresearch_session, add_history_to_contextTrue, num_history_runs6, max_tool_calls_from_history3, markdownTrue, show_members_responsesTrue, )这里涉及的三个记忆体量参数在 Team 源码 中并列定义均为可选add_history_to_context是否从会话存储中回灌历史消息num_history_runs回灌最近多少个 run 的消息示例取最近 6 个 runnum_history_messages与num_history_runs二选一的另一种口径限制回灌最近多少条消息max_tool_calls_from_history从历史中最多提取多少个工具调用结果参与本轮上下文。为什么需要max_tool_calls_from_history工具调用的返回通常非常重搜索结果可能上千 token 且多为噪音。在第 4 个问题谁在引领 AI 基础设施到来时如果系统把前 3 个问题的全部搜索返回都回灌会同时造成 token 浪费与注意力稀释。设置为 3 表示即使历史中曾有几十次搜索团队也最多挑选少量最相关的工具调用结果参与推理其余只保留对话摘要与最终结论层面的消息。由于此类示例连续发起 4 个长任务单次运行耗时较长仓库 TEST_LOG.md 中该类脚本曾因 30s 超时被标记为 FAIL属测试执行超时而非配置错误建议实际验证时预留充足的执行时间或先减少scenarios中的问题数量。十、参数速查Team 上下文配置全表综合上述示例与 Team 类源码把团队上下文相关参数汇总如下便于作为配置清单直接对照参数类型默认值说明对应示例instructionslist[str]/str—追加在系统提示词后的行为准则全部示例descriptionstr—团队职责描述供协调者与外部引用filter_tool_calls_from_historysystem_messagestr框架默认值全量替换协调者系统消息custom_system_messagesystem_message_rolestr依框架系统消息注入角色如systemcustom_system_messageintroductionstr—会话开场介绍语introductionadditional_contextstrNone注入到上下文的补充文本additional_contextadditional_inputlist[str \| Dict \| BaseModel \| Message]None注入额外输入可用于 few-shotfew_shot_learningresolve_in_contextboolTrue是否解析上下文中的{placeholder}additional_contextadd_name_to_contextboolFalse是否把团队名写入上下文custom_system_message / few_shot_learningadd_datetime_to_contextboolFalse是否注入当前时间datetime_formatdatetime_formatstr依框架strftime 格式串datetime_formatadd_location_to_contextboolFalse是否注入位置上下文location_contexttimezone_identifierstr依环境IANA 时区标识符datetime_format / location_contextadd_history_to_contextboolFalse是否回灌历史消息introduction / filter_tool_calls_from_historynum_history_runsintNone回灌最近的 N 个 runfilter_tool_calls_from_historynum_history_messagesintNone回灌最近的 N 条消息—max_tool_calls_from_historyintNone回灌时最多携带的过往工具调用数filter_tool_calls_from_history需要提醒的是不同 Agno 版本对这些参数的默认值可能微调例如resolve_in_context在 team.py 中默认为True若追求确定性行为建议在构建Team时显式写出关键开关不要依赖默认值。十一、组合策略建议面向场景选择上下文方案把上述能力放到真实业务中可以按场景—配置组合的原则快速决策客服/支持团队additional_input注入分诊 few-shot add_name_to_contextTrue让团队学会按问题类型自动转给 Support Specialist 或 Escalation Manager运营合规团队additional_context模板 dependencies运行时解析让同一套政策适用于不同角色/区域避免为每个团队写死文案排期与会议助手add_datetime_to_contextTruetimezone_identifier 人类可读的datetime_format保证30 分钟后落在正确的本地时刻旅行/本地生活助手add_location_to_contextTruetimezone_identifier结合季节与昼夜给出建议多轮长期研究团队SqliteDb持久化会话 add_history_to_contextTruenum_history_runs控制体量 max_tool_calls_from_history过滤笨重的工具返回有严格人设与回答边界的产品用system_message全量接管系统提示词并配合introduction在会话层面给出开场白。上下文管理是越复杂越值钱的团队能力单 Agent 时代你只需要写好一条系统提示词而在 Team 中你必须同时回答团队是谁、现在几点、用户在哪、上轮发生了什么、工具噪音要不要带进来这五个问题。本文给出的 7 个示例与对应源码位置构成了回答这些问题的完整工具箱——建议在 cookbook/03_teams/09_context_management 目录中逐个运行并观察不同配置下的 system 消息与行为差异以形成最直观的体感。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
