@t-agent/sdk

TA Core SDK 提供 SSE (Server-Sent Events) 连接管理和实时通信功能。

特性

• 🔄 SSE 连接管理 - 自动管理 SSE 连接生命周期
• 🛡️ 连接保护 - 防止多重连接，自动关闭之前的连接
• ⏱️ 超时处理 - 内置连接超时机制 (150秒)
• 🔁 错误重试 - 完整的错误处理和重连机制
• 📨 消息分发 - 基于消息类型的智能分发
• 🎯 类型安全 - 完整的 TypeScript 类型定义

安装

# 使用 pnpm
pnpm add @t-agent/sdk

# 使用 npm
npm install @t-agent/sdk

# 使用 yarn
yarn add @t-agent/sdk

快速开始

1. 初始化 SDK

import { initSDK } from '@t-agent/sdk';

// 初始化配置
initSDK({
  baseUrl: 'https://api.example.com',
  accessToken: 'your-access-token', // 可选
});

2. 订阅 SSE 连接

import { sseSubscribe } from '@t-agent/sdk';
import type { SSECallbacks, SessionRunStreamRequest } from '@t-agent/sdk';

// 定义回调函数
const callbacks: SSECallbacks = {
  onMessage: message => {
    console.log('收到消息:', message);
  },
  onChatMessage: (content, message) => {
    console.log('聊天消息:', content);
  },
  onProcessMessage: (content, message) => {
    console.log('处理消息:', content);
  },
  onMaterialMessage: (content, message) => {
    console.log('材料消息:', content);
  },
  onAggregate: (content, message) => {
    console.log('聚合消息:', content);
  },
  onEnd: () => {
    console.log('连接结束');
  },
  onError: () => {
    console.error('连接错误');
  },
  onTimeout: () => {
    console.warn('连接超时');
  },
};

// 请求数据
const requestData: SessionRunStreamRequest = {
  sessionId: 123,
  userInput: 'Hello, world!',
  metadata: {
    attachments: [],
  },
};

// 订阅连接
sseSubscribe({
  url: '/api/stream',
  data: requestData,
  callbacks,
  options: {
    method: 'POST',
    headers: {
      'Custom-Header': 'value',
    },
  },
});

3. 管理连接

import {
  closeSSEConnection,
  isSSEConnectionActive,
  destroySSEManager,
} from '@t-agent/sdk';

// 检查连接状态
if (isSSEConnectionActive()) {
  console.log('连接活跃');
}

// 关闭当前连接
closeSSEConnection();

// 销毁管理器（清理所有资源）
destroySSEManager();

API 参考

配置函数

initSDK(config)

初始化 SDK 配置。

initSDK({
  baseUrl: string;        // 基础 URL
  accessToken?: string;   // 访问令牌（可选）
});

setBaseUrl(url) / getBaseUrl()

设置/获取基础 URL。

setAccessToken(token) / getAccessToken()

设置/获取访问令牌。

SSE 连接函数

sseSubscribe(options)

订阅 SSE 连接。

sseSubscribe({
  url: string;                    // SSE 端点 URL
  data: SessionRunStreamRequest;  // 请求数据
  callbacks: SSECallbacks;        // 回调函数
  options?: SSEOptions;           // 可选配置
});

closeSSEConnection()

关闭当前 SSE 连接。

isSSEConnectionActive()

检查是否有活跃的 SSE 连接。

destroySSEManager()

销毁 SSE 管理器，清理所有资源。

类型定义

SessionRunStreamRequest

interface SessionRunStreamRequest {
  sessionId: number;
  resumeOffset?: boolean;
  userInput?: string;
  metadata?: {
    attachments?: Attachment[];
    referenceMaterialId?: number;
  };
}

SSECallbacks

interface SSECallbacks {
  onMessage: (message: SessionMessage) => void;
  onChatMessage: (content: string, message: ChatMessage) => void;
  onProcessMessage: (content: ProcessContent, message: ProcessMessage) => void;
  onMaterialMessage: (content: string, message: MaterialMessage) => void;
  onAggregate: (content: string, message: AggregateMessage) => void;
  onStartResponse?: (response: EventSourceMessage) => void;
  onEnd?: () => void;
  onError?: () => void;
  onTimeout?: () => void;
}

SSEOptions

interface SSEOptions {
  method?: 'GET' | 'POST';
  headers?: Record<string, unknown>;
}

消息类型

SDK 支持以下消息类型：

• process - 处理过程消息
• chat_input - 聊天输入消息
• chat_output - 聊天输出消息
• material - 材料消息
• aggregate - 聚合消息
• other - 其他类型消息

最佳实践

1. 错误处理

const callbacks: SSECallbacks = {
  // ... 其他回调
  onError: () => {
    console.error('SSE 连接错误，尝试重连...');
    // 实现重连逻辑
  },
  onTimeout: () => {
    console.warn('SSE 连接超时，请检查网络');
    // 处理超时情况
  },
};

2. 连接管理

// 在组件卸载时清理连接
useEffect(() => {
  return () => {
    destroySSEManager();
  };
}, []);

3. 多连接处理

SDK 自动处理多连接情况，新的连接会自动关闭之前的连接。

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！