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

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

<Info>
  **Quick Reference**

  ```javascript theme={null}
  // 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) => {}
  });
  ```
</Info>

## 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](/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 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="JavaScript">
    ```js theme={null}
    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);
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    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);
    ```
  </Tab>
</Tabs>

<Warning>
  Always remove AI Assistant listeners when the component unmounts to prevent memory leaks.

  ```javascript theme={null}
  CometChat.removeAIAssistantListener("unique_listener_id");
  ```
</Warning>

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

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    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);
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    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);
    ```
  </Tab>
</Tabs>

<Warning>
  Always remove message listeners when the component unmounts to prevent memory leaks.

  ```javascript theme={null}
  CometChat.removeMessageListener("unique_listener_id");
  ```
</Warning>

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="AI Agents Overview" icon="robot" href="/ai-agents">
    Explore the full AI Agents platform documentation
  </Card>

  <Card title="AI Moderation" icon="shield-check" href="/sdk/react-native/ai-moderation">
    Automatically moderate messages using AI
  </Card>
</CardGroup>