数据截至 (上游 commit 11cdf466d042)
MetaGPT — 多智能体软件公司框架:架构与原理
30 秒导读: MetaGPT 把「一家软件公司怎么运作」这套标准作业流程(SOP,Standard Operating Procedure)写进一队 LLM 角色里。你丢进一句话需求(「做个 2048 游戏」),产品经理写 PRD、 架构师出设计、工程师写代码——角色之间不直接互相调用函数,而是把产物当消息发到一个共享 环境里,谁「订阅」了这类产物就自动被触发 接力。一句话哲学:
Code = SOP(Team)。
1. 这是什么(零基础也能懂)
-
一句话定义: MetaGPT 是一个多智能体(multi-agent)框架——让多个各有分工的 LLM 角色, 按一套模拟真实软件公司的流程协作,把一句话需求变成需求文档、架构设计、可运行的代码仓库。
-
解决什么问题 / 给谁用: 单个 LLM 一口气写完整个项目容易「想哪写哪」、丢三落四。MetaGPT 的思路是:把复杂任务拆成公司里的岗位与交接流程,每个岗位只干一件擅长的事、只在拿到上游 产物时才动手。给谁用?想让 AI 端到端产出软件的开发者、研究多智能体协作的人。
-
它能做什么:
- 从一行需求生成用户故事、竞品分析、需求文档(PRD)、数据结构、API 设计、代码。
- 提供一整套「软件公司」角色:产品经理 / 架构师 / 项目经理 / 工程师 / 数据分析师。
- 既支持固定流水线(经典 SOP),也支持由 TeamLeader 动态调度的自由智能体团队(MGX)。
-
用起来什么样: 命令行一句话即可启动一整支团队跑起来。
# 安装后,一句需求启动整个「软件公司」metagpt "Create a 2048 game"它对应的 Python 入口是把一队角色「雇」进一个
Team,再投点「预算」跑几轮:# 示意,非源码:generate_repo 的核心骨架(见 software_company.py)company = Team(context=ctx)company.hire([TeamLeader(), ProductManager(), Architect(), Engineer2(), DataAnalyst()])company.invest(investment=3.0) # 预算上限,超支就停asyncio.run(company.run(n_round=5, idea="Create a 2048 game")) -
一句话直觉 / 类比: 把它想成一家会自己运转的微型软件公司:需求是老板拍下来的一句话, 员工各就各位;唯一的沟通方式是往公司公告栏(环境)贴东西,别人看到与自己相关的就接着干。
本节不谈底层代码。目标:完全不懂的人读完知道「这是干嘛的」。
2. 顶层全景(它大概怎么转)
2.1 核心哲学:Code = SOP(Team)
MetaGPT 的全部设计都从一句话展开:把标准作业流程(SOP)当成一个函数,作用在一支团队上。
- Team(团队) = 一群 角色 + 一个共享环境。
- SOP(流程) = 「谁看到什么产物就该接着做什么」的规则。
- 把 SOP 施加到 Team 上,就「跑」出了软件——所以叫
Code = SOP(Team)。
2.2 四层结构
整个框架自底向上是四层积木,上层由下层拼成:
┌─────────────────────────────────────────────┐
一句话需求 ──▶ │ Team（团队） ── 投预算、跑 N 轮、最后归档 │
│ └── Environment（共享环境 = 消息总线） │
└───────────────────┬─────────────────────────┘
│ 广播 / 订阅 Message
┌──────── ──────┬───────┴───────┬──────────────┐
▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Role A │ │ Role B │ │ Role C │ │ ... │ ← 角色 = 智能体原子
│ 观察-思考-行动 每个角色内部是一个 观察→思考→行动 循环 │
└────┬────┘ └────┬────┘ └────┬────┘ └─────────┘
│ 执行 │ │
▼ ▼ ▼
Action ─────▶ ActionNode（把 LLM 的自由文本压成结构化产物） ← 工作单元
怎么读这张图: 从上往下是「谁包含谁」。需求进入 Team,Team 持有一个 Environment(消息 总线);角色都挂在环境上,各自跑「观察-思考-行动」循环;角色行动时执行 Action,Action 常借 ActionNode 把 LLM 输出变成结构化数据(PRD、设计、代码)。
2.3 部件一句话职责
| 部件 | 干什么 | 在哪个文件 |
|---|---|---|
Team | 雇角色、管预算、驱动 N 轮运行、结束归档 | metagpt/team.py:32 |
Environment | 共享消息总线:按订阅地址把消息投递给角色 | metagpt/environment/base_env.py:124 |
Role | 智能体原子:观察消息→思考选动作→行动产出 | metagpt/roles/role.py:125 |
Action | 一个工作单元(写 PRD、写代码…),封装一次 LLM 调用 | metagpt/actions/action.py:29 |
ActionNode | 把 LLM 自由文本按 schema 解析成结构化对象 | metagpt/actions/action_node.py:135 |
Message | 角色之间流转的产物,带 cause_by/send_to 路由信息 | metagpt/schema.py:232 |
MGXEnv | 让 TeamLeader 接管消息发布的动态团队环境 | metagpt/environment/mgx/mgx_env.py:11 |
RoleZero | 能动态思考、每轮自选工具命令的通用智能体基类 | metagpt/roles/di/role_zero.py:55 |
2.4 主线走一遍(高层,不进代码)
一次运行从需求到产物,大致这样流动:
需求 ──▶ Team.run_project 把 Message 发到 Environment
│
▼ 每一轮(round),Environment 让所有「不空闲」的角色并发跑一次
Role.run: _observe（挑出我订阅的新消息）
└─▶ _think（决定这轮做哪个 Action）
└─▶ _act（跑 Action,产出新 Message）
└─▶ publish_message（发回 Environment）
│
▼ 新消息又触发下游角色…… 如此接力,直到没有新活(全部 idle)或轮数用尽
产物汇聚成一个代码仓库
关键点:角色之间零直接调用。 产品经理写完 PRD 不会「call 架构师」;它只是把 PRD 消息发到
环境,而架构师订阅了 PRD 这类产物(_watch({WritePRD})),于是下一轮自然被唤醒。这种
「谁产出什么就触发谁」的发布-订阅关系,就是 SOP 被编码进代码的地方。
3. 阅读地图(建议顺序)
本子库分五章,由浅入深。先建立「角色循环 + 消息总线」这两块地基,再看两种上层玩法 (固定流水线 vs 动态团队)。
| 顺序 | 章节 | 讲什么 | 读完你会 |
|---|---|---|---|
| 0 | MetaGPT 是什么 · 全景 · 阅读地图 | 本页:全景与导航 | 知道整体怎么拼 |
| 1 | Role:观察-思考-行动的智能体原子 | Role 的 _observe/_think/_act 循环、三种 react 模式 | 看懂单个智能体怎么动 |
| 2 | Action 与 ActionNode:工作单元 + 结构化输出引擎 | Action 封装 LLM 调用,ActionNode 把自由文本压成结构化产物 | 看懂「一次思考如何落成可用数据」 |
| 3 | Environment 消息总线、Message 路由与 Team | 发布-订阅、cause_by/send_to 路由、Team 如何驱动多轮 | 看懂角色如何在不直接调用下协作 |
| 4 | 经典 SOP 流水线:一行 需求跑成一个软件仓库 | 产品→架构→工程 的固定订阅链,端到端追一遍 | 看懂固定流水线怎么把需求变成代码 |
| 5 | MGX 与 RoleZero:TeamLeader 调度的动态命令智能体 | MGXEnv 让 TeamLeader 接管路由,RoleZero 每轮自选工具命令 | 看懂「自由团队」这套新范式 |
两条主线的分岔(先建立心智模型): MetaGPT 里同时活着两代设计。
- 经典 SOP(固定流水线): 角色用
by_order/ 固定_watch订阅,像装配线一样按预定顺序 接力。代表:ProductManager(use_fixed_sop=True)、Architect、经典Engineer。见第 4 章。 - MGX / RoleZero(动态团队): 由
TeamLeader(名叫 Mike)接管消息发布,像真人领导一样 决定「这条消息该派给谁」;每个角色是RoleZero,用react模式每轮让 LLM 自选下一条 工具命令。默认Team(use_mgx=True)走这条路。见第 5 章。
4. 巧妙之处(可带走的技术)
这几处是 MetaGPT 值得借鉴的设计,先说妙在哪,再给引用。
-
把「协作」降维成「发布-订阅」。 角色不持有彼此引用,只往环境发消息、只从自己的私有 buffer 读订阅到的消息。加一个角色 = 声明它
_watch什么、发什么,零改动已有角色。 订阅过滤见Role._observe(metagpt/roles/role.py:399),按cause_by ∈ watch或点名send_to命中;发布见Environment.publish_message(metagpt/environment/base_env.py:175)。 -
cause_by让消息自带「我是谁产的」标签。 每条Message记录它由哪个 Action 产生 (cause_by,metagpt/schema.py:239),下游订阅就是匹配这个标签——SOP 的「交接规则」 因此变成一行声明,而不是硬编码的调用图。 -
ActionNode:让 LLM 的自由文本变成可靠的结构化对象。 它用 Pydantic 的
create_model按 schema 动态造类再校验(ActionNode.create_model_class,metagpt/actions/action_node.py:248), 把「模型说的一段话」精确落成 PRD/设计/代码字段。这是把不可靠 LLM 输出工程化的关键一招。 -
TeamLeader 作为「消息路由的人」。 经典环境是广播;MGX 里几乎所有消息都先过 TeamLeader (
MGXEnv.publish_message,metagpt/environment/mgx/mgx_env.py:24),由它决定派给谁 (publish_team_message,metagpt/roles/di/team_leader.py)。把「调度」显式建成一个角色, 比写死流程更灵活。 -
一个
react循环,统一「思考」与「工具调用」。 RoleZero 每轮_think让 LLM 输出一串 命令、_act解析并执行(metagpt/roles/di/role_zero.py:198/:280),最多 50 轮 (max_react_loop)。同一套循环既能规划、又能调工具,不必为每种角色写专用逻辑。 -
预算即熔断。
Team每轮先_check_balance,累计成本超过投资额就抛NoMoneyException停机(metagpt/team.py:98),给「让 LLM 自由跑」加了一道硬性成本闸。
5. 代码地图(导航索引)
下表是给人和 agent 的跳转表:用符号名 grep 比行号更抗上游漂移。所有引用锚定
sourceCommit: 11cdf466。
| 主题 | 文件路径 | 关键符号 |
|---|---|---|
| CLI 入口 / 组队 | metagpt/software_company.py | generate_repo、app(typer) |
| 团队驱动多轮 | metagpt/team.py | Team、Team.run、run_project、invest、_check_balance |
| 共享环境 / 消息总线 | metagpt/environment/base_env.py | Environment、publish_message、Environment.run、member_addrs |
| 角色循环 | metagpt/roles/role.py | Role、_observe、_think、_act、_react、publish_message、RoleReactMode |
| 工作单元 | metagpt/actions/action.py | Action、Action.run、_run_action_node |
| 结构化输出引擎 | metagpt/actions/action_node.py | ActionNode、fill、create_model_class、compile、SIMPLE_TEMPLATE |
| 消息与路由字段 | metagpt/schema.py | Message(cause_by/send_to/instruct_content)、AIMessage、MessageQueue.pop_all |
| 动态团队环境 | metagpt/environment/mgx/mgx_env.py | MGXEnv、publish_message、_publish_message、move_message_info_to_content |
| 动态智能体基类 | metagpt/roles/di/role_zero.py | RoleZero、_think、_act、_run_commands、max_react_loop |
| 团队领导 / 调度 | metagpt/roles/di/team_leader.py | TeamLeader(name=Mike)、publish_team_message、publish_message |
| 经典 SOP 角色 | metagpt/roles/product_manager.py、architect.py | ProductManager(use_fixed_sop)、Architect(_watch({WritePRD})) |
| 工程实现角色 | metagpt/roles/engineer.py、metagpt/roles/di/engineer2.py | Engineer(n_borg)、Engineer2(Terminal/Editor 工具) |
| 关键常量 | metagpt/const.py | TEAMLEADER_NAME="Mike"、MESSAGE_ROUTE_TO_ALL="<all>"、MESSAGE_ROUTE_TO_SELF="<self>" |
深入各机制请沿「阅读地图」进对应章节。 本页只负责让你(或 agent)低成本判断相关性、 决定下钻哪一章;真正的代码走读在 01–05 各章。