Skip to main content

Overview

Provides Cloud Development AI integration capabilities, enabling rapid access to large language models and AI agents.

Basic Usage Examples​

Publishable Key can be generated in Cloud Development Platform/API Key Configuration

Type Declaration​

function ai(): AI;

Return Value​

Returns the newly created AI instance.

import cloudbase from "@cloudbase/js-sdk";

// Initialization
const app = cloudbase.init({
  env: "your-env-id", // Replace with your environment ID
  region: "ap-shanghai", // region, defaults to Shanghai
  accessKey: "", // Enter the generated Publishable Key
});

// If the accessKey is filled in, this step is not required
await app.auth.signInAnonymously();

const ai = app.ai();

AI​

Class used to create AI models.

createModel​

function createModel(model: string): ChatModel;

Create the specified AI model.

  • Create a new AI model instance
  • Return a model instance that implements the ChatModel abstract class
  • This instance provides capabilities related to AI-generated text.

参数

model
string

Model identifier, such as 'hunyuan-exp', 'hunyuan-lite', etc.

返回

ChatModel
ChatModel

A model instance that implements the ChatModel abstract class, providing capabilities related to AI-generated text

示例

bot​

An instance of the Bot class is mounted, which aggregates a series of methods for interacting with the Agent. For details, refer to the Bot class documentation.

Usage Examples​

const agentList = await ai.bot.list({ pageNumber: 1, pageSize: 10 });

registerFunctionTool​

function registerFunctionTool(functionTool: FunctionTool): void;

Register function tools. When making large model calls, you can inform the large model of the available function tools. If the large model's response is parsed as a tool call, the corresponding function tool will be automatically invoked.

参数

functionTool
FunctionTool

Definition of the function tool to be registered

返回

void
undefined

No return value

示例

ChatModel​

This abstract class describes the interface provided by the AI text generation model class.

generateText​

function generateText(data: BaseChatModelInput): Promise<{
  rawResponses: Array<unknown>;
  text: string;
  messages: Array<ChatModelMessage>;
  usage: Usage;
  error?: unknown;
}>;

Invoking large models to generate text.

  • Send a message to the large model and retrieve the generated text response
  • Supports complete dialogue context management
  • Return detailed invocation information and token consumption statistics

参数

data
BaseChatModelInput

Large model input parameters, including model configuration and message content

返回

Promise
object

Generated text response from the large model

示例

streamText​

function streamText(data: BaseChatModelInput): Promise<StreamTextResult>;

Streaming invocation of large models to generate text.

  • During streaming invocation, the generated text and other response data will be returned via SSE. The return value of this interface encapsulates SSE to varying degrees, allowing developers to retrieve both the text stream and the complete data stream according to their actual needs.
  • Streaming invocation of large models to generate text, supporting real-time retrieval of incremental content

参数

data
BaseChatModelInput

Large model input parameters, including model configuration and message content

返回

Promise
StreamTextResult

Results of streaming text generation, including text streams and data streams

示例

Bot​

A class for interacting with the Agent.

get​

function get(props: { botId: string }): Promise<BotInfo>;

Retrieve information about an Agent.

  • Retrieve detailed Agent information based on Agent ID.
  • Return complete Agent information including basic configuration, welcome message, avatar, etc.

参数

props
object

Parameters for retrieving Agent information

返回

Promise
BotInfo

Detailed information of the Agent

示例

list​

function list(props: {
  name: string;
  introduction: string;
  information: string;
  enable: boolean;
  pageSize: number;
  pageNumber: number;
}): Promise<AgentListResult>;

Batch retrieval of information for multiple Agents.

  • Query and filter the available Agent list.
  • Support paginated queries and conditional filtering
  • Return Agent's basic information and configuration details
  • Applicable for building applications such as Agent selectors and Agent management interfaces.

参数

props
object

Parameters for querying the Agent list

返回

Promise
AgentListResult

Agent list query result

示例

sendMessage​

function sendMessage(props: {
  botId: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
}): Promise<StreamResult>;

Converse with the Agent.

  • Response will be returned via SSE. The return value of this interface encapsulates SSE to varying degrees, allowing developers to retrieve both the text stream and the complete data stream according to their actual needs.
  • Supports multi-turn conversation context management
  • Returns streaming responses, supporting real-time retrieval of Agent replies
  • Applicable for building applications such as chatbots and intelligent assistants.

参数

props
object

Parameters for sending messages

返回

Promise
StreamResult

Results of streaming conversation, including text streams and data streams

示例

getChatRecords​

function getChatRecords(props: {
  botId: string;
  sort: string;
  pageSize: number;
  pageNumber: number;
}): Promise<ChatRecordsResult>;

Retrieve chat history.

  • Retrieve the chat history of the specified Agent.
  • Support paginated queries and sorting
  • Return complete conversation history information
  • Suitable for building chat history viewing features

参数

props
object

parameters for retrieving chat history

返回

Promise
ChatRecordsResult

Chat history query result

示例

sendFeedback​

function sendFeedback(props: {
  userFeedback: IUserFeedback;
  botId: string;
}): Promise<void>;

Send feedback for a specific chat message.

  • Evaluate and provide feedback for specified chat messages.
  • Supports various feedback methods such as rating, commenting, and tagging.
  • Help improve the quality of Agent responses
  • Suitable for building user feedback systems

参数

props
object

Parameters for sending feedback

返回

Promise
void

No return value

示例

getFeedback​

function getFeedback(props: {
  botId: string;
  type: string;
  sender: string;
  senderFilter: string;
  minRating: number;
  maxRating: number;
  from: number;
  to: number;
  pageSize: number;
  pageNumber: number;
}): Promise<FeedbackResult>;

Retrieve existing feedback.

  • Query the user feedback records of the specified Agent.
  • Support multiple filter conditions: time range, score range, user filtering, etc.
  • Return paginated feedback results and statistics
  • Suitable for building feedback analysis and management systems

参数

props
object

Parameters for querying feedback information

返回

Promise
FeedbackResult

Feedback query results

示例

uploadFiles​

function uploadFiles(props: {
  botId: string;
  fileList: Array<{
    fileId: string;
    fileName: string;
    type: "file";
  }>;
}): Promise<void>;

Upload files from cloud storage to the Agent for document-based chatting.

  • Supports uploading files from cloud storage to the specified Agent
  • Uploaded files can be used for document chat functionality.
  • Supports batch uploading of multiple files.
  • Applicable for building application scenarios such as document Q&A and file analysis.

参数

props
object

File upload parameters

返回

Promise
void

No return value

示例

getRecommendQuestions​

function getRecommendQuestions(props: {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
}): Promise<StreamResult>;

Generating recommended questions based on conversation context to intelligently generate relevant question suggestions.

  • Intelligently recommend relevant questions based on current conversation content and historical records
  • Supports streaming responses for real-time retrieval of recommended questions
  • Applicable for building applications such as intelligent conversational assistants and chatbots.
  • Help users discover more related topics to enhance the conversation experience

参数

props
object

Parameters for retrieving recommended questions

返回

Promise
StreamResult

streaming recommended questions

示例

createConversation​

function createConversation(props: {
  botId: string;
  title?: string;
}): Promise<IConversation>;

Create a new conversation with the Agent to establish an independent conversation session.

  • Create a new conversation session for the specified Agent
  • Supports custom conversation titles for easy management and identification
  • Each conversation session independently stores conversation history
  • Suitable for multi-user, multi-scenario conversation management requirements

参数

props
object

Parameters for creating a conversation

返回

Promise
IConversation

Created conversation information

示例

getConversation​

function getConversation(props: {
  botId: string;
  pageSize?: number;
  pageNumber?: number;
  isDefault?: boolean;
}): Promise<ConversationListResult>;

Retrieve the Agent's conversation list, supporting pagination and conditional filtering.

  • Query all conversation records of the specified Agent.
  • Support pagination to facilitate the management of large volumes of conversations.
  • Filter default or all conversations.
  • Suitable for scenarios such as conversation management and historical record viewing

参数

props
object

Parameters for retrieving the conversation list

返回

Promise
ConversationListResult

Conversation list query result

示例

deleteConversation​

function deleteConversation(props: {
  botId: string;
  conversationId: string;
}): Promise<void>;

Delete the specified conversation session and clear the conversation history.

  • Permanently delete the specified conversation session.
  • Clear all message records in the conversation
  • Free up storage space and optimize system performance
  • Suitable for scenarios such as conversation management and data cleanup

参数

props
object

Parameters for deleting a conversation

返回

Promise
void

Deletion operation completed, no return value

示例

speechToText​

function speechToText(props: {
  botId: string;
  engSerViceType: string;
  voiceFormat: string;
  url: string;
  isPreview?: boolean;
}): Promise<SpeechToTextResult>;

Convert speech files to text, supporting multiple audio formats and language recognition.

  • Supports multiple audio formats: MP3, WAV, AAC, etc.
  • Supports multiple language recognition engines
  • Can process local or remote audio files
  • Suitable for scenarios such as voice assistants, meeting minutes, voice notes, etc.

参数

props
object

Speech-to-text parameters

返回

Promise
SpeechToTextResult

ASR result

示例

textToSpeech​

function textToSpeech(props: {
  botId: string;
  voiceType: number;
  text: string;
  isPreview?: boolean;
}): Promise<TextToSpeechResult>;

Convert text to speech, supporting multiple voice types and timbre options.

  • Supports multiple voice types and timbre options
  • Adjustable parameters such as speech rate and pitch
  • Support segmented conversion of long texts
  • Suitable for scenarios such as voice broadcasting, audiobooks, voice assistants, etc.

参数

props
object

Text-to-speech parameters

返回

Promise
TextToSpeechResult

Text-to-speech result

示例

getTextToSpeechResult​

function getTextToSpeechResult(props: {
  botId: string;
  taskId: string;
  isPreview?: boolean;
}): Promise<TextToSpeechResult>;

Get the result of a text-to-speech task, query the completion status of the TTS task and the generated audio file.

  • Query the status and result of asynchronous TTS tasks
  • Retrieve generated audio file information
  • Supports preview mode and production mode
  • Suitable for asynchronous scenarios such as batch TTS and long-text processing

参数

props
object

Parameters for retrieving TTS results

返回

Promise
TextToSpeechResult

TTS task result

示例

Complete Type Definitions​

IBotCreateConversation​

interface IBotCreateConversation {
  botId: string;
  title?: string;
}

IBotGetConversation​

interface IBotGetConversation {
  botId: string;
  pageSize?: number;
  pageNumber?: number;
  isDefault?: boolean;
}

IBotDeleteConversation​

interface IBotDeleteConversation {
  botId: string;
  conversationId: string;
}

IBotSpeechToText​

interface IBotSpeechToText {
  botId: string;
  engSerViceType: string;
  voiceFormat: string;
  url: string;
  isPreview?: boolean;
}

IBotTextToSpeech​

interface IBotTextToSpeech {
  botId: string;
  voiceType: number;
  text: string;
  isPreview?: boolean;
}

IBotGetTextToSpeechResult​

interface IBotGetTextToSpeechResult {
  botId: string;
  taskId: string;
  isPreview?: boolean;
}

BaseChatModelInput​

interface BaseChatModelInput {
  model: string;
  messages: Array<ChatModelMessage>;
  temperature?: number;
  topP?: number;
  tools?: Array<FunctionTool>;
  toolChoice?: "none" | "auto" | "custom";
  maxSteps?: number;
  onStepFinish?: (prop: IOnStepFinish) => unknown;
}
BaseChatModelInput Property NameTypeDescription
modelstringModel name.
messagesArray<ChatModelMessage>Message list.
temperaturenumberSampling temperature, which controls the randomness of the output.
topPnumberTemperature sampling, where the model considers tokens within the top_p probability mass.
toolsArray<FunctionTool>List of tools available for large models.
toolChoicestringSpecifies the method for large models to select tools.
maxStepsnumberMaximum number of requests to the large model.
onStepFinish(prop: IOnStepFinish) => unknownThe callback function triggered when a request to the large model is completed.

BotInfo​

interface BotInfo {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  welcomeMessage: string;
  avatar: string;
  background: string;
  tags: Array<string>;
  isNeedRecommend: boolean;
  knowledgeBase: Array<string>;
  type: string;
  initQuestions: Array<string>;
  enable: true;
}

IUserFeedback​

interface IUserFeedback {
  recordId: string;
  type: string;
  botId: string;
  comment: string;
  rating: number;
  tags: Array<string>;
  input: string;
  aiAnswer: string;
}

ChatModelMessage​

type ChatModelMessage =
  | UserMessage
  | SystemMessage
  | AssistantMessage
  | ToolMessage;

UserMessage​

type UserMessage = {
  role: "user";
  content: string;
};

SystemMessage​

type SystemMessage = {
  role: "system";
  content: string;
};

AssistantMessage​

type AssistantMessage = {
  role: "assistant";
  content?: string;
  tool_calls?: Array<ToolCall>;
};

ToolMessage​

type ToolMessage = {
  role: "tool";
  tool_call_id: string;
  content: string;
};

ToolCall​

export type ToolCall = {
  id: string;
  type: string;
  function: { name: string; arguments: string };
};

FunctionTool​

Tool definition type.

type FunctionTool = {
  name: string;
  description: string;
  fn: CallableFunction;
  parameters: object;
};
FunctionTool Property NameTypeDescription
namestringTool name.
descriptionstringDescription of the tool. A clear tool description helps the large model understand the tool's purpose.
fnCallableFunctionThe tool's execution function. When the AI SDK parses that the large model's response requires calling this tool, it invokes this function and returns the result to the large model.
parametersobjectThe input parameters for the tool's execution function, which must be defined using JSON Schema format.

IOnStepFinish​

The type of input parameters for the callback function triggered after the large model responds.

interface IOnStepFinish {
  messages: Array<ChatModelMessage>;
  text?: string;
  toolCall?: ToolCall;
  toolResult?: unknown;
  finishReason?: string;
  stepUsage?: Usage;
  totalUsage?: Usage;
}
IOnStepFinish Property NameTypeDescription
messagesArray<ChatModelMessage>List of all messages up to the current step.
textstringThe text of the current response.
toolCallToolCallThe tool called by the current response.
toolResultunknownThe corresponding tool call result.
finishReasonstringReason for termination of large model inference.
stepUsageUsageThe tokens consumed by the current step.
totalUsageUsageThe total tokens consumed up to the current step.

Usage​

type Usage = {
  completion_tokens: number;
  prompt_tokens: number;
  total_tokens: number;
};

IConversation​

Agent session.

interface IConversation {
  id: string;
  envId: string;
  ownerUin: string;
  userId: string;
  conversationId: string;
  title: string;
  startTime: string; // date-time format
  createTime: string;
  updateTime: string;
}