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

# AI Agents

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

<Accordion title="AI Integration Quick Reference">
  | Feature | Description |
  | - | - |
  | [AI Agents](#agent-run-lifecycle-and-message-flow) | Intelligent automated conversations with real-time streaming |
  | [AI Moderation](/sdk/ios/ai-moderation) | Automatic content moderation with pending/approved/disapproved flow |
  | [AI User Copilot](/fundamentals/ai-user-copilot/overview) | Smart Replies, Conversation Starter, Conversation Summary (Dashboard-enabled) |

  ```swift theme={null}
  // 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](https://app.cometchat.com)
  **Event flow:** Run Start -> Tool Call(s) -> Text Message Stream -> Run Finished
</Accordion>

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

<Note>
  Agents only respond to text messages.
</Note>

## Sending a Message to an AI Agent

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

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

## 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`](/sdk/reference/messages#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 |

<Note>
  `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.
</Note>

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

#### 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`](/sdk/reference/messages#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. |

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    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
        }
    }
    ```
  </Tab>
</Tabs>

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

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

<Warning>
  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.
</Warning>

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

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

***

## Next Steps

<CardGroup cols={2}>
  <Card title="AI Chatbots" icon="robot" href="https://assets.cometchat.io/legacy-docs/ai-chatbots/ai-bots/overview.html">
    Set up AI-powered chatbots for automated conversations
  </Card>

  <Card title="AI Moderation" icon="shield-check" href="/sdk/ios/ai-moderation">
    Automatically moderate messages with AI
  </Card>

  <Card title="AI User Copilot" icon="wand-magic-sparkles" href="/sdk/ios/ai-user-copilot-overview">
    AI-powered features like smart replies and conversation summaries
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/ios/send-message">
    Send text messages that trigger AI Agent responses
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.