​
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.
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:
  1. Run Start
  2. Zero or more tool call cycles (repeats for each tool invocation):
    • Tool Call Start
    • Tool Call Arguments
    • Tool Call End
    • Tool Call Result
  3. One or more assistant reply streams:
    • Text Message Start
    • Text Message Content (multiple times; token/char streaming)
    • Text Message End
  4. 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.
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);

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