@base44/sdk
Version:
JavaScript SDK for Base44 API
398 lines (397 loc) • 16.8 kB
TypeScript
import { AxiosInstance } from "axios";
import { RoomsSocket } from "../utils/socket-utils.js";
import { ModelFilterParams } from "../types.js";
/**
* Registry of agent names. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`AgentName`](#agentname) resolves to a union of the keys.
*/
export interface AgentNameRegistry {
}
/**
* Union of all agent names from the [`AgentNameRegistry`](#agentnameregistry). Defaults to `string` when no types have been generated.
*
* @example
* ```typescript
* // Using generated agent name types
* // With generated types, you get autocomplete on agent names
* const conversation = await base44.agents.createConversation({ agent_name: 'SupportBot' });
* ```
*/
export type AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry;
/**
* Reasoning information for an agent message.
*
* Contains details about the agent's reasoning process when generating a response.
*/
export interface AgentMessageReasoning {
/** When reasoning started. */
start_date: string;
/** When reasoning ended. */
end_date?: string;
/** Reasoning content. */
content: string;
}
/**
* A tool call made by the agent.
*
* Represents a function or tool that the agent invoked during message generation.
*/
export interface AgentMessageToolCall {
/** Tool call ID. */
id: string;
/** Name of the tool called. */
name: string;
/** Arguments passed to the tool as JSON string. */
arguments_string: string;
/** Status of the tool call. */
status: "running" | "success" | "error" | "stopped" | "waiting_for_user_input";
/** Results from the tool call. */
results?: string;
}
/**
* Token usage statistics for an agent message.
*
* Tracks the number of tokens consumed when generating the message.
*/
export interface AgentMessageUsage {
/** Number of tokens in the prompt. */
prompt_tokens?: number;
/** Number of tokens in the completion. */
completion_tokens?: number;
}
/**
* Custom context provided with an agent message.
*
* Additional contextual information that can be passed to the agent.
*/
export interface AgentMessageCustomContext {
/** Context message. */
message: string;
/** Associated data for the context. */
data: Record<string, any>;
/** Type of context. */
type: string;
}
/**
* Metadata about when and by whom a message was created.
*/
export interface AgentMessageMetadata {
/** When the message was created. */
created_date: string;
/** Email of the user who created the message. */
created_by_email: string;
/** Full name of the user who created the message. */
created_by_full_name: string;
}
/**
* An agent conversation containing messages exchanged with an AI agent.
*/
export interface AgentConversation {
/** Unique identifier for the conversation. */
id: string;
/** App ID. */
app_id: string;
/** Name of the agent in this conversation. */
agent_name: string;
/** ID of the user who created the conversation. */
created_by_id: string;
/** When the conversation was created. */
created_date: string;
/** When the conversation was last updated. */
updated_date: string;
/** Array of messages in the conversation. */
messages: AgentMessage[];
/** Optional metadata associated with the conversation. */
metadata?: Record<string, any>;
}
/**
* A message in an agent conversation.
*/
export interface AgentMessage {
/** Unique identifier for the message. */
id: string;
/** Role of the message sender. */
role: "user" | "assistant" | "system";
/** When the message was created. */
created_date: string;
/** When the message was last updated. */
updated_date: string;
/** Optional reasoning information for the message. */
reasoning?: AgentMessageReasoning | null;
/** Message content. */
content?: string | Record<string, any>;
/** URLs to files attached to the message. */
file_urls?: string[];
/** Tool calls made by the agent. */
tool_calls?: AgentMessageToolCall[];
/** Token usage statistics. */
usage?: AgentMessageUsage;
/** Whether the message is hidden from the user. */
hidden?: boolean;
/** Custom context provided with the message. */
custom_context?: AgentMessageCustomContext[];
/** Model used to generate the message. */
model?: string;
/** Checkpoint ID for the message. */
checkpoint_id?: string;
/** Metadata about when and by whom the message was created. */
metadata?: AgentMessageMetadata;
/** Additional custom parameters for the message. */
additional_message_params?: Record<string, any>;
}
/**
* Parameters for creating a new conversation.
*/
export interface CreateConversationParams {
/** The name of the agent to create a conversation with. */
agent_name: AgentName;
/** Optional metadata to attach to the conversation. */
metadata?: Record<string, any>;
}
/**
* Configuration for creating the agents module.
* @internal
*/
export interface AgentsModuleConfig {
/** Axios instance for HTTP requests */
axios: AxiosInstance;
/** Function to get WebSocket instance for realtime updates (lazy initialization) */
getSocket: () => ReturnType<typeof RoomsSocket>;
/** App ID */
appId: string;
/** Server URL */
serverUrl?: string;
/** Authentication token */
token?: string;
}
/**
* Agents module for managing AI agent conversations.
*
* This module provides methods to create and manage conversations with AI agents,
* send messages, and subscribe to realtime updates. Conversations can be used
* for chat interfaces, support systems, or any interactive AI app.
*
* ## Key Features
*
* The agents module enables you to:
*
* - **Create conversations** with agents defined in the app.
* - **Send messages** from users to agents and receive AI-generated responses.
* - **Retrieve conversations** individually or as filtered lists with sorting and pagination.
* - **Subscribe to realtime updates** using WebSocket connections to receive instant notifications when new messages arrive.
* - **Attach metadata** to conversations for tracking context, categories, priorities, or linking to external systems.
* - **Generate WhatsApp connection URLs** for users to interact with agents through WhatsApp.
*
* ## Conversation Structure
*
* The agents module operates with a two-level hierarchy:
*
* 1. **Conversations**: Top-level containers that represent a dialogue with a specific agent. Each conversation has a unique ID, is associated with an agent by name, and belongs to the user who created it. Conversations can include optional metadata for tracking app-specific context like ticket IDs, categories, or custom fields.
*
* 2. **Messages**: Individual exchanges within a conversation. Each message has a role, content, and optional metadata like token usage, tool calls, file attachments, and reasoning information. Messages are stored as an array within their parent conversation.
*
* ## Authentication Modes
*
* This module is available to use with a client in all authentication modes:
*
* - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Users must be authenticated to create and access conversations.
* - **Service role authentication** (`base44.asServiceRole.agents`): Operations have elevated admin-level permissions. Can access all conversations that the app's admin role has access to.
*
* ## Generated Types
*
* If you're working in a TypeScript project, you can generate types from your agents to get autocomplete on agent names when creating conversations or subscribing to updates. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
*/
export interface AgentsModule {
/**
* Gets all conversations from all agents in the app.
*
* Retrieves all conversations. Use {@linkcode listConversations | listConversations()} to filter which conversations are returned, apply sorting, or paginate results. Use {@linkcode getConversation | getConversation()} to retrieve a specific conversation by ID.
*
* @returns Promise resolving to an array of conversations.
*
* @example
* ```typescript
* // Get all conversations
* const conversations = await base44.agents.getConversations();
* console.log(`Total conversations: ${conversations.length}`);
* ```
*
* @see {@linkcode listConversations | listConversations()} for filtering, sorting, and pagination
* @see {@linkcode getConversation | getConversation()} for retrieving a specific conversation by ID
*/
getConversations(): Promise<AgentConversation[]>;
/**
* Gets a specific conversation by ID.
*
* Retrieves a single conversation using its unique identifier. To retrieve
* all conversations, use {@linkcode getConversations | getConversations()}. To filter, sort, or paginate conversations, use {@linkcode listConversations | listConversations()}.
*
* This function returns the complete stored conversation including full tool call results, even for large responses.
*
* @param conversationId - The unique identifier of the conversation.
* @returns Promise resolving to the conversation, or undefined if not found.
*
* @example
* ```typescript
* // Get a specific conversation by ID
* const conversation = await base44.agents.getConversation('conv-123');
* if (conversation) {
* console.log(`Conversation has ${conversation.messages.length} messages`);
* }
* ```
*
* @see {@linkcode getConversations | getConversations()} for retrieving all conversations
* @see {@linkcode listConversations | listConversations()} for filtering and sorting conversations
*/
getConversation(conversationId: string): Promise<AgentConversation | undefined>;
/**
* Lists conversations with filtering, sorting, and pagination.
*
* Provides querying capabilities including filtering by fields, sorting, pagination, and field selection. For cases where you need all conversations without filtering, use {@linkcode getConversations | getConversations()}. To retrieve a specific conversation by ID, use {@linkcode getConversation | getConversation()}.
*
* @param filterParams - Filter parameters for querying conversations.
* @returns Promise resolving to an array of filtered conversations.
*
* @example
* ```typescript
* // List recent conversations with pagination
* const recentConversations = await base44.agents.listConversations({
* limit: 10,
* sort: '-created_date'
* });
* ```
*
* @example
* ```typescript
* // Filter by agent and metadata
* const supportConversations = await base44.agents.listConversations({
* q: {
* agent_name: 'support-agent',
* 'metadata.priority': 'high'
* },
* sort: '-created_date',
* limit: 20
* });
* ```
*
* @see {@linkcode getConversations | getConversations()} for retrieving all conversations without filtering
* @see {@linkcode getConversation | getConversation()} for retrieving a specific conversation by ID
*/
listConversations(filterParams: ModelFilterParams): Promise<AgentConversation[]>;
/**
* Creates a new conversation with an agent.
*
* @param conversation - Conversation details including agent name and optional metadata.
* @returns Promise resolving to the created conversation.
*
* @example
* ```typescript
* // Create a new conversation with metadata
* const conversation = await base44.agents.createConversation({
* agent_name: 'support-agent',
* metadata: {
* order_id: 'ORD-789',
* product_id: 'PROD-456',
* category: 'technical-support'
* }
* });
* console.log(`Created conversation: ${conversation.id}`);
* ```
*/
createConversation(conversation: CreateConversationParams): Promise<AgentConversation>;
/**
* Adds a message to a conversation.
*
* Sends a message to the agent and updates the conversation. This method
* also updates the realtime socket to notify any subscribers.
*
* @param conversation - The conversation to add the message to.
* @param message - The message to add.
* @returns Promise resolving to the created message.
*
* @example
* ```typescript
* // Send a message to the agent
* const message = await base44.agents.addMessage(conversation, {
* role: 'user',
* content: 'Hello, I need help with my order #12345'
* });
* console.log(`Message sent with ID: ${message.id}`);
* ```
*/
addMessage(conversation: AgentConversation, message: Partial<AgentMessage>): Promise<AgentMessage>;
/**
* Subscribes to realtime updates for a conversation.
*
* Establishes a WebSocket connection to receive instant updates when new
* messages are added to the conversation. Returns an unsubscribe function
* to clean up the connection.
*
* <Note>
* When receiving messages through this function, tool call data is truncated for efficiency. The `arguments_string` is limited to 500 characters and `results` to 50 characters. The complete tool call data is always saved in storage and can be retrieved by calling {@linkcode getConversation | getConversation()} after the message completes.
* </Note>
*
* @param conversationId - The conversation ID to subscribe to.
* @param onUpdate - Callback function called when the conversation is updated. The callback receives a conversation object with the following properties:
* - `id`: Unique identifier for the conversation.
* - `agent_name`: Name of the agent in this conversation.
* - `created_date`: ISO 8601 timestamp of when the conversation was created.
* - `updated_date`: ISO 8601 timestamp of when the conversation was last updated.
* - `messages`: Array of messages in the conversation. Each message includes `id`, `role` (`'user'`, `'assistant'`, or `'system'`), `content`, `created_date`, and optionally `tool_calls`, `reasoning`, `file_urls`, and `usage`.
* - `metadata`: Optional metadata associated with the conversation.
* @returns Unsubscribe function to stop receiving updates.
*
* @example
* ```typescript
* // Subscribe to realtime updates
* const unsubscribe = base44.agents.subscribeToConversation(
* 'conv-123',
* (updatedConversation) => {
* const latestMessage = updatedConversation.messages[updatedConversation.messages.length - 1];
* console.log('New message:', latestMessage.content);
* }
* );
*
* // Later, clean up the subscription
* unsubscribe();
* ```
*/
subscribeToConversation(conversationId: string, onUpdate?: (conversation: AgentConversation) => void): () => void;
/**
* Gets WhatsApp connection URL for an agent.
*
* Generates a URL that users can use to connect with the agent through WhatsApp.
* The URL includes authentication if a token is available.
*
* @param agentName - The name of the agent.
* @returns WhatsApp connection URL.
*
* @example
* ```typescript
* // Get WhatsApp connection URL
* const whatsappUrl = base44.agents.getWhatsAppConnectURL('support-agent');
* console.log(`Connect through WhatsApp: ${whatsappUrl}`);
* // User can open this URL to start a WhatsApp conversation
* ```
*/
getWhatsAppConnectURL(agentName: AgentName): string;
/**
* Gets Telegram connection URL for an agent.
*
* Generates a URL that users can use to connect with the agent through Telegram.
* The URL includes authentication if a token is available. When the user opens
* this URL, they are redirected to the agent's Telegram bot with an activation
* code that securely links their account.
*
* @param agentName - The name of the agent.
* @returns Telegram connection URL.
*
* @example
* ```typescript
* // Get Telegram connection URL
* const telegramUrl = base44.agents.getTelegramConnectURL('support-agent');
* console.log(`Connect through Telegram: ${telegramUrl}`);
* // User can open this URL to start a Telegram conversation
* ```
*/
getTelegramConnectURL(agentName: AgentName): string;
}