> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-audit-content-webhooks.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 Flutter app to process messages, trigger tools, and respond with context.

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

> **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:

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="Dart">
    ```dart theme={null}
    import 'package:flutter/foundation.dart';
    import 'package:cometchat_sdk/cometchat_sdk.dart';

    class AIAssistantEventHandler with AIAssistantListener {
    final String _sdkStreamListenerId = "unique_listener_id";

    /// Call this to start listening to AI Assistant events
    void addListener() {
    CometChat.addAIAssistantListener(_sdkStreamListenerId, this);
    debugPrint("AIAssistantListener added successfully.");
    }

    /// Call this to remove the AI Assistant listener
    void removeListener() {
    CometChat.removeAIAssistantListener(_sdkStreamListenerId);
    debugPrint("AIAssistantListener removed successfully.");
    }

    @override
    void onAIAssistantEventReceived(AIAssistantBaseEvent aiAssistantBaseEvent) {
    debugPrint(
    "Received AI Event: ${aiAssistantBaseEvent.type} for Run ID: ${aiAssistantBaseEvent.id}",
    );
    }
    }
    ```
  </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="Dart">
    ```dart theme={null}
    const listenerId = "unique_listener_id";

        class Class_Name with MessageListener {
        // Adding the MessageListener
        // CometChat.addMessageListener(listenerId, this);
          @override
          void onAIAssistantMessageReceived(AIAssistantMessage aiAssistantMessage) {
            debugPrint("AI Assistant Message Received: ${aiAssistantMessage.toString()}");
          }

          @override
          void onAIToolResultReceived(AIToolResultMessage aiToolArgumentMessage) {
            debugPrint("AI Assistant Message Received: ${aiToolArgumentMessage.toString()}");
          }

          @override
          void onAIToolArgumentsReceived(AIToolArgumentMessage aiToolArgumentMessage) {
            debugPrint("AI Assistant Message Received: ${aiToolArgumentMessage.toString()}");
          }
        }
    ```
  </Tab>
</Tabs>