BotCore

A base class that provides the basic functionality for functional agents. Inherit from this class to quickly implement functional agents.

context

Cloud function context. For details, see Function-based Cloud Hosting | Input parameters event and context for functions.

botId

string

botId, that is, the id of the functional agent.

botTag

string

The format of the functional agent's botId is ibot-xxx-botTag, separated by - into three segments. We call the third segment botTag.

sseSender

interface SSESender {
  send(prop: {data: {content: string}}): void;
  end(): void;
}

An object that streams SSE messages. It provides two methods:

• send() sends SSE messages, where the prop.data.content field is the agent's text output.
• end() ends SSE and sends a closing message. Once all content has been sent, this method can be called to terminate the SSE connection.

Usage Example

Below is an example of streaming a string character by character to the client:

class MyBot extends BotCore {
  async sendMessage() {
    const ANSWER = "This is a piece of streaming content."

    for (let i = 0; i < ANSWER.length; i++) { 
      // Send a message to the client
      this.sseSender.send({ data: { content: ANSWER[i] } });
    }
    // Send complete
    this.sseSender.end();
  }
} 

chatRecord

type ChatRecordDataModel = DataModelMethods<{
  /** Asynchronous reply content */
  async_reply?: string
  /** Whether to reply asynchronously */
  need_async_reply?: boolean
  /** Request id */
  trace_id?: string
  /** Reply message id */
  reply?: string
  /** Replied message id */
  reply_to?: string
  /** Raw message content */
  origin_msg?: string
  /** Source */
  trigger_src?: string
  /** Session */
  conversation?: string
  /** Sender */
  sender?: string
  /** Recommended questions */
  recommend_questions?: string[]
  /** Event type */
  event?: string
  /** Image URL */
  image?: string
  /** Content */
  content?: string
  /** Message type */
  type?: string
  /** Role */
  role?: string
  /** conversation record ID */
  record_id?: string
  /** Agent ID */
  bot_id?: string
}>

Chat records data model provides CRUD methods. For details, refer to Data Model | SDK Type Declarations | DataModelMethods.

tip

BotCore wraps methods such as createRecordPair, getChatRecords, and getHistoryMessages on top of this data model, which can meet the requirements of most scenarios. For more granular needs, you can directly manipulate the chat records data model through this property.

Usage Example

Below is an example of retrieving a chat records list:

class MyBot extends BotCore {
  getRecordList() {
    return this.chatRecord.list({
      pageSize: 10
    })
  }
}

More data model usage examples can be found at Data Model | SDK Type Declarations | DataModelMethods.

createRecordPair()

interface CreateRecordPair {
  ({userContent: string}): Promise<{
    updateBotRecord: ({content: string}) => Promise<void>
  }>
}

Creates a pair of 'user - agent' chat records and stores them in the data model. The return value provides a method to update the agent's chat records.

In agent conversation scenarios, chat records appear in pairs. After the user sends a message, the agent should reply to that message.

This method requires the input of the user's chat content and will create the following in the data model:

• User's chat record, with the content being the passed-in chat message
• Agent's chat record with empty content

Developers can obtain the updateBotRecord function from the return value. After collecting the complete agent chat content, this function can be called to update the agent's chat record.

Usage Example

The following example implements an agent by conversing with a large model and stores both the user's message records and the large model's responses in the data model.

import OpenAI from 'openai';

const client = new OpenAI();

class MyBot extends BotCore {
  sendMessage({ msg }) {
    // Create a pair of 'user - agent' chat records
    const { updateBotRecord } = await this.createRecordPair({ userContent: msg })
    
    const chatCompletion = await client.chat.completions.create({
      messages: [{ role: 'user', content: 'Say this is a test' }],
      model: 'gpt-4o',
      stream: true,
    });

    // Create a variable to store the agent's messages
    let content = '';
    for await (const chunk of stream) {
      const chunkContent = chunk.choices[0]?.delta?.content || '';
      // Send an SSE message to the client
      this.sseSender.send({ data: { content: chunkContent }});
      // Accumulate message fragments into the content variable
      content += chunkContent;
    }

    // Terminate SSE transmission  
    this.sseSender.end()
    // Update the agent's chat record
    await updateBotRecord({content})
  }
}

getHistoryMessages()

interface GetHistoryMessages {
  (option?: {
    size?: number;
    removeLastUser?: boolean
  }): Promise<Array<{ 
      role: "user" | "assistant", 
      content: string 
    }>>
}

Retrieve historical messages from the chat record data model. The return value is an array of chat records, but this array is specially processed to ensure:

1. The array starts with the user's chat records.
2. In the array, the user's and agent's chat records alternate, presenting a question-and-answer pattern.
3. (Default) The array ends with the agent's chat record.
4. The content field of each chat record is not empty.

Parameters

Input Parameters

Parameter	Type	Description
option.size	number	The number of chat records to retrieve. This value determines how many records are fetched from the chat record data model. Since records are filtered in this method, the actual number returned may be less than the specified value.
option.removeLastUser	boolean	Whether to ensure the array ends with the agent's chat record.

Usage Example

The following example implements an agent by conversing with a large model. When initiating a call, it reads the historical messages between the user and the agent from the data model and passes them to the large model.

import OpenAI from 'openai';

const client = new OpenAI();

class MyBot extends BotCore {
  sendMessage({ msg }) {
    // Retrieve chat history
    const history = await this.getHistoryMessage()
    
    const chatCompletion = await client.chat.completions.create({
      messages: [
        ...history, // Add chat history to the request parameters
        { role: 'user', content: 'Say this is a test' }
      ],
      model: 'gpt-4o',
      stream: true,
    });

    for await (const chunk of stream) {
      const chunkContent = chunk.choices[0]?.delta?.content || '';
      // Send an SSE message to the client
      this.sseSender.send({ data: { content: chunkContent }}); 
    }

    // Terminate SSE transmission  
    this.sseSender.end() 
  }
}

getChatRecords()

Retrieves chat records from the data model. This is the default implementation of getChatRecords defined in the IBot interface provided by BotCore.