@cloudbase/agent-adapter-yuanqi 0.0.16 → 0.0.18

package/README.md

@@ -8,6 +8,7 @@ Tencent Yuanqi adapter for AG-Kit agents. This package provides integration betw
 - ✅ **Streaming Support**: Real-time streaming responses via OpenAI-compatible API
 - ✅ **Thinking/Reasoning Support**: Handles reasoning content from Yuanqi models with thinking events
 - ✅ **Custom Variables**: Pass custom parameters to Yuanqi agents
+- ✅ **Chat History Persistence**: Automatic conversation history storage via Tencent CloudBase
 
 ## Installation
 
@@ -19,9 +20,24 @@ npm install @cloudbase/agent-adapter-yuanqi
 
 Configure the following environment variables:
 
+**Important**: If chat history behavior is not overridden, chat history will be stored in Tencent CloudBase as default. Please ensure that the necessary environment variables are set for CloudBase authentication.
+
 ```bash
-YUANQI_APP_ID=your-yuanqi-assistant-id   # Yuanqi assistant ID (required)
-YUANQI_APP_KEY=your-yuanqi-app-key       # Yuanqi application key (required)
+# Yuanqi Configuration (required)
+YUANQI_APP_ID=your-yuanqi-assistant-id   # Yuanqi assistant ID
+YUANQI_APP_KEY=your-yuanqi-app-key       # Yuanqi application key
+
+# CloudBase Configuration (required for chat history persistence)
+CLOUDBASE_ENV_ID=your-cloudbase-env-id   # CloudBase environment ID
+# Alternative env names: CBR_ENV_ID or SCF_NAMESPACE are also supported
+
+# Tencent Cloud Credentials (required for chat history persistence)
+# Option 1: Use SecretId + SecretKey (permanent credentials)
+TENCENTCLOUD_SECRETID=your-secret-id
+TENCENTCLOUD_SECRETKEY=your-secret-key
+
+# Option 2: Use Session Token (temporary credentials, e.g., in cloud functions)
+TENCENTCLOUD_SESSIONTOKEN=your-session-token
 ```
 
 ## Quick Start
@@ -33,13 +49,19 @@ import { YuanqiAgent } from "@cloudbase/agent-adapter-yuanqi";
 
 const agent = new YuanqiAgent({
   yuanqiConfig: {
-    appId: process.env.YUANQI_APP_ID,   // Or set via YUANQI_APP_ID env
-    appKey: process.env.YUANQI_APP_KEY, // Or set via YUANQI_APP_KEY env
+    appId: "your-assistant-id",
+    appKey: "your-app-key",
+    envId: "your-cloudbase-env-id",  // Or set via CLOUDBASE_ENV_ID env
+    credential: {
+      secretId: "your-secret-id",      // Or set via TENCENTCLOUD_SECRETID env
+      secretKey: "your-secret-key",    // Or set via TENCENTCLOUD_SECRETKEY env
+      token: "your-session-token",     // Optional, for temporary credentials
+    },
   },
 });
 ```
 
-### With Custom Configuration
+### With Full Custom Configuration
 
 ```typescript
 import { YuanqiAgent } from "@cloudbase/agent-adapter-yuanqi";
@@ -48,6 +70,11 @@ const agent = new YuanqiAgent({
   yuanqiConfig: {
     appId: "your-assistant-id",
     appKey: "your-app-key",
+    envId: "your-cloudbase-env-id",
+    credential: {
+      secretId: "your-secret-id",
+      secretKey: "your-secret-key",
+    },
     request: {
       baseUrl: "https://yuanqi.tencent.com/openapi/v1/agent", // Default base URL
       body: {
@@ -106,18 +133,47 @@ Agent class that extends `AbstractAgent` from `@ag-ui/client` and connects to Te
 constructor(config: AgentConfig & { yuanqiConfig: YuanqiConfig })
 ```
 
+**Overridable Methods:**
+
+The following protected methods can be overridden in subclasses to customize chat history behavior:
+
+```typescript
+// Get chat history from database and combine with current message
+protected async getChatHistory(
+  subscriber: Subscriber<BaseEvent>,
+  latestUserMessage: Message
+): Promise<ChatMessage[]>
+
+// Save user and assistant messages to chat history
+protected async saveChatHistory(
+  subscriber: Subscriber<BaseEvent>,
+  input: RunAgentInput,
+  userRecordId: string,
+  assistantRecordId: string,
+  userContent: string,
+  assistantContent: string
+): Promise<void>
+```
+
 ### YuanqiConfig
 
 Configuration options for the Yuanqi adapter.
 
 ```typescript
 interface YuanqiConfig {
-  appId?: string;  // Yuanqi assistant ID (optional if YUANQI_APP_ID env is set)
-  appKey?: string; // Yuanqi app key (optional if YUANQI_APP_KEY env is set)
+  appId?: string;       // Yuanqi assistant ID (optional if YUANQI_APP_ID env is set)
+  appKey?: string;      // Yuanqi app key (optional if YUANQI_APP_KEY env is set)
+  envId?: string;       // CloudBase environment ID (optional if CLOUDBASE_ENV_ID env is set)
+  historyCount?: number; // Number of history messages to fetch (default: 10)
+  credential?: {
+    secretId?: string;  // Tencent Cloud SecretId (optional if TENCENTCLOUD_SECRETID env is set)
+    secretKey?: string; // Tencent Cloud SecretKey (optional if TENCENTCLOUD_SECRETKEY env is set)
+    token?: string;     // Session token for temporary credentials (optional)
+  };
   request?: {
-    baseUrl?: string; // Base URL (default: https://yuanqi.tencent.com/openapi/v1/agent)
+    baseUrl?: string;                  // Base URL (default: https://yuanqi.tencent.com/openapi/v1/agent)
     body?: Partial<YuanqiChatRequest>; // Additional request body options
-    headers?: Record<string, string>; // Additional request headers
+    headers?: Record<string, string>;  // Additional request headers
   };
 }
 ```
@@ -138,6 +194,153 @@ interface YuanqiChatRequest {
 }
 ```
 
+### YuanqiAgentError
+
+Custom error class for Yuanqi-specific errors.
+
+```typescript
+class YuanqiAgentError extends Error {
+  code?: string;
+  constructor(message: string, code?: string);
+}
+```
+
+Error codes include:
+- `MISSING_YUANQI_APP_ID` - Yuanqi assistant ID not provided
+- `MISSING_YUANQI_APP_KEY` - Yuanqi app key not provided
+- `MISSING_CLOUDBASE_ENV_ID` - CloudBase environment ID not provided
+- `MISSING_SECRET_ID` - Tencent Cloud SecretId not provided
+- `MISSING_SECRET_KEY` - Tencent Cloud SecretKey not provided
+- `MESSAGE_FORMAT_ERROR` - No user message found in the request
+
+### processYuanqiStream
+
+Utility function to process Yuanqi streaming responses and emit AG-UI events.
+
+```typescript
+async function* processYuanqiStream(
+  stream: AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>,
+  context: StreamContext
+): AsyncGenerator<BaseEvent>
+
+interface StreamContext {
+  threadId: string;
+  runId: string;
+  messageId: string;
+}
+```
+
+### ChatHistoryEntity
+
+Entity class for chat history records stored in CloudBase.
+
+```typescript
+class ChatHistoryEntity {
+  id: number;
+  botId: string;
+  recordId: string;           // Unique conversation ID
+  role: string;               // "user" or "assistant"
+  content: string;
+  recommendQuestions: string[];
+  sender: string;
+  conversation: string;
+  type: string;
+  status: string;             // Message status: pending, done, error, cancel
+  image: string;
+  triggerSrc: string;
+  originMsg: string;
+  replyTo: string;
+  reply: string;
+  traceId: string;
+  needAsyncReply: boolean;
+  asyncReply: string;
+  createTime: string;
+  updateTime: string;
+  createdAt: number;
+  updatedAt: number;
+  event: string;
+}
+```
+
+### ChatHistoryData
+
+Interface for raw chat history data from CloudBase database.
+
+```typescript
+interface ChatHistoryData {
+  bot_id: string;
+  record_id: string;
+  role: string;
+  status: string;
+  content: string;
+  sender: string;
+  conversation: string;
+  type: string;
+  trigger_src: string;
+  origin_msg: string;
+  reply_to: string;
+  reply: string;
+  trace_id: string;
+  need_async_reply: boolean;
+  async_reply: string;
+  createdAt: number;
+  updatedAt: number;
+}
+```
+
+### Chat History Utilities
+
+The package exports utility functions for chat history management:
+
+```typescript
+// Create a new chat history record
+function createChatHistory(params: {
+  tcbClient: tcb.CloudBase;
+  chatHistoryEntity: ChatHistoryEntity;
+}): Promise<string | undefined>
+
+// Update chat history by record ID
+function updateChatHistoryByRecordId(params: {
+  tcbClient: tcb.CloudBase;
+  recordId: string;
+  chatHistoryEntity: ChatHistoryEntity;
+}): Promise<string | undefined>
+
+// Query chat history from database (paginated)
+function describeChatHistory(params: {
+  tcbClient: tcb.CloudBase;
+  botId: string;
+  sort: "asc" | "desc";
+  pageSize?: number;
+  pageNumber?: number;
+  conversation?: string;
+  startCreatedAt?: number;
+  triggerSrc?: string;
+}): Promise<[ChatHistoryEntity[], number]>
+
+// Transform raw database data to ChatHistoryEntity
+function transDataToChatEntity(item: ChatHistoryData): ChatHistoryEntity
+
+// Query chat history for LLM context
+function queryForLLM(params: {
+  tcbClient: tcb.CloudBase;
+  botId: string;
+  pageSize?: number;
+  startCreatedAt?: number;
+  triggerSrc?: string;
+}): Promise<{ role: string; content: string }[]>
+```
+
+### Message Conversion Utility
+
+```typescript
+// Convert AG-UI messages to OpenAI chat completion format
+function convertMessagesToOpenAI(
+  messages: Message[],
+  systemPrompt?: string
+): ChatMessage[]
+```
+
 ### Supported Events
 
 The adapter emits the following AG-UI events:
@@ -155,9 +358,39 @@ The adapter emits the following AG-UI events:
 **Tool Calls:**
 - `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END` - Tool call events
 
+**Raw Events:**
+- `RAW` - Custom raw events (e.g., message trimming warnings, database error notifications)
+
+## Message History Handling
+
+The adapter manages message history through CloudBase database. When you pass multiple messages to the agent:
+
+- **Only the latest user message** is used for the current request
+- Previous messages are trimmed and a `RAW` event with `type: "warn"` is emitted to notify you
+- Historical context is automatically loaded from the database (up to `historyCount` messages, default: 10)
+- History messages are fetched as complete user-assistant pairs to ensure valid conversation context
+
+This design ensures consistent conversation context management through the database rather than relying on client-side message arrays.
+
+## Chat History Persistence
+
+### Requirements
+
+The adapter uses a collection named `ai_bot_chat_history_5hobd2b` to store chat history. The collection will be automatically created if it doesn't exist. To enable chat history persistence, ensure:
+
+1. `CLOUDBASE_ENV_ID` (or `CBR_ENV_ID`/`SCF_NAMESPACE`) environment variable is set
+2. Valid Tencent Cloud credentials are configured via:
+   - `TENCENTCLOUD_SECRETID` + `TENCENTCLOUD_SECRETKEY`, or
+   - `TENCENTCLOUD_SESSIONTOKEN` (for temporary credentials in cloud functions)
+3. The CloudBase environment has database access enabled
+
+**Important**: If chat history behavior is not overridden, chat history will be stored in Tencent CloudBase as default. Please ensure that the necessary environment variables are set for CloudBase authentication.
+
 ## Dependencies
 
 - `@ag-ui/client`: AG-UI client protocol (provides `AbstractAgent` base class)
+- `@cloudbase/node-sdk`: Tencent CloudBase Node.js SDK for database operations
+- `@cloudbase/manager-node`: Tencent CloudBase Manager for collection management
 - `openai`: OpenAI SDK for API compatibility
 - `rxjs`: Reactive extensions for JavaScript
 
@@ -165,3 +398,4 @@ The adapter emits the following AG-UI events:
 
 - [Tencent Yuanqi](https://yuanqi.tencent.com/)
 - [Yuanqi API Documentation](https://yuanqi.tencent.com/guide/publish-agent-api-documentation)
+- [Tencent CloudBase Documentation](https://docs.cloudbase.net/)

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { AbstractAgent, AgentConfig, RunAgentInput, BaseEvent, Message } from '@ag-ui/client';
+import { AbstractAgent, AgentConfig, RunAgentInput, BaseEvent, Message, EventType } from '@ag-ui/client';
 import OpenAI from 'openai';
-import { Observable } from 'rxjs';
+import { Observable, Subscriber } from 'rxjs';
+import tcb from '@cloudbase/node-sdk';
 
 interface YuanqiConfig {
     request?: {
@@ -10,6 +11,13 @@ interface YuanqiConfig {
     };
     appId?: string;
     appKey?: string;
+    envId?: string;
+    credential?: {
+        secretId?: string;
+        secretKey?: string;
+        token?: string;
+    };
+    historyCount?: number;
 }
 type ChatMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
 interface YuanqiChatRequest {
@@ -22,9 +30,15 @@ interface YuanqiChatRequest {
     chatType?: "published" | "preview";
     [key: string]: any;
 }
+
+declare class YuanqiAgentError extends Error {
+    code?: string;
+    constructor(message: string, code?: string);
+}
 declare class YuanqiAgent extends AbstractAgent {
     protected yuanqiConfig: YuanqiConfig;
     private finalAppId;
+    private finalCloudCredential;
     private model;
     constructor(config: AgentConfig & {
         yuanqiConfig: YuanqiConfig;
@@ -35,15 +49,180 @@ declare class YuanqiAgent extends AbstractAgent {
     }): YuanqiChatRequest;
     run(input: RunAgentInput): Observable<BaseEvent>;
     private _run;
+    protected getChatHistory(subscriber: Subscriber<BaseEvent>, latestUserMessage: Message): Promise<OpenAI.Chat.Completions.ChatCompletionMessageParam[]>;
+    protected saveChatHistory(subscriber: Subscriber<BaseEvent>, input: RunAgentInput, userRecordId: string, assistantRecordId: string, userContent: string, assistantContent: string): Promise<void>;
+    private getTcbClient;
+    private checkIsDatabaseReady;
 }
 /**
  * Convert AGUI messages to OpenAI chat completion format
  */
-declare function convertMessagesToOpenAI(messages: Message[], systemPrompt?: string): OpenAI.Chat.ChatCompletionMessageParam[];
+declare function convertMessagesToOpenAI(messages: Message[], systemPrompt?: string): ChatMessage[];
 
-/**
- * 递归地将对象的所有小驼峰属性名转换为下划线格式
- */
-declare function camelToSnakeKeys<T>(obj: T): T;
+interface StreamContext {
+    threadId: string;
+    runId: string;
+    messageId: string;
+}
+interface StreamState {
+    hasStarted: boolean;
+    fullContent: string;
+    toolCallsMap: Map<string, {
+        name: string;
+        args: string;
+    }>;
+}
+type Delta = OpenAI.Chat.Completions.ChatCompletionChunk["choices"][number]["delta"] & {
+    reasoning_content?: string;
+};
+declare function processYuanqiStream(stream: AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>, context: StreamContext): AsyncGenerator<{
+    type: EventType;
+    threadId: string;
+    runId: string;
+    toolCallId: any;
+    content?: undefined;
+    messageId?: undefined;
+    role?: undefined;
+    delta?: undefined;
+    toolCallName?: undefined;
+} | {
+    type: EventType;
+    threadId: string;
+    runId: string;
+    toolCallId: any;
+    content: string;
+    messageId?: undefined;
+    role?: undefined;
+    delta?: undefined;
+    toolCallName?: undefined;
+} | {
+    type: EventType;
+    threadId: string;
+    runId: string;
+    messageId: string;
+    toolCallId?: undefined;
+    content?: undefined;
+    role?: undefined;
+    delta?: undefined;
+    toolCallName?: undefined;
+} | {
+    type: EventType;
+    threadId: string;
+    runId: string;
+    messageId: string;
+    role: string;
+    toolCallId?: undefined;
+    content?: undefined;
+    delta?: undefined;
+    toolCallName?: undefined;
+} | {
+    type: EventType;
+    threadId: string;
+    runId: string;
+    messageId: string;
+    delta: string;
+    toolCallId?: undefined;
+    content?: undefined;
+    role?: undefined;
+    toolCallName?: undefined;
+} | {
+    type: EventType;
+    threadId: string;
+    runId: string;
+    toolCallId: string;
+    toolCallName: string;
+    content?: undefined;
+    messageId?: undefined;
+    role?: undefined;
+    delta?: undefined;
+} | {
+    type: EventType;
+    threadId: string;
+    runId: string;
+    toolCallId: string;
+    delta: string;
+    content?: undefined;
+    messageId?: undefined;
+    role?: undefined;
+    toolCallName?: undefined;
+}, void, unknown>;
+
+declare function createChatHistory({ tcbClient, chatHistoryEntity, }: {
+    tcbClient: tcb.CloudBase;
+    chatHistoryEntity: ChatHistoryEntity;
+}): Promise<string | undefined>;
+declare function updateChatHistoryByRecordId({ tcbClient, recordId, chatHistoryEntity, }: {
+    tcbClient: tcb.CloudBase;
+    recordId: string;
+    chatHistoryEntity: ChatHistoryEntity;
+}): Promise<string | undefined>;
+declare function describeChatHistory({ tcbClient, botId, sort, pageSize, pageNumber, conversation, startCreatedAt, triggerSrc, }: {
+    tcbClient: tcb.CloudBase;
+    botId: string;
+    sort: "asc" | "desc";
+    pageSize?: number;
+    pageNumber?: number;
+    conversation?: string;
+    startCreatedAt?: number;
+    triggerSrc?: string;
+}): Promise<[ChatHistoryEntity[], number]>;
+declare function transDataToChatEntity(item: ChatHistoryData): ChatHistoryEntity;
+declare function queryForLLM({ tcbClient, botId, pageSize, startCreatedAt, triggerSrc, }: {
+    tcbClient: tcb.CloudBase;
+    botId: string;
+    pageSize?: number;
+    startCreatedAt?: number;
+    triggerSrc?: string;
+}): Promise<{
+    role: string;
+    content: string;
+}[]>;
+interface ChatHistoryData {
+    bot_id: string;
+    record_id: string;
+    role: string;
+    status: string;
+    content: string;
+    sender: string;
+    conversation: string;
+    type: string;
+    trigger_src: string;
+    origin_msg: string;
+    reply_to: string;
+    reply: string;
+    trace_id: string;
+    need_async_reply: boolean;
+    async_reply: string;
+    createdAt: number;
+    updatedAt: number;
+}
+declare class ChatHistoryEntity {
+    id: number;
+    botId: string;
+    recordId: string;
+    role: string;
+    content: string;
+    recommendQuestions: string[];
+    sender: string;
+    conversation: string;
+    type: string;
+    /**
+     * 消息状态，pending done error cancel
+     */
+    status: string;
+    image: string;
+    triggerSrc: string;
+    originMsg: string;
+    replyTo: string;
+    reply: string;
+    traceId: string;
+    needAsyncReply: boolean;
+    asyncReply: string;
+    createTime: string;
+    updateTime: string;
+    createdAt: number;
+    updatedAt: number;
+    event: string;
+}
 
-export { type ChatMessage, YuanqiAgent, type YuanqiChatRequest, type YuanqiConfig, camelToSnakeKeys, convertMessagesToOpenAI };
+export { type ChatHistoryData, ChatHistoryEntity, type ChatMessage, type Delta, type StreamContext, type StreamState, YuanqiAgent, YuanqiAgentError, type YuanqiChatRequest, type YuanqiConfig, convertMessagesToOpenAI, createChatHistory, describeChatHistory, processYuanqiStream, queryForLLM, transDataToChatEntity, updateChatHistoryByRecordId };