FluxAgent

一个灵活可扩展的 AI Agent 框架，支持多种大语言模型、插件系统和智能对话管理。

特性

🤖 多模型支持 - 支持 OpenAI、Claude 等多种大语言模型
🔧 插件系统 - 可自定义工具和对话流程
💾 知识库管理 - 内置知识存储和检索功能
📸 状态快照 - 保存和恢复 Agent 状态
🌊 流式响应 - 实时获取 AI 响应内容

安装

npm install fluxagent

快速开始

基础用法

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);
  }
});

自定义系统提示

const agent = new Agent({
  llm: {
    apiKey: 'your-api-key',
    modelName: 'gpt-4'
  },
  systemPrompt: '你是一个专业的客服助手，请用友善的语气回答用户问题。'
});

知识库功能

为你的 Agent 添加专业知识：

// 添加知识条目
const knowledgeId = agent.knowledge.add({
  name: '产品介绍',
  description: '我们的主要产品功能',
  content: '我们的产品主要提供...',
  tags: ['产品', '介绍']
});

// 搜索知识
const results = agent.knowledge.search('产品功能');

// 获取所有知识
const allKnowledge = agent.knowledge.getAllKnowledge();

事件监听

监听 Agent 运行过程中的各种事件：

// 监听状态变化
agent.eventHub.register('StateChange', (event) => {
  console.log('Agent 状态:', event.payload.state);
});

// 监听工具调用
agent.eventHub.register('Before-CalculatorTool', (event) => {
  console.log('开始计算:', event.payload.arguments);
});

插件系统

通过插件扩展 Agent 功能：

// 添加计算器功能
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): 移除某个阶段

插件示例

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: 知识库清空

事件监听

基本事件监听

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 方法可以监听某个类型的所有事件，这对于全局监控非常有用：

// 监听所有阶段事件
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);
});

组合使用

名称监听器和类型监听器可以同时使用，事件触发时两者都会被调用：

// 监听特定事件
agent.eventHub.register(AgentEventName.BEFORE_PLAN, (event) => {
  console.log('特定事件监听器 - 计划阶段开始');
});

// 监听所有阶段事件
agent.eventHub.registerType('PhaseEvent', (event) => {
  console.log(`类型监听器 - 阶段事件: ${event.name}`);
});

// 当BEFORE_PLAN事件触发时，两个监听器都会被调用

取消监听

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);

实际应用场景

全局事件监控：

// 创建全局事件监控器
const eventTypes = ['PhaseEvent', 'ToolCallEvent', 'StateChangeEvent', 'StreamEvent', 'KnowledgeEvent', 'UIEvent'];

eventTypes.forEach(eventType => {
  agent.eventHub.registerType(eventType, (event) => {
    console.log(`[全局监控] ${eventType}: ${event.name}`, event.payload);
  });
});

流式事件统一处理：

// 统一处理所有流式事件
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;
  }
});

知识库操作监控：

// 监控所有知识库操作
agent.eventHub.registerType('KnowledgeEvent', (event) => {
  const { action, knowledgeName, itemCount } = event.payload;
  console.log(`知识库操作: ${action} - ${knowledgeName} (总数: ${itemCount})`);
});

4. 知识库能力

内置的知识库系统支持完整的CRUD操作。

添加知识条目

// 添加单个知识条目
const knowledgeId = agent.knowledge.add({
  name: '法律条文',
  description: '民法典第一条的相关内容',
  content: '根据《民法典》第一条...',
  tags: ['民法', '基础']
});

获取知识库数据

// 获取所有知识
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 }

搜索知识条目

// 关键词搜索
const results = agent.knowledge.search('民法典');
console.log('搜索结果:', results);

更新知识条目

// 更新知识条目
const success = agent.knowledge.update(knowledgeId, {
  content: '更新后的内容',
  tags: ['民法', '基础', '更新']
});

删除知识条目

// 删除单个知识条目
const success = agent.knowledge.remove([knowledgeId]);

// 清空所有知识
agent.knowledge.clear();

导入导出

// 导出知识库
const exportData = agent.knowledge.export();

// 导入知识库
agent.knowledge.import(exportData);

5. 快照能力

快照功能允许保存和恢复 Agent 的完整状态。

生成快照

// 生成当前状态快照
const snapshot = agent.genSnapshot();

console.log('快照信息:', {
  timestamp: snapshot.timestamp,
  version: snapshot.version,
  state: snapshot.state,
  currentPhase: snapshot.currentPhase,
  knowledgeCount: snapshot.knowledgeItems?.length || 0
});

应用快照

// 恢复到指定快照状态
agent.applySnapshot(snapshot);
console.log('Agent状态已恢复');

重置状态

// 重置Agent到初始状态
agent.reset();
console.log('Agent已重置到初始状态');

快照数据结构

interface AgentSnapshot {
  state: AgentState;           // Agent状态
  currentPhase: PhaseType;     // 当前阶段
  contextRecords: any[];       // 上下文记录
  memoryMessages: any[];       // 记忆消息
  phaseState?: any;           // 阶段状态
  userInputStack: string[];    // 用户输入栈
  knowledgeItems?: KnowledgeItem[]; // 知识库条目
  timestamp: number;           // 时间戳
  version: string;            // 快照版本
}

6. 记忆模块

记忆模块管理与LLM的对话上下文。

获取记忆数据

// 通过Context获取Memory实例
const memory = agent.context.getMemory();

// 获取所有对话消息
const messages = memory.getMessages();
console.log('对话记录:', messages);

消息格式

// 消息结构示例
const messageFormat = {
  role: 'user' | 'assistant' | 'system',
  content: string,
  tool_calls?: Array<any>,
  timestamp: number
};

清空记忆

// 清空所有对话记录
memory.clear();
console.log('对话记录已清空');

记忆状态监控

// 监控记忆变化
agent.eventHub.register('MemoryUpdate', (event) => {
  const messageCount = agent.context.getMemory().getMessages().length;
  console.log(`当前对话记录数量: ${messageCount}`);
});

7. 启动执行

流式执行 (推荐)

流式执行提供实时的响应和状态更新。

// 创建流式回调
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);

传统执行 (已废弃)

// 注意：此方法已被流式执行替代，现在只返回提示信息
const response = await agent.handleUserInput('用户输入');
// 返回: '请使用流式执行方法 runStream 来运行Agent'

完整使用示例

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按照以下标准阶段执行：

CONFIRM: 确认和澄清用户需求
THINKPLAN: 思考和规划任务
PLAN: 制定详细执行计划
REACT: 执行具体任务步骤
SUMMARY: 总结执行结果

每个阶段都可以通过插件进行自定义或禁用。

系统工具

框架内置以下系统工具：

EndPhaseTool: 结束当前阶段，流转到下一阶段

工具使用说明

系统工具会自动注册到Agent中，LLM可以根据需要调用：

// LLM决定结束当前阶段时会调用
EndPhaseTool.execute()

最佳实践

使用流式执行: 为了更好的用户体验，建议使用runStream方法而不是handleUserInput
合理使用知识库: 将常用信息添加到知识库，系统会自动将相关知识注入到用户输入中
监听关键事件: 通过事件系统监控Agent状态和工具调用，便于调试和监控
定期生成快照: 在关键节点保存Agent状态，支持状态恢复
插件模块化: 将不同功能封装为独立插件，使用context.addTools()添加工具
工具设计: 优先使用新的BaseTool类型，支持更好的上下文管理
事件命名: 使用AgentEventName枚举而不是字符串，避免拼写错误

性能优化建议

知识库条目过多时，可以选择性激活：agent.knowledge.setActive(id, false)
定期清理不需要的记忆：agent.context.getMemory().clear()
合理使用插件的disconnect()方法跳过不必要的阶段

故障排除

LLM连接问题: 检查API密钥和baseURL配置，确保模型名称正确
工具调用失败: 查看AgentLogger日志，检查工具参数和执行上下文
记忆过载: 定期使用agent.context.getMemory().clear()清理或使用快照功能
事件监听问题: 使用AgentEventName枚举，确认事件名称正确
知识库不生效: 检查知识条目是否激活（isActive: true），内容格式是否正确
插件工具未注册: 确保在插件中正确调用context.addTools()

调试技巧

// 开启详细日志
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聊天服务器示例：

# 启动聊天服务器
cd src/examples
ts-node chat-server.ts

# 访问聊天界面
open http://localhost:8080

聊天服务器支持：

实时流式对话
知识库管理界面
记忆查看和清理
Agent状态监控
快照生成和恢复

Package detail

readme

FluxAgent

特性

安装

快速开始

基础用法

自定义系统提示

知识库功能

事件监听

插件系统

状态管理

插件示例

3. 事件系统

事件类型

阶段事件 (PhaseEvent)

工具调用事件 (ToolCallEvent)

状态变更事件 (StateChangeEvent)

流式事件 (StreamEvent)

UI事件 (UIEvent)

知识库事件 (KnowledgeEvent)

事件监听

基本事件监听

类型监听器 (新增)

组合使用

取消监听

实际应用场景

4. 知识库能力

添加知识条目

获取知识库数据

搜索知识条目

更新知识条目

删除知识条目

导入导出

5. 快照能力

生成快照

应用快照

重置状态

快照数据结构

6. 记忆模块

获取记忆数据

消息格式

清空记忆

记忆状态监控

7. 启动执行

流式执行 (推荐)

传统执行 (已废弃)

完整使用示例

Agent流程阶段

系统工具

工具使用说明

最佳实践

性能优化建议

故障排除

调试技巧

技术栈

WebSocket服务器示例