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. Each user can read and add messages only to conversations they created, even if the user is an admin. - 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():Gets the current user’s conversations with all agents in the app. Retrieves every conversation the current user started, across all agents. Conversations that other users started aren’t included, even if the user is an admin. UsePromise<AgentConversation[]>
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.
Promise resolving to an array of conversations.
Properties
Properties
Array of messages in the conversation.
Properties
Properties
Whether the message is hidden from the user.
Example
See
listConversations()for filtering, sorting, and paginationgetConversation()for retrieving a specific conversation by ID
getConversation()
getConversation(Gets a specific conversation by ID. Retrieves a single conversation using its unique identifier. The conversation must belong to the current user. If another user created it, the request fails with aconversationId):Promise<AgentConversation|undefined>
403 error. If no conversation has that ID, the request fails with a 404 error. To retrieve
all of the current user’s 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
Returns
AgentConversation
An agent conversation containing messages exchanged with an AI agent.
Promise resolving to the conversation.
Properties
Properties
Array of messages in the conversation.
Properties
Properties
Whether the message is hidden from the user.
Example
See
getConversations()for retrieving all of the current user’s conversationslistConversations()for filtering and sorting conversations
listConversations()
listConversations(Lists the current user’s conversations with filtering, sorting, and pagination. Provides querying capabilities including filtering by fields, sorting, pagination, and field selection. Results only include conversations the current user created, even with a filter onfilterParams):Promise<AgentConversation[]>
created_by_id. For cases where you need all of the current user’s conversations without filtering, use getConversations(). To retrieve a specific conversation by ID, use getConversation().
Parameters
Properties
Properties
Returns
AgentConversation
An agent conversation containing messages exchanged with an AI agent.
Promise resolving to an array of filtered conversations.
Properties
Properties
Array of messages in the conversation.
Properties
Properties
Whether the message is hidden from the user.
Examples
See
getConversations()for retrieving all of the current user’s conversations without filteringgetConversation()for retrieving a specific conversation by ID
createConversation()
createConversation(Creates a new conversation with an agent. The conversation belongs to the current user. Only that user can read it or add messages to it.conversation):Promise<AgentConversation>
Parameters
Properties
Properties
Returns
AgentConversation
An agent conversation containing messages exchanged with an AI agent.
Promise resolving to the created conversation.
Properties
Properties
Array of messages in the conversation.
Properties
Properties
Whether the message is hidden from the user.
Example
addMessage()
addMessage(Adds a message to a conversation. Sends a message to the agent and updates the conversation. You can only add messages to conversations the current user created. This method also updates the realtime socket to notify any subscribers.conversation,message):Promise<AgentMessage>
Parameters
Properties
Properties
Properties
Properties
Array of messages in the conversation.
Properties
Properties
Whether the message is hidden from the user.
Properties
Properties
Whether the message is hidden from the user.
Returns
AgentMessage
A message in an agent conversation.
Promise resolving to the created message.
Properties
Properties
Whether the message is hidden from the user.
Example
subscribeToConversation()
subscribeToConversation(Subscribes to realtime updates for a conversation. Establishes a WebSocket connection to receive instant updates when new messages are added to the conversation. You can only subscribe to conversations the current user created. Returns an unsubscribe function to clean up the connection.conversationId,onUpdate?): () =>void
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
Properties
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 includesid,role('user','assistant', or'system'),content,created_date, and optionallytool_calls,reasoning,file_urls, andusage.metadata: Optional metadata associated with the conversation.
Returns
Unsubscribe function to stop receiving updates.Example
getWhatsAppConnectURL()
getWhatsAppConnectURL(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.agentName):string
Parameters
Returns
string
WhatsApp connection URL.
Example
getTelegramConnectURL()
getTelegramConnectURL(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.agentName):string
Parameters
Returns
string
Telegram connection URL.
Example
Type Definitions
AgentName
AgentName = keyofUnion of all agent names from theAgentNameRegistryextendsnever?string: keyofAgentNameRegistry
AgentNameRegistry. Defaults to string when no types have been generated.
Example
AgentNameRegistry
Registry of agent names. Thetypes generate command fills this registry, then AgentName resolves to a union of the keys.