AgentVerse — 架构与原理
30 秒导读: AgentVerse 是清华 OpenBMB 出的多智能体框架。你写一份 YAML,它就把多个 LLM 智能体组装成一个系统:既能做「自由模拟」(NLP 课堂、囚徒困境、宝可梦),也能做「协作解题」(头脑风暴、写代码、用工具)。核心巧思是把多智能体里所有「该怎么协调」的决策抽成可插拔的 Rule 组件,换组件就换玩法,不用改框架代 码。
1. 这是什么(零基础也能懂)
一句话定义: AgentVerse 是一个让多个 LLM 智能体一起干活/一起演的框架——你用配置文件描述「有哪些角色、按什么规矩互动」,它负责跑起来。
解决什么问题 / 给谁用: 假设你想让 3 个 GPT 扮演「教授 + 两个学生」开一场 NLP 课,或者让「一个工程师 + 一个经济学家 + 一个律师」一起为某项目出主意——你不想自己写「谁先说、谁能听见谁、说完怎么进下一轮、最后谁来打分」这一堆调度逻辑。AgentVerse 把这套调度逻辑做成了可配置的积木。它面向做多智能体研究、想快速搭多角色 demo 的工程师和研究者。
它提供两套框架(全文主线):
| 框架 | 干什么 | 典型应用 |
|---|---|---|
| Simulation(模拟) | 设定一个环境,让多个智能体自由互动,观察涌现行为 | NLP 课堂、囚徒困境、宝可梦小游戏 |
| Task-solving(解题) | 把多个智能体组成一条流水线,协作完成一个明确任务 | 软件开发、咨询、头脑风暴、用工具 |
这两套是 README 开篇就点明的两大支柱,也是整个代码库的分水岭(agentverse/simulation.py vs agentverse/tasksolving.py)。
用起来什么样: 你几乎只跟 YAML 打交道。下面是一段真实的模拟配置(NLP 课堂),把「环境规则 + 三个智能体」全写在一个 文件里:
# agentverse/tasks/simulation/nlp_classroom_3players/config.yaml(节选)
environment:
env_type: sim-basic # 用哪种环境
max_turns: 10 # 跑 10 轮
rule:
order: { type: sequential } # 发言顺序:轮流
visibility: { type: all } # 可见性:所有人都听得见
selector: { type: basic } # 选哪些消息生效:全要
updater: { type: basic } # 怎么写进记忆:广播给所有人
describer: { type: basic } # 给每个智能体的环境描述
agents:
- agent_type: conversation
name: Professor Micheal
role_description: You are Prof. Micheal, a knowledgeable professor in NLP...
# ... Student Beta、Teaching Assistant Gamma
然后代码只有三行:
# 示意,非源码
from agentverse import Simulation
sim = Simulation.from_task("nlp_classroom_3players", tasks_dir) # 读 YAML 装配
sim.run() # 一直 step 到 max_turns
一句话直觉/类比: 把 AgentVerse 想成多智能体的「桌游主持人」。桌游有两类规则书:一类是「自由角色扮演」(模拟),主持人只管维持秩序——谁该说话了、谁能偷看谁的牌;另一类是「闯关合作」(解题),主持人安排固定流程——先分工、再讨论、再行动、最后裁判打分,不过关就再来一轮。AgentVerse 的精华就是:把「主持人的规则」从「玩家的智能」里彻底分离出来,做成可换的组件。
2. 顶层全景(它大概怎么转)
怎么读这张图
从上到下是一次运行的生命周期:YAML 配置 → 装配成对象 → 进入某种 Environment → 反复 step。左右两条腿就是两套框架,它们共享上面的装配层、共享下面的 Agent/LLM。
┌──────────────────────────────┐
│ config.yaml (任务配置) │
└──────────────┬───────────────┘
│ prepare_task_config / load_*
▼
┌───────────── ─────────────────┐
│ initialization.py (装配层) │ ← Registry 按字符串建对象
└───────┬──────────────┬───────┘
│ │
模拟一条腿 ▼ ▼ 解题一条腿
┌─────────────────┐ ┌──────────────────────┐
│ Simulation │ │ TaskSolving │
│ 环境=sim-basic │ │ 环境=task-basic │
│ 循环: step() │ │ 循环: step(advice…) │
└────────┬────────┘ └──────────┬───────────┘
│ │
每步问 5 个 Rule 每步走 4 个阶段
order/visibility/... role→decision→execute→evaluate
│ │
└───────────┬───────────┘
▼
┌────────────────────┐
│ Agent → BaseLLM │ ← 真正调 OpenAI/本地模型
│ → OutputParser │
└────────────────────┘
部件一句话职责
| 部件 | 干什么 | 在哪个文件 |
|---|---|---|
Simulation / TaskSolving | 两个顶层入口,各自的 run() 循环 | agentverse/simulation.py、agentverse/tasksolving.py |
AgentVerse | 早期统一入口(模拟风格),保留兼容 | agentverse/agentverse.py |
initialization.py | 读 YAML、按类型字符串造出所有对象 | agentverse/initialization.py |
Registry | 「字符串 → 类」的注册表,装配靠它 | agentverse/registry.py |
BasicEnvironment(sim) | 模拟环境,每步问 5 个 Rule | agentverse/environments/simulation_env/basic.py |
BasicEnvironment(task) | 解题环境,每步走 4 个阶段 | agentverse/environments/tasksolving_env/basic.py |
SimulationRule | 把 order/visibility/selector/updater/describer 5 件套打包 | agentverse/environments/simulation_env/rules/base.py |
TasksolvingRule | 把 role_assigner/decision_maker/executor/evaluator 4 件套打包 | agentverse/environments/tasksolving_env/rules/base.py |
BaseAgent 及子类 | 角色本体:填 prompt → 调 LLM → 解析 | agentverse/agents/base.py |
BaseLLM / OpenAIChat | 真正请求模型、记花费 | agentverse/llms/openai.py |
主线走一遍(高层,不进代码)
装配阶段(两套通用):from_task(task, tasks_dir) 读 config.yaml → 对每个 agent 配置,load_memory/load_llm/load_tools/output_parser 把子部件造好(initialization.py:96-119)→ load_environment 按 env_type 造环境。Registry 是这一切的中枢:每个组件类用 @xxx_registry.register("名字") 登记,装配时按 YAML 里的字符串取出来 build。
模拟运行:Simulation.run() 反复 asyncio.run(environment.step()) 直到 is_done()(simulation.py:41-46)。每个 step() 依次问 5 个 Rule:谁该说(order)→ 给它们看什么环境描述(describer)→ 并发让它们各说一句 → 哪些消息算数(selector)→ 写进谁的记忆(updater)→ 更新谁能看见谁(visibility)(simulation_env/basic.py:57-84)。
解题运行:TaskSolving.run() 反复 environment.step(advice, previous_plan),把上一轮的 advice(评委意见)和 previous_plan(上一版方案)喂回去,直到通过或耗尽轮数(tasksolving.py:59-72)。每个 step() 走四阶段:招募专家(role_assign)→ 讨论出方案(decision_making)→ 执行(execute)→ 打分给建议(evaluate),分够高就 success=True 退出,否则带着 advice 再来一轮(tasksolving_env/basic.py:45-109)。
3. 阅读地图(建议顺序)
这是一个中型框架,核心价值在「Rule 组件如何切分多智能体协调逻辑」。建议按下面顺序读:
-
01-simulation-env.md— 先看模拟框架。它的「5 组件 Rule」最能体现 AgentVerse 的设计哲学:把一次对话轮拆成 order/visibility/selector/updater/describer 五个正交的问题。读完你会懂「为什么换个 order 组件就从『轮流发言』变成『课堂举手』」。 -
02-tasksolving-pipeline.md— 再看解题框架。它是一条「招募→讨论→执行→评分→反馈重来」的流水线,带一个评委打分驱动的循环。读完你会懂多智能体怎么「自我迭代直到达标」。 -
03-decision-makers.md— 深入解题框架里最有料的一环:讨论拓扑。同一个「让一群专家讨论」的目标,horizontal(轮流评论)、vertical(并发评审)、central(中心协调)、brainstorming(讨论后清空记忆只留摘要)是四种不同的实现,直接对应多智能体协作的几种经典结构。 -
04-infra.md— 最后看底座:Registry 注册表怎么实现「字符串造对象」、YAML 怎么一步步变成对象、Agent 的 prompt 三段式、LLM 层的花费统计。附代码地图供 agent 跳转。
4. 一句话边界(详见各章)
- 这是研究/demo 框架,不是生产级 agent 运行时:没有持久化、没有错误恢复编排,
execute默认是none(很多解题任务只讨论不真执行)。 - 解题框架的「合格线」是硬编码的
score >= 8(tasksolving_env/basic.py:97,注释自己标了# TODO: 8 is an arbitrary threshold)。 dynamic决策器是半成品(decision_maker/dynamic.py里写着## To Do: implement dynamic)。
横向对比与各机制细节,见后续章节。