Quick Reference for AI Agents & Developers

// Listen for real-time AI events
CometChat.addAIAssistantListener("LISTENER_ID", object : CometChat.AIAssistantListener() {
    override fun onAIAssistantEventReceived(event: AIAssistantBaseEvent) {
        // Handle run start, tool calls, text streaming, run finished
    }
})

// Listen for persisted agentic messages
CometChat.addMessageListener("LISTENER_ID", object : CometChat.MessageListener() {
    override fun onAIAssistantMessageReceived(message: AIAssistantMessage) { }
    override fun onAIToolResultReceived(message: AIToolResultMessage) { }
    override fun onAIToolArgumentsReceived(message: AIToolArgumentMessage) { }
})

Available via: SDK | REST API | UI Kits | Dashboard

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:

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.

Java
Kotlin

String LISTENERS_TAG = "UNIQUE_LISTENER_ID";

CometChat.addAIAssistantListener(LISTENERS_TAG, new CometChat.AIAssistantListener() {
    @Override
    public void onAIAssistantEventReceived(AIAssistantBaseEvent aiAssistantBaseEvent) {
        Log.d(TAG, "AIAssistant event received successfully: " + aiAssistantBaseEvent.toString());
    }
});

val LISTENERS_TAG = "UNIQUE_LISTENER_ID"

CometChat.addAIAssistantListener(LISTENERS_TAG, object : CometChat.AIAssistantListener() {
    override fun onAIAssistantEventReceived(aiAssistantBaseEvent: AIAssistantBaseEvent) {
        Log.d(TAG, "AIAssistant event received successfully: " + aiAssistantBaseEvent.toString())
    }
})

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.

Java
Kotlin

String listenerId = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(listenerId, new CometChat.MessageListener() {
    @Override
    public void onAIAssistantMessageReceived(AIAssistantMessage aiAssistantMessage) {
        Log.d(TAG, "AIAssistantMessage received successfully: " + aiAssistantMessage.toString());
    }

    @Override
    public void onAIToolResultReceived(AIToolResultMessage aiToolResultMessage) {
        Log.d(TAG, "AIToolResultMessage received successfully: " + aiToolResultMessage.toString());
    }

    @Override
    public void onAIToolArgumentsReceived(AIToolArgumentMessage aiToolArgumentMessage) {
        Log.d(TAG, "AIToolArgumentMessage received successfully: " + aiToolArgumentMessage.toString());
    }
});

val listenerId = "UNIQUE_LISTENER_ID"

CometChat.addMessageListener(listenerId, object : CometChat.MessageListener() {
    override fun onAIAssistantMessageReceived(aiAssistantMessage: AIAssistantMessage) {
        Log.d(TAG, "AIAssistantMessage received successfully: " + aiAssistantMessage.toString())
    }

    override fun onAIToolResultReceived(aiToolResultMessage: AIToolResultMessage) {
        Log.d(TAG, "AIToolResultMessage received successfully: " + aiToolResultMessage.toString())
    }

    override fun onAIToolArgumentsReceived(aiToolArgumentMessage: AIToolArgumentMessage) {
        Log.d(TAG, "AIToolArgumentMessage received successfully: " + aiToolArgumentMessage.toString())
    }
})

Best Practices

Always Remove AI Listeners

Remove AI assistant and message listeners in onDestroy() or onPause() to prevent memory leaks. Use unique listener IDs to manage multiple listeners effectively.

Handle Streaming Content Progressively

Use Text Message Content events to render AI responses incrementally as they arrive. This provides a better user experience than waiting for the complete response.

Display Tool Call Information

Show users when the agent is invoking tools (e.g., “Searching for flights…”) using Tool Call Start and Tool Call End events. This provides transparency about agent actions.

Store Agentic Messages for History

Persist AIAssistantMessage, AIToolResultMessage, and AIToolArgumentMessage objects locally to display conversation history when users return to the chat.

Next Steps