AI Agents

Handle CometChat AI Agent events, tool calls, and agent messages in JavaScript apps.

AI Agents Overview

AI Agents enable intelligent, automated interactions within your application. They can process user messages, trigger tools, and respond with contextually relevant information. For a broader introduction, see the AI Agents section.

Agents only respond to text messages.

Agent Run Lifecycle and Message Flow

When a user sends a text message to an Agent:

1. The platform starts a run and streams real-time events via AIAssistantListener
2. After the run completes, persisted Agentic Messages arrive via MessageListener

Real-time Events

Events are received via the onAIAssistantEventReceived method of the AIAssistantListener class as AIAssistantBaseEvent objects, in this general order:

Events arrive via onAIAssistantEventReceived in this order:

Order	Event	Description
1	Run Start	A new run has begun
2	Tool Call Start	Agent decided to invoke a tool
3	Tool Call Arguments	Arguments being passed to the tool
4	Tool Call End	Tool execution completed
5	Tool Call Result	Tool’s output is available
6	Text Message Start	Agent started composing a reply
7	Text Message Content	Streaming content chunks (multiple)
8	Text Message End	Agent reply is complete
9	Run Finished	Run finalized; persisted messages follow

Run Start and Run Finished are always emitted. Tool Call events only appear when tools are invoked — there can be multiple tool call cycles in a single run. Text Message events are always emitted and carry the assistant’s reply incrementally.

Event Object Properties

Every event is an AIAssistantBaseEvent with these common properties:

Getter	Return Type	Description
getType()	string	Event type (e.g., run_started, text_message_content)
getConversationId()	string	The conversation this event belongs to
getMessageId()	string	The message ID associated with the event
getParentMessageId()	string	Parent message ID (for threaded messages)
getRunId()	string	The run ID for this agent execution
getThreadId()	string	The thread ID for this agent execution
getTimestamp()	number	Timestamp of the event
getData()	object	Full event data payload

Some events carry additional data:

Event	Extra Getter	Description
Text Message Content	getDelta()	The streaming text chunk for progressive rendering
Tool Call Arguments	getToolCallId(), getDelta()	Tool call ID and argument chunk
Tool Call Result	getToolCallId(), getContent(), getRole()	Tool call ID, result content, and role

TypeScript

        const listnerId: string = "unique_listener_id";

        // Adding the AIAssistantListener
        CometChat.addAIAssistantListener(listnerId, {
            onAIAssistantEventReceived: (message: CometChat.AIAssistantBaseEvent) => {
                console.log("AIAssistant event received successfully", message);
            }
        });

        // Removing the AIAssistantListener
        CometChat.removeAIAssistantListener(listnerId);

JavaScript

        const listnerId: string = "unique_listener_id";

        // Adding the AIAssistantListener
        CometChat.addAIAssistantListener(listnerId, {
            onAIAssistantEventReceived: (message: CometChat.AIAssistantBaseEvent) => {
                console.log("AIAssistant event received successfully", message);
            }
        });

        // Removing the AIAssistantListener
        CometChat.removeAIAssistantListener(listnerId);

Event descriptions

• Run Start: A new run has begun for the user’s message.
• Tool Call Start: The agent decided to invoke a tool.
• Tool Call Arguments: Arguments being passed to the tool.
• Tool Call End: Tool execution completed.
• Tool Call Result: Tool’s output is available.
• Text Message Start: The agent started composing a reply.
• Text Message Content: Streaming content chunks for progressive rendering.
• Text Message End: The agent reply is complete.
• Run Finished: The run is finalized; persisted messages will follow.

Agentic Messages

After the run completes, these messages arrive via MessageListener:

Message Type	Description
AIAssistantMessage	The full assistant reply
AIToolResultMessage	The final output of a tool call
AIToolArgumentMessage	The arguments passed to a tool

Each message type extends BaseMessage and has a typed data accessor:

Message Type	Data Getter	Data Properties
AIAssistantMessage	getAssistantMessageData()	getRunId(), getThreadId(), getText()
AIToolResultMessage	getToolResultMessageData()	getRunId(), getThreadId(), getText(), getToolCallId()
AIToolArgumentMessage	getToolArgumentMessageData()	getRunId(), getThreadId(), getToolCalls()

When an agent reply contains a card, the card is embedded inline in the AIAssistantMessage and exposed through getElements(). Cards are also streamed in real time via the card_start / card / card_end events on the AIAssistantListener. See the Card Messages guide for both flows.

The getToolCalls() method on AIToolArgumentMessage returns an array of AIToolCall objects, each with:

Getter	Return Type	Description
getId()	string	Unique tool call ID
getType()	string	Tool call type
getFunction()	AIToolCallFunction	Function object with getName() and getArguments()
getDisplayName()	string	Display name of the tool
getExecutionText()	string	Execution description text

TypeScript

const listnerId: string = "unique_listener_id";

// Adding the MessageListener
CometChat.addMessageListener(listnerId, {
    onAIAssistantMessageReceived: (message: CometChat.AIAssistantMessage) => {
        console.log("AI Assistant message received successfully", message);
    },
    onAIToolResultReceived: (message: CometChat.AIToolResultMessage) => {
        console.log("AI Tool result message received successfully", message);
    },
    onAIToolArgumentsReceived: (message: CometChat.AIToolArgumentMessage) => {
        console.log("AI Tool argument message received successfully", message);
    },
});

// Removing the MessageListener
CometChat.removeMessageListener(listnerId);

JavaScript

const listnerId = "unique_listener_id";

// Adding the MessageListener
CometChat.addMessageListener(listnerId, {
    onAIAssistantMessageReceived: (message) => {
        console.log("AI Assistant message received successfully", message);
    },
    onAIToolResultReceived: (message) => {
        console.log("AI Tool result message received successfully", message);
    },
    onAIToolArgumentsReceived: (message) => {
        console.log("AI Tool argument message received successfully", message);
    },
});

// Removing the MessageListener
CometChat.removeMessageListener(listnerId);

Always remove listeners when they’re no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling.

---

Next Steps

AI Chatbots

Set up AI-powered chatbots for automated conversations

AI Moderation

Automatically moderate messages with AI

AI User Copilot

AI-powered features like smart replies and conversation summaries

Send Messages

Send text messages that trigger AI Agent responses