📚 编程进阶教程站

第 18 章 · Agent Team 入门：协作模式 ​

本章目标：理解 Agno Team 的"领导者-成员"架构，掌握 coordinate / route / broadcast / tasks 四种协作模式的机制与适用场景，动手搭建一个 researcher + writer 双成员团队。

18.1 为什么需要 Team ​

单个 Agent 的上下文和角色定位有限：让它既查资料又写报告又审校，提示词会越来越臃肿，工具也会互相干扰。Team 把任务拆给多个专职 Agent（members），由一个领导者（leader）模型负责分派、汇总——就像小团队分工：每人专注自己的事，组长对最终交付负责。

何时不用 Team

Team 的每次分派都是独立的模型调用，会带来更高的延迟、token 消耗和协调复杂度。官方建议：单领域能搞定的事就用单 Agent，不要为了"多智能体"而多智能体。

python
from agno.agent import Agent
from agno.team import Team

team = Team(
    members=[
        Agent(name="英语客服", role="用英语回答客户问题"),
        Agent(name="中文客服", role="用中文回答客户问题"),
    ],
)

18.2 四种协作模式 ​

Agno 2.x 通过 mode 参数显式指定模式（从 agno.team.mode 导入 TeamMode），四种模式决定了领导者的分派路径：

模式配置行为
Coordinate（默认）mode=TeamMode.coordinate领导者挑选成员、为每人生成子任务、最后综合结果
Routemode=TeamMode.route领导者把请求路由给一个最合适的成员，直接返回其结果
Broadcastmode=TeamMode.broadcast同一任务发给所有成员，再汇总各方回答
Tasksmode=TeamMode.tasks领导者维护共享任务清单，逐项执行直到目标完成

版本说明

早期版本靠 respond_directly=True（等价 route）和 delegate_to_all_members=True（等价 broadcast）两个布尔开关组合表达模式，现已推荐统一使用 mode=；未设置 mode 时旧标志仍然兼容。

python
from agno.team import Team, TeamMode

router_team = Team(
    name="语言路由台",
    members=[english_agent, chinese_agent],
    mode=TeamMode.route,
    determine_input_for_members=False,   # 用户原话直传成员，不经领导者改写
)

选型口诀：要拆解综合选 coordinate，要分类转发选 route，要多角度交叉验证选 broadcast，要清单式推进选 tasks。

python
from agno.team import Team, TeamMode

# broadcast：同一任务发给全部成员再汇总（旧写法 delegate_to_all_members=True）
review_team = Team(
    name="多视角评审团",
    model=model,
    members=[lawyer, engineer, marketer],
    mode=TeamMode.broadcast,
)

# tasks：领导者维护共享任务清单逐项推进，适合长链路交付
delivery_team = Team(
    name="交付小组",
    model=model,
    members=[planner, developer, tester],
    mode=TeamMode.tasks,
)

18.3 领导者如何分派 ​

Coordinate 模式下的完整流程：

  1. Team 收到用户输入；
  2. 领导者分析输入，决定委派给哪些成员；
  3. 领导者为每个选中成员撰写具体子任务（不是简单转发）；
  4. 成员各自执行并返回结果（无依赖的成员可并发执行）；
  5. 领导者把所有产出综合成最终回复。

领导者同样可以自己调工具或直接作答（简单问题不必惊动成员）。给成员设置稳定的显式 id 有助于分派追踪与调试。

18.4 实战：研究员 + 作家双成员团队 ​

python
# research_writer_team.py
import os
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.team import Team, TeamMode
from agno.tools.duckduckgo import DuckDuckGoTools

model = OpenAIChat(
    id="deepseek-chat",
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com/v1",
)

researcher = Agent(
    name="研究员",
    id="researcher",
    role="负责联网搜集资料，只输出事实与来源",
    tools=[DuckDuckGoTools()],           # 研究员专属工具：搜索
)

writer = Agent(
    name="作家",
    id="writer",
    role="负责把资料改写成流畅的中文短文，不做事实核查",
)

team = Team(
    name="内容编辑部",
    model=model,                          # 领导者也需一个模型做分派与综合
    members=[researcher, writer],
    mode=TeamMode.coordinate,
    instructions=[
        "先委派研究员收集素材，再把素材交给作家成文。",
        "最终输出一篇 300 字以内的短文，并附资料来源。",
    ],
    markdown=True,
)

team.print_response("介绍一下 MCP 协议的核心价值")

运行后观察日志可以看到两阶段：先出现研究员的工具调用与返回，随后作家基于素材生成文章，最后领导者润色输出。

18.5 调试与成本控制 ​

  • 看清分派链路：开启 debug_mode=True 或阅读各成员独立的响应与 metrics，确认领导者是否把任务派给了对的成员；
  • 收敛指令：instructions 要明确"谁先谁后、产出什么"，模糊指令会导致领导者来回摇摆；
  • 控制规模：成员数量通常 2–4 个为宜；更多角色应考虑嵌套 Team 或下一章的 Workflow 固定编排；
  • 模型分级：领导者可用便宜快速的模型，重活成员按需配强模型。

本章小结 ​

  • Team = 领导者（分派/综合）+ 多个专职成员（执行），本质是用额外模型调用换取职责分离；
  • TeamMode 四种模式：coordinate（拆解综合）、route（单路转发）、broadcast（全员并行）、tasks（任务清单推进），优先用 mode= 显式声明；
  • Coordinate 流程：分析 → 选人 → 写子任务 → 成员并发执行 → 综合回复；
  • determine_input_for_members=False 可让用户输入原样直达成员；
  • 单 Agent 能解决的任务不要上 Team，注意延迟与 token 成本。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Agno 2.x 中 Team 默认的协作模式是？

2. 希望"同一个问题发给所有成员、再汇总多方观点"，应该用哪种模式？

3. 关于 Team 与单 Agent 的取舍，下列说法正确的是？

4. 在 route 模式下想让用户的原始输入不加改写地传给成员，应设置什么参数？

🛠️ 动手实践 ​

  1. 把 18.4 的团队改为 route 模式并新增一个"翻译员"成员，观察请求是如何被路由到不同成员的。
  2. 用 broadcast 模式让三个不同风格的成员同时点评同一段文案，对比领导者如何汇总分歧意见。
  3. 给研究员成员加一个自定义 @tool 工具，验证团队成员可以拥有与领导者不同的工具集。

掌握了动态协作后，下一章学习确定性的流程编排：第 20 章：Workflow 入门。若想继续深入 Team 的共享状态与成员通信，请等待第 19 章。