Agent Stream SDK

这是一个用于处理智能代理流式响应的SDK，支持从不同数据源（如SSE或WebSocket）接收消息，并转换为统一的格式。

功能特点

• 支持多种数据源：Server-Sent Events (SSE) 和 WebSocket
• 统一的事件处理机制
• 丰富的回调函数支持
• 内容块管理和更新
• 工具事件处理
• 支持调试模式便于排查问题

安装

npm install agent-stream-sdk

基本用法

创建处理器

import { AgentStreamHandler } from 'agent-stream-sdk';

// 创建处理器
const agentStreamHandler = new AgentStreamHandler({
  onNewBlock: (block) => console.log('新内容块:', block),
  onBlockUpdate: (index, block) => console.log(`内容块${index}更新:`, block),
  onComplete: (blocks) => console.log('会话完成, 所有内容块:', blocks),
  onNewToolEvent: (toolEvent) => console.log('工具事件:', toolEvent),
  onError: (error) => console.error('发生错误:', error),
  debug: true // 启用调试模式
});

// 直接处理事件
agentStreamHandler.handleEvent({
  event: 'content_block_start',
  data: {
    type: 'content_block_start',
    index: 0,
    content_block: { text: '', type: 'text' }
  }
});

使用WebSocket

以下是一个使用WebSocket接收数据并处理的示例：

<script src="../dist/agent-stream-sdk.js"></script>

<script>
  // 创建处理器实例
  const agentStreamHandler = new AgentStreamSDK.AgentStreamHandler({
    debug: true
  });
  
  // 直接设置回调方法
  agentStreamHandler.onNewBlock = function(block) {
    console.log('新块:', block);
  };
  
  agentStreamHandler.onBlockUpdate = function(index, block) {
    console.log('块更新:', index, block);
  };
  
  agentStreamHandler.onComplete = function(blocks) {
    console.log('会话完成:', blocks);
  };
  
  agentStreamHandler.onNewToolEvent = function(toolEvent) {
    console.log('新工具事件:', toolEvent);
  };
  
  agentStreamHandler.onError = function(error) {
    console.error('错误:', error);
  };

  // 创建WebSocket连接
  const ws = new WebSocket('ws://localhost:6544');

  // 接收消息时
  ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    // 将消息交给 agentStreamHandler 处理
    agentStreamHandler.handleEvent(message);
  };
</script>

内容展示

SDK支持在UI上展示处理后的内容块：

// 更新UI上的内容块
agentStreamHandler.onNewBlock = function(block) {
  console.log('新块:', block);
  
  // 为新块创建元素，并设置唯一ID
  const messageEl = document.createElement('div');
  messageEl.className = 'message';
  messageEl.id = `block-${blockCounter}`; // 使用计数器
  
  const eventNameEl = document.createElement('div');
  eventNameEl.className = 'event-name';
  eventNameEl.textContent = `回调: onNewBlock (索引: ${blockCounter})`;
  
  const dataEl = document.createElement('pre');
  dataEl.className = 'block-content';
  dataEl.textContent = JSON.stringify(block, null, 2);
  
  messageEl.appendChild(eventNameEl);
  messageEl.appendChild(dataEl);
  blocksEl.appendChild(messageEl);
  
  // 递增计数器
  blockCounter++;
};

// 更新已有的内容块
agentStreamHandler.onBlockUpdate = function(index, block) {
  console.log('块更新:', index, block);
  
  // 查找对应索引的块元素
  const blockEl = document.getElementById(`block-${index}`);
  
  if (blockEl) {
    // 更新内容
    const dataEl = blockEl.querySelector('.block-content');
    if (dataEl) {
      dataEl.textContent = JSON.stringify(block, null, 2);
    }
    
    // 高亮显示更新的元素
    blockEl.style.backgroundColor = '#ffffd0';
    setTimeout(() => {
      blockEl.style.backgroundColor = '';
    }, 500);
  }
};

特性说明

内容块处理

SDK会处理不同类型的内容块：

• TEXT: 文本内容
• TOOL_USE: 工具使用
• TOOL_EVENT: 工具事件

事件类型

SDK处理以下类型的事件：

• THREAD_START: 会话开始
• MESSAGE_START: 消息开始
• CONTENT_BLOCK_START: 内容块开始
• CONTENT_BLOCK_DELTA: 内容块增量更新
• CONTENT_BLOCK_END: 内容块结束
• THREAD_END: 会话结束
• MESSAGE_DELTA: 消息增量
• MESSAGE_STOP: 消息结束

获取处理结果

// 获取所有内容块
const blocks = agentStreamHandler.getAllBlocks();

// 获取线程ID
const threadId = agentStreamHandler.getThreadId();

// 获取工具事件
const toolEvents = agentStreamHandler.getToolEvents();

// 将处理后的内容转换为标准响应格式
const response = agentStreamHandler.convertToResponse();

示例代码

SDK包含一个完整的演示页面，请查看 examples/demo.html，其中包含：

1. WebSocket连接和数据处理
2. 分离显示原始事件和处理后的内容块
3. 实时更新内容块的UI展示

API参考

AgentStreamHandler类

class AgentStreamHandler {
  constructor({
    onNewBlock,
    onBlockUpdate,
    onComplete,
    onNewToolEvent,
    onError,
    debug = false
  }: {
    onNewBlock: (block: ContentBlock) => void;
    onBlockUpdate: (index: number, block: ContentBlock) => void;
    onComplete: (blocks: ContentBlock[]) => void;
    onNewToolEvent: (toolEvent: ToolEvent[]) => void;
    onError: (error: any) => void;
    debug: boolean;
  })

  // 重要方法
  handleEvent(event: StreamEvent): void
  reset(): void
  registerRequest(request: AgentRequest): void
  handleStreamEnd(): void
  convertToResponse(): AgentResponse
  getAllBlocks(): ContentBlock[]
  getThreadId(): string
  getToolEvents(): ToolEvent[]
  setDebugMode(enabled: boolean): void
}

浏览器使用

在浏览器中使用UMD格式的SDK包：

<script src="dist/agent-stream-sdk.js"></script>
<script>
  // SDK会通过AgentStreamSDK全局变量提供
  const handler = new AgentStreamSDK.AgentStreamHandler({
    // 配置回调...
  });
</script>

示例演示

运行以下命令构建SDK和启动演示服务器：

# 构建SDK
npm run build

# 启动SSE服务器 (监听端口6543)
node examples/server.js

# 启动WebSocket服务器 (监听端口6544)
node examples/server-ws.js

# 然后在浏览器中打开 examples/demo.html

SSE服务器

SSE服务器会在端口6543上运行，提供Server-Sent Events数据流。

• 访问地址：http://localhost:6543/test/sse

WebSocket服务器

WebSocket服务器会在端口6544上运行。

• WebSocket连接地址：ws://localhost:6544