Streaming

How Streaming Works

The SDK has one streaming method. send(_:conversationId:configure:) is an async throws function. It calls your callbacks as text arrives, then returns the finished ChatResponse when the reply is complete.

While it runs: your onTextDelta, onToolCall, and onToolResult callbacks fire.
When it succeeds: it returns a ChatResponse.
When it fails: it throws.

The same call also runs your tools. If the agent asks for a tool, the SDK runs your handler, sends the result back, and continues the reply. See Client-Side Tools.

If you are building a SwiftUI chat screen, you usually do not call send yourself. ConversationState connects these callbacks to a message list for you.

send

public func send(
    _ message: String,
    conversationId: String? = nil,
    configure: @Sendable (inout StreamCallbacks) -> Void = { _ in }
) async throws -> ChatResponse

Sends a message, streams the reply, runs any registered tools, and returns the finished ChatResponse.

String

required

The message to send to the agent.

String?

Continue an existing conversation. nil always starts a new conversation.

@Sendable (inout StreamCallbacks) -> Void

A closure where you set the callbacks you want. Set only the ones you need.

Unlike the Android SDK, passing conversationId: nil does not fall back to currentConversationId. It starts a new conversation. To continue one, pass the ID yourself, or use ConversationState, which keeps track of it.

let response = try await client.send("Tell me a story") { cb in
    cb.onTextDelta = { chunk in
        print(chunk, terminator: "")
    }
    cb.onToolCall = { info in
        print("Agent is calling: \(info.toolName)")
    }
    cb.onToolResult = { info in
        print("Got a result from: \(info.toolName)")
    }
}

print("\nMessage ID: \(response.message.id)")
print("Finish reason: \(response.finishReason)")

StreamCallbacks

public struct StreamCallbacks: Sendable {
    public var onTextDelta: (@Sendable (String) async -> Void)?
    public var onToolCall: (@Sendable (ToolCallInfo) async -> Void)?
    public var onToolResult: (@Sendable (ToolResultInfo) async -> Void)?
}

Callback	When it runs
`onTextDelta`	For each chunk of text as it arrives.
`onToolCall`	When the agent asks for a tool, before your handler runs.
`onToolResult`	When a tool result is ready, whether it came from your handler or from the server.

Callbacks you do not set are ignored. There is no onStart, onFinish, or onError callback. The async throws signature covers all three:

do {
    let response = try await client.send("Hello") { cb in
        cb.onTextDelta = { print($0, terminator: "") }
    }
    // Same as onFinish
    handle(response)
} catch {
    // Same as onError
    show(error)
}

Callbacks do not run on the main thread. Switch to the main actor before touching your UI:

cb.onTextDelta = { @Sendable chunk in
    await MainActor.run { self.text += chunk }
}

The SDK waits for each callback to finish before reading more of the reply, so a slow callback slows the whole stream. Keep them short.

Showing text as it arrives

@MainActor
@Observable
final class ChatViewModel {
    var text = ""
    var isSending = false

    private let client: ChatbaseClient
    private var conversationId: String?

    init(client: ChatbaseClient) { self.client = client }

    func send(_ message: String) async {
        isSending = true
        defer { isSending = false }
        text = ""

        do {
            let response = try await client.send(message, conversationId: conversationId) { cb in
                cb.onTextDelta = { [weak self] chunk in
                    await self?.append(chunk)
                }
            }
            conversationId = response.conversationId
        } catch {
            text = "Something went wrong. Please try again."
        }
    }

    private func append(_ chunk: String) { text += chunk }
}

ChatViewModel is marked @MainActor, so await self?.append(chunk) moves to the main thread for you.

Stopping a Reply

Cancelling the Task around send closes the connection.

var streamTask: Task<Void, Never>?

func start(_ message: String) {
    streamTask = Task {
        do {
            _ = try await client.send(message) { cb in
                cb.onTextDelta = { chunk in await self.append(chunk) }
            }
        } catch is CancellationError {
            // The user stopped it. Keep the text received so far.
        } catch {
            self.show(error)
        }
    }
}

func stop() {
    streamTask?.cancel()
}

Cancelling stops your app from reading the reply. The agent may still finish on the server, and the partial message is saved. The text you already received is still correct, and it will be there when you next call listMessages.

Continuing a Conversation

The client remembers the last conversation in currentConversationId, but you have to pass it back in to continue:

// First message, starts a new conversation
let first = try await client.send("My name is Alice.")
print(first.conversationId) // "conv_abc123"

// Continue it
let second = try await client.send(
    "What is my name?",
    conversationId: first.conversationId
) // The agent remembers: "Alice"

To start fresh, pass nil (the default), or clear the saved ID:

client.newConversation()
_ = try await client.send("Fresh start!")

See Conversations & History for listing conversations and loading old messages, and SwiftUI for state that tracks the conversation ID for you.

retry

public func retry(
    conversationId: String,
    messageId: String,
    configure: @Sendable (inout StreamCallbacks) -> Void = { _ in }
) async throws -> ChatResponse

Ask the agent to answer again. Streams and runs tools exactly like send.

String

required

The conversation the message belongs to.

String

required

The ID of the agent message to redo.

@Sendable (inout StreamCallbacks) -> Void

The same callbacks as send.

let response = try await client.send("Hello")

// Later, from a "Regenerate" button:
let retried = try await client.retry(
    conversationId: response.conversationId,
    messageId: response.message.id
) { cb in
    cb.onTextDelta = { print($0, terminator: "") }
}

The old message and everything after it are replaced. Remove those messages from your UI before the new reply starts. ConversationState.retry(messageId:) does this for you.

sendNonStreaming

public func sendNonStreaming(
    _ message: String,
    conversationId: String? = nil
) async throws -> ChatResponse

Sends a message and returns the whole reply at once. No callbacks, and no tools.

String

required

The message to send to the agent.

String?

Continue an existing conversation. nil starts a new one.

let response = try await client.sendNonStreaming("Summarize my last order")
print(response.message.text)
print(response.finishReason)  // .stop, .error, or .toolCalls
print(response.usage.credits)

Your registered tools do not run. If the agent asks for a tool, you get back finishReason == .toolCalls and no answer. Use send for any agent that has client-side Custom Actions.

Use sendNonStreaming when you do not need to show text as it arrives, such as a background summary or a scripted first message.

Which Method to Use

	`send`	`retry`	`sendNonStreaming`
Streams text	Yes	Yes	No
Runs your tools	Yes	Yes	No
Callbacks	Yes	Yes	No
Starts a new conversation	When `conversationId` is `nil`	Never	When `conversationId` is `nil`
Returns	`ChatResponse`	`ChatResponse`	`ChatResponse`

Client-Side Tools

Let the agent run functions on the device

Streaming Types

StreamCallbacks, ToolCallInfo, and more

ChatResponse

What a finished reply contains

Error Handling

Error types and how to handle them

Getting Started

Reference

How Streaming Works

send

StreamCallbacks

Showing text as it arrives

Stopping a Reply

Continuing a Conversation

retry

sendNonStreaming

Which Method to Use

Client-Side Tools

Streaming Types

ChatResponse

Error Handling

​How Streaming Works

​send

​StreamCallbacks

​Showing text as it arrives

​Stopping a Reply

​Continuing a Conversation

​retry

​sendNonStreaming

​Which Method to Use

​Related

Client-Side Tools

Streaming Types

ChatResponse

Error Handling

How Streaming Works

send

StreamCallbacks

Showing text as it arrives

Stopping a Reply

Continuing a Conversation

retry

sendNonStreaming

Which Method to Use

Related