FluxAgent - 一个可灵活插拔的AI Agent系统框架，基于TypeScript开发，支持流式执行、事件系统、插件系统、知识库管理等功能 (Protected Release)
一个灵活可扩展的 AI Agent 框架，支持多种大语言模型、插件系统和智能对话管理。
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()]);
});
事件系统提供了对 Agent 运行过程的完整监控能力，支持两种监听方式：
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阶段结束后Before-[ToolName]: 工具调用前（如：Before-PushUITool）After-[ToolName]: 工具调用后（如：After-PushUITool）StateChange: Agent状态变更stream-token: 实时token流stream-partial-response: 部分响应stream-phase-change: 阶段变更stream-tool-call-start: 工具调用开始stream-tool-call-end: 工具调用结束PushComponent: UI组件推送事件UIResultEvent: UI操作结果事件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})`);
});
内置的知识库系统支持完整的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);
快照功能允许保存和恢复 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; // 快照版本
}
记忆模块管理与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}`);
});
流式执行提供实时的响应和状态更新。
// 创建流式回调
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按照以下标准阶段执行：
每个阶段都可以通过插件进行自定义或禁用。
框架内置以下系统工具：
EndPhaseTool: 结束当前阶段，流转到下一阶段系统工具会自动注册到Agent中，LLM可以根据需要调用：
// LLM决定结束当前阶段时会调用
EndPhaseTool.execute()
runStream方法而不是handleUserInputcontext.addTools()添加工具BaseTool类型，支持更好的上下文管理AgentEventName枚举而不是字符串，避免拼写错误agent.knowledge.setActive(id, false)agent.context.getMemory().clear()disconnect()方法跳过不必要的阶段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);
});
});
FluxAgent 提供了完整的WebSocket聊天服务器示例：
# 启动聊天服务器
cd src/examples
ts-node chat-server.ts
# 访问聊天界面
open http://localhost:8080
聊天服务器支持：
FAQs
FluxAgent - 一个可灵活插拔的AI Agent系统框架，基于TypeScript开发，支持流式执行、事件系统、插件系统、知识库管理等功能 (Protected Release)
We found that fluxagent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses the recent npm supply chain attacks on PodRocket, covering novel attack vectors and how developers can protect themselves.
Security News
Maintainers back GitHub’s npm security overhaul but raise concerns about CI/CD workflows, enterprise support, and token management.
Product
Socket Firewall is a free tool that blocks malicious packages at install time, giving developers proactive protection against rising supply chain attacks.