Skip to main content

Overview

Provide cloud development AI access capability for quick integration with large models and Agent.

Basic Usage Example​

Publishable Key can be generated by going to Cloud Development Platform/API Key Configuration

Type Declaration​

function ai(): AI;

Return value​

Return the newly created AI instance.

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

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

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

const ai = app.ai();

AI​

Class for creating AI models.

createModel​

function createModel(model: string): ChatModel;

Create the specified AI model.

-Create a new AI model instance -Return a model instance implemented the ChatModel abstract class -The instance provides AI text generation capabilities.

参数

model
string

Model identifier, for example 'hunyuan-exp', 'hunyuan-lite'

返回

ChatModel
ChatModel

A model instance implemented the ChatModel abstract class, providing AI text generation capabilities

示例

bot​

An instance of the Bot class is mounted, with a collection of methods to interact with the Agent. For details, see the Bot class detailed documentation.

Usage Example​

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

registerFunctionTool​

function registerFunctionTool(functionTool: FunctionTool): void;

Register function tools. When performing large model invocation, you can inform the large model of available function tools. When the large model's response is resolved to a tool call, it will automatically call the corresponding function tool.

参数

functionTool
FunctionTool

Function tool definition to register

返回

void
undefined

no return value

示例

ChatModel​

This abstract class describes the interface provided by the AI Model Class.

generateText​

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

Call the large model to generate text.

-Send message to the large model and obtain the generated text response -Support fully managed dialogue context -Return detailed invocation information and token consumption statistics

参数

data
BaseChatModelInput

Input parameters for the large model, including model configuration and message content

返回

Promise
object

Response result of text generated by the large model

示例

streamText​

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

Call the large model to generate text with streaming.

-When calling with streaming, the generated text and other response data are returned via SSE. This API's returned value encapsulates SSE at different levels, allowing developers to obtain the text stream and complete data stream according to actual needs. -Call the large model in streaming method to generate text, supporting real-time access to incremental content.

参数

data
BaseChatModelInput

Input parameters for the large model, including model configuration and message content

返回

Promise
StreamTextResult

Streaming text generation result, including text stream and data stream

示例

Bot​

Class for interacting with Agent.

get​

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

Get info of a certain Agent.

-Get detailed Agent info based on Agent ID -Return the complete information of Agent, including basic configuration, welcome message and avatar.

参数

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 get info of multiple Agents.

-Query and filter the available Agent list -Support paging query and conditional filtering -Return the basic info and configuration detail of Agent -Suitable for building applications like Agent selector and management interface.

参数

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>;

Start dialogue with the Agent.

-The response will be returned via SSE. This API's returned value encapsulates SSE at different levels, allowing developers to obtain text streams and complete data streams based on actual needs. -Support multi-round dialogue context management

  • Return streaming response and support real-time access to Agent reply -Suitable for building chatbots, smart assistants and other applications.

参数

props
object

Parameters for sending messages

返回

Promise
StreamResult

Streaming dialogue result, including text stream and data stream

示例

getChatRecords​

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

Retrieve chat record.

  • Retrieve historical chat records of the specified Agent
  • Support paging query and sort
  • Return complete chat history
  • Suitable to build chat history view function

参数

props
object

Parameters for chat record retrieval

返回

Promise
ChatRecordsResult

Chat record query result

示例

sendFeedback​

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

Send feedback information for a chat record.

-Evaluate and provide feedback for the specified chat record.

  • Support multiple feedback methods such as score, comment, and tag. -Help improve Agent response quality -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 information.

-Query specified Agent user feedback records -Support various filter conditions: time range, score range, user filtering, etc.

  • Return paginated feedback results and statistical information -Suitable for building feedback analytics and management systems

参数

props
object

Parameters for querying feedback information

返回

Promise
FeedbackResult

Feedback query result

示例

uploadFiles​

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

Upload files in cloud storage to Agent for document chat.

-Support uploading files in cloud storage to the specified Agent -Files after uploading can be used for the chat feature. -Support batch uploading multiple files -Suitable for building document QA, file analysis and other applications.

参数

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>;

Get recommended issues, intelligently generate related issues based on dialogue context.

-Intelligently recommend related issues based on current conversation content and history -Support streaming return and real-time access to recommended issues -Suitable for building intelligent dialogue assistants, chatbots and other applications. -Help users discover more related topics and enhance dialogue experience

参数

props
object

Parameters for obtaining recommended questions

返回

Promise
StreamResult

Streaming results of recommended questions

示例

createConversation​

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

Create a new dialog with the Agent and establish an independent session.

-Create a new session for the specified Agent

  • Support customizable dialogue titles for easy management and identification
  • Each session independently stores dialogue history
  • Suitable for multi-user dialogue management requirements in various scenarios

参数

props
object

Parameters for creating a dialogue

返回

Promise
IConversation

Created dialogue info

示例

getConversation​

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

Retrieve the conversation list of the Agent, support paging query and conditional filtering.

  • Query specified Agent ALL dialogue records -Support paging query, easy to manage large number of dialogues
  • Filter default dialogue or ALL dialogues
  • Suitable for dialogue management, view history record and other scenarios

参数

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 specified dialogue session and clear dialogue history.

-Delete specified dialogue session permanently -Clear all messages in the dialogue -Free up storage space, optimize system performance

  • Suitable for dialogue management, data clearing and other scenarios

参数

props
object

Parameters for deleting a conversation

返回

Promise
void

Delete operation complete, no return value

示例

speechToText​

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

Convert voice files into text, support various audio formats and language recognition.

  • Support various audio formats such as MP3, WAV, and AAC -Support multiple language recognition engines -Process local or remote audio files -Suitable for voice assistant, meeting minutes, voice note and other scenarios

参数

props
object

Parameters for speech to text

返回

Promise
SpeechToTextResult

ASR result

示例

textToSpeech​

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

Convert text to speech, support various speech types and voice types.

-Support various speech types and voice types -Adjustable parameters such as speaking rate and pitch -Support long text segment switch -Suitable for voice broadcast, audiobook, voice assistant and other scenarios

参数

props
object

Parameters for text to speech

返回

Promise
TextToSpeechResult

Result of text to speech

示例

getTextToSpeechResult​

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

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

-Querying the status and result of the async TTS task -Retrieve the generated audio file info -Support preview mode and official mode -Suitable for batch TTS, long text processing and other async scenarios

参数

props
object

Parameters for obtaining TTS results

返回

Promise
TextToSpeechResult

TTS task result

示例

Complete type definition​

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 attribute namedata typedescription
modelstringmodel name
messagesArray<ChatModelMessage>message list
temperaturenumberSampling temperature, controls output randomness.
topPnumberTemperature sampling, consider results with probability mass top_p.
toolsArray<FunctionTool>Available tool list for large model
toolChoicestringSpecify the way for the large model to select tools.
maxStepsnumberMaximum number of times to request the large model.
onStepFinish(prop: IOnStepFinish) => unknownThe callback function that departs upon completion of a single request to the large model.

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 attribute namedata typedescription
namestringtool name
descriptionstringtool description. A clear tool description helps the large model meet the tool purpose.
fnCallableFunctionThe execution function of the tool. When the AI SDK parses out the large model response requires this tool to invoke, it will invoke this function and return the result to the large model.
parametersobjectThe input parameters of the tool execution function. Require the use of JSON Schema format definition.

IOnStepFinish​

Input parameter type of 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 attribute namedata typedescription
messagesArray<ChatModelMessage>List of all messages up to the current step.
textstringCurrent response text.
toolCallToolCallTool called by the current response.
toolResultunknownTool call result.
finishReasonstringThe causes for large model inference ended.
stepUsageUsageTokens spent in the current step.
totalUsageUsageTotal tokens spent 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;
}