Quick Reference for AI Agents & Developers

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

// Listen for AI messages (after run completes)
CometChat.addMessageListener("MSG_LISTENER", {
  onAIAssistantMessageReceived: (msg) => console.log("AI reply:", msg),
  onAIToolResultReceived: (msg) => console.log("Tool result:", msg),
  onAIToolArgumentsReceived: (msg) => console.log("Tool args:", msg)
});

// Remove listeners
CometChat.removeAIAssistantListener("AI_LISTENER");

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.

Available via: SDK | REST API | UI Kits | Widget Builder

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

Handling Specific Event Types

Use the event’s type property to handle each stage of the run:

JavaScript
TypeScript

CometChat.addAIAssistantListener("AI_EVENTS", {
  onAIAssistantEventReceived: (event) => {
    switch (event.getType()) {
      case "run_start":
        console.log("Agent run started");
        showLoadingIndicator();
        break;

      case "tool_call_start":
        console.log("Tool invoked:", event.getData());
        break;

      case "tool_call_arguments":
        console.log("Tool arguments:", event.getData());
        break;

      case "tool_call_end":
        console.log("Tool execution complete");
        break;

      case "tool_call_result":
        console.log("Tool result:", event.getData());
        break;

      case "text_message_start":
        console.log("Agent started composing reply");
        break;

      case "text_message_content":
        // Streaming content — append to UI for progressive rendering
        appendToAgentReply(event.getData());
        break;

      case "text_message_end":
        console.log("Agent reply complete");
        break;

      case "run_finished":
        console.log("Run finalized");
        hideLoadingIndicator();
        break;
    }
  }
});

CometChat.addAIAssistantListener("AI_EVENTS", {
  onAIAssistantEventReceived: (event: CometChat.AIAssistantBaseEvent) => {
    switch (event.getType()) {
      case "run_start":
        console.log("Agent run started");
        showLoadingIndicator();
        break;

      case "text_message_content":
        appendToAgentReply(event.getData());
        break;

      case "tool_call_result":
        console.log("Tool result:", event.getData());
        break;

      case "run_finished":
        console.log("Run finalized");
        hideLoadingIndicator();
        break;
    }
  }
});

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

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

Complete Example

Here’s a full implementation that handles both real-time streaming events and persisted agentic messages:

class AIAgentHandler {
  constructor() {
    this.currentReply = "";
    this.isRunning = false;
    this.setupListeners();
  }

  setupListeners() {
    // Real-time streaming events
    CometChat.addAIAssistantListener("AI_STREAM", {
      onAIAssistantEventReceived: (event) => {
        switch (event.getType()) {
          case "run_start":
            this.isRunning = true;
            this.currentReply = "";
            this.onRunStart();
            break;

          case "text_message_content":
            this.currentReply += event.getData();
            this.onStreamChunk(this.currentReply);
            break;

          case "tool_call_start":
            this.onToolCallStart(event.getData());
            break;

          case "tool_call_result":
            this.onToolCallResult(event.getData());
            break;

          case "run_finished":
            this.isRunning = false;
            this.onRunFinished(this.currentReply);
            break;
        }
      }
    });

    // Persisted messages (for history and offline retrieval)
    CometChat.addMessageListener("AI_MESSAGES", {
      onAIAssistantMessageReceived: (message) => {
        // Full agent reply — use for message history display
        console.log("Agent reply persisted:", message.getText());
      },
      onAIToolResultReceived: (message) => {
        console.log("Tool result persisted:", message);
      },
      onAIToolArgumentsReceived: (message) => {
        console.log("Tool arguments persisted:", message);
      }
    });
  }

  // Override these in your UI layer
  onRunStart() { /* Show typing indicator */ }
  onStreamChunk(partialText) { /* Update UI with streaming text */ }
  onToolCallStart(data) { /* Show "Agent is using a tool..." */ }
  onToolCallResult(data) { /* Display tool output */ }
  onRunFinished(fullReply) { /* Finalize UI, hide typing indicator */ }

  cleanup() {
    CometChat.removeAIAssistantListener("AI_STREAM");
    CometChat.removeMessageListener("AI_MESSAGES");
  }
}

// Usage
const handler = new AIAgentHandler();

// Send a message to the agent (agents respond to text messages)
const message = new CometChat.TextMessage(
  "AGENT_UID",
  "What's the weather in San Francisco?",
  CometChat.RECEIVER_TYPE.USER
);
await CometChat.sendMessage(message);
// The agent processes the message and events stream in via the listeners above

Always remove both AIAssistantListener and MessageListener when your component unmounts or the user navigates away to prevent memory leaks.

Next Steps

AI Moderation

Automatically moderate messages with AI

AI Chatbots

Create intelligent chatbot experiences

Receive Messages

Handle all real-time message events

AI Agents Platform

Create and configure agents in the dashboard

​AI Agents Overview

​Agent Run Lifecycle and Message Flow

​Real-time Events

​Handling Specific Event Types

​Event descriptions

​Agentic Messages

​Complete Example

​Next Steps

AI Moderation

AI Chatbots

Receive Messages

AI Agents Platform

AI Agents Overview

Agent Run Lifecycle and Message Flow

Real-time Events

Handling Specific Event Types

Event descriptions

Agentic Messages

Complete Example

Next Steps