AI Agents

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:

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.

Dart

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}",
);
}
}

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.

Dart

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