agents - Base44 Support Documentation

Overview

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:

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.
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 are invoked with the service role for backend code that needs elevated permissions.

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 guide to get started.

Methods

getConversations()

getConversations(): Promise<AgentConversation[]>

Gets all conversations from all agents in the app. Retrieves all conversations. Use listConversations() to filter which conversations are returned, apply sorting, or paginate results. Use getConversation() to retrieve a specific conversation by ID.

Returns

AgentConversation An agent conversation containing messages exchanged with an AI agent.

Properties

string

required

Unique identifier for the conversation.

string

required

App ID.

string

required

Name of the agent in this conversation.

string

required

ID of the user who created the conversation.

string

required

When the conversation was created.

string

required

When the conversation was last updated.

AgentMessage[]

required

Array of messages in the conversation.

Properties

string

required

Unique identifier for the message.

"user" | "assistant" | "system"

required

Role of the message sender.

string

required

When the message was created.

string

required

When the message was last updated.

AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

string

required

When reasoning started.

string

When reasoning ended.

string

required

Reasoning content.

string | Record<string, any>

Message content.

string[]

URLs to files attached to the message.

AgentMessageToolCall[]

Tool calls made by the agent.

Properties

string

required

Tool call ID.

string

required

Name of the tool called.

string

required

Arguments passed to the tool as JSON string.

"success" | "error" | "running" | "stopped" | "waiting_for_user_input"

required

Status of the tool call.

string

Results from the tool call.

AgentMessageUsage

Token usage statistics.

Properties

number

Number of tokens in the prompt.

number

Number of tokens in the completion.

boolean

Whether the message is hidden from the user.

AgentMessageCustomContext[]

Custom context provided with the message.

Properties

string

required

Context message.

Record<string, any>

required

Associated data for the context.

string

required

Type of context.

string

Model used to generate the message.

string

Checkpoint ID for the message.

AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

string

required

When the message was created.

string

required

Email of the user who created the message.

string

required

Full name of the user who created the message.

Record<string, any>

Additional custom parameters for the message.

Record<string, any>

Optional metadata associated with the conversation.

Example

const conversations = await base44.agents.getConversations();
console.log(`Total conversations: ${conversations.length}`);

See

listConversations() for filtering, sorting, and pagination
getConversation() for retrieving a specific conversation by ID

getConversation()

getConversation(conversationId): Promise<AgentConversation | undefined>

Gets a specific conversation by ID. Retrieves a single conversation using its unique identifier. To retrieve all conversations, use getConversations(). To filter, sort, or paginate conversations, use listConversations(). This function returns the complete stored conversation including full tool call results, even for large responses.

Parameters

string

required

The unique identifier of the conversation.

Returns

AgentConversation An agent conversation containing messages exchanged with an AI agent.

Properties

string

required

Unique identifier for the conversation.

string

required

App ID.

string

required

Name of the agent in this conversation.

string

required

ID of the user who created the conversation.

string

required

When the conversation was created.

string

required

When the conversation was last updated.

AgentMessage[]

required

Array of messages in the conversation.

Properties

string

required

Unique identifier for the message.

"user" | "assistant" | "system"

required

Role of the message sender.

string

required

When the message was created.

string

required

When the message was last updated.

AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

string

required

When reasoning started.

string

When reasoning ended.

string

required

Reasoning content.

string | Record<string, any>

Message content.

string[]

URLs to files attached to the message.

AgentMessageToolCall[]

Tool calls made by the agent.

Properties

string

required

Tool call ID.

string

required

Name of the tool called.

string

required

Arguments passed to the tool as JSON string.

"success" | "error" | "running" | "stopped" | "waiting_for_user_input"

required

Status of the tool call.

string

Results from the tool call.

AgentMessageUsage

Token usage statistics.

Properties

number

Number of tokens in the prompt.

number

Number of tokens in the completion.

boolean

Whether the message is hidden from the user.

AgentMessageCustomContext[]

Custom context provided with the message.

Properties

string

required

Context message.

Record<string, any>

required

Associated data for the context.

string

required

Type of context.

string

Model used to generate the message.

string

Checkpoint ID for the message.

AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

string

required

When the message was created.

string

required

Email of the user who created the message.

string

required

Full name of the user who created the message.

Record<string, any>

Additional custom parameters for the message.

Record<string, any>

Optional metadata associated with the conversation.

Example

const conversation = await base44.agents.getConversation('conv-123');
if (conversation) {
  console.log(`Conversation has ${conversation.messages.length} messages`);
}

See

getConversations() for retrieving all conversations
listConversations() for filtering and sorting conversations

listConversations()

listConversations(filterParams): Promise<AgentConversation[]>

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 getConversations(). To retrieve a specific conversation by ID, use getConversation().

Parameters

ModelFilterParams

required

Filter parameters for querying conversations.

Properties

Record<string, any>

Query object with field-value pairs for filtering.

string | null

Sort parameter. For example, “-created_date” for descending order.

string | null

Alternative sort parameter. Use either sort or sort_by.

number | null

Maximum number of results to return.

number | null

Number of results to skip. Used for pagination.

string[] | null

Array of field names to include in the response.

Returns

AgentConversation An agent conversation containing messages exchanged with an AI agent.

Properties

string

required

Unique identifier for the conversation.

string

required

App ID.

string

required

Name of the agent in this conversation.

string

required

ID of the user who created the conversation.

string

required

When the conversation was created.

string

required

When the conversation was last updated.

AgentMessage[]

required

Array of messages in the conversation.

Properties

string

required

Unique identifier for the message.

"user" | "assistant" | "system"

required

Role of the message sender.

string

required

When the message was created.

string

required

When the message was last updated.

AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

string

required

When reasoning started.

string

When reasoning ended.

string

required

Reasoning content.

string | Record<string, any>

Message content.

string[]

URLs to files attached to the message.

AgentMessageToolCall[]

Tool calls made by the agent.

Properties

string

required

Tool call ID.

string

required

Name of the tool called.

string

required

Arguments passed to the tool as JSON string.

"success" | "error" | "running" | "stopped" | "waiting_for_user_input"

required

Status of the tool call.

string

Results from the tool call.

AgentMessageUsage

Token usage statistics.

Properties

number

Number of tokens in the prompt.

number

Number of tokens in the completion.

boolean

Whether the message is hidden from the user.

AgentMessageCustomContext[]

Custom context provided with the message.

Properties

string

required

Context message.

Record<string, any>

required

Associated data for the context.

string

required

Type of context.

string

Model used to generate the message.

string

Checkpoint ID for the message.

AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

string

required

When the message was created.

string

required

Email of the user who created the message.

string

required

Full name of the user who created the message.

Record<string, any>

Additional custom parameters for the message.

Record<string, any>

Optional metadata associated with the conversation.

Examples

const recentConversations = await base44.agents.listConversations({
  limit: 10,
  sort: '-created_date'
});

const supportConversations = await base44.agents.listConversations({
  q: {
    agent_name: 'support-agent',
    'metadata.priority': 'high'
  },
  sort: '-created_date',
  limit: 20
});

See

getConversations() for retrieving all conversations without filtering
getConversation() for retrieving a specific conversation by ID

createConversation()

createConversation(conversation): Promise<AgentConversation>

Creates a new conversation with an agent.

Parameters

CreateConversationParams

required

Conversation details including agent name and optional metadata.

Properties

string

required

The name of the agent to create a conversation with.

Record<string, any>

Optional metadata to attach to the conversation.

Returns

AgentConversation An agent conversation containing messages exchanged with an AI agent.

Properties

string

required

Unique identifier for the conversation.

string

required

App ID.

string

required

Name of the agent in this conversation.

string

required

ID of the user who created the conversation.

string

required

When the conversation was created.

string

required

When the conversation was last updated.

AgentMessage[]

required

Array of messages in the conversation.

Properties

string

required

Unique identifier for the message.

"user" | "assistant" | "system"

required

Role of the message sender.

string

required

When the message was created.

string

required

When the message was last updated.

AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

string

required

When reasoning started.

string

When reasoning ended.

string

required

Reasoning content.

string | Record<string, any>

Message content.

string[]

URLs to files attached to the message.

AgentMessageToolCall[]

Tool calls made by the agent.

Properties

string

required

Tool call ID.

string

required

Name of the tool called.

string

required

Arguments passed to the tool as JSON string.

"success" | "error" | "running" | "stopped" | "waiting_for_user_input"

required

Status of the tool call.

string

Results from the tool call.

AgentMessageUsage

Token usage statistics.

Properties

number

Number of tokens in the prompt.

number

Number of tokens in the completion.

boolean

Whether the message is hidden from the user.

AgentMessageCustomContext[]

Custom context provided with the message.

Properties

string

required

Context message.

Record<string, any>

required

Associated data for the context.

string

required

Type of context.

string

Model used to generate the message.

string

Checkpoint ID for the message.

AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

string

required

When the message was created.

string

required

Email of the user who created the message.

string

required

Full name of the user who created the message.

Record<string, any>

Additional custom parameters for the message.

Record<string, any>

Optional metadata associated with the conversation.

Example

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}`);

addMessage()

addMessage(conversation, message): Promise<AgentMessage>

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.

Parameters

Properties

AgentConversation

required

The conversation to add the message to.

Properties

string

required

Unique identifier for the conversation.

string

required

App ID.

string

required

Name of the agent in this conversation.

string

required

ID of the user who created the conversation.

string

required

When the conversation was created.

string

required

When the conversation was last updated.

AgentMessage[]

required

Array of messages in the conversation.

Properties

string

required

Unique identifier for the message.

"user" | "assistant" | "system"

required

Role of the message sender.

string

required

When the message was created.

string

required

When the message was last updated.

AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

string

required

When reasoning started.

string

When reasoning ended.

string

required

Reasoning content.

string | Record<string, any>

Message content.

string[]

URLs to files attached to the message.

AgentMessageToolCall[]

Tool calls made by the agent.

Properties

string

required

Tool call ID.

string

required

Name of the tool called.

string

required

Arguments passed to the tool as JSON string.

"success" | "error" | "running" | "stopped" | "waiting_for_user_input"

required

Status of the tool call.

string

Results from the tool call.

AgentMessageUsage

Token usage statistics.

Properties

number

Number of tokens in the prompt.

number

Number of tokens in the completion.

boolean

Whether the message is hidden from the user.

AgentMessageCustomContext[]

Custom context provided with the message.

Properties

string

required

Context message.

Record<string, any>

required

Associated data for the context.

string

required

Type of context.

string

Model used to generate the message.

string

Checkpoint ID for the message.

AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

string

required

When the message was created.

string

required

Email of the user who created the message.

string

required

Full name of the user who created the message.

Record<string, any>

Additional custom parameters for the message.

Record<string, any>

Optional metadata associated with the conversation.

Partial<AgentMessage>

required

The message to add.

Properties

string

required

Unique identifier for the message.

"user" | "assistant" | "system"

required

Role of the message sender.

string

required

When the message was created.

string

required

When the message was last updated.

AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

string

required

When reasoning started.

string

When reasoning ended.

string

required

Reasoning content.

string | Record<string, any>

Message content.

string[]

URLs to files attached to the message.

AgentMessageToolCall[]

Tool calls made by the agent.

Properties

string

required

Tool call ID.

string

required

Name of the tool called.

string

required

Arguments passed to the tool as JSON string.

"success" | "error" | "running" | "stopped" | "waiting_for_user_input"

required

Status of the tool call.

string

Results from the tool call.

AgentMessageUsage

Token usage statistics.

Properties

number

Number of tokens in the prompt.

number

Number of tokens in the completion.

boolean

Whether the message is hidden from the user.

AgentMessageCustomContext[]

Custom context provided with the message.

Properties

string

required

Context message.

Record<string, any>

required

Associated data for the context.

string

required

Type of context.

string

Model used to generate the message.

string

Checkpoint ID for the message.

AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

string

required

When the message was created.

string

required

Email of the user who created the message.

string

required

Full name of the user who created the message.

Record<string, any>

Additional custom parameters for the message.

Returns

AgentMessage A message in an agent conversation.

Properties

string

required

Unique identifier for the message.

"user" | "assistant" | "system"

required

Role of the message sender.

string

required

When the message was created.

string

required

When the message was last updated.

AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

string

required

When reasoning started.

string

When reasoning ended.

string

required

Reasoning content.

string | Record<string, any>

Message content.

string[]

URLs to files attached to the message.

AgentMessageToolCall[]

Tool calls made by the agent.

Properties

string

required

Tool call ID.

string

required

Name of the tool called.

string

required

Arguments passed to the tool as JSON string.

"success" | "error" | "running" | "stopped" | "waiting_for_user_input"

required

Status of the tool call.

string

Results from the tool call.

AgentMessageUsage

Token usage statistics.

Properties

number

Number of tokens in the prompt.

number

Number of tokens in the completion.

boolean

Whether the message is hidden from the user.

AgentMessageCustomContext[]

Custom context provided with the message.

Properties

string

required

Context message.

Record<string, any>

required

Associated data for the context.

string

required

Type of context.

string

Model used to generate the message.

string

Checkpoint ID for the message.

AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

string

required

When the message was created.

string

required

Email of the user who created the message.

string

required

Full name of the user who created the message.

Record<string, any>

Additional custom parameters for the message.

Example

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}`);

subscribeToConversation()

subscribeToConversation(conversationId, onUpdate?): () => void

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.

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 getConversation() after the message completes.

Parameters

Properties

string

required

The conversation ID to subscribe to.

(conversation) => void

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

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

getWhatsAppConnectURL()

getWhatsAppConnectURL(agentName): string

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.

Parameters

string

required

The name of the agent.

Returns

string WhatsApp connection URL.

Example

const whatsappUrl = base44.agents.getWhatsAppConnectURL('support-agent');
console.log(`Connect through WhatsApp: ${whatsappUrl}`);
// User can open this URL to start a WhatsApp conversation

getTelegramConnectURL()

getTelegramConnectURL(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.

Parameters

string

required

The name of the agent.

Returns

string Telegram connection URL.

Example

const telegramUrl = base44.agents.getTelegramConnectURL('support-agent');
console.log(`Connect through Telegram: ${telegramUrl}`);
// User can open this URL to start a Telegram conversation

Type Definitions

AgentName

AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry

Union of all agent names from the AgentNameRegistry. Defaults to string when no types have been generated.

Example

// With generated types, you get autocomplete on agent names
const conversation = await base44.agents.createConversation({ agent_name: 'SupportBot' });

AgentNameRegistry

Registry of agent names. The types generate command fills this registry, then AgentName resolves to a union of the keys.

​Overview

​Key Features

​Conversation Structure

​Authentication Modes

​Generated Types

​Methods

​getConversations()

​Returns

​Example

​See

​getConversation()

​Parameters

​Returns

​Example

​See

​listConversations()

​Parameters

​Returns

​Examples

​See

​createConversation()

​Parameters

​Returns

​Example

​addMessage()

​Parameters

​Returns

​Example

​subscribeToConversation()

​Parameters

​Returns

​Example

​getWhatsAppConnectURL()

​Parameters

​Returns

​Example

​getTelegramConnectURL()

​Parameters

​Returns

​Example

​Type Definitions

​AgentName

​Example

​AgentNameRegistry

Overview

Key Features

Conversation Structure

Authentication Modes

Generated Types

Methods

getConversations()

Returns

Example

See

getConversation()

Parameters

Returns

Example

See

listConversations()

Parameters

Returns

Examples

See

createConversation()

Parameters

Returns

Example

addMessage()

Parameters

Returns

Example

subscribeToConversation()

Parameters

Returns

Example

getWhatsAppConnectURL()

Parameters

Returns

Example

getTelegramConnectURL()

Parameters

Returns

Example

Type Definitions

AgentName

Example

AgentNameRegistry