AI Agents

Learn how to integrate AI Agents in your React Native app using the CometChat SDK, including real-time event streaming and agentic message handling.

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:

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.

JavaScript

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

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

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

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

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

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.

Next Steps

AI Agents Overview

Explore the full AI Agents platform documentation

AI Moderation

Automatically moderate messages using AI