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

# AI Agents

> Guide to integrating AI Agents for intelligent automated interactions using the CometChat iOS SDK.

<Info>
  **Quick Reference for AI Agents & Developers**

  * **Send to agent:** Send text message to agent's UID like any other user
  * **Agent responses:** Received via message listener as regular messages
  * **Run events:** Real-time events during agent processing via `onAgentRunStarted`, `onAgentRunCompleted`
  * **Note:** Agents currently only respond to text messages
  * **Related:** [AI Agents Overview](/ai-agents) · [Send Message](/sdk/ios/send-message) · [Receive Message](/sdk/ios/receive-message)
</Info>

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

## 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")
        // Agent will process and respond via listeners
    } onError: { error in
        print("Error: \(error?.errorDescription)")
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Sample Payload - Send Message to AI Agent">
  **Request Parameters:**

  | Parameter    | Type         | Description                                                                |
  | ------------ | ------------ | -------------------------------------------------------------------------- |
  | agentUID     | String       | Unique identifier of the AI agent. Example: `"ai-agent-uid"`               |
  | text         | String       | Message content to send. Example: `"Hello AI Agent, how can you help me?"` |
  | receiverType | ReceiverType | Type of receiver. Example: `.user`                                         |

  **Success Response (TextMessage Object):**

  | Parameter   | Type    | Description                                     |
  | ----------- | ------- | ----------------------------------------------- |
  | id          | Int     | Unique message identifier. Example: `38255`     |
  | muid        | String? | Message unique ID. Example: `nil`               |
  | senderUid   | String? | UID of the sender. Example: `"cometchat-uid-2"` |
  | receiverUid | String? | UID of the agent. Example: `"ai-agent-uid"`     |

  **Next Steps:**

  | Event Source              | Description                                                                            |
  | ------------------------- | -------------------------------------------------------------------------------------- |
  | AIAssistantEventsDelegate | Real-time streaming events via `onAIAssistantEventReceived`                            |
  | CometChatMessageDelegate  | Persisted messages via `onAIAssistantMessageReceived`, `onAIToolResultMessageReceived` |
</Accordion>

## 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 **`AIAssistantEventsDelegate`**.
* After the run completes, persisted Agentic Messages arrive via the **`CometChatMessageDelegate`**.

### Real-time Events

Events are received via the **`onAIAssistantEventReceived`** method of the **`AIAssistantEventsDelegate`** protocol 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.

```swift theme={null}
import CometChatSDK

class AIAssistantEventHandler: AIAssistantEventsDelegate {
    
    private let sdkStreamListenerId = "unique_listener_id"
    
    /// Call this to start listening to AI Assistant events
    func addListener() {
        CometChat.addAIAssistantListener(sdkStreamListenerId, self)
        print("AIAssistantListener added successfully.")
    }
    
    /// Call this to remove the AI Assistant listener
    func removeListener() {
        CometChat.removeAIAssistantListener(sdkStreamListenerId)
        print("AIAssistantListener removed successfully.")
    }
    
    func onAIAssistantEventReceived(_ event: AIAssistantBaseEvent) {
        print("Received AI Event: \(event.type) for Run ID: \(event.id)")
    }
}
```

<Accordion title="Sample Payload - AIAssistantBaseEvent Properties">
  **Event Object (AIAssistantBaseEvent):**

  | Parameter | Type   | Description                                                             |
  | --------- | ------ | ----------------------------------------------------------------------- |
  | type      | String | Event type identifier. Example: `"run_start"`, `"text_message_content"` |
  | id        | String | Run ID for the event. Example: `"run_abc123"`                           |

  **Event Types:**

  | Type                   | Description                                       |
  | ---------------------- | ------------------------------------------------- |
  | `run_start`            | New run has begun for the user's message          |
  | `tool_call_start`      | 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`   | Agent started composing a reply                   |
  | `text_message_content` | Streaming content chunk for progressive rendering |
  | `text_message_end`     | Agent reply is complete                           |
  | `run_finished`         | Run is finalized; persisted messages will follow  |
</Accordion>

<Accordion title="Sample Payload - AI Agent Event Sequence">
  **1. Run Start Event:**

  | Parameter | Type   | Description                             |
  | --------- | ------ | --------------------------------------- |
  | type      | String | Event type. Example: `"run_start"`      |
  | id        | String | Run identifier. Example: `"run_abc123"` |

  **2. Tool Call Start Event (if agent uses tools):**

  | Parameter | Type   | Description                                                 |
  | --------- | ------ | ----------------------------------------------------------- |
  | type      | String | Event type. Example: `"tool_call_start"`                    |
  | id        | String | Run identifier. Example: `"run_abc123"`                     |
  | toolName  | String | Name of the tool being invoked. Example: `"weather_lookup"` |

  **3. Tool Call Result Event:**

  | Parameter | Type   | Description                               |
  | --------- | ------ | ----------------------------------------- |
  | type      | String | Event type. Example: `"tool_call_result"` |
  | id        | String | Run identifier. Example: `"run_abc123"`   |
  | result    | String | Tool output. Example: `"72°F, Sunny"`     |

  **4. Text Message Content Event (streaming):**

  | Parameter | Type   | Description                                                 |
  | --------- | ------ | ----------------------------------------------------------- |
  | type      | String | Event type. Example: `"text_message_content"`               |
  | id        | String | Run identifier. Example: `"run_abc123"`                     |
  | content   | String | Streaming content chunk. Example: `"The weather today is "` |

  **5. Run Finished Event:**

  | Parameter | Type   | Description                             |
  | --------- | ------ | --------------------------------------- |
  | type      | String | Event type. Example: `"run_finished"`   |
  | id        | String | Run identifier. Example: `"run_abc123"` |
</Accordion>

#### 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 **`CometChatMessageDelegate`** 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.

```swift theme={null}
import CometChatSDK

let listenerId = "unique_listener_id"

class MessageHandler: CometChatMessageDelegate {
    
    // Adding the MessageListener
    // 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)")
    }
}
```

<Accordion title="Sample Payload - AIAssistantMessage">
  **Event Trigger:** Received via `CometChatMessageDelegate.onAIAssistantMessageReceived(_:)`

  **AIAssistantMessage Object:**

  | Parameter | Type   | Description                                                             |
  | --------- | ------ | ----------------------------------------------------------------------- |
  | type      | String | Message type. Example: `"ai_assistant_message"`                         |
  | id        | Int    | Unique message identifier. Example: `12347`                             |
  | senderUid | String | UID of the AI agent. Example: `"ai-agent-uid"`                          |
  | text      | String | Full assistant reply. Example: `"The weather today is 72°F and sunny!"` |
</Accordion>

<Accordion title="Sample Payload - AIToolResultMessage">
  **Event Trigger:** Received via `CometChatMessageDelegate.onAIToolResultMessageReceived(_:)`

  **AIToolResultMessage Object:**

  | Parameter | Type   | Description                                                   |
  | --------- | ------ | ------------------------------------------------------------- |
  | type      | String | Message type. Example: `"ai_tool_result_message"`             |
  | id        | Int    | Unique message identifier. Example: `12348`                   |
  | toolName  | String | Name of the tool that was called. Example: `"weather_lookup"` |
  | result    | String | Final output of the tool call. Example: `"72°F, Sunny"`       |
</Accordion>

<Accordion title="Sample Payload - AIToolArgumentMessage">
  **Event Trigger:** Received via `CometChatMessageDelegate.onAIToolArgumentsMessageReceived(_:)`

  **AIToolArgumentMessage Object:**

  | Parameter | Type           | Description                                                            |
  | --------- | -------------- | ---------------------------------------------------------------------- |
  | type      | String         | Message type. Example: `"ai_tool_argument_message"`                    |
  | id        | Int            | Unique message identifier. Example: `12349`                            |
  | toolName  | String         | Name of the tool that was called. Example: `"weather_lookup"`          |
  | arguments | \[String: Any] | Arguments passed to the tool. Example: `{"location": "San Francisco"}` |
</Accordion>