Quick Reference for AI Agents & Developers// Add AI Assistant listener for real-time events
CometChat.addAIAssistantListener("LISTENER_ID", AIAssistantListener(
onAIAssistantEventReceived: (AIAssistantBaseEvent event) {
debugPrint("AI Event: ${event.type}");
},
));
// Add Message listener for agentic messages
CometChat.addMessageListener("LISTENER_ID", MessageListener(
onAIAssistantMessageReceived: (AIAssistantMessage msg) {
debugPrint("AI Reply: ${msg.text}");
},
onAIToolResultReceived: (AIToolResultMessage result) {
debugPrint("Tool Result: $result");
},
));
// Remove listeners when done
CometChat.removeAIAssistantListener("LISTENER_ID");
CometChat.removeMessageListener("LISTENER_ID");
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:
- 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.
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}",
);
}
}
Always remove AI Assistant listeners when they’re no longer needed (e.g., on widget dispose or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling.
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.
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()}");
}
}
Next Steps
