AI Agents

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

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 · Send Message · Receive Message

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.

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

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

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.

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

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

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"

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.

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

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!"

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"

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"}