Beaver Agent Team Explained

先记住一句话

责任边界

用户

只说想要什么。

例如：做 MGM/Galaxy 财报对比

Skill Resolver

负责选 Skill。

选中 mgm-galaxy...

Main Agent

负责决定是否用 Team，并提交 Team 参数。

调用 run_agent_team

TaskExecutionPlanner

负责把 JSON 变成 ExecutionGraph。

校验 / 修复 / fallback

Scheduler

负责按 DAG 调度子 Agent。

谁先跑 / 谁等谁

Final Synthesis

负责只总结已经完成的 Team 结果。

不能再说“我将启动 Team”

成功案例：MGM/Galaxy

Skill 有模板

读到的 Skill

mgm-galaxy-financial-chart-report-safe → 里面有 beaver-team-template → DAG 已经写好

Main Agent 应输出

第一轮不要先 web_search → 调用 run_agent_team → 传 task-only nodes

谁加载 DAG

Main Agent 不直接加载 → TaskExecutionPlanner 适配 → Scheduler 执行

collect_official_sources

收集官方来源。

应绑定搜索 Skillweb_search/web_fetch

extract_financial_metrics

从来源提取指标。

depends_on collect

validate_metrics

校验周期、币种、单位。

no tools

generate_chart_report

生成 Markdown 报告。

no chart image claim

MGM Skill 自身有没有问题？

DAG 结构是对的。真正可能有问题的是 use_skill: "web-operation" 如果环境里没有这个 exact Skill，会走 fallback。更稳的写法是绑定当前实际存在的搜索 Skill，或者只保留 skill_query。

坏案例：韩国队任务

Skill 没有 Team 模板

读到的 Skill

multi-search-engine → 只是搜索指导 → 没有 beaver-team-template

Planner 产出的坏 DAG

strategy=parallel → collect analyze_tactics analyze_players analyze_media

实际加载后

4 个节点同时 ready → 分析节点没等 collect → 没有上游 evidence

collect 节点

有搜索 Skill，有工具，真的查了。

tool_count > 0

analyze 节点

说“基于搜索结果”，但没有依赖 collect。

容易模拟容易空写

坏 DAG 的真实形状

问题在图，不在总结

Main Agent / Planner 错误输出

{
  "strategy": "parallel",
  "nodes": [
    {"node_id": "collect", "task": "搜索韩国队表现"},
    {"node_id": "analyze_tactics", "task": "基于搜索结果分析战术"},
    {"node_id": "analyze_players", "task": "基于搜索结果分析球员"},
    {"node_id": "analyze_media", "task": "基于搜索结果分析媒体"}
  ]
}

应该修成这样

{
  "strategy": "dag",
  "nodes": [
    {"node_id": "collect", "task": "搜索韩国队表现"},
    {"node_id": "analyze_tactics", "depends_on": ["collect"]},
    {"node_id": "analyze_players", "depends_on": ["collect"]},
    {"node_id": "analyze_media", "depends_on": ["collect"]},
    {"node_id": "synthesize", "depends_on": [
      "analyze_tactics", "analyze_players", "analyze_media"
    ]}
  ]
}

如果 Main Agent 要输出 Team，它到底该输出什么

run_agent_team 参数

Main Agent 不输出“角色”。它输出 run_agent_team 的 JSON 参数：strategy + nodes + depends_on。

类型 1：顺序流水线

A → B → C

collect

先拿资料。

extract

再提取。

report

最后输出。

Main Agent 应输出

{
  "strategy": "dag",
  "nodes": [
    {"node_id": "collect", "task": "收集资料"},
    {"node_id": "extract", "task": "提取指标", "depends_on": ["collect"]},
    {"node_id": "report", "task": "生成报告", "depends_on": ["extract"]}
  ]
}

类型 2：真正并行

互不依赖

source_a

独立来源 A。

source_b

独立来源 B。

source_c

独立来源 C。

Main Agent 应输出

{
  "strategy": "parallel",
  "nodes": [
    {"node_id": "source_a", "task": "查官方公告"},
    {"node_id": "source_b", "task": "查媒体报道"},
    {"node_id": "source_c", "task": "查数据网站"}
  ]
}

类型 3：先 collect，再并行分析

最常见

collect

统一事实池。

→

analyze_a

角度 A。

analyze_b

角度 B。

analyze_c

角度 C。

→

synthesize

合并。

Main Agent 应输出

{
  "strategy": "dag",
  "nodes": [
    {"node_id": "collect", "task": "收集事实材料"},
    {"node_id": "analyze_a", "depends_on": ["collect"]},
    {"node_id": "analyze_b", "depends_on": ["collect"]},
    {"node_id": "analyze_c", "depends_on": ["collect"]},
    {"node_id": "synthesize", "depends_on": ["analyze_a", "analyze_b", "analyze_c"]}
  ]
}

类型 4：带校验门的报告

finance 常用

collect

来源。

extract

指标。

validate

校验。

report

报告。

Main Agent 应输出

{
  "strategy": "dag",
  "nodes": [
    {"node_id": "collect", "required_evidence": ["tool_result", "url"], "block_downstream_on_partial": true},
    {"node_id": "extract", "depends_on": ["collect"], "block_downstream_on_partial": true},
    {"node_id": "validate", "depends_on": ["extract"], "requested_tools": []},
    {"node_id": "report", "depends_on": ["validate"], "requested_tools": []}
  ]
}

输出规则：不要输出这些

错误格式

×

不要输出 agent.role = researcher / writer / reviewer。

×

不要把“基于搜索结果”的节点放到 parallel 里。

×

不要让最终节点再调用工具，除非明确需要。

Skill 里面的 demo 长什么样

简化版

mgm-galaxy-financial-chart-report-safe.SKILL.md

---
name: mgm-galaxy-financial-chart-report-safe
tools:
  - web_search
  - web_fetch
---

```beaver-team-template
{
  "strategy": "dag",
  "nodes": [
    {
      "node_id": "collect_official_sources",
      "task": "Collect official MGM and Galaxy financial disclosures.",
      "use_skill": "web-operation",
      "skill_query": "official financial disclosure web research",
      "requested_tools": ["web_search", "web_fetch"],
      "required_evidence": ["tool_result", "url"],
      "block_downstream_on_partial": true
    },
    {
      "node_id": "extract_financial_metrics",
      "task": "Extract comparable metrics from collected official sources.",
      "depends_on": ["collect_official_sources"],
      "requested_tools": ["web_fetch"],
      "block_downstream_on_partial": true
    },
    {
      "node_id": "validate_metrics",
      "task": "Validate period, currency, unit, and source consistency.",
      "depends_on": ["extract_financial_metrics"],
      "requested_tools": []
    },
    {
      "node_id": "generate_chart_report",
      "task": "Generate Markdown table and chart-ready data.",
      "depends_on": ["validate_metrics"],
      "requested_tools": []
    }
  ]
}
```

加载链路：谁把 Skill 变成 DAG

实际责任人

1. Skill Catalog

读 SKILL.md→解析 beaver-team-template→SkillRecord.team_template

2. Context Builder

SkillRecord→SkillContext.team_template→给 Planner / Main Agent 看

3. Main Agent

看到 primary template→选择 run_agent_team→传 task-only JSON

4. Planner

校验 JSON→构造 ExecutionGraph→每个 node 是 generic worker

5. Scheduler

按 depends_on 找 ready node→创建 DelegationEnvelope→LocalAgentRunner 执行

每个子 Agent 怎么选 Skill

优先级

第一优先：use_skill

精确绑定。比如 use_skill: "web-operation"。

第二优先：skill_query

exact 找不到，就按 query 动态找。

第三优先：node task

query 也不行，就用节点任务文本找。

最后兜底：ephemeral guidance

没有合适 Skill，也不 hard fail，继续跑。

为什么 MGM 仍可能不稳？

如果 Steven 里没有 web-operation，collect 节点不会 exact bind，只能 fallback。DAG 没错，但 Skill 绑定名需要和真实环境对齐。

复杂 DAG 怎么办：不是只能一条线

多阶段 DAG

collect_base

先拿共同材料。

→

analyze_market

市场角度。

analyze_finance

财务角度。

analyze_risk

风险角度。

→

merge_findings

合并。

validate_claims

校验。

final_report

输出。

复杂 DAG 的关键不是 strategy 名字，而是 depends_on

[
  {"node_id": "collect_base"},
  {"node_id": "analyze_market", "depends_on": ["collect_base"]},
  {"node_id": "analyze_finance", "depends_on": ["collect_base"]},
  {"node_id": "analyze_risk", "depends_on": ["collect_base"]},
  {"node_id": "merge_findings", "depends_on": ["analyze_market", "analyze_finance", "analyze_risk"]},
  {"node_id": "validate_claims", "depends_on": ["merge_findings"]},
  {"node_id": "final_report", "depends_on": ["validate_claims"]}
]

先别记术语，只看四类错误

从左到右定位

1. 图错了

DAG 依赖关系错。

韩国队 case

2. Skill 没绑上

use_skill 不存在，工具没装出来。

web-operation miss

3. 节点输出不合格

没证据、raw tool call、模拟搜索。

partial / failed

4. 最终总结跑偏

Team 已完成，但总结又说“我将启动 Team”。

fake final

当前已经有的机制

已有

问题

系统怎么处理

结果

Planner JSON 格式错

repair 一次

还错就 fallback single

use_skill 找不到

fallback 到 skill_query

不直接 hard fail

工具不在 allowed_tool_names

AgentLoop 过滤 + ToolExecutor 二次拒绝

工具不可用

required_evidence 缺失

节点 partial / success=false

按 block 设置决定是否阻断

finalized 还是 raw tool call

不能标 succeeded

节点 failed

还应该补的机制

下一步重点

问题

应该怎么处理

为什么

“基于搜索结果”的节点没有 depends_on

Planner repair DAG

坏图不能执行

parallel 用错

改成 dag / safe sequence

防止分析节点空跑

节点声称搜索但 tool_count=0

判 partial 或 retry node

防止“模拟搜索”成功

final synthesis 输出“我将启动 Team”

判失败并重试一次总结

Team 已经跑完，不能再规划

一条错误从哪里冒出来，就在哪里处理

定位图

DAG 生成阶段

字段错→repair→fallback 依赖错→repair DAG→禁止执行坏图

节点执行阶段

Skill miss→skill_query→ephemeral guidance 工具 denied→node failed

证据判断阶段

required_evidence 满足→succeeded 缺证据→partial block=true→阻断下游

最终输出阶段

required 节点全成功→complete required 节点有 partial/failed→incomplete 输出又开始规划→应该重试总结

Swarms 是怎么工作的

先选工作流，再跑 Agent

1. 先定义 Agent

每个 Agent 有名字、系统提示词、工具、模型。

Agent = worker

2. 再选择 Workflow

顺序、并行、图、群聊、层级等。

workflow first

3. 明确连接关系

谁先跑、谁依赖谁、谁把结果给谁。

edges / flow

4. Runtime 执行

按 workflow 调度，不靠模型临场猜顺序。

orchestration

Swarms 常见多步形态

workflow shapes

类型

关系

适合

SequentialWorkflow

A → B → C

一步接一步的流水线

ConcurrentWorkflow

A ∥ B ∥ C

互不依赖的并行任务

AgentRearrange

agent1 → agent2 → agent3

用字符串表达 agent 流向

GraphWorkflow

节点 + 边

复杂 DAG，拓扑调度

Mixture / Group / Hierarchical

多个 Agent 协作或分层

讨论、投票、管理者分派

多步怎么表达

不是一句 prompt

Agent A

收集事实。

→

Agent B

分析视角 1。

Agent C

分析视角 2。

Agent D

分析视角 3。

→

Agent E

合并总结。

关键点

Swarms 的强项不是“提示词更神”，而是把多 Agent 的关系做成显式 workflow。模型负责单步任务，框架负责调度关系。

Swarms 思路对 Beaver 的启发

拿 workflow，不拿固定角色

✓

保留 Beaver 的 generic worker，不必变成 researcher/writer/reviewer。

✓

学习 Swarms 的显式 workflow：sequence / parallel / graph / hierarchy。

!

不要让 LLM 自由猜 DAG；让它选择 workflow shape 或填槽。

✓

Runtime 根据结构执行，LLM 只负责节点内完成任务。

我们和 Swarms 的差别

现在的问题在这里

维度

Swarms

Beaver 当前

工作流来源

开发者显式选择 workflow

Planner / Main Agent 临场生成 JSON

Agent 定义

通常是具名 Agent + 角色/工具

generic worker，role 为空

依赖关系

flow / edge 是一等公民

depends_on 只是字段，提示不够强

复杂多步

GraphWorkflow / AgentRearrange

让 LLM 自己写 DAG，容易写错

Skill

不是核心概念

Skill 是 Beaver 的优势：可提供模板、工具、约束

Beaver 做对的地方

保留

Skill-first

用户不用懂 Agent 架构，Skill 可以携带业务模板。

Generic worker

不把产品锁死在固定 researcher/writer 角色。

工具安全上限

allowed_tool_names 可以限制节点越权。

Evidence gate

节点是否完成可以和证据绑定。

Beaver 当前缺的地方

要补

Workflow shape 不明确

没有先选 sequence / collect-then-parallel / graph。

depends_on 语义没教

prompt 只列字段，没有规则。

坏 DAG 没被拦

parallel 用错也会执行。

final synthesis 不够硬

Team 已跑完还可能输出“我要启动 Team”。

正确定位

Beaver ≠ 复制 Swarms

不要变成

固定角色 Agent 库+用户手写 workflow+没有 Skill 语义

应该变成

Skill Template+Generic Worker+显式 Workflow Shape+Runtime 校验 DAG

我们现在明确要做什么

本地 MCP Workflow 工具

1. Main Agent

不再手写复杂 DAG。它只选择一个 workflow 工具。

Sequential / Concurrent / Graph...

2. 本地 MCP Server

永远本地加载，专门暴露 Team Workflow tools。

local_team_workflow_mcp

3. Workflow Tool

每个 workflow 单独一个 Python 实现文件。

sequential.py / graph.py...

4. Beaver Runtime

工具内部生成现有 ExecutionGraph，再交给 Scheduler 跑。

不新增 Team runtime

最终调用模型

workflow = tool

Agent 看到

SequentialWorkflowConcurrentWorkflowGraphWorkflowMixtureOfAgents

Agent 填写

task+agents[]+每个 agent 的 instruction / skill_query

工具负责

生成 depends_on→校验结构→启动 Team

关键变化

不是一个 run_swarm_workflow(architecture=...) 大工具；而是每种 architecture 自己就是一个工具。这样工具 schema 更短，LLM 更容易选对。

建议工具清单

MCP tools

工具

Agent 必填什么

系统怎么连

SequentialWorkflow

agents[]

按顺序 A → B → C

ConcurrentWorkflow

agents[]

全部并行，无依赖

MixtureOfAgents

agents[], aggregator

并行专家 → 聚合者

AgentRearrange

agents[], flow

解析 flow 字符串

GraphWorkflow

agents[], edges[], output_agent

严格按 edges 执行

GroupChat

agents[], rounds

多轮讨论后汇总

HierarchicalSwarm

manager, agents[]

manager 分派和汇总

完整运行链路

保持 Beaver 现有 runtime

工具加载

config loader→local_team_workflow_mcp→MCPToolWrapper→AgentLoop tools

用户任务

Main Agent→选择 Workflow tool→填写 agents→tool 生成 ExecutionGraph

执行

TeamService→Scheduler→LocalAgentRunner→Evidence / synthesis

代码放哪里、改哪些文件

implementation map

配置层

把 workflow MCP 加入永远加载的本地 MCP 列表。

foundation/config/loader.py

MCP 层

tools_server 增加 team_workflow category。

interfaces/mcp/tools_server.py

Workflow 层

每个 workflow 一个 Python 文件。

beaver/team_workflows/*.py

Runtime 层

复用 ExecutionGraph / Scheduler / LocalAgentRunner。

不新增 runtime

新增目录

workflow implementations

new package

app-instance/backend/beaver/team_workflows/
  __init__.py
  base.py
  mcp_tools.py
  sequential.py
  concurrent.py
  mixture_of_agents.py
  agent_rearrange.py
  graph.py
  group_chat.py
  hierarchical.py

设计原则

base.py 放公共 WorkerSpec、schema 解析、ExecutionNode 构造、图校验；每个 workflow 文件只实现自己的连线规则。

修改现有文件

integration points

文件

改动

foundation/config/loader.py

新增 local_team_workflow_mcp，永远本地加载

interfaces/mcp/tools_server.py

新增 team_workflow category，返回 workflow tools

tools/mcp/wrapper.py

原则上不改；继续包装 MCP tools

tools/builtins/agent_team.py

原则上不改；workflow tool 复用同一 TeamService 路径

coordinator/*

原则上不改；继续执行 ExecutionGraph

每个 workflow 文件怎么做

file responsibilities

文件

职责

连线规则

sequential.py

SequentialWorkflow

agents[i] 依赖 agents[i-1]

concurrent.py

ConcurrentWorkflow

所有 agents 无依赖并行

mixture_of_agents.py

MixtureOfAgents

所有专家 → aggregator

agent_rearrange.py

AgentRearrange

解析 flow，再生成边

graph.py

GraphWorkflow

edges[] 必填，严格校验无环和引用

group_chat.py

GroupChat

v1 可先不做，或 rounds → 顺序轮次

hierarchical.py

HierarchicalSwarm

v2；manager 分派 workers 后汇总

本地 MCP Server 包装方式

always loaded

loading path

foundation/config/loader.py
→ LOCAL_MCP_CATEGORIES["local_team_workflow_mcp"] = {"category": "team_workflow", ...}
→ python -m beaver.interfaces.mcp.tools_server --category team_workflow
→ tools_server._category_tools("team_workflow")
→ beaver.team_workflows.mcp_tools.create_team_workflow_tools()
→ MCPToolWrapper exposes tools to AgentLoop

边界范围

明确不做什么

✓

做：本地 MCP workflow tools、每个 workflow 单独 py、args → ExecutionGraph、复用 TeamService/Scheduler。

×

不做：新 Team runtime、固定角色 Agent registry、nested Team、前端改造、chart renderer、高风险审批 UI。

Planner 的位置

Planner 可以继续作为兼容路径存在，但不再是 Agent Team 成败的核心入口。主路径是 Main Agent 在 AgentLoop 中调用具体 workflow MCP tool。

最终定稿：每个 Team Workflow 本身就是一个工具

workflow = tool

Main Agent

只负责选哪个 workflow 工具。

SequentialWorkflow / GraphWorkflow...

填 agents

args 主要是 agents / instruction / skill_query。

不是手写自由 DAG

Workflow 工具

根据自己的规则生成 ExecutionGraph。

内部生成 depends_on

Scheduler

执行 Graph，收集 evidence，最终总结。

runtime owns orchestration

SequentialWorkflow 工具

agents 顺序就是执行顺序

tool call

{
  "tool": "SequentialWorkflow",
  "arguments": {
    "task": "比较 MGM China 和 Galaxy Entertainment，输出中文财务报告",
    "agents": [
      {"name": "source_collector", "instruction": "收集官方财务披露来源"},
      {"name": "metric_extractor", "instruction": "提取收入、EBITDA、净利润等指标"},
      {"name": "validator", "instruction": "校验来源、周期、币种、单位"},
      {"name": "reporter", "instruction": "生成 Markdown 报告和 chart-ready data"}
    ]
  }
}

工具内部生成

source_collector → metric_extractor → validator → reporter。Main Agent 不需要写 depends_on。

ConcurrentWorkflow 工具

agents 全部并行

tool call

{
  "tool": "ConcurrentWorkflow",
  "arguments": {
    "task": "从多个独立来源调研同一主题",
    "agents": [
      {"name": "official_sources", "instruction": "查官方来源"},
      {"name": "media_sources", "instruction": "查媒体报道"},
      {"name": "data_sources", "instruction": "查数据网站"}
    ]
  }
}

工具内部生成

所有 agents 无依赖并行执行。只有真正互不依赖的任务才用它。

GraphWorkflow：高级工具，edges 是必填 args

explicit graph

GraphWorkflow tool call

{
  "tool": "GraphWorkflow",
  "arguments": {
    "task": "分析今天早上韩国队在世界杯上的表现，输出中文结构化报告",
    "agents": [
      {"name": "collector", "instruction": "收集比赛事实、比分、关键事件和可靠来源", "skill_query": "multi search sports news"},
      {"name": "tactics", "instruction": "基于 collector 的结果分析战术表现"},
      {"name": "players", "instruction": "基于 collector 的结果分析球员表现"},
      {"name": "media", "instruction": "基于 collector 的结果分析媒体舆论"},
      {"name": "synthesizer", "instruction": "合并所有分析，输出最终中文报告"}
    ],
    "edges": [
      ["collector", "tactics"],
      ["collector", "players"],
      ["collector", "media"],
      ["tactics", "synthesizer"],
      ["players", "synthesizer"],
      ["media", "synthesizer"]
    ],
    "output_agent": "synthesizer"
  }
}

精确定义

GraphWorkflow 不是让 Agent 写自然语言 flow，也不是自由 DAG 文本。它是工具，edges 是 args schema 的必填字段，runtime 必须校验无环、节点存在、output_agent 可达。

每种 workflow 工具暴露什么 args

schema contract

工具

必填 args

工具内部怎么连

SequentialWorkflow

task, agents[]

按 agents 顺序生成链式依赖

ConcurrentWorkflow

task, agents[]

全部并行，无依赖

MixtureOfAgents

task, agents[], aggregator

非 aggregator 并行 → aggregator

AgentRearrange

task, agents[], flow

flow 是结构参数，按工具规则解析

GraphWorkflow

task, agents[], edges[], output_agent

edges 必填，runtime 严格校验

GroupChat

task, agents[], moderator/rounds

轮流发言，moderator/last agent 汇总

HierarchicalSwarm

task, manager, agents[]

manager 分派，workers 执行，manager 汇总

几种方案对比

LLM 难度越低越稳

方案

LLM 要做什么

综合判断

A. 自由输出 DAG JSON

自己判断类型、节点、依赖、工具、证据

最灵活，最容易错

B. 一个 run_swarm_workflow + architecture 参数

选 architecture + 填 agents/flow/edges

比自由 DAG 好，但工具语义不够清晰

C. Skill Template 严格驱动

只适配已有模板

业务场景最稳

D. 每个 workflow 是一个工具

选工具 + 填 agents/instructions

推荐主线；最接近 swarms architecture

E. GraphWorkflow 工具

填 agents + 必填 edges + output_agent

高级路径；显式但受 schema 约束

10 个从简单到复杂的场景

1 最简单，10 最难

1

单问答

例如“解释一下 EBITDA”。不需要 Team。最佳：single_agent。

2

单工具查询

例如“查今天珠海天气”。最佳：single_agent + tool。

3

单来源总结

给一个 URL，让它总结。最佳：single_agent。

4

多来源独立搜索

多个来源互不依赖。最佳：ConcurrentWorkflow。

5

先收集再多角度分析

韩国队这类。最佳：GraphWorkflow 或 AgentRearrange，edges/flow 必须表达 collector → analyses → synthesizer。

6

财务来源→指标→校验→报告

MGM/Galaxy。最佳：SequentialWorkflow，agents 顺序生成依赖。

7

多轮修订任务

用户验收失败后重跑部分节点。需要 run version + evidence reuse。

8

复杂 DAG：并行后合并再并行

需要显式 dependency。最佳：GraphWorkflow，edges 是必填 args。

9

需要判断证据是否充分

需要 LLM judge / evidence contract。不能只看 finish_reason。

10

动态协作 / 运行中新增节点

接近 Swarms 高级编排。需要独立设计，不应 v1 直接做。