flux-agent
Version:
FluxAgent - 一个可灵活插拔的AI Agent系统框架，基于TypeScript开发，支持流式执行、事件系统、插件系统、知识库管理等功能 (Protected Release) (Protected Release) (Protected Release) (Protected Release) (Protected Release) (Protected Release) (Protected Release) (Protected Release) (Protected Release) (
678 lines (529 loc) • 17.7 kB
Markdown
# FluxAgent
一个灵活可扩展的 AI Agent 框架，支持多种大语言模型、插件系统和智能对话管理。
## 特性
- 🤖 **多模型支持** - 支持 OpenAI、Claude 等多种大语言模型
- 🔧 **插件系统** - 可自定义工具和对话流程
- 💾 **知识库管理** - 内置知识存储和检索功能
- 📸 **状态快照** - 保存和恢复 Agent 状态
- 🌊 **流式响应** - 实时获取 AI 响应内容
## 安装
```bash
npm install fluxagent
```
## 快速开始
### 基础用法
```typescript
import { Agent } from 'fluxagent';
// 创建 Agent 实例
const agent = new Agent({
llm: {
apiKey: 'your-openai-api-key',
modelName: 'gpt-4'
}
});
// 启动对话
await agent.runStream('你好，请介绍一下你自己', {
onLLMToken: (token) => {
process.stdout.write(token); // 实时输出
},
onComplete: (response) => {
console.log('\n对话完成:', response);
}
});
```
### 自定义系统提示
```typescript
const agent = new Agent({
llm: {
apiKey: 'your-api-key',
modelName: 'gpt-4'
},
systemPrompt: '你是一个专业的客服助手，请用友善的语气回答用户问题。'
});
```
## 知识库功能
为你的 Agent 添加专业知识：
```typescript
// 添加知识条目
const knowledgeId = agent.knowledge.add({
name: '产品介绍',
description: '我们的主要产品功能',
content: '我们的产品主要提供...',
tags: ['产品', '介绍']
});
// 搜索知识
const results = agent.knowledge.search('产品功能');
// 获取所有知识
const allKnowledge = agent.knowledge.getAllKnowledge();
```
## 事件监听
监听 Agent 运行过程中的各种事件：
```typescript
// 监听状态变化
agent.eventHub.register('StateChange', (event) => {
console.log('Agent 状态:', event.payload.state);
});
// 监听工具调用
agent.eventHub.register('Before-CalculatorTool', (event) => {
console.log('开始计算:', event.payload.arguments);
});
```
## 插件系统
通过插件扩展 Agent 功能：
```typescript
// 添加计算器功能
agent.plugin('calculator', (context) => {
context.addTools([{
type: 'function',
function: {
name: 'calculate',
description: '执行数学计算',
parameters: {
type: 'object',
properties: {
expression: {
type: 'string',
description: '要计算的数学表达式'
}
}
}
}
}]);
});
// 自定义对话流程
agent.plugin('customerService', (context) => {
context.tap('Before-confirm', (payload) => {
return {
prompt: `作为客服，${payload.prompt}`
};
});
});
```
## 状态管理
- `addTools(tools: Array<BaseTool | Tool>)`: 添加工具列表（支持新旧工具类型）
- `tap(eventName: AgentEventName, callback)`: 影响输出的事件监听
- `tapVoid(eventName: AgentEventName, callback)`: 只执行动作的事件监听
- `disconnect(phaseName: string)`: 移除某个阶段
### 插件示例
```typescript
import { PushUITool } from './tools/PushUITool';
// 注册UI推送插件
agent.plugin('uiPlugin', (context) => {
const pushUITool = new PushUITool();
context.addTools([pushUITool]);
});
// 注册计算器插件
import { CalculatorTool } from './tools/CalculatorTool';
agent.plugin('calculator', (context) => {
context.addTools([CalculatorTool.getCalculatorTool()]);
});
```
## 3. 事件系统
事件系统提供了对 Agent 运行过程的完整监控能力，支持两种监听方式：
- **事件名称监听**：监听特定的事件名称
- **事件类型监听**：监听某一类型的所有事件
### 事件类型
#### 阶段事件 (PhaseEvent)
- `Before-confirm`: confirm阶段开始前
- `After-confirm`: confirm阶段结束后
- `Before-thinkplan`: thinkplan阶段开始前
- `After-thinkplan`: thinkplan阶段结束后
- `Before-plan`: plan阶段开始前
- `After-plan`: plan阶段结束后
- `Before-react`: react阶段开始前
- `After-react`: react阶段结束后
- `Before-summary`: summary阶段开始前
- `After-summary`: summary阶段结束后
#### 工具调用事件 (ToolCallEvent)
- `Before-[ToolName]`: 工具调用前（如：`Before-PushUITool`）
- `After-[ToolName]`: 工具调用后（如：`After-PushUITool`）
#### 状态变更事件 (StateChangeEvent)
- `StateChange`: Agent状态变更
#### 流式事件 (StreamEvent)
- `stream-token`: 实时token流
- `stream-partial-response`: 部分响应
- `stream-phase-change`: 阶段变更
- `stream-tool-call-start`: 工具调用开始
- `stream-tool-call-end`: 工具调用结束
#### UI事件 (UIEvent)
- `PushComponent`: UI组件推送事件
- `UIResultEvent`: UI操作结果事件
#### 知识库事件 (KnowledgeEvent)
- `knowledge-added`: 知识条目添加
- `knowledge-removed`: 知识条目删除
- `knowledge-updated`: 知识条目更新
- `knowledge-applied`: 知识库内容应用
- `knowledge-cleared`: 知识库清空
### 事件监听
#### 基本事件监听
```typescript
import { AgentEventName } from './core/EventHub';
// 监听特定事件名称
agent.eventHub.register(AgentEventName.STATE_CHANGE, (event) => {
console.log('Agent状态变更:', event.payload.state);
});
// 监听阶段变更
agent.eventHub.register(AgentEventName.BEFORE_CONFIRM, (event) => {
console.log('进入确认阶段前:', event.payload);
});
```
#### 类型监听器 (新增)
使用 `registerType` 方法可以监听某个类型的所有事件，这对于全局监控非常有用：
```typescript
// 监听所有阶段事件
agent.eventHub.registerType('PhaseEvent', (event) => {
console.log(`阶段事件: ${event.name}`, event.payload);
});
// 监听所有流式事件
agent.eventHub.registerType('StreamEvent', (event) => {
console.log(`流式事件: ${event.name}`, event.payload);
});
// 监听所有知识库事件
agent.eventHub.registerType('KnowledgeEvent', (event) => {
console.log(`知识库事件: ${event.name}`, event.payload);
});
// 监听所有工具调用事件
agent.eventHub.registerType('ToolCallEvent', (event) => {
console.log(`工具调用事件: ${event.name}`, event.payload);
});
// 监听所有UI事件
agent.eventHub.registerType('UIEvent', (event) => {
console.log(`UI事件: ${event.name}`, event.payload);
});
```
#### 组合使用
名称监听器和类型监听器可以同时使用，事件触发时两者都会被调用：
```typescript
// 监听特定事件
agent.eventHub.register(AgentEventName.BEFORE_PLAN, (event) => {
console.log('特定事件监听器 - 计划阶段开始');
});
// 监听所有阶段事件
agent.eventHub.registerType('PhaseEvent', (event) => {
console.log(`类型监听器 - 阶段事件: ${event.name}`);
});
// 当BEFORE_PLAN事件触发时，两个监听器都会被调用
```
#### 取消监听
```typescript
const listener = (event) => console.log(event);
// 注册监听器
agent.eventHub.register(AgentEventName.STATE_CHANGE, listener);
agent.eventHub.registerType('PhaseEvent', listener);
// 取消监听器
agent.eventHub.unregister(AgentEventName.STATE_CHANGE, listener);
agent.eventHub.unregisterType('PhaseEvent', listener);
```
#### 实际应用场景
**全局事件监控**：
```typescript
// 创建全局事件监控器
const eventTypes = ['PhaseEvent', 'ToolCallEvent', 'StateChangeEvent', 'StreamEvent', 'KnowledgeEvent', 'UIEvent'];
eventTypes.forEach(eventType => {
agent.eventHub.registerType(eventType, (event) => {
console.log(`[全局监控] ${eventType}: ${event.name}`, event.payload);
});
});
```
**流式事件统一处理**：
```typescript
// 统一处理所有流式事件
agent.eventHub.registerType('StreamEvent', (event) => {
switch (event.name) {
case AgentEventName.STREAM_TOKEN:
process.stdout.write(event.payload.token);
break;
case AgentEventName.STREAM_PHASE_CHANGE:
console.log(`\n[阶段变更] ${event.payload.toPhase}`);
break;
case AgentEventName.STREAM_TOOL_CALL_START:
console.log(`\n[工具调用] ${event.payload.toolName}`);
break;
}
});
```
**知识库操作监控**：
```typescript
// 监控所有知识库操作
agent.eventHub.registerType('KnowledgeEvent', (event) => {
const { action, knowledgeName, itemCount } = event.payload;
console.log(`知识库操作: ${action} - ${knowledgeName} (总数: ${itemCount})`);
});
```
## 4. 知识库能力
内置的知识库系统支持完整的CRUD操作。
### 添加知识条目
```typescript
// 添加单个知识条目
const knowledgeId = agent.knowledge.add({
name: '法律条文',
description: '民法典第一条的相关内容',
content: '根据《民法典》第一条...',
tags: ['民法', '基础']
});
```
### 获取知识库数据
```typescript
// 获取所有知识
const allKnowledge = agent.knowledge.getAllKnowledge();
// 获取单个知识条目
const item = agent.knowledge.get(knowledgeId);
// 获取知识库统计
const stats = agent.knowledge.getStats();
console.log('知识库统计:', stats); // { total: 10, active: 8, inactive: 2 }
```
### 搜索知识条目
```typescript
// 关键词搜索
const results = agent.knowledge.search('民法典');
console.log('搜索结果:', results);
```
### 更新知识条目
```typescript
// 更新知识条目
const success = agent.knowledge.update(knowledgeId, {
content: '更新后的内容',
tags: ['民法', '基础', '更新']
});
```
### 删除知识条目
```typescript
// 删除单个知识条目
const success = agent.knowledge.remove([knowledgeId]);
// 清空所有知识
agent.knowledge.clear();
```
### 导入导出
```typescript
// 导出知识库
const exportData = agent.knowledge.export();
// 导入知识库
agent.knowledge.import(exportData);
```
## 5. 快照能力
快照功能允许保存和恢复 Agent 的完整状态。
### 生成快照
```typescript
// 生成当前状态快照
const snapshot = agent.genSnapshot();
console.log('快照信息:', {
timestamp: snapshot.timestamp,
version: snapshot.version,
state: snapshot.state,
currentPhase: snapshot.currentPhase,
knowledgeCount: snapshot.knowledgeItems?.length || 0
});
```
### 应用快照
```typescript
// 恢复到指定快照状态
agent.applySnapshot(snapshot);
console.log('Agent状态已恢复');
```
### 重置状态
```typescript
// 重置Agent到初始状态
agent.reset();
console.log('Agent已重置到初始状态');
```
### 快照数据结构
```typescript
interface AgentSnapshot {
state: AgentState; // Agent状态
currentPhase: PhaseType; // 当前阶段
contextRecords: any[]; // 上下文记录
memoryMessages: any[]; // 记忆消息
phaseState?: any; // 阶段状态
userInputStack: string[]; // 用户输入栈
knowledgeItems?: KnowledgeItem[]; // 知识库条目
timestamp: number; // 时间戳
version: string; // 快照版本
}
```
## 6. 记忆模块
记忆模块管理与LLM的对话上下文。
### 获取记忆数据
```typescript
// 通过Context获取Memory实例
const memory = agent.context.getMemory();
// 获取所有对话消息
const messages = memory.getMessages();
console.log('对话记录:', messages);
```
### 消息格式
```typescript
// 消息结构示例
const messageFormat = {
role: 'user' | 'assistant' | 'system',
content: string,
tool_calls?: Array<any>,
timestamp: number
};
```
### 清空记忆
```typescript
// 清空所有对话记录
memory.clear();
console.log('对话记录已清空');
```
### 记忆状态监控
```typescript
// 监控记忆变化
agent.eventHub.register('MemoryUpdate', (event) => {
const messageCount = agent.context.getMemory().getMessages().length;
console.log(`当前对话记录数量: ${messageCount}`);
});
```
## 7. 启动执行
### 流式执行 (推荐)
流式执行提供实时的响应和状态更新。
```typescript
// 创建流式回调
const streamCallbacks: AgentStreamCallbacks = {
onPhaseChange: (fromPhase, toPhase) => {
console.log(`阶段变更: ${fromPhase} -> ${toPhase}`);
},
onLLMToken: (token, phase, id) => {
process.stdout.write(token); // 实时输出token
},
onLLMPartialResponse: (partial, phase, id) => {
console.log('部分响应:', partial);
},
onToolCall: (toolName, args, phase) => {
console.log(`工具调用: ${toolName}`, args);
},
onToolResult: (toolName, result, phase) => {
console.log(`工具结果: ${toolName}`, result);
},
onError: (error, phase) => {
console.error('执行错误:', error.message);
},
onComplete: (finalResponse) => {
console.log('执行完成:', finalResponse);
}
};
// 启动流式执行
const sessionId = 'session_' + Date.now();
await agent.runStream('帮我分析这个法律案例', streamCallbacks, sessionId);
```
### 传统执行 (已废弃)
```typescript
// 注意：此方法已被流式执行替代，现在只返回提示信息
const response = await agent.handleUserInput('用户输入');
// 返回: '请使用流式执行方法 runStream 来运行Agent'
```
## 完整使用示例
```typescript
import { Agent, AgentConfig, AgentStreamCallbacks } from './core/Agent';
import { PushUITool } from './tools/PushUITool';
// 1. 初始化Agent
const config: AgentConfig = {
llm: {
apiKey: process.env.OPENAI_API_KEY,
baseURL: process.env.OPENAI_BASE_URL,
modelName: "gpt-4"
},
systemPrompt: "你是一个专业的法律助手"
};
const agent = new Agent(config);
// 2. 注册插件
agent.plugin('legalAssistant', (context) => {
const pushUITool = new PushUITool();
pushUITool.applyAgent(agent);
context.addTools([pushUITool]);
});
// 3. 设置事件监听
agent.eventHub.register('StateChange', (event) => {
console.log('状态变更:', event.payload.state);
});
// 4. 添加知识库
agent.knowledge.add({
name: '民法典第一条',
description: '民法典第一条的内容说明',
content: '为了保护民事主体的合法权益...',
tags: ['法律', '民法典']
});
// 5. 创建流式回调
const callbacks: AgentStreamCallbacks = {
onLLMToken: (token) => process.stdout.write(token),
onComplete: (response) => console.log('\n执行完成:', response)
};
// 6. 启动执行
await agent.runStream('帮我解释民法典第一条', callbacks);
// 7. 生成快照
const snapshot = agent.genSnapshot();
console.log('快照已生成');
// 8. 重置Agent
agent.reset();
```
## Agent流程阶段
Agent按照以下标准阶段执行：
1. **CONFIRM**: 确认和澄清用户需求
2. **THINKPLAN**: 思考和规划任务
3. **PLAN**: 制定详细执行计划
4. **REACT**: 执行具体任务步骤
5. **SUMMARY**: 总结执行结果
每个阶段都可以通过插件进行自定义或禁用。
## 系统工具
框架内置以下系统工具：
- `EndPhaseTool`: 结束当前阶段，流转到下一阶段
### 工具使用说明
系统工具会自动注册到Agent中，LLM可以根据需要调用：
```typescript
// LLM决定结束当前阶段时会调用
EndPhaseTool.execute()
```
## 最佳实践
1. **使用流式执行**: 为了更好的用户体验，建议使用`runStream`方法而不是`handleUserInput`
2. **合理使用知识库**: 将常用信息添加到知识库，系统会自动将相关知识注入到用户输入中
3. **监听关键事件**: 通过事件系统监控Agent状态和工具调用，便于调试和监控
4. **定期生成快照**: 在关键节点保存Agent状态，支持状态恢复
5. **插件模块化**: 将不同功能封装为独立插件，使用`context.addTools()`添加工具
6. **工具设计**: 优先使用新的`BaseTool`类型，支持更好的上下文管理
7. **事件命名**: 使用`AgentEventName`枚举而不是字符串，避免拼写错误
### 性能优化建议
- 知识库条目过多时，可以选择性激活：`agent.knowledge.setActive(id, false)`
- 定期清理不需要的记忆：`agent.context.getMemory().clear()`
- 合理使用插件的`disconnect()`方法跳过不必要的阶段
## 故障排除
1. **LLM连接问题**: 检查API密钥和baseURL配置，确保模型名称正确
2. **工具调用失败**: 查看AgentLogger日志，检查工具参数和执行上下文
3. **记忆过载**: 定期使用`agent.context.getMemory().clear()`清理或使用快照功能
4. **事件监听问题**: 使用`AgentEventName`枚举，确认事件名称正确
5. **知识库不生效**: 检查知识条目是否激活（`isActive: true`），内容格式是否正确
6. **插件工具未注册**: 确保在插件中正确调用`context.addTools()`
### 调试技巧
```typescript
// 开启详细日志
import { AgentLogger } from './core/Agent';
console.log(AgentLogger.getLogs()); // 查看所有日志
// 监听所有事件进行调试
Object.values(AgentEventName).forEach(eventName => {
agent.eventHub.register(eventName, (event) => {
console.log(`事件触发: ${eventName}`, event.payload);
});
});
```
## 技术栈
- **语言**: TypeScript
- **包管理**: pnpm
- **LLM支持**: OpenAI兼容接口（支持阿里云、OpenAI等）
- **事件系统**: 内置EventHub，支持同步和流式事件
- **流式处理**: 内置流式执行引擎，支持实时Token输出
- **工具系统**: 支持新旧两种工具类型（BaseTool和Tool）
- **存储**: 内存存储，支持快照导入导出
## WebSocket服务器示例
FluxAgent 提供了完整的WebSocket聊天服务器示例：
```bash
# 启动聊天服务器
cd src/examples
ts-node chat-server.ts
# 访问聊天界面
open http://localhost:8080
```
聊天服务器支持：
- 实时流式对话
- 知识库管理界面
- 记忆查看和清理
- Agent状态监控
- 快照生成和恢复