Agno Team 路由模式（Route Mode）实战：让团队领导者把请求一键转派给专业成员

Agno Team 路由模式（Route Mode）实战：让团队领导者把请求一键转派给专业成员

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno

路由模式（TeamMode.route）是 Agno 中 Team 的四种执行模式之一。它的核心思路很直接：团队领导者（leader）分析用户请求后，只把任务转派给最匹配的一位专业成员（specialist），并把这个成员的回复原样返回给用户，不再做二次合成。本文基于仓库cookbook/03_teams/02_modes/route/目录下的三个可运行示例展开，分别演示语言路由、领域专家路由和带兜底（fallback）的路由。读完本文，你将掌握 route mode 的语义、Team的搭建方式、成员角色的编写要点，以及如何在自己的多智能体场景里用它实现"专人专事"的分发。

什么是 Route Mode：与其它 Team 模式的定位差异

Agno 的 Team 支持四种执行模式，定义位于 mode.py 的TeamMode枚举中：

从源码注释看，route 模式的精确定义是：

"Router pattern. Leader routes to a specialist and returns the member's response directly."（mode.py）

对比 coordinate/broadcast 需要领导者"综合各路答案"，route 模式不合成——谁的活谁干，回答是谁的就原样给谁。这种"零合成分支"的设计让它在语言分发、领域专送、客服工单分类等场景下响应路径最短、语义最不容易被中间层稀释。

底层语义：mode=route 在源码里做了什么

选择mode=TeamMode.route并不是一个黑盒开关，它在 Team 初始化阶段（_init.py）会被"确定性归一化"成一组布尔配置：

if mode == TeamMode.route: team.respond_directly = True # 成员回答直接返回，不合成 team.delegate_to_all_members = False # 不广播给所有人

也就是说 route 模式等价于"只派单 + 直连返回"。源码里还做了反向归一化：如果你只设置了respond_directly=True而未指定mode，Team 会被自动归为route模式。这保证了同一套语义无论从哪个入口配置都不会互相冲突。

而路由任务本身通过delegate_task_to_member这一团队工具完成。在 route 模式下，系统注入给领导者的提示词会明确约束其行为（见 _messages.py）：

你工作在 route 模式：必须把请求交给恰好一个成员（调用delegate_task_to_member），并把该成员的回答原样返回给用户，随后结束本轮。

结合三个示例中都会设置的show_members_responses=True，运行时可直观看到"领导者选人 → 成员作答 → 直接透传"的完整链路。

示例一：语言路由（01_basic.py）

第一个例子把三个"只会说一种语言"的 Agent 装进一个Language Router团队：领导者先检测用户输入属于哪种语言，再把问题转给对应的语言专家，而不支持的输入默认兜底给英语专家。

完整代码见 01_basic.py，核心结构如下：

from agno.agent import Agent from agno.models.openai import OpenAIResponses from agno.team.mode import TeamMode from agno.team.team import Team # 1. 创建成员：每个 Agent 用 name/role 表明身份与边界 english_agent = Agent( name="English Agent", role="Responds only in English", model=OpenAIResponses(id="gpt-5.2"), instructions=["Always respond in English, regardless of the input language."], ) spanish_agent = Agent( name="Spanish Agent", role="Responds only in Spanish", model=OpenAIResponses(id="gpt-5.2"), instructions=["Always respond in Spanish, regardless of the input language."], ) french_agent = Agent( name="French Agent", role="Responds only in French", model=OpenAIResponses(id="gpt-5.2"), instructions=["Always respond in French, regardless of the input language."], ) # 2. 创建 Team：mode=route 是关键 team = Team( name="Language Router", mode=TeamMode.route, model=OpenAIResponses(id="gpt-5.2"), members=[english_agent, spanish_agent, french_agent], instructions=[ "You are a language router.", "Detect the language of the user's message and route to the matching agent.", "If the language is not supported, default to the English Agent.", ], show_members_responses=True, markdown=True, ) # 3. 连续提问：分别用英语 / 西班牙语 / 法语 team.print_response("What is the capital of France?", stream=True) team.print_response("Cual es la capital de Francia?", stream=True) team.print_response("Quelle est la capitale de la France?", stream=True)

注意mode=route模式下领导者依然需要自己的model（上例复用同一个gpt-5.2模型）。团队成员用role自我声明职责、用instructions硬约束行为，这是保证路由准确性的第一道防线——例如语言专家必须"无论输入语言是什么都用指定语言回复"，即使领导者偶尔派错，成员输出也依然守规矩。

示例二：领域专家路由（02_specialist_router.py）

当问题不是"按语言分类"而是"按学科派活"时，做法完全一致，只是把成员换成数学、编程、科学三个领域专家。见 02_specialist_router.py：

math_agent = Agent( name="Math Specialist", role="Solves mathematical problems and explains concepts", model=OpenAIResponses(id="gpt-5.2"), instructions=[ "You are a mathematics expert.", "Solve problems step by step, showing your work clearly.", "Explain the underlying concepts when relevant.", ], ) code_agent = Agent( name="Code Specialist", role="Writes code and explains programming concepts", model=OpenAIResponses(id="gpt-5.2"), instructions=[ "You are a programming expert.", "Write clean, well-commented code.", "Explain your approach and any trade-offs.", ], ) science_agent = Agent( name="Science Specialist", role="Explains scientific concepts and phenomena", model=OpenAIResponses(id="gpt-5.2"), instructions=[ "You are a science expert covering physics, chemistry, and biology.", "Explain concepts clearly with real-world examples.", ], ) team = Team( name="Expert Router", mode=TeamMode.route, model=OpenAIResponses(id="gpt-5.2"), members=[math_agent, code_agent, science_agent], instructions=[ "You are an expert router.", "Analyze the user's question and route it to the best specialist:", "- Math questions -> Math Specialist", "- Programming questions -> Code Specialist", "- Science questions -> Science Specialist", ], show_members_responses=True, markdown=True, ) team.print_response( "What is the time complexity of merge sort and why?", stream=True, )

这里值得学习的是Team 级instructions的"路由规则表"写法：用一行一个- 类别 -> 成员的显式映射，把"什么题找谁"讲清楚。把分发逻辑写成确定性规则，比让领导者自由发挥更能获得稳定的路由结果。

示例三：带兜底 Agent 的路由（03_with_fallback.py）

真实场景中并非每个问题都命中专家。第三个示例在 SQL 专家、Python 专家之外，增加了一个通用助手General Assistant，专门接住"不属于任何专家"或"拿不准"的问题，见 03_with_fallback.py：

sql_agent = Agent( name="SQL Expert", role="Writes and optimizes SQL queries", model=OpenAIResponses(id="gpt-5.2"), instructions=[ "You are an SQL expert.", "Write correct, optimized SQL queries.", "Explain query plans and indexing strategies when asked.", ], ) python_agent = Agent( name="Python Expert", role="Writes Python code and solves Python-specific problems", model=OpenAIResponses(id="gpt-5.2"), instructions=[ "You are a Python expert.", "Write idiomatic, well-structured Python code.", "Follow PEP 8 and use type hints.", ], ) general_agent = Agent( name="General Assistant", role="Handles general questions that do not match a specialist", model=OpenAIResponses(id="gpt-5.2"), instructions=[ "You are a helpful general assistant.", "Answer questions clearly and concisely.", "If the question is about SQL or Python, still do your best.", ], ) team = Team( name="Dev Help Router", mode=TeamMode.route, model=OpenAIResponses(id="gpt-5.2"), members=[sql_agent, python_agent, general_agent], instructions=[ "You route questions to the right expert.", "- SQL or database questions -> SQL Expert", "- Python questions -> Python Expert", "- Everything else -> General Assistant", "When in doubt, route to the General Assistant.", ], show_members_responses=True, markdown=True, ) # SQL 问题 -> 路由给 SQL Expert team.print_response( "Write a query to find the top 10 customers by total order value, " "joining the customers and orders tables.", stream=True, ) # 通用问题 -> 兜底到 General Assistant team.print_response( "What are some good practices for code review?", stream=True, )

兜底路由之所以高效，靠的是两条写在规则里的兜底策略：一是"Everything else -> General Assistant"，二是"When in doubt, route to the General Assistant"（拿不准就交给兜底）。这两句话合起来，几乎消灭了"无专家可派"的分叉死路，同时兜底成员的 instructions 也主动声明"即使问 SQL/Python 我也会尽力回答"，进一步降低路由失败时的体验损失。

Team 路由编排要点小结

把三个示例放在一起，可以提炼出 route 模式的标准编排配方：

1. 模式选择：Team(..., mode=TeamMode.route)，导入路径from agno.team.mode import TeamMode；
2. 领导者大脑：Team 自带model负责"读懂问题 + 选人"；
3. 成员画像：每个成员必须有清晰的name与role，领导者正是依据这些信息判断把任务交给谁；
4. 规则显式化：在 Team 的instructions中写明- 条件 -> 成员映射表，并补充默认分支；
5. 兜底兜死：预留General Assistant之类的通用成员承接未知问题；
6. 过程可视化：show_members_responses=True在响应中展示每个成员被选/被派的情况，便于调试路由决策。

仓库父目录 02_modes/README.md 以对比表形式列出了四种模式——route 模式适合"专家选择、语言路由"这类天然只有一条正确执行路径的任务；如果你的场景需要综合多方意见或把一个大目标拆成依赖链条，则应分别考虑 coordinate / broadcast / tasks 模式。

运行方式与环境说明

三个示例的运行方式相同，替换脚本文件名即可：

.venvs/demo/bin/python cookbook/03_teams/02_modes/route/01_basic.py .venvs/demo/bin/python cookbook/03_teams/02_modes/route/02_specialist_router.py .venvs/demo/bin/python cookbook/03_teams/02_modes/route/03_with_fallback.py

运行前提与注意事项：

• 示例使用.venvs/demo这一仓库约定的虚拟环境解释器，需先按仓库说明完成依赖安装（agno 本体位于 libs/agno 下）；
• 示例统一使用OpenAIResponses(id="gpt-5.2")，运行时需要配置对应的 OpenAI 服务凭据（环境变量OPENAI_API_KEY）；
• print_response(..., stream=True)开启流式输出，三份脚本都以分隔行（如"=" * 60）切分多个问题以便观察每次路由结果；
• 每个if __name__ == "__main__":块内按顺序发问，建议一次只跑一个脚本，逐个观察路由行为；
• 目录内的 TEST_LOG.md 记录了这三个脚本的自动化测试状态：三个文件均可完成运行（Run: completed），仅在"docstring 下划线样式"这类静态风格校验上未通过，不影响示例功能本身。

总结

Route Mode 是 Agno Team 中"单点直派"的执行模式：领导者用delegate_task_to_member把请求交给恰好一个成员，成员回答经respond_directly语义原样透传、不经过合成层。在实现上，mode=TeamMode.route会被归一化为respond_directly=True与delegate_to_all_members=False（源码证据），从行为模型上保证了"只派一人、直连返回"。无论是按语言分发（01_basic.py）、按学科派活（02_specialist_router.py）还是用通用成员兜底（03_with_fallback.py），核心都是把"选人规则"显式写进 Team 的 instructions、把"职责边界"写进成员的 role 与 instructions。掌握这一模式后，你就能以极低的编排成本构建出"专人专事、答即所问"的多语言客服、领域问答或工单分发系统。

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno