你的AI开发还是单打独斗？MetaGPT焊死「多智能体协作」，从角色分工到代码生成一篇打通

技术教学类文章，非 MetaGPT 官方文档。代码基于 MetaGPT v0.8+，API 随版本迭代会有变化，以官方仓库为准；建议锁定版本（如 pip install metagpt==0.8.x）后使用。

MIT 开源协议，生产环境使用请自行评估风险。

文中所有 API Key 均通过环境变量读取，禁止硬编码。.gitignore 里记得加 .env。

⚠️ 文中代码仅用于原理演示，省略异常捕获、鉴权、重试等工程逻辑，请勿直接复制用于生产环境。

周一早上，老板甩来一句话：「给我做一个电商系统，带商品管理、订单、支付，下周上线。」你打开 ChatGPT，输入需求，它给你吐了三千行代码------前端后端数据库全搅在一起，接口参数对不上，表结构没有外键，连个 README 都没有。你花了三天理清这些代码，比自己从头写还累。你要是有个 AI 团队就好了------产品经理先写 PRD，架构师画系统设计图，工程师按文档写代码，QA 跑测试用例------各干各的，流水线产出。这不是幻想，MetaGPT 干的就是这事。

注：开篇为模拟业务场景，用于引出痛点，非真实事件。

一、MetaGPT 是什么？一句话说清楚

MetaGPT = 让多个 AI 角色按 SOP 协作，像软件公司一样流水线产出代码和文档。

打个比方：你雇了一个全能外包，啥都能干但啥都干不精------这是 ChatGPT 单 Agent 模式。MetaGPT 不一样，它直接给你组了个公司：产品经理出需求文档，架构师定技术方案，项目经理拆任务，工程师写代码，QA 验收测试。每个角色由一个 Agent 承担，用各自的 prompt 驱动，通过消息订阅发布机制传递产出物。

核心就三个概念：

概念	一句话解释	类比
Role（角色）	一个 Agent 的身份、职责和能做的动作	公司里的岗位 JD
Action（动作）	角色能执行的具体任务	岗位对应的工作内容
Environment（环境）	共享消息板，Agent 往里发消息、从中取消息	公司的飞书群

整个流程跑下来长这样：

复制代码

┌─────────────────────────────────────────────────────────────┐
│                    MetaGPT Environment                       │
│                  (共享消息板 / 消息订阅发布)                    │
│                                                               │
│  ┌──────────┐  PRD   ┌──────────┐ 设计文档 ┌──────────┐       │
│  │ 产品经理  │──────→│  架构师   │───────→│ 项目经理  │       │
│  │   (PM)   │        │(Architect)│        │(ProjMgr) │       │
│  └──────────┘        └──────────┘        └────┬─────┘       │
│                                                │ 任务分解     │
│                                                ▼             │
│  ┌──────────┐  测试报告 ┌──────────┐  代码    ┌──────────┐   │
│  │ QA工程师  │←───────│  工程师   │←───────│ 项目经理  │   │
│  │  (QA)    │        │(Engineer)│        │(ProjMgr) │   │
│  └──────────┘        └──────────┘        └──────────┘   │
│        │                                              │       │
│        ▼                                              │       │
│   [Bug 反馈消息] ──→ 工程师订阅 → 修复 → 重新提交 ──→ QA 复测  │
│                                                               │
│  ※ 虚线 = 人类介入点（Human-in-the-loop）                      │
└─────────────────────────────────────────────────────────────┘
         ┆
         ▼
    最终交付：PRD + 设计文档 + 代码 + 测试用例 + 测试报告

消息机制是关键 ：角色不是直接互相调用，而是往 Environment 这个"消息板"上贴消息。别的角色看到自己关注的消息类型（通过 _watch 属性订阅），就领走处理，处理完再把结果贴回去。解耦得干干净净------产品经理不需要认识工程师，只管往板上贴 PRD 就行。

二、3 个场景，让你秒懂 MetaGPT 多香

场景一：从一句话需求到完整项目

你说"写一个待办清单 API"，MetaGPT 跑完给你 PRD、接口设计、代码、测试用例一条龙。

python 复制代码

import asyncio
from metagpt.team import Team
from metagpt.roles import (
    ProductManager, Architect, ProjectManager,
    Engineer, QAEngineer
)

async def startup(idea: str, investment: float = 5.0):
    """一句话需求 → 完整项目"""
    company = Team()
    # 按SOP顺序hire角色，顺序影响消息处理优先级
    company.hire([
        ProductManager(),
        Architect(),
        ProjectManager(),
        Engineer(n_iter=3),  # n_iter=工程师迭代写代码的轮数
        QAEngineer(),
    ])
    company.invest(investment)  # ⚠️ token预算，单位美元，5.0约够跑一轮完整SOP
    company.run_project(idea=idea)
    await company.run(n_round=5)  # SOP跑5轮，每轮所有角色各执行一次

if __name__ == "__main__":
    asyncio.run(startup("写一个待办清单API，支持增删改查和优先级标记"))

跑完之后，项目目录里会有：

docs/prd/ --- 产品需求文档
docs/system_design/ --- 系统设计（含数据模型、接口定义、序列图）
docs/task/ --- 任务拆解
src/ --- 实际代码
tests/ --- 测试用例

这是 MetaGPT 最核心的能力：你只管提需求，它按 SOP 流程全链路产出。不是给你一堆代码片段，而是给你一个有文档、有设计、有测试的项目结构。

场景二：数据分析报告自动化

不用全套 SOP，只用部分角色，做数据分析流水线。

python 复制代码

import asyncio
from metagpt.team import Team
from metagpt.roles import Role
from metagpt.actions import Action
from metagpt.schema import Message

# 自定义动作：数据清洗
class CleanData(Action):
    name: str = "CleanData"
    prompt_template: str = "清洗以下数据，去除异常值和空值：\n{data_desc}"

    async def run(self, data_desc: str):
        return await self.llm.aask(self.prompt_template.format(data_desc=data_desc))

# 自定义动作：生成分析报告
class WriteReport(Action):
    name: str = "WriteReport"
    prompt_template: str = "基于以下分析结果写一份结构化报告：\n{analysis}"

    async def run(self, analysis: str):
        return await self.llm.aask(self.prompt_template.format(analysis=analysis))

# 自定义角色：数据分析师
class DataAnalyst(Role):
    name: str = "DataAnalyst"
    profile: str = "DataAnalyst"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([CleanData, WriteReport])
        # 订阅用户输入的消息，触发整个流程
        self._watch({Action.userdata})

async def analyze():
    company = Team()
    company.hire([DataAnalyst()])
    company.invest(3.0)
    company.run_project(idea="分析某电商平台Q3销售数据，数据在 sales_q3.csv，字段：date,product,amount,region")
    await company.run(n_round=3)

asyncio.run(analyze())

亮点：不是所有场景都需要五件套。数据分析场景下，一个自定义角色串两个 Action 就够了。MetaGPT 的角色不一定按固定 SOP 跑，你可以根据业务自由组合。

场景三：多 Agent 辩论改进方案

两个 Agent 互相 Review 代码，像同事 Code Review 一样挑毛病。

python 复制代码

import asyncio
from metagpt.team import Team
from metagpt.roles import Role
from metagpt.actions import Action
from metagpt.schema import Message

class WriteCode(Action):
    name: str = "WriteCode"
    prompt_template: str = "实现以下需求，写Python代码：\n{requirement}"
    async def run(self, requirement: str):
        return await self.llm.aask(self.prompt_template.format(requirement=requirement))

class ReviewCode(Action):
    name: str = "ReviewCode"
    prompt_template: str = (
        "你是严格的Code Reviewer。审查以下代码，"
        "指出Bug、安全问题、性能问题，给出修改建议：\n{code}"
    )
    async def run(self, code: str):
        return await self.llm.aask(self.prompt_template.format(code=code))

# 编码者：写完代码发布出去
class Coder(Role):
    name: str = "Coder"
    profile: str = "Coder"
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([WriteCode])
        self._watch({Action.userdata, ReviewCode})  # 订阅用户输入和Review反馈

# 审查者：收到代码就Review
class Reviewer(Role):
    name: str = "Reviewer"
    profile: str = "Reviewer"
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([ReviewCode])
        self._watch({WriteCode})  # 订阅代码产出，一有代码就开审

async def debate():
    company = Team()
    company.hire([Coder(), Reviewer()])
    company.invest(3.0)
    company.run_project(idea="实现一个LRU缓存，要求线程安全")
    await company.run(n_round=4)  # ⚠️ 轮数别太多，否则两个Agent可能无限辩论下去

asyncio.run(debate())

这场景有意思 ：Coder 写完代码 → Reviewer 收到代码开审 → Reviewer 把问题贴回消息板 → Coder 收到反馈重新写 → Reviewer 再审......来回几轮，代码质量肉眼可见地提升。但注意 n_round 别设太大，不然两个 Agent 可能吵到 token 烧光。

三、MetaGPT 的 4 种高级用法

用法一：自定义角色（继承 Role 基类）

默认五件套不够用？自己造角色。

python 复制代码

from metagpt.roles import Role
from metagpt.actions import Action, ActionNode
from metagpt.schema import Message

# Step 1: 定义Action
class SecurityScan(Action):
    """安全扫描动作"""
    name: str = "SecurityScan"

    async def run(self, code: str):
        prompt = (
            "你是安全审计专家。检查以下代码的安全漏洞"
            "（SQL注入、XSS、硬编码密钥等），给出风险等级和修复建议：\n\n"
            f"{code}"
        )
        return await self.llm.aask(prompt)

# Step 2: 定义Role，绑定Action和订阅源
class SecurityAuditor(Role):
    """安全审计角色"""
    name: str = "SecurityAuditor"
    profile: str = "Security Auditor"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        # 绑定这个角色能做的Action
        self.set_actions([SecurityScan])
        # ⚠️ _watch 决定角色何时被触发
        # 这里订阅 WriteCode 动作，一有代码产出就触发安全扫描
        self._watch({WriteCode})

    async def _act(self) -> Message:
        # 从记忆中取最近的代码消息
        code_msg = self.rc.history.pick(WriteCode)
        if not code_msg:
            return Message(content="无代码可审计", role=self.profile)
        code = code_msg[-1].content
        result = await self.actions[0].run(code)
        msg = Message(content=result, role=self.profile, cause_by=SecurityScan)
        self.rc.memory.add(msg)
        return msg

核心三步 ：定义 Action → 定义 Role 绑定 Action → 设置 _watch 决定触发时机。_watch 是整个 SOP 的编排核心------谁订阅谁的消息，就决定了流程的走向。

用法二：人类介入机制（Human-in-the-loop）

关键决策点暂停，等人确认再继续。

python 复制代码

from metagpt.actions import Action
from metagpt.schema import Message

class HumanApprovalAction(Action):
    """需要人类确认的动作"""
    name: str = "HumanApproval"

    async def run(self, content: str):
        # 实际项目中这里可以接飞书/Slack通知，等人回复
        # 示例用 input() 模拟，生产环境别这么干
        print(f"\n{'='*50}")
        print(f"待确认内容：\n{content[:500]}...")
        print(f"{'='*50}")
        # ⚠️ 生产环境用异步通知 + 回调，别用 input() 阻塞
        approval = input("批准？(y/n): ").strip().lower()
        if approval == 'y':
            return "APPROVED"
        else:
            feedback = input("请输入修改意见：").strip()
            return f"REJECTED: {feedback}"

# 在架构师角色中插入人类确认环节
class ArchitectWithApproval(Role):
    name: str = "Architect"
    profile: str = "Architect"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([WriteDesign, HumanApprovalAction])
        self._watch({WritePRD})  # 收到PRD后开始设计

    async def _act(self) -> Message:
        prd_msg = self.rc.history.pick(WritePRD)
        design = await self.actions[0].run(prd_msg[-1].content)
        # 关键决策点：设计文档需人类确认
        approval = await self.actions[1].run(design)
        if "REJECTED" in approval:
            # 被拒了，把反馈贴回消息板，PRD角色会收到重新改
            return Message(content=approval, role=self.profile, cause_by=self.actions[1])
        return Message(content=design, role=self.profile, cause_by=WriteDesign)

用法精髓：不是所有环节都要人盯，只在关键节点（架构设计、安全审计、上线前验收）插一道人工关卡。MetaGPT 的消息机制让"打回重来"很自然------被拒绝的消息回到消息板，上游角色看到就重新处理。

用法三：SOP 自定义（修改默认流程）

默认是 PM→架构师→项目经理→工程师→QA，但你的项目可能需要加安全审计、法务审核等环节。

python 复制代码

from metagpt.team import Team
from metagpt.roles import (
    ProductManager, Architect, ProjectManager,
    Engineer, QAEngineer
)

# 在标准SOP中间插入安全审计角色
class SecurityAuditor(Role):
    # ... (同上用法一定义)
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([SecurityScan])
        # 订阅工程师的代码产出，代码一出来就做安全扫描
        self._watch({WriteCode})
        pass

async def custom_sop():
    company = Team()
    company.hire([
        ProductManager(),
        Architect(),
        ProjectManager(),
        Engineer(n_iter=2),
        SecurityAuditor(),   # ← 插入自定义角色
        QAEngineer(),
    ])
    company.invest(8.0)  # ⚠️ 加了角色，token预算要相应调高
    company.run_project(idea="做一个用户注册登录系统，含密码加密和JWT鉴权")
    await company.run(n_round=6)  # ⚠️ 角色多了，轮数也要加

asyncio.run(custom_sop())

自定义 SOP 的逻辑 ：不需要改框架代码，只需要在 hire 时加入自定义角色，并通过 _watch 把它接入消息流。新角色订阅哪个上游消息、产出什么消息被谁订阅，就自动织进了 SOP。这是 MetaGPT 设计最优雅的地方------SOP 不是写死的流程图，而是消息订阅关系自然涌现的拓扑。

用法四：多项目并行（多个 Environment 实例）

同时跑多个项目，互不干扰。

python 复制代码

import asyncio
from metagpt.team import Team
from metagpt.roles import ProductManager, Architect, Engineer

async def run_project(name: str, idea: str, investment: float):
    """单个项目跑一轮"""
    team = Team()
    team.hire([ProductManager(), Architect(), Engineer(n_iter=2)])
    team.invest(investment)
    team.run_project(idea=idea)
    await team.run(n_round=4)
    print(f"[{name}] 完成")

async def parallel():
    """多个项目并行执行"""
    projects = [
        ("项目A", "写一个CLI待办清单工具", 3.0),
        ("项目B", "写一个Markdown转HTML的转换器", 2.0),
        ("项目C", "写一个简单的HTTP接口压测脚本", 1.5),
    ]
    # 每个Team实例独立，Environment不共享
    # ⚠️ 并行数量受API rate limit约束，别同时开太多
    await asyncio.gather(*[run_project(n, i, b) for n, i, b in projects])

asyncio.run(parallel())

注意：多个 Team 实例的 Environment 是隔离的，角色之间不会串消息。但底层 LLM API 是共享的，并行太多会被 rate limit 拍死。一般同时跑 2-3 个比较稳。

四、避坑清单：8 个暗坑

序号	坑名	现象	解法
1	角色 prompt 冲突	两个角色订阅了同一类消息，同时抢着处理，产出矛盾	`_watch` 只订阅自己关心的 Action 类型，别全订阅；用 `cause_by` 字段精确路由
2	消息风暴死循环	Agent A 的输出触发 B，B 的输出又触发 A，无限来回	严格控制 `n_round`；在 `_act` 里加终止条件判断；设置消息去重
3	token 消耗惊人	5 个角色跑 5 轮，一次调用烧掉十几美元	`company.invest()` 设预算上限；用便宜模型做草稿、贵模型做关键决策；减少 `n_iter`
4	SOP 不适配所有场景	简单 CRUD 非要走完五件套，产出一堆没用的文档	简单项目只 hire 1-2 个角色；按场景裁剪 SOP，不是所有项目都要 PM
5	角色间信息丢失	架构师的设计文档没传到工程师，工程师自己猜着写	检查 `_watch` 是否覆盖上游 Action；用 `Memory` 持久化中间产出；打印消息流转日志排查
6	版本兼容问题	v0.6 的代码跑在 v0.8 上报错，API 改了	锁版本 `pip install metagpt==0.8.0`；看 CHANGELOG 跟迁移指南；CI 里加版本检测
7	人类介入超时阻塞	`input()` 等人确认，人不在，整个流程卡死	生产环境用异步通知（飞书/邮件）+ 超时自动降级；设 `timeout`，超时走默认逻辑
8	输出格式不一致	不同模型/不同轮次输出的代码格式乱七八糟，JSON 解析报错	用 `ActionNode` 约束输出 schema；在 Action 的 prompt 里给 few-shot 示例；加输出格式校验

五、面试速查表：8 道必考题

Q1：MetaGPT 的核心思想是什么？

用 SOP（标准作业流程）驱动多个 AI Agent 协作。每个 Agent 扮演一个角色（产品经理、架构师等），通过消息订阅发布机制传递产出物，像软件公司流水线一样产出完整的代码和文档。

Q2：MetaGPT 和 AutoGPT、BabyAGI 有什么区别？

AutoGPT 是单 Agent 自主循环（思考→规划→执行→反思），灵活但容易跑飞。BabyAGI 是任务列表驱动的单 Agent，简单但缺乏角色分工。MetaGPT 是多 Agent 协作，通过 SOP 约束流程，产出结构化、可预测，但灵活性不如单 Agent 自主模式。

Q3：MetaGPT 中 Role 的 _watch 属性是干什么的？

_watch 定义了一个角色订阅哪些 Action 类型的消息。比如工程师角色 _watch(WriteDesign)，意味着架构师发布设计文档后，工程师会被触发执行写代码动作。_watch 是 SOP 编排的核心------它决定了消息流转的拓扑结构，也就是"谁在什么条件下干活"。

Q4：MetaGPT 的 Environment 是什么？有什么作用？

Environment 是所有 Agent 共享的消息环境，本质是一个消息板。Agent 把产出物（PRD、设计文档、代码等）作为 Message 发布到 Environment，其他 Agent 通过订阅机制领取自己关心的消息。作用是解耦------角色之间不直接调用，只通过消息板交互。

Q5：SOP 驱动有什么优势？劣势是什么？

优势：产出可预测、流程可复现、角色职责清晰、中间产出物可追溯。劣势：灵活性差------不适合需求不明确需要反复试错的项目；流程固定，遇到非标准场景需要改 SOP；角色多了协调成本高。

Q6：MetaGPT 如何实现 Human-in-the-loop？

通过在关键节点插入需要人类确认的 Action。人类确认后消息继续流转；人类拒绝则把反馈消息发回消息板，上游角色收到后重新处理。本质是利用消息订阅机制实现"打回重来"------不需要中断整个流程，只需要让特定消息回到上游。

Q7：MetaGPT 适合什么场景？不适合什么场景？

适合：需求明确的中小型项目（从需求到代码全链路）、文档自动化生成（PRD/设计文档/测试用例）、多角色协作场景模拟。不适合：需要实时交互的对话系统、需求频繁变更的探索性项目、单步任务（一个 API 调用就能搞定的事没必要上多 Agent）。

Q8：MetaGPT 的可观测性怎么做？

MetaGPT 内置日志系统，记录每个角色的输入输出、消息流转路径、token 消耗。可以通过配置 logging 级别输出调试信息。进阶方案：把每轮消息流转写入数据库，用可视化工具画出 Agent 协作拓扑图，追踪每条消息从哪个角色发出、被哪个角色消费。

六、总结

三句话讲清楚 MetaGPT：

MetaGPT 用 SOP 把多个 AI Agent 组织成流水线------产品经理出 PRD、架构师定方案、工程师写代码、QA 跑测试，不是一个人从头干到尾。
核心机制是消息订阅发布------角色不直接调用，往共享消息板贴消息，谁订阅谁触发，SOP 是消息订阅关系自然涌现的拓扑，不是写死的流程图。
适合需求明确、流程固定的场景，不适合需要灵活探索的项目------别拿着锤子到处找钉子，简单任务用单 Agent 就够了。

万能落地模板（照着改就能跑）：

python 复制代码

import asyncio
from metagpt.team import Team
from metagpt.roles import Role
from metagpt.actions import Action

# 1. 定义你的Action
class YourAction(Action):
    name: str = "YourAction"
    async def run(self, input_data: str):
        return await self.llm.aask(f"处理以下内容：\n{input_data}")

# 2. 定义你的Role
class YourRole(Role):
    name: str = "YourRole"
    profile: str = "YourRole"
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([YourAction])
        self._watch({Action.userdata})  # 订阅用户输入触发

# 3. 组队跑起来
async def main():
    team = Team()
    team.hire([YourRole()])
    team.invest(2.0)
    team.run_project(idea="你的需求描述")
    await team.run(n_round=3)

asyncio.run(main())

什么情况不该用 MetaGPT：

单步任务（翻译一段话、总结一篇文章）------直接调 LLM，别上多 Agent，杀鸡用牛刀。
需求不确定、需要反复试错的项目------SOP 是流程约束，探索性任务被框死反而束手束脚。
实时对话系统（客服、问答机器人）------MetaGPT 的 SOP 是批处理模式，不适合一来一回的实时交互。
token 预算极度有限的场景------多 Agent 协作的 token 消耗是单 Agent 的几倍到几十倍。

参考资料

MetaGPT 官方仓库：https://github.com/geekan/MetaGPT
MetaGPT 论文：《MetaGPT: Meta Programming for Multi-Agent Collaborative Framework》
MetaGPT 官方文档：https://docs.deepwisdom.ai/main/
LLM Agent 综述：《A Survey on Large Language Model based Autonomous Agents》

模型能力和 SDK API 更新很快，本文基于 MetaGPT v0.8+，后续版本可能有 API 变动。遇到接口报错先查官方文档和 CHANGELOG，别死磕本文代码。

封面动物：长颈鹿 ------ 寓意"站得高看得远，像 MetaGPT 的全局 SOP 编排"