> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents

> Integrate AI-powered agents for intelligent, automated interactions in the CometChat Android SDK.

<Accordion title="AI Integration Quick Reference">
  ```kotlin theme={null}
  // 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) { }
  })
  ```
</Accordion>

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](/ai-agents).

<Note>
  Currently, an Agent only responds to **Text Messages**.
</Note>

## 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`](/sdk/reference/messages#aiassistantbaseevent) objects 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.

<Tabs>
  <Tab title="Java">
    ```java theme={null}

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

    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}

    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())
        }
    })

    ```
  </Tab>
</Tabs>

#### 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.

<Tabs>
  <Tab title="Java">
    ```java theme={null}

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

    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}

    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())
        }
    })

    ```
  </Tab>
</Tabs>

## Agentic Message Payload Structures

<Accordion title="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](/sdk/reference/entities#user) | User who sent the message                                                                         |
  | `receiver`        | AppEntity                            | Message receiver ([User](/sdk/reference/entities#user) or [Group](/sdk/reference/entities#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:**

  ```json theme={null}
  {
    "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"]
  }
  ```
</Accordion>

<Accordion title="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](/sdk/reference/entities#user)     | User who sent the message                                                                         |
  | `receiver`        | AppEntity                                | Message receiver ([User](/sdk/reference/entities#user) or [Group](/sdk/reference/entities#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](#aitoolcall-object)> | List of tool calls                                                                                |
  | `tags`            | Array\<String>                           | Message tags                                                                                      |

  **Sample AIToolArgumentMessage Object:**

  ```json theme={null}
  {
    "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"]
  }
  ```
</Accordion>

<Accordion title="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](/sdk/reference/entities#user) | User who sent the message                                                                         |
  | `receiver`        | AppEntity                            | Message receiver ([User](/sdk/reference/entities#user) or [Group](/sdk/reference/entities#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:**

  ```json theme={null}
  {
    "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"]
  }
  ```
</Accordion>

<Accordion title="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:**

  ```json theme={null}
  {
    "id": "call_abc123",
    "name": "search_flights",
    "arguments": {
      "origin": "NYC",
      "destination": "LA",
      "date": "2024-01-15"
    }
  }
  ```
</Accordion>

<Accordion title="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:**

  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="AI Agents Overview" icon="robot" href="/ai-agents">
    Learn about AI agent capabilities and configuration
  </Card>

  <Card title="Send Message" icon="paper-plane" href="/sdk/android/send-message">
    Send text messages to AI agents to trigger runs
  </Card>

  <Card title="Receive Messages" icon="envelope" href="/sdk/android/receive-messages">
    Handle incoming messages including AI responses
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://app.cometchat.com">
    Configure and manage AI agents in the CometChat Dashboard
  </Card>
</CardGroup>