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:

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

​AI Agents Overview

​Sending a Message to an AI Agent

​Agent Run Lifecycle and Message Flow

​Real-time Events

​Event descriptions