AI Agents

Integrate AI Agents for intelligent automated interactions using the CometChat iOS SDK with real-time streaming events.

AI Integration Quick Reference

Feature	Description
AI Agents	Intelligent automated conversations with real-time streaming
AI Moderation	Automatic content moderation with pending/approved/disapproved flow
AI User Copilot	Smart Replies, Conversation Starter, Conversation Summary (Dashboard-enabled)

// Listen for real-time AI Agent events (streaming)
CometChat.addAIAssistantListener("LISTENER_ID", self)

// Listen for persisted agentic messages
// Conform to CometChatMessageDelegate
func onAIAssistantMessageReceived(_ msg: AIAssistantMessage) { }
func onAIToolResultMessageReceived(_ msg: AIToolResultMessage) { }
func onAIToolArgumentsMessageReceived(_ msg: AIToolArgumentMessage) { }

// Cleanup
CometChat.removeAIAssistantListener("LISTENER_ID")
CometChat.removeMessageListener("LISTENER_ID")

Prerequisites: CometChat.init() + CometChat.login() completed, AI features enabled in Dashboard Event flow: Run Start -> Tool Call(s) -> Text Message Stream -> Run Finished

AI Agents enable intelligent, automated interactions within your application. They process user messages, trigger tools, and respond with contextually relevant information. For a broader introduction, see the AI Agents section.

Agents only respond to text messages.

Sending a Message to an AI Agent

Send a text message to an agent’s UID like any other user:

Swift

let agentUID = "ai-agent-uid"
let textMessage = TextMessage(
    receiverUid: agentUID,
    text: "What's the weather today?",
    receiverType: .user
)

CometChat.sendTextMessage(message: textMessage) { sentMessage in
    print("Message sent to agent")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Agent Run Lifecycle and Message Flow

When a user sends a text message to an Agent:

1. The platform starts a run and streams real-time events via AIAssistantEventsDelegate
2. After the run completes, persisted Agentic Messages arrive via CometChatMessageDelegate

Real-time Events

Events are received via onAIAssistantEventReceived as AIAssistantBaseEvent objects, in this order:

Order	Event	Description
1	Run Start	A new run has begun
2	Tool Call Start	Agent decided to invoke a tool
3	Tool Call Arguments	Arguments being passed to the tool
4	Tool Call End	Tool execution completed
5	Tool Call Result	Tool’s output is available
6	Card Start	Agent began producing a card
7	Card	Full card payload is available
8	Card End	Card stream is complete
9	Text Message Start	Agent started composing a reply
10	Text Message Content	Streaming content chunks (multiple)
11	Text Message End	Agent reply is complete
12	Run Finished	Run finalized; persisted messages follow

Run Start and Run Finished are always emitted. Tool Call events only appear when tools are invoked. Card events (Card Start → Card → Card End) appear only when the agent produces a card, and repeat for each card. Text Message events are always emitted and carry the assistant’s reply incrementally.

Swift

import CometChatSDK

class AIAssistantEventHandler: AIAssistantEventsDelegate {
    
    private let sdkStreamListenerId = "unique_listener_id"
    
    func addListener() {
        CometChat.addAIAssistantListener(sdkStreamListenerId, self)
    }
    
    func removeListener() {
        CometChat.removeAIAssistantListener(sdkStreamListenerId)
    }
    
    func onAIAssistantEventReceived(_ event: AIAssistantBaseEvent) {
        print("Received AI Event: \(event.type) for Run ID: \(event.id)")
    }
}

Card Streaming Events

When an agent produces a card, it is delivered through three streaming events on onAIAssistantEventReceived. Each event is a subclass of AIAssistantBaseEvent — check the concrete type to handle it.

Event	Accessor	Description
AIAssistantCardStartedEvent	cardId	Identifier for the card being generated.
	executionText	Loading label shown while the card is built.
	streamMessageId	Identifier of the streaming message that owns this card.
AIAssistantCardReceivedEvent	cardId	Identifier matching the corresponding start event.
	getCard()	The complete card payload ([String: Any]?) to render.
AIAssistantCardEndedEvent	cardId	Signals the card stream for this cardId is complete.

Swift

import CometChatSDK

func onAIAssistantEventReceived(_ event: AIAssistantBaseEvent) {
    switch event {
    case let started as AIAssistantCardStartedEvent:
        let cardId = started.cardId
        let label = started.executionText   // e.g. "Building card…"
    case let received as AIAssistantCardReceivedEvent:
        let cardId = received.cardId
        let card = received.getCard()        // full card payload
    case let ended as AIAssistantCardEndedEvent:
        // card stream for ended.cardId is complete
        break
    default:
        break
    }
}

Agentic Messages

After the run completes, these messages arrive via CometChatMessageDelegate:

Message Type	Description
AIAssistantMessage	The full assistant reply
AIToolResultMessage	The final output of a tool call
AIToolArgumentMessage	The arguments passed to a tool

Swift

import CometChatSDK

let listenerId = "unique_listener_id"

class MessageHandler: CometChatMessageDelegate {
    
    // CometChat.addMessageListener(listenerId, self)
    
    func onAIAssistantMessageReceived(_ aiAssistantMessage: AIAssistantMessage) {
        print("AI Assistant Message Received: \(aiAssistantMessage)")
    }
    
    func onAIToolResultMessageReceived(_ aiToolResultMessage: AIToolResultMessage) {
        print("AI Tool Result Message Received: \(aiToolResultMessage)")
    }
    
    func onAIToolArgumentsMessageReceived(_ aiToolArgumentMessage: AIToolArgumentMessage) {
        print("AI Tool Arguments Message Received: \(aiToolArgumentMessage)")
    }
}

Always remove listeners when they’re no longer needed (e.g., on view dismissal). Failing to remove listeners can cause memory leaks and duplicate event handling.

AIAssistantMessage Elements

Once a run completes, the assistant’s reply is persisted as an AIAssistantMessage. Its content is exposed as an ordered list of blocks via getElements(), letting you render text and cards in the exact order the agent produced them. When getElements() is nil or empty, fall back to the plain text body.

Method	Returns	Description
getElements()	[AIAssistantElement]?	Ordered content blocks. nil/empty for plain-text replies.
text	String	Plain-text body (fallback when there are no elements).

Each AIAssistantElement exposes:

Method	Returns	Description
getType()	String	Block type — "text" or "card".
getData()	Any?	The block body (text string, or card payload).

Swift

import CometChatSDK

if let elements = message.getElements(), !elements.isEmpty {
    for element in elements {
        switch element.getType() {
        case "text":
            renderText(String(describing: element.getData() ?? ""))
        case "card":
            renderCard(element.getData())
        default:
            break
        }
    }
} else {
    renderText(message.text)
}

---

Next Steps

AI Chatbots

Set up AI-powered chatbots for automated conversations

AI Moderation

Automatically moderate messages with AI

AI User Copilot

AI-powered features like smart replies and conversation summaries

Send Messages

Send text messages that trigger AI Agent responses