AI Agents

Quick Reference

// Listen for real-time AI Agent events
CometChat.addAIAssistantListener("listenerId", {
  onAIAssistantEventReceived: (event) => {}
});

// Listen for persisted agentic messages
CometChat.addMessageListener("listenerId", {
  onAIAssistantMessageReceived: (message) => {},
  onAIToolResultReceived: (message) => {},
  onAIToolArgumentsReceived: (message) => {}
});

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.

Currently, an Agent only responds to Text Messages.

Agent Run Lifecycle and Message Flow

This section explains how a user’s text message to an Agent becomes a structured “run” which emits real-time events and then produces agentic messages for historical retrieval.

A user sends a text message to an Agent.
The platform starts a run and streams real-time events via the AIAssistantListener.
After the run completes, persisted Agentic Messages arrive via the MessageListener.

Real-time Events

Events are received via the onAIAssistantEventReceived method of the AIAssistantListener class in this general order:

Run Start
Zero or more tool call cycles (repeats for each tool invocation):
- Tool Call Start
- Tool Call Arguments
- Tool Call End
- Tool Call Result
One or more assistant reply streams:
- Text Message Start
- Text Message Content (multiple times; token/char streaming)
- Text Message End
Run Finished

Notes:

Run Start and Run Finished are always emitted.
Tool Call events appear only when a backend or frontend tool is invoked. There can be multiple tool calls in a single run.
Text Message events are always emitted and carry the assistant’s reply incrementally.

JavaScript
TypeScript

const listnerId = "unique_listener_id";

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

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

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

Always remove AI Assistant listeners when the component unmounts to prevent memory leaks.

CometChat.removeAIAssistantListener("unique_listener_id");

Event Descriptions

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

These events are received via the MessageListener after the run completes.

AIAssistantMessage: The full assistant reply.
AIToolResultMessage: The final output of a tool call.
AIToolArgumentMessage: The arguments that were passed to a tool.

JavaScript
TypeScript

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

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

Always remove message listeners when the component unmounts to prevent memory leaks.

CometChat.removeMessageListener("unique_listener_id");

Best Practices

Register both AIAssistantListener (for real-time streaming) and MessageListener (for persisted messages) to get the complete agent interaction flow
Use Text Message Content events for progressive rendering of the agent’s reply as it streams in
Handle Tool Call events to show tool execution status in your UI (e.g., loading indicators)
Always remove both listeners on component unmount to avoid memory leaks
Since agents only respond to text messages, validate the message type before sending to an agent

Troubleshooting

No events received: Ensure you registered the AIAssistantListener with a unique listener ID before sending a message to the agent.
Missing agentic messages: Agentic messages arrive via MessageListener after the run completes. Make sure you have both listeners registered.
Duplicate events: Verify you are not registering the same listener ID multiple times without removing the previous one.
Tool call events not appearing: Tool call events only fire when the agent invokes a tool. Not all runs include tool calls.

Overview

Agent Run Lifecycle and Message Flow

Real-time Events

Event Descriptions

Agentic Messages

Next Steps

AI Agents Overview

AI Moderation

​Overview

​Agent Run Lifecycle and Message Flow

​Real-time Events

​Event Descriptions

​Agentic Messages

​Next Steps

AI Agents Overview

AI Moderation

Overview

Agent Run Lifecycle and Message Flow

Real-time Events

Event Descriptions

Agentic Messages

Next Steps