elizaOS 多智能体架构设计分析
📋 概述
elizaOS 是一个开源的多智能体 AI 开发框架，用于构建、部署和管理自主 AI 智能体。采用现代化、可扩展的全功能平台设计。
核心特性
- 🔌 丰富的连接器：内置 Discord、Telegram、Farcaster 等支持
- 🧠 模型无关：支持 OpenAI、Gemini、Anthropic、Llama、Grok 等主流模型
- 🖥️ 现代 Web UI：专业仪表板，实时管理智能体、群组和对话
- 🤖 多智能体架构：从底层设计支持创建和编排专业智能体组
- 📄 文档摄取：轻松摄取文档，支持 RAG 检索和问答
- 🛠️ 高度可扩展：强大的插件系统构建自定义功能
- 📦 开箱即用：无缝的设置和开发体验
🏗️ 系统架构概览
项目结构
eliza/
├── packages/
│ ├── typescript/ # 核心包 (@elizaos/core)
│ ├── python/ # Python API 实现
│ ├── rust/ # Rust 实现（原生 + WASM）
│ ├── elizaos/ # 主应用
│ ├── daemon/ # 守护进程
│ ├── docs/ # 文档
│ ├── interop/ # 互操作层
│ ├── prompts/ # 提示词库
│ ├── schemas/ # 数据模式
│ ├── skills/ # 技能模块
│ ├── sweagent/ # SWE Agent
│ ├── training/ # 训练模块
│ ├── tui/ # 终端 UI
│ └── computeruse/ # 计算机使用能力
├── plugins/ # 官方插件
└── scripts/ # 构建和工具脚本
架构层次图
graph TB
subgraph "应用层"
WebUI["Web UI 仪表板"]
TUI["终端 UI (TUI)"]
Daemon["守护进程"]
end
subgraph "核心层 (@elizaos/core)"
AgentRuntime["AgentRuntime<br/>（代理运行时）"]
PluginSystem["Plugin System<br/>（插件系统）"]
ActionSystem["Action System<br/>（动作系统）"]
MemorySystem["Memory System<br/>（记忆系统）"]
ModelSystem["Model System<br/>（模型系统）"]
ServiceSystem["Service System<br/>（服务系统）"]
end
subgraph "扩展层"
Plugins["官方插件<br/>（Discord/Telegram/OpenAI 等）"]
Providers["Providers<br/>（数据提供者）"]
Evaluators["Evaluators<br/>（评估器）"]
Actions["Actions<br/>（动作）"]
end
subgraph "基础设施层"
Database["数据库适配器<br/>（PostgreSQL/PGLite）"]
Network["网络层<br/>（沙箱代理）"]
Security["安全层<br/>（Token 管理）"]
end
WebUI --> AgentRuntime
TUI --> AgentRuntime
Daemon --> AgentRuntime
AgentRuntime --> PluginSystem
AgentRuntime --> ActionSystem
AgentRuntime --> MemorySystem
AgentRuntime --> ModelSystem
AgentRuntime --> ServiceSystem
PluginSystem --> Plugins
PluginSystem --> Providers
PluginSystem --> Evaluators
PluginSystem --> Actions
AgentRuntime --> Database
AgentRuntime --> Network
AgentRuntime --> Security
🔑 核心模块详解
1. AgentRuntime（代理运行时）
位置：packages/typescript/src/runtime.ts
AgentRuntime 是整个 elizaOS 的核心，负责协调所有子系统的工作。
核心属性
export class AgentRuntime implements IAgentRuntime {
readonly agentId: UUID;
readonly character: Character;
public adapter!: IDatabaseAdapter;
// 核心组件集合
readonly actions: Action[] = [];
readonly evaluators: Evaluator[] = [];
readonly providers: Provider[] = [];
readonly plugins: Plugin[] = [];
// 状态缓存（LRU 策略）
stateCache = new Map<string, State>();
private static readonly STATE_CACHE_MAX = 200;
// 服务和模型
services = new Map<ServiceTypeName, Service[]>();
models = new Map<string, ModelHandler[]>();
// 沙箱模式
public readonly sandboxMode: boolean;
public readonly sandboxTokenManager: SandboxTokenManager | null;
// 事件系统
events: RuntimeEventStorage = {};
private eventHandlers: Map<string, Array<(data: EventPayload) => void>>;
}
构造函数参数
constructor(opts: {
conversationLength?: number; // 对话历史长度
agentId?: UUID; // 代理 ID
character?: Character; // 角色配置
plugins?: Plugin[]; // 插件列表
fetch?: typeof fetch; // 自定义 fetch
adapter?: IDatabaseAdapter; // 数据库适配器
settings?: RuntimeSettings; // 运行时设置
allAvailablePlugins?: Plugin[]; // 所有可用插件
logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
disableBasicCapabilities?: boolean; // 禁用基础能力
advancedCapabilities?: boolean; // 启用高级能力
actionPlanning?: boolean; // 动作规划模式
llmMode?: LLMModeType; // LLM 模式
})
关键工作流
sequenceDiagram
participant Client as 客户端
participant Runtime as AgentRuntime
participant Plugin as 插件系统
participant Action as 动作系统
participant Model as 模型系统
participant Memory as 记忆系统
Client->>Runtime: initialize()
Runtime->>Plugin: 加载插件
Plugin->>Runtime: 注册 Actions/Evaluators/Providers
Runtime->>Memory: 初始化数据库
Runtime->>Model: 配置模型处理器
Client->>Runtime: processMessage()
Runtime->>Memory: 获取对话历史
Runtime->>Plugin: 调用 Providers 收集上下文
Runtime->>Model: 生成响应/选择动作
Runtime->>Action: 执行选定动作
Action->>Runtime: 返回动作结果
Runtime->>Memory: 保存新记忆
Runtime->>Client: 返回响应
2. 插件系统（Plugin System）
位置：packages/typescript/src/plugin.ts
插件系统是 elizaOS 的扩展核心，支持动态加载、依赖解析和自动安装。
Plugin 接口结构
interface Plugin {
name: string; // 插件名称
description?: string; // 描述
init?: (runtime: IAgentRuntime) => Promise<void>;
// 核心组件
services?: Service[]; // 服务
providers?: Provider[]; // 数据提供者
actions?: Action[]; // 动作
evaluators?: Evaluator[]; // 评估器
// 依赖管理
dependencies?: string[]; // 依赖插件
testDependencies?: string[]; // 测试依赖
}
插件加载流程
flowchart TD
A[插件名称或对象] --> B{是字符串吗?}
B -->|是| C[尝试 import]
B -->|否| D[验证插件形状]
C --> E{导入成功?}
E -->|否| F[尝试自动安装]
F --> G{安装成功?}
G -->|是| C
G -->|否| H[返回 null]
E -->|是| I[查找有效导出]
D --> J{验证通过?}
J -->|否| H
J -->|是| K[返回插件]
I --> L{找到有效插件?}
L -->|是| K
L -->|否| H
依赖解析算法
使用拓扑排序（Topological Sort）解析插件依赖：
function resolvePluginDependencies(
availablePlugins: Map<string, Plugin>,
isTestMode: boolean = false
): Plugin[] {
const resolutionOrder: string[] = [];
const visited = new Set<string>();
const visiting = new Set<string>();
function visit(pluginName: string) {
// 检测循环依赖
if (visiting.has(canonicalName)) {
logger.error("Circular dependency detected");
return;
}
// 递归访问依赖
for (const dep of plugin.dependencies || []) {
visit(dep);
}
resolutionOrder.push(canonicalName);
}
return resolutionOrder.map(name => availablePlugins.get(name));
}
3. 动作系统（Action System）
位置：packages/typescript/src/actions.ts
动作系统定义了代理可以执行的操作，包括参数验证、示例生成等。
Action 接口
interface Action {
name: string;
description: string;
similes?: string[]; // 相似名称
examples?: ActionExample[][]; // 使用示例
validate?: (
runtime: IAgentRuntime,
message: Memory,
state?: State
) => Promise<boolean>;
handler: (
runtime: IAgentRuntime,
message: Memory,
state?: State,
options?: { [key: string]: unknown },
callback?: HandlerCallback
) => Promise<ActionResult | null | undefined>;
suppressInitialMessage?: boolean;
parameters?: ActionParameter[]; // 参数定义
}
动作调用示例格式
User: 请帮我搜索关于人工智能的最新新闻
Assistant:
<actions>
<action>searchWeb</action>
</actions>
<params>
<searchWeb>
<query>人工智能 最新新闻</query>
<count>5</count>
</searchWeb>
</params>
4. 记忆系统（Memory System）
位置：packages/typescript/src/memory.ts 和 packages/typescript/src/types/memory.ts
Memory 结构
interface Memory {
id: UUID;
agentId: UUID;
roomId: UUID;
userId?: UUID;
content: Content; // 消息内容
createdAt: number; // 创建时间戳
embedding?: number[]; // 向量嵌入
metadata?: MemoryMetadata; // 元数据
}
interface Content {
text: string;
source?: boolean;
url?: string;
inReplyTo?: UUID;
action?: string;
attachments?: Attachment[];
}
记忆检索流程
graph LR
A[查询输入] --> B[生成向量嵌入]
B --> C[BM25 关键词搜索]
B --> D[向量相似度搜索]
C --> E[混合排序]
D --> E
E --> F[返回 Top-K 记忆]
F --> G[构建对话上下文]
5. 模型系统（Model System）
位置：packages/typescript/src/types/model.ts
支持多种模型类型和提供商：
enum ModelType {
TEXT = "text",
TEXT_SMALL = "text-small",
EMBEDDING = "embedding",
IMAGE = "image",
TRANSCRIPTION = "transcription",
}
interface ModelHandler {
modelName: string;
modelType: ModelType;
generate: (
params: ModelParamsMap[ModelType],
context?: any
) => Promise<ModelResultMap[ModelType]>;
stream?: (
params: ModelParamsMap[ModelType],
context?: any
) => AsyncIterable<StreamEvent>;
}
6. 服务系统（Service System）
位置：packages/typescript/src/types/service.ts 和 packages/typescript/src/services/
Service 生命周期
interface Service {
name: ServiceTypeName;
service?: Service;
initialize?(runtime: IAgentRuntime): Promise<void>;
start?(): Promise<void>;
stop?(): Promise<void>;
}
内置服务
| 服务名 | 功能 |
|---|---|
| message | 消息处理 |
| action-filter | 动作过滤 |
| tool-policy | 工具策略 |
📦 核心类型定义
Character（角色）
角色定义了代理的人格、行为和能力：
interface Character {
name: string;
bio: string | string[];
lore: string[];
messageExamples: MessageExample[][];
postExamples: PostExample[][];
topics: string[];
style: {
all: string[];
chat: string[];
post: string[];
};
adjectives: string[];
plugins?: Plugin[];
settings?: Partial<RuntimeSettings>;
clientSettings?: { [key: string]: any };
}
State（状态）
代理的当前状态，包括对话上下文、用户信息等：
interface State {
agentId?: UUID;
roomId?: UUID;
userId?: UUID;
conversationLength?: number;
agentName?: string;
senderName?: string;
actors?: string;
recentMessages?: string;
recentPosts?: string;
[key: string]: StateValue;
}
🔄 消息处理工作流
完整处理流程
flowchart TD
Start([收到消息]) --> A1[验证消息]
A1 --> A2[创建/获取 Room]
A2 --> A3[创建 Memory]
A3 --> A4[保存到数据库]
A4 --> B1[获取对话历史]
B1 --> B2[调用 Providers]
B2 --> B3[构建 State]
B3 --> C1{检查是否响应?}
C1 -->|否| D1[结束]
C1 -->|是| E1[选择/规划动作]
E1 --> E2{需要规划?}
E2 -->|是| E3[生成多步计划]
E2 -->|否| E4[单步执行]
E3 --> F1[执行动作]
E4 --> F1
F1 --> F2{动作成功?}
F2 -->|是| G1[评估结果]
F2 -->|否| G2[处理错误]
G1 --> H1[生成响应]
G2 --> H1
H1 --> I1[发送响应]
I1 --> J1[保存新 Memory]
J1 --> D1
🛡️ 安全与沙箱
沙箱模式
elizaOS 提供完整的沙箱功能：
// SandboxTokenManager - 管理敏感信息的 Token 化
class SandboxTokenManager {
tokenize(secret: string): string;
detokenize(token: string): string | null;
}
// SandboxFetchProxy - 审计和限制网络请求
createSandboxFetchProxy({
auditHandler: (event: SandboxFetchAuditEvent) => {
// 记录、阻止或修改请求
}
});
🚀 启动与初始化流程
AgentRuntime 初始化
// 1. 创建运行时实例
const runtime = new AgentRuntime({
character: myCharacter,
plugins: [plugin1, plugin2],
settings: runtimeSettings,
});
// 2. 初始化
await runtime.initialize();
// 3. 处理消息
await runtime.processMessage(message);
初始化详细步骤
graph TB
A[构造 AgentRuntime] --> B[设置基础属性]
B --> C[创建匿名 Character<br/>如果未提供]
C --> D[初始化数据库适配器]
D --> E[创建 Bootstap Plugin]
E --> F[解析插件依赖]
F --> G[按顺序加载插件]
G --> H[注册 Actions/Evaluators/Providers]
H --> I[初始化服务]
I --> J[启动事件系统]
J --> K[初始化完成!]
💡 设计亮点
1. 模块化与可扩展性
- 插件系统支持动态加载和依赖管理
- 清晰的接口分离（IAgentRuntime、Plugin、Action 等）
- 多语言实现（TypeScript、Python、Rust）
2. 性能优化
- LRU 状态缓存，限制内存增长
- 动作索引，O(1) 精确查找
- 确定性生成，可复现的测试
3. 开发体验
- 开箱即用的配置
- 完善的类型定义
- 自动插件安装
4. 生产就绪
- 沙箱模式安全保障
- 完整的日志系统
- 数据库抽象层
📚 参考资料
- GitHub: https://github.com/elizaos/eliza
- 文档: https://docs.elizaos.ai/
- 论文: arXiv:2501.06781 - “Eliza: A Web3 friendly AI Agent Operating System”
- Discord: https://discord.gg/ai16z