agents

---

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:

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

id · string · required

Unique identifier for the conversation.

app_id · string · required

App ID.

agent_name · string · required

Name of the agent in this conversation.

created_by_id · string · required

ID of the user who created the conversation.

created_date · string · required

When the conversation was created.

updated_date · string · required

When the conversation was last updated.

messages · AgentMessage[] · required

Array of messages in the conversation.

Properties

id · string · required

Unique identifier for the message.

role · "user" | "assistant" | "system" · required

Role of the message sender.

created_date · string · required

When the message was created.

updated_date · string · required

When the message was last updated.

reasoning · AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

start_date · string · required

When reasoning started.

end_date · string

When reasoning ended.

content · string · required

Reasoning content.

content · string | Record<string, any>

Message content.

file_urls · string[]

URLs to files attached to the message.

tool_calls · AgentMessageToolCall[]

Tool calls made by the agent.

Properties

id · string · required

Tool call ID.

name · string · required

Name of the tool called.

arguments_string · string · required

Arguments passed to the tool as JSON string.

status · "success" | "error" | "running" | "stopped" | "waiting_for_user_input" · required

Status of the tool call.

results · string

Results from the tool call.

usage · AgentMessageUsage

Token usage statistics.

Properties

prompt_tokens · number

Number of tokens in the prompt.

completion_tokens · number

Number of tokens in the completion.

hidden · boolean

Whether the message is hidden from the user.

custom_context · AgentMessageCustomContext[]

Custom context provided with the message.

Properties

message · string · required

Context message.

data · Record<string, any> · required

Associated data for the context.

type · string · required

Type of context.

model · string

Model used to generate the message.

checkpoint_id · string

Checkpoint ID for the message.

metadata · AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

created_date · string · required

When the message was created.

created_by_email · string · required

Email of the user who created the message.

created_by_full_name · string · required

Full name of the user who created the message.

additional_message_params · Record<string, any>

Additional custom parameters for the message.

metadata · Record<string, any>

Optional metadata associated with the conversation.

Example

Get all conversations

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

conversationId · string · required

The unique identifier of the conversation.

Returns

AgentConversation

An agent conversation containing messages exchanged with an AI agent.

Properties

id · string · required

Unique identifier for the conversation.

app_id · string · required

App ID.

agent_name · string · required

Name of the agent in this conversation.

created_by_id · string · required

ID of the user who created the conversation.

created_date · string · required

When the conversation was created.

updated_date · string · required

When the conversation was last updated.

messages · AgentMessage[] · required

Array of messages in the conversation.

Properties

id · string · required

Unique identifier for the message.

role · "user" | "assistant" | "system" · required

Role of the message sender.

created_date · string · required

When the message was created.

updated_date · string · required

When the message was last updated.

reasoning · AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

start_date · string · required

When reasoning started.

end_date · string

When reasoning ended.

content · string · required

Reasoning content.

content · string | Record<string, any>

Message content.

file_urls · string[]

URLs to files attached to the message.

tool_calls · AgentMessageToolCall[]

Tool calls made by the agent.

Properties

id · string · required

Tool call ID.

name · string · required

Name of the tool called.

arguments_string · string · required

Arguments passed to the tool as JSON string.

status · "success" | "error" | "running" | "stopped" | "waiting_for_user_input" · required

Status of the tool call.

results · string

Results from the tool call.

usage · AgentMessageUsage

Token usage statistics.

Properties

prompt_tokens · number

Number of tokens in the prompt.

completion_tokens · number

Number of tokens in the completion.

hidden · boolean

Whether the message is hidden from the user.

custom_context · AgentMessageCustomContext[]

Custom context provided with the message.

Properties

message · string · required

Context message.

data · Record<string, any> · required

Associated data for the context.

type · string · required

Type of context.

model · string

Model used to generate the message.

checkpoint_id · string

Checkpoint ID for the message.

metadata · AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

created_date · string · required

When the message was created.

created_by_email · string · required

Email of the user who created the message.

created_by_full_name · string · required

Full name of the user who created the message.

additional_message_params · Record<string, any>

Additional custom parameters for the message.

metadata · Record<string, any>

Optional metadata associated with the conversation.

Example

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

• 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

filterParams · ModelFilterParams · required

Filter parameters for querying conversations.

Properties

q · Record<string, any>

Query object with field-value pairs for filtering.

sort · string | null

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

sort_by · string | null

Alternative sort parameter. Use either sort or sort_by.

limit · number | null

Maximum number of results to return.

skip · number | null

Number of results to skip. Used for pagination.

fields · string[] | null

Array of field names to include in the response.

Returns

AgentConversation

An agent conversation containing messages exchanged with an AI agent.

Properties

id · string · required

Unique identifier for the conversation.

app_id · string · required

App ID.

agent_name · string · required

Name of the agent in this conversation.

created_by_id · string · required

ID of the user who created the conversation.

created_date · string · required

When the conversation was created.

updated_date · string · required

When the conversation was last updated.

messages · AgentMessage[] · required

Array of messages in the conversation.

Properties

id · string · required

Unique identifier for the message.

role · "user" | "assistant" | "system" · required

Role of the message sender.

created_date · string · required

When the message was created.

updated_date · string · required

When the message was last updated.

reasoning · AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

start_date · string · required

When reasoning started.

end_date · string

When reasoning ended.

content · string · required

Reasoning content.

content · string | Record<string, any>

Message content.

file_urls · string[]

URLs to files attached to the message.

tool_calls · AgentMessageToolCall[]

Tool calls made by the agent.

Properties

id · string · required

Tool call ID.

name · string · required

Name of the tool called.

arguments_string · string · required

Arguments passed to the tool as JSON string.

status · "success" | "error" | "running" | "stopped" | "waiting_for_user_input" · required

Status of the tool call.

results · string

Results from the tool call.

usage · AgentMessageUsage

Token usage statistics.

Properties

prompt_tokens · number

Number of tokens in the prompt.

completion_tokens · number

Number of tokens in the completion.

hidden · boolean

Whether the message is hidden from the user.

custom_context · AgentMessageCustomContext[]

Custom context provided with the message.

Properties

message · string · required

Context message.

data · Record<string, any> · required

Associated data for the context.

type · string · required

Type of context.

model · string

Model used to generate the message.

checkpoint_id · string

Checkpoint ID for the message.

metadata · AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

created_date · string · required

When the message was created.

created_by_email · string · required

Email of the user who created the message.

created_by_full_name · string · required

Full name of the user who created the message.

additional_message_params · Record<string, any>

Additional custom parameters for the message.

metadata · Record<string, any>

Optional metadata associated with the conversation.

Examples

List recent conversations with pagination

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

conversation · CreateConversationParams · required

Conversation details including agent name and optional metadata.

Properties

agent_name · string · required

The name of the agent to create a conversation with.

metadata · Record<string, any>

Optional metadata to attach to the conversation.

Returns

AgentConversation

An agent conversation containing messages exchanged with an AI agent.

Properties

id · string · required

Unique identifier for the conversation.

app_id · string · required

App ID.

agent_name · string · required

Name of the agent in this conversation.

created_by_id · string · required

ID of the user who created the conversation.

created_date · string · required

When the conversation was created.

updated_date · string · required

When the conversation was last updated.

messages · AgentMessage[] · required

Array of messages in the conversation.

Properties

id · string · required

Unique identifier for the message.

role · "user" | "assistant" | "system" · required

Role of the message sender.

created_date · string · required

When the message was created.

updated_date · string · required

When the message was last updated.

reasoning · AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

start_date · string · required

When reasoning started.

end_date · string

When reasoning ended.

content · string · required

Reasoning content.

content · string | Record<string, any>

Message content.

file_urls · string[]

URLs to files attached to the message.

tool_calls · AgentMessageToolCall[]

Tool calls made by the agent.

Properties

id · string · required

Tool call ID.

name · string · required

Name of the tool called.

arguments_string · string · required

Arguments passed to the tool as JSON string.

status · "success" | "error" | "running" | "stopped" | "waiting_for_user_input" · required

Status of the tool call.

results · string

Results from the tool call.

usage · AgentMessageUsage

Token usage statistics.

Properties

prompt_tokens · number

Number of tokens in the prompt.

completion_tokens · number

Number of tokens in the completion.

hidden · boolean

Whether the message is hidden from the user.

custom_context · AgentMessageCustomContext[]

Custom context provided with the message.

Properties

message · string · required

Context message.

data · Record<string, any> · required

Associated data for the context.

type · string · required

Type of context.

model · string

Model used to generate the message.

checkpoint_id · string

Checkpoint ID for the message.

metadata · AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

created_date · string · required

When the message was created.

created_by_email · string · required

Email of the user who created the message.

created_by_full_name · string · required

Full name of the user who created the message.

additional_message_params · Record<string, any>

Additional custom parameters for the message.

metadata · Record<string, any>

Optional metadata associated with the conversation.

Example

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

---

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

conversation · AgentConversation · required

The conversation to add the message to.

Properties

id · string · required

Unique identifier for the conversation.

app_id · string · required

App ID.

agent_name · string · required

Name of the agent in this conversation.

created_by_id · string · required

ID of the user who created the conversation.

created_date · string · required

When the conversation was created.

updated_date · string · required

When the conversation was last updated.

messages · AgentMessage[] · required

Array of messages in the conversation.

Properties

id · string · required

Unique identifier for the message.

role · "user" | "assistant" | "system" · required

Role of the message sender.

created_date · string · required

When the message was created.

updated_date · string · required

When the message was last updated.

reasoning · AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

start_date · string · required

When reasoning started.

end_date · string

When reasoning ended.

content · string · required

Reasoning content.

content · string | Record<string, any>

Message content.

file_urls · string[]

URLs to files attached to the message.

tool_calls · AgentMessageToolCall[]

Tool calls made by the agent.

Properties

id · string · required

Tool call ID.

name · string · required

Name of the tool called.

arguments_string · string · required

Arguments passed to the tool as JSON string.

status · "success" | "error" | "running" | "stopped" | "waiting_for_user_input" · required

Status of the tool call.

results · string

Results from the tool call.

usage · AgentMessageUsage

Token usage statistics.

Properties

prompt_tokens · number

Number of tokens in the prompt.

completion_tokens · number

Number of tokens in the completion.

hidden · boolean

Whether the message is hidden from the user.

custom_context · AgentMessageCustomContext[]

Custom context provided with the message.

Properties

message · string · required

Context message.

data · Record<string, any> · required

Associated data for the context.

type · string · required

Type of context.

model · string

Model used to generate the message.

checkpoint_id · string

Checkpoint ID for the message.

metadata · AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

created_date · string · required

When the message was created.

created_by_email · string · required

Email of the user who created the message.

created_by_full_name · string · required

Full name of the user who created the message.

additional_message_params · Record<string, any>

Additional custom parameters for the message.

metadata · Record<string, any>

Optional metadata associated with the conversation.

message · Partial<AgentMessage> · required

The message to add.

Properties

id · string · required

Unique identifier for the message.

role · "user" | "assistant" | "system" · required

Role of the message sender.

created_date · string · required

When the message was created.

updated_date · string · required

When the message was last updated.

reasoning · AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

start_date · string · required

When reasoning started.

end_date · string

When reasoning ended.

content · string · required

Reasoning content.

content · string | Record<string, any>

Message content.

file_urls · string[]

URLs to files attached to the message.

tool_calls · AgentMessageToolCall[]

Tool calls made by the agent.

Properties

id · string · required

Tool call ID.

name · string · required

Name of the tool called.

arguments_string · string · required

Arguments passed to the tool as JSON string.

status · "success" | "error" | "running" | "stopped" | "waiting_for_user_input" · required

Status of the tool call.

results · string

Results from the tool call.

usage · AgentMessageUsage

Token usage statistics.

Properties

prompt_tokens · number

Number of tokens in the prompt.

completion_tokens · number

Number of tokens in the completion.

hidden · boolean

Whether the message is hidden from the user.

custom_context · AgentMessageCustomContext[]

Custom context provided with the message.

Properties

message · string · required

Context message.

data · Record<string, any> · required

Associated data for the context.

type · string · required

Type of context.

model · string

Model used to generate the message.

checkpoint_id · string

Checkpoint ID for the message.

metadata · AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

created_date · string · required

When the message was created.

created_by_email · string · required

Email of the user who created the message.

created_by_full_name · string · required

Full name of the user who created the message.

additional_message_params · Record<string, any>

Additional custom parameters for the message.

Returns

AgentMessage

A message in an agent conversation.

Properties

id · string · required

Unique identifier for the message.

role · "user" | "assistant" | "system" · required

Role of the message sender.

created_date · string · required

When the message was created.

updated_date · string · required

When the message was last updated.

reasoning · AgentMessageReasoning | null

Optional reasoning information for the message.

Properties

start_date · string · required

When reasoning started.

end_date · string

When reasoning ended.

content · string · required

Reasoning content.

content · string | Record<string, any>

Message content.

file_urls · string[]

URLs to files attached to the message.

tool_calls · AgentMessageToolCall[]

Tool calls made by the agent.

Properties

id · string · required

Tool call ID.

name · string · required

Name of the tool called.

arguments_string · string · required

Arguments passed to the tool as JSON string.

status · "success" | "error" | "running" | "stopped" | "waiting_for_user_input" · required

Status of the tool call.

results · string

Results from the tool call.

usage · AgentMessageUsage

Token usage statistics.

Properties

prompt_tokens · number

Number of tokens in the prompt.

completion_tokens · number

Number of tokens in the completion.

hidden · boolean

Whether the message is hidden from the user.

custom_context · AgentMessageCustomContext[]

Custom context provided with the message.

Properties

message · string · required

Context message.

data · Record<string, any> · required

Associated data for the context.

type · string · required

Type of context.

model · string

Model used to generate the message.

checkpoint_id · string

Checkpoint ID for the message.

metadata · AgentMessageMetadata

Metadata about when and by whom the message was created.

Properties

created_date · string · required

When the message was created.

created_by_email · string · required

Email of the user who created the message.

created_by_full_name · string · required

Full name of the user who created the message.

additional_message_params · Record<string, any>

Additional custom parameters for the message.

Example

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

---

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

conversationId · string · required

The conversation ID to subscribe to.

onUpdate · (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

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

---

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

agentName · string · required

The name of the agent.

Returns

string

WhatsApp connection URL.

Example

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

---

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

agentName · string · required

The name of the agent.

Returns

string

Telegram connection URL.

Example

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

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

Using generated agent name types

// 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.