flux-agent

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状态监控
• 快照生成和恢复