AI Agents - CometChat Docs

AI Integration Quick Reference

// 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) { }
})

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 as AIAssistantBaseEvent objects 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())
    }
})

Agentic Message Payload Structures

AIAssistantMessage Object

The AIAssistantMessage object contains the AI assistant’s response:

Parameter	Type	Description
`id`	long	Unique message identifier
`muid`	String	Developer-defined message ID
`sender`	User	User who sent the message
`receiver`	AppEntity	Message receiver (User or Group)
`receiverUid`	String	Receiver’s unique identifier
`type`	String	Message type. Value: `"assistant"`
`receiverType`	String	Type of receiver. Values: `"user"`, `"group"`
`category`	String	Message category. Value: `"agentic"`
`sentAt`	long	Unix timestamp when sent
`deliveredAt`	long	Unix timestamp when delivered
`readAt`	long	Unix timestamp when read
`metadata`	JSONObject	Custom message metadata
`readByMeAt`	long	When logged-in user read message
`deliveredToMeAt`	long	When delivered to logged-in user
`deletedAt`	long	Unix timestamp when deleted (0 if not deleted)
`editedAt`	long	Unix timestamp when edited (0 if not edited)
`deletedBy`	String	UID of user who deleted (null if not deleted)
`editedBy`	String	UID of user who edited (null if not edited)
`updatedAt`	long	Unix timestamp of last update
`conversationId`	String	Associated conversation ID
`runId`	long	AI run identifier
`threadId`	String	AI thread identifier
`text`	String	AI response text
`tags`	Array<String>	Message tags

Sample AIAssistantMessage Object:

{
  "id": 12345,
  "muid": "msg_abc123",
  "sender": {
    "uid": "user_123",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png",
    "status": "online",
    "role": "default"
  },
  "receiver": {
    "uid": "user_456",
    "name": "Jane Smith"
  },
  "receiverUid": "user_456",
  "type": "assistant",
  "receiverType": "user",
  "category": "agentic",
  "sentAt": 1699900000,
  "deliveredAt": 1699900001,
  "readAt": 1699900002,
  "metadata": {"priority": "high"},
  "readByMeAt": 1699900002,
  "deliveredToMeAt": 1699900001,
  "deletedAt": 0,
  "editedAt": 0,
  "deletedBy": null,
  "editedBy": null,
  "updatedAt": 1699900000,
  "conversationId": "user_123_user_456",
  "runId": 98765,
  "threadId": "thread_abc",
  "text": "Here's the answer...",
  "tags": ["ai-response"]
}

AIToolArgumentMessage Object

The AIToolArgumentMessage object contains the arguments passed to a tool:

Parameter	Type	Description
`id`	long	Unique message identifier
`muid`	String	Developer-defined message ID
`sender`	User	User who sent the message
`receiver`	AppEntity	Message receiver (User or Group)
`receiverUid`	String	Receiver’s unique identifier
`type`	String	Message type. Value: `"tool_arguments"`
`receiverType`	String	Type of receiver. Values: `"user"`, `"group"`
`category`	String	Message category. Value: `"agentic"`
`sentAt`	long	Unix timestamp when sent
`deliveredAt`	long	Unix timestamp when delivered
`readAt`	long	Unix timestamp when read
`metadata`	JSONObject	Custom message metadata
`readByMeAt`	long	When logged-in user read message
`deliveredToMeAt`	long	When delivered to logged-in user
`deletedAt`	long	Unix timestamp when deleted (0 if not deleted)
`editedAt`	long	Unix timestamp when edited (0 if not edited)
`deletedBy`	String	UID of user who deleted (null if not deleted)
`editedBy`	String	UID of user who edited (null if not edited)
`updatedAt`	long	Unix timestamp of last update
`conversationId`	String	Associated conversation ID
`runId`	long	AI run identifier
`threadId`	String	AI thread identifier
`toolCalls`	Array<AIToolCall>	List of tool calls
`tags`	Array<String>	Message tags

Sample AIToolArgumentMessage Object:

{
  "id": 12346,
  "muid": "msg_tool_arg_123",
  "sender": {
    "uid": "user_123",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png",
    "status": "online",
    "role": "default"
  },
  "receiver": {
    "uid": "user_456",
    "name": "Jane Smith"
  },
  "receiverUid": "user_456",
  "type": "tool_arguments",
  "receiverType": "user",
  "category": "agentic",
  "sentAt": 1699900000,
  "deliveredAt": 1699900001,
  "readAt": 1699900002,
  "metadata": {"priority": "high"},
  "readByMeAt": 1699900002,
  "deliveredToMeAt": 1699900001,
  "deletedAt": 0,
  "editedAt": 0,
  "deletedBy": null,
  "editedBy": null,
  "updatedAt": 1699900000,
  "conversationId": "user_123_user_456",
  "runId": 98765,
  "threadId": "thread_abc",
  "toolCalls": [
    {
      "id": "call_abc123",
      "name": "search_flights",
      "arguments": {"origin": "NYC", "destination": "LA"}
    }
  ],
  "tags": ["tool-arguments"]
}

AIToolResultMessage Object

The AIToolResultMessage object contains the result from a tool execution:

Parameter	Type	Description
`id`	long	Unique message identifier
`muid`	String	Developer-defined message ID
`sender`	User	User who sent the message
`receiver`	AppEntity	Message receiver (User or Group)
`receiverUid`	String	Receiver’s unique identifier
`type`	String	Message type. Value: `"tool_result"`
`receiverType`	String	Type of receiver. Values: `"user"`, `"group"`
`category`	String	Message category. Value: `"agentic"`
`sentAt`	long	Unix timestamp when sent
`deliveredAt`	long	Unix timestamp when delivered
`readAt`	long	Unix timestamp when read
`metadata`	JSONObject	Custom message metadata
`readByMeAt`	long	When logged-in user read message
`deliveredToMeAt`	long	When delivered to logged-in user
`deletedAt`	long	Unix timestamp when deleted (0 if not deleted)
`editedAt`	long	Unix timestamp when edited (0 if not edited)
`deletedBy`	String	UID of user who deleted (null if not deleted)
`editedBy`	String	UID of user who edited (null if not edited)
`updatedAt`	long	Unix timestamp of last update
`conversationId`	String	Associated conversation ID
`runId`	long	AI run identifier
`threadId`	String	AI thread identifier
`text`	String	Tool result text
`toolCallId`	String	ID of the tool call that produced this result
`tags`	Array<String>	Message tags

Sample AIToolResultMessage Object:

{
  "id": 12347,
  "muid": "msg_tool_result_123",
  "sender": {
    "uid": "user_123",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png",
    "status": "online",
    "role": "default"
  },
  "receiver": {
    "uid": "user_456",
    "name": "Jane Smith"
  },
  "receiverUid": "user_456",
  "type": "tool_result",
  "receiverType": "user",
  "category": "agentic",
  "sentAt": 1699900000,
  "deliveredAt": 1699900001,
  "readAt": 1699900002,
  "metadata": {"priority": "high"},
  "readByMeAt": 1699900002,
  "deliveredToMeAt": 1699900001,
  "deletedAt": 0,
  "editedAt": 0,
  "deletedBy": null,
  "editedBy": null,
  "updatedAt": 1699900000,
  "conversationId": "user_123_user_456",
  "runId": 98765,
  "threadId": "thread_abc",
  "text": "Flight found: NYC to LA...",
  "toolCallId": "call_abc123",
  "tags": ["tool-result"]
}

AIToolCall Object

The AIToolCall object represents a single tool invocation:

Parameter	Type	Description
`id`	String	Unique identifier for the tool call
`name`	String	Name of the tool being called
`arguments`	JSONObject	Arguments passed to the tool

Sample AIToolCall Object:

{
  "id": "call_abc123",
  "name": "search_flights",
  "arguments": {
    "origin": "NYC",
    "destination": "LA",
    "date": "2024-01-15"
  }
}

User Object (AI)

The nested User object in sender contains:

Parameter	Type	Description
`uid`	String	Unique identifier of the user
`name`	String	Display name of the user
`avatar`	String	URL to user’s profile picture
`link`	String	URL to user’s profile page
`role`	String	User role for access control
`metadata`	JSONObject	Custom data set by developer
`status`	String	User online status. Values: `"online"`, `"offline"`
`statusMessage`	String	Custom status message
`lastActiveAt`	long	Unix timestamp of last activity
`hasBlockedMe`	boolean	Whether this user has blocked the logged-in user
`blockedByMe`	boolean	Whether the logged-in user has blocked this user
`tags`	Array<String>	List of tags for user identification
`deactivatedAt`	long	Unix timestamp when user was deactivated (0 if active)

Sample User Object:

{
  "uid": "user_123",
  "name": "John Doe",
  "avatar": "https://example.com/avatar.png",
  "link": "https://example.com/profile/user_123",
  "role": "default",
  "metadata": {"department": "engineering"},
  "status": "online",
  "statusMessage": "Available",
  "lastActiveAt": 1699900000,
  "hasBlockedMe": false,
  "blockedByMe": false,
  "tags": ["premium"],
  "deactivatedAt": 0
}

Next Steps

AI Agents Overview

Learn about AI agent capabilities and configuration

Send Message

Send text messages to AI agents to trigger runs

Receive Messages

Handle incoming messages including AI responses

Dashboard

Configure and manage AI agents in the CometChat Dashboard

​Agent Run Lifecycle and Message Flow

​Real-time Events

​Event descriptions

​Agentic Messages

​Agentic Message Payload Structures

​Next Steps

AI Agents Overview

Send Message

Receive Messages

Dashboard

Agent Run Lifecycle and Message Flow

Real-time Events

Event descriptions

Agentic Messages

Agentic Message Payload Structures

Next Steps