第 40 章 · Agno Team 与 Workflow

一个 Agent 扛不动一份像样的市场报告

还是那个跨境卖家。他现在有了一个能查资料、能记住偏好的 Research Agent，于是给了它一个真实任务：“帮我出一份德国玩具市场的机会与风险报告。”这份报告要联网搜最新政策、要查竞品的财务表现、要核对合规手册、最后还要写成一份结论清晰的中文简报。

他把这些能力一股脑全塞进一个 Agent：搜索工具、财务工具、合规知识库、写作指令……结果 Agent 开始犯迷糊——该搜政策时去查了财报，该核合规时又跑去搜新闻，最后输出一篇东拼西凑、结论和依据对不上的报告。不是能力不够，是一个脑子同时干四件专业活，必然顾此失彼。

这正是第 15、16 章处理的问题：当任务复杂到单个 Agent 扛不动时，要么按角色把它拆给多个 Agent 协作，要么按步骤把它拆成一条可控的流水线。Agno 对应两类能力——Team 和 Workflow。这一章要讲清它们各自怎么落地、以及一个关键判断：什么时候用 Team，什么时候用 Workflow，什么时候两个都别用。

概念与主书映射：两种编排，别混用

第 16 章讲多 Agent 协作（谁来做），第 17 章讲 DAG 工作流（按什么步骤做）。Agno 把这两种思路做成了两个不同的原语：

Team（对应第 16 章）：多个各有专长的 Agent 分工协作，由一个协调者动态决定“这一步该问谁”。适合需要专业角色判断、且下一步取决于上一步结果的开放任务。
Workflow（对应第 17 章）：把任务拆成固定的步骤序列，每一步叫什么、谁负责、输入输出是什么都写死。适合流程明确、要恢复、要审计的任务。

一句话区分：Team 解决“谁来做”，Workflow 解决“按什么步骤做”。 Team 的路径是模型运行时决定的、有弹性；Workflow 的路径是你事先编排的、可预测。这个差别决定了它们各自的适用场景，也决定了它们的可观测性——后面会看到，Workflow 的每一步天然可追踪，Team 的协调过程则需要额外观测。

Team：按角色分工

先看 Team。把那个手忙脚乱的 Research Agent 拆成三个专职角色——搜索、财务、主编，每个成员只拿自己该用的工具，由 coordinate 模式的协调者统筹：

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.team.team import Team
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.yfinance import YFinanceTools

web_agent = Agent(
    name="Web Researcher",                   # 成员必须有清晰的 name
    role="搜索最新市场与政策信息",             # role 告诉协调者“这一步该不该问我”
    model=OpenAIChat(id="gpt-4o"),
    tools=[DuckDuckGoTools()],               # 只给搜索工具
    instructions="用中文总结资料，并尽量附上来源链接。",
    markdown=True,
)

finance_agent = Agent(
    name="Finance Analyst",
    role="查询公司与市场财务数据",
    model=OpenAIChat(id="gpt-4o"),
    tools=[YFinanceTools(stock_price=True, company_info=True)],  # 只给财务工具
    instructions="解释财务数据，避免堆砌过度专业的术语。",
    markdown=True,
)

team = Team(
    mode="coordinate",                       # 协调模式：由 leader 动态分派给成员
    members=[web_agent, finance_agent],
    model=OpenAIChat(id="gpt-4o"),           # 这是协调者（leader）用的模型
    instructions=[
        "你是中文商业研究主编。",
        "整合成员的信息，先给结论，再列依据。",
        "成员意见冲突时，明确标出不确定性，不要强行调和。",
    ],
    markdown=True,
)

team.print_response("分析某类跨境玩具在德国市场的机会与风险。", stream=True)

mode="coordinate" 是关键：协调者读完任务后，根据每个成员的 role 决定先问谁、后问谁、要不要追问，最后把结果整合成一份报告。这正是第 16 章讲的“协调者模式”——有一个负责统筹的角色，成员各司其职。

Team 的核心不是把 Agent 越拆越多，而是让每个成员的能力边界更清楚。工具越多，单个 Agent 越容易选错；按角色分配工具，等于给每个成员划定最小权限：

角色	应该拥有	不应该拥有
搜索 Agent	联网搜索、资料整理	财务解释、最终决策权
财务 Agent	财务数据工具	公开网页搜索的全量权限
合规 Agent	政策知识库	改价、下单等写操作
主编 Agent	综合、取舍、输出结构	随意调用所有危险工具

这张表其实就是第 16 章“分工即降低选择空间”的落地：Team 的价值之一，正是把工具按角色切开，让每个成员面对的选择更少、更不容易出错。

Workflow：按步骤流水线

如果任务的步骤是固定的——比如“检索资料 → 写草稿 → 人审 → 发布”——那么用 Workflow 比 Team 更稳。因为你不需要模型每次临场决定顺序，顺序本身就是确定的：

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.workflow.v2 import Step, Workflow

researcher = Agent(
    model=OpenAIChat(id="gpt-4o"),
    instructions="收集德国玩具市场的资料，列出关键发现和来源。",
)

writer = Agent(
    model=OpenAIChat(id="gpt-4o"),
    instructions="把研究要点写成一份结构清晰的中文摘要。",
)

workflow = Workflow(
    name="研究写作流程",
    steps=[
        Step(name="研究阶段", agent=researcher),   # 每一步有名字、有负责的 agent
        Step(name="写作阶段", agent=writer),       # 上一步的输出自动成为下一步的输入
    ],
)

workflow.print_response("研究德国玩具市场的合规风险", markdown=True)

Workflow 的优势是可控与可回放：每一步叫什么、谁负责、输入输出是什么，都能被记录下来。这更接近第 17 章的 DAG 思维——步骤是事先画好的图，不是模型临场发挥。

除了这种顺序执行，Workflow 还能表达更复杂的编排结构：

顺序（sequential）：步骤一个接一个，前一步的输出喂给后一步——上面的例子就是。
并行（parallel）：几个互不依赖的步骤同时跑，比如“同时搜政策、查财务、核合规”，再汇总。对应第 17 章 DAG 里的并行分支，能显著压缩总耗时。
条件（conditional）：根据上一步的结果决定走哪条分支，比如“如果检索到高风险条款，就多加一个法务复核步骤”。
循环（loop）：反复执行某一步直到满足条件，比如“草稿质量不达标就重写，最多三次”。

这四种结构合起来，就把第 17 章讲的 DAG 从概念变成了可执行的编排。关键在于：它们都是你事先声明的，路径可预测、可测试——这正是 Workflow 相对 Team 的根本优势。

Team 和 Workflow 组合起来

真实项目里，二者常常一起用。Workflow 管大阶段，Team 管某个阶段内部的智能协作：

Workflow: 选题 → 研究 → 审校 → 发布
                 │
                 └─→ 这一步内部是一个 Team：
                     搜索 Agent + 合规 Agent + 财务 Agent 协作产出研究结论

也就是说，Workflow 定骨架，Team 填某个关节里的智能。这个结构比“一个超级 Agent 干所有事”更适合生产，因为它同时拿到了两种编排的好处：

每个阶段可观测——卡在哪一步一目了然。
每个角色权限更小——搜索的碰不到改价。
某一步失败可以单独重试，不用从头再来。
人审节点可以插在任意阶段之间。
评测可以按阶段拆分，而不是只看最终一锤子输出。

深入一层：coordinate 到底在做什么，以及和 pi 的分野

coordinate 模式下，协调者是怎么决定问谁的？ 它本质上把每个成员当成一个工具来调用——成员的 name 和 role 就是这个“工具”的名字和说明。协调者读完任务，像调用工具一样“调用”某个成员、拿到结果、再决定下一步。所以第 4 章那条“工具的 docstring 就是模型看到的说明”在这里同样成立：成员的 role 写得含糊，协调者就会分派错人。 把 role 当成“这个成员的招聘启事”来写，才不会出现该搜政策却问了财务的情况。

Team 和 Workflow 最本质的区别在哪？ 在于路径由谁决定。Team 的执行路径是协调者在运行时动态决定的——灵活，但也意味着每次跑的路径可能不同，较难精确复现和审计。Workflow 的路径是你事先编排死的——可预测、可回放、可按步测试。所以一条经验法则是：步骤能事先画出来的，用 Workflow；下一步取决于上一步内容、画不出固定图的，才用 Team。 对“要审计、要恢复”的生产流程，Workflow 的确定性几乎总是更值钱。

这和 pi 的做法什么关系？ 第 15、16 章里，pi 作为 harness 并不内建 Team 或 Workflow 这样的高层原语——多 Agent 协作在 pi 里是“把子 Agent 当成一个工具/服务来调用”，工作流是“你自己写的编排代码或状态机”。pi 给你的是最底层的积木和完全的掌控；Agno 则把“协调者调度成员”和“步骤编排”封装成了 Team 和 Workflow 两个现成组件。同样一套多 Agent 与 DAG 方法论，Agno 换来的是几行代码就能起一个团队或流水线，代价是协调逻辑、路径选择这些细节被收进了框架内部，观测和调优要顺着它的接口来。

什么时候别上 Team/Workflow

不要为了显得高级而过早编排。以下情况，单个 Agent 反而更合适：

任务只需要一个工具或一个知识库就能完成。
没有清晰的角色边界——硬拆只会增加协调开销。
步骤不固定，每次都高度开放——那 Workflow 的确定性用不上。
还没有评测样本，无法判断“拆了之后到底有没有变好”。

正确的顺序是：先用单 Agent 跑通，再根据真实的失败点去拆。 第 16 章说得很直接——编排是为了解决复杂性，不是制造复杂性。没有 baseline 就上多 Agent，往往只是把一个可控的问题拆成了几个更难观测的问题。

动手看看

拿本章的例子做起点，做三个小实验：

给上面的 Team 再加一个 compliance_agent（挂第 38 章那个合规知识库），问一个同时涉及政策、财务、合规的问题，打开 show_tool_calls，观察协调者是按什么顺序分派给三个成员的——你会直观看到 role 如何影响分派。
把某个成员的 role 故意写得很含糊（比如只写“帮忙”），再跑一次，看协调者是不是开始分派错人。这就是“role 即招聘启事”的反面教材。
把 Workflow 的两步顺序流，改成先并行跑“搜索”和“财务”两步、再汇总的结构（如果 API 支持声明并行步骤），对比总耗时的变化——这是 DAG 并行分支省时的直接体现。

实战中的几个坑

坑一：成员 role 写得含糊，协调者分派错人。

现象：该让搜索 Agent 干的活，被派给了财务 Agent，输出驴唇不对马嘴。
原因：coordinate 模式把成员当工具调，role 就是模型看到的说明，含糊等于没说清。
对策：把每个成员的 role 当“招聘启事”写清楚——擅长什么、什么任务该找它、什么不该。

坑二：该用 Workflow 的固定流程，硬上了 Team。

现象：一个明明是“检索→写→审→发”的固定流程，用 Team 跑得每次路径都不一样，没法复现也没法审计。
原因：把“步骤确定的任务”交给了运行时动态调度，白白丢掉了确定性。
对策：步骤能事先画出来的用 Workflow，只有下一步取决于上一步内容时才用 Team。

坑三：工具没按角色切，每个成员都能碰危险操作。

现象：搜索 Agent 居然也能调改价工具，越权风险散落在每个成员身上。
原因：图省事给所有成员挂了同一套全量工具，没有按角色做最小权限分配。
对策：按上文那张角色权限表分配工具，写操作只给该有的成员，配合第 37 章的 human-in-the-loop。

坑四：没有单 Agent baseline 就上多 Agent。

现象：拆成 Team 后感觉“更专业”，但说不清到底比单 Agent 好在哪，成本还翻了几倍。
原因：没有评测样本作对照，编排的收益全靠感觉。
对策：先跑通单 Agent 并留下评测样本，再按真实失败点拆分，用数据证明编排确实更好。

Agno vs 主书 pi 做法

能力	Agno 怎么做	pi（harness）怎么做	各自适合谁
多 Agent 协作	`Team(mode="coordinate", members=[...])`，协调者动态分派	把子 Agent 当成工具/服务调用，自己写调度逻辑	Agno 几行起一个团队；pi 完全掌控调度
角色与权限	成员的 `name`/`role` + 各自的 `tools` 切分	每个子 Agent 的能力与权限由你在接入时定义	两者理念一致，Agno 把角色做成了字段
步骤编排	`Workflow(steps=[Step(...)])`，声明顺序/并行/条件/循环	自己写编排代码或状态机表达 DAG	Agno 声明式更快；pi 灵活到任意控制流
路径可预测性	Workflow 路径事先编排、可回放；Team 路径运行时动态	编排逻辑是你写的代码，可预测性由你保证	要审计/恢复选 Workflow 或 pi 的显式编排
组合使用	Team 可嵌进 Workflow 的某个 Step	自由组合，边界由你的代码定义	Agno 提供现成组合；pi 无框架约束

分野和前几章一致：Agno 是应用框架，把“协调者调度成员”和“步骤编排”封装成 Team 和 Workflow 两个开箱即用的原语，让你几行代码就能起一个团队或一条流水线；pi 是 harness，把多 Agent 协作看作“调用子 Agent 服务”、把工作流看作“你自己写的编排代码”，更灵活、也更要求你亲手把路径和权限编排清楚。底层是同一套方法论——协调者模式、DAG 编排——只是抽象层次不同。而“该用 Team 还是 Workflow、该不该编排”的判断，无论用哪个框架，都得回到那句话：编排是为了解决复杂性，不是制造复杂性。

工程检查项

每个 Team 成员是否有清晰的 name/role/instructions？
工具是否按角色做了最小化分配，写操作是否只给了该有的成员？
Workflow 的每一步是否有可测试的输入输出？
高风险步骤之间是否插入了人审节点？
是否能记录每个成员、每个步骤的成本、延迟和失败？
是否有单 Agent baseline，用来证明 Team/Workflow 确实带来了改进？

小结

Team 解决“谁来做”（对应第 16 章）：mode="coordinate" 由协调者按成员 role 动态分派，适合需要专业角色判断、路径开放的任务。
Workflow 解决“按什么步骤做”（对应第 17 章）：Step 声明顺序/并行/条件/循环，路径事先编排、可预测、可回放，适合要恢复、要审计的固定流程。
二者可组合：Workflow 定骨架，Team 填某个关节里的智能协作——比“一个超级 Agent”更可观测、权限更小、失败可重试。
成员 role 就是招聘启事：coordinate 把成员当工具调，role 写含糊就会分派错人；工具要按角色做最小权限切分。
别过早编排：先用单 Agent 跑通并留下评测 baseline，再按真实失败点拆分——编排是为了解决复杂性，不是制造复杂性。

现在 Research Agent 已经从单打独斗成长为一支分工明确、流程可控的团队。但它仍然只活在一个本地 Python 脚本里，跑完就停。下一章，我们把这套能力推上运行时——让它变成一个能被远程调用、能观测、能恢复、能取消的服务。