Streaming Types

StreamCallbacks

struct StreamCallbacks: Sendable The callbacks you pass to send(_:conversationId:configure:) and retry(conversationId:messageId:configure:).

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)?

    public init()
}

(@Sendable (String) async -> Void)?

Runs for each chunk of text. Add it to the current bubble.

(@Sendable (ToolCallInfo) async -> Void)?

Runs when the agent asks for a tool, before your handler runs.

(@Sendable (ToolResultInfo) async -> Void)?

Runs when a tool result is ready, whether it came from your handler or from the server.

Callbacks you do not set are ignored:

let response = try await client.send("Hello") { cb in
    cb.onTextDelta = { chunk in await self.append(chunk) }
    // onToolCall and onToolResult not set
}

There is no onStart, onFinish, or onError callback. The async throws signature covers all three: the call returns a ChatResponse when it works and throws when it does not. See Streaming.

Callbacks do not run on the main thread. Use await MainActor.run { ... }, or call into a @MainActor type, before touching your UI. The SDK waits for each callback before reading more of the reply, so keep them quick.

ToolCallInfo

struct ToolCallInfo: Sendable Passed to onToolCall.

public struct ToolCallInfo: Sendable {
    public let toolCallId: String
    public let toolName: String
    public let input: JSONValue
}

String

required

An ID for this tool call. Use it to match this call with its ToolResultInfo.

String

required

The tool’s name, which matches the Custom Action on your agent.

JSONValue

required

Everything the agent passed to the tool. See JSONValue.

cb.onToolCall = { info in
    let city = info.input["city"]?.stringValue
    await self.showToolCard(id: info.toolCallId, name: info.toolName, city: city)
}

ToolResultInfo

struct ToolResultInfo: Sendable Passed to onToolResult.

public struct ToolResultInfo: Sendable {
    public let toolCallId: String
    public let toolName: String
    public let output: JSONValue
}

String

required

Matches the toolCallId on the ToolCallInfo it belongs to.

String

required

The tool’s name.

JSONValue

required

What the tool returned. An object with an error key means it failed. See JSONValue.

cb.onToolResult = { info in
    let failed = info.output["error"] != nil
    await self.completeToolCard(id: info.toolCallId, failed: failed)
}

Both callbacks also run for tools the server handles, not just your own, so one piece of UI can show every tool the agent uses.

ToolHandler

public typealias ToolHandler = @Sendable (JSONValue) async throws -> JSONValue

The shape of a tool handler you register with client.tool(_:handler:). See Client-Side Tools.

Lower-Level Types

The types below are the pieces a reply is made of. The SDK handles them for you and gives you the results through StreamCallbacks and ChatResponse, so you do not work with them directly. They are public so you can read what a reply contains and name the types in your own code.

There is no way to read these events as they arrive. ChatbaseClient has no Combine publisher and no AsyncSequence, so there is no equivalent of Android’s sendMessageStream. Use send with callbacks. If the callbacks do not give you what you need, contact support.

StreamEvent

public enum StreamEvent: Sendable {
    case messageStarted(id: String)
    case textChunk(String)
    case toolCall(ToolCall)
    case toolOutput(toolCallId: String, output: JSONValue)
    case finished(StreamFinishInfo)
}

Case	What it means
`.messageStarted(id:)`	The server created the agent’s message.
`.textChunk(String)`	A chunk of text. You get this as `onTextDelta`.
`.toolCall(ToolCall)`	The agent asked for a tool and sent everything it needs.
`.toolOutput(toolCallId:output:)`	The server finished a tool.
`.finished(StreamFinishInfo)`	The reply is done and the details are final.

ToolCall

public struct ToolCall: Sendable {
    public let toolCallId: String
    public let toolName: String
    public let input: JSONValue
}

The raw tool call inside .toolCall. ToolCallInfo is the version you get in callbacks.

StreamFinishInfo

The details that arrive when a reply ends. Everything is optional, since the server may leave any of it out.

public struct StreamFinishInfo: Sendable {
    public let conversationId: String?
    public let messageId: String?
    public let userMessageId: String?
    public let userId: String?
    public let finishReason: FinishReason?
    public let usage: Usage?
}

String?

The conversation this reply belongs to. On a new conversation, this is where the ID first arrives.

String?

The agent’s final message ID.

String?

The server’s ID for the user’s message.

String?

Who the reply belongs to. This fills in client.currentUserId.

FinishReason?

See FinishReason. Treated as .stop when missing.

Usage?

Credits used. Treated as 0 when missing.

These become the matching fields on the ChatResponse that send returns.

Anything in a reply that the SDK does not recognize is skipped rather than treated as an error, so a shipped app keeps working as Chatbase adds new capabilities. A reply that cannot be read at all ends with ChatError.decodingFailed.

Streaming

Using the callbacks in practice

Client-Side Tools

Registering tools the agent can run

ChatResponse

What a finished reply contains

JSONValue

Reading tool data

Getting Started

Reference

StreamCallbacks

ToolCallInfo

ToolResultInfo

ToolHandler

Lower-Level Types

StreamEvent

ToolCall

StreamFinishInfo

Streaming

Client-Side Tools

ChatResponse

JSONValue

​StreamCallbacks

​ToolCallInfo

​ToolResultInfo

​ToolHandler

​Lower-Level Types

​StreamEvent

​ToolCall

​StreamFinishInfo

​Related

Streaming

Client-Side Tools

ChatResponse

JSONValue

StreamCallbacks

ToolCallInfo

ToolResultInfo

ToolHandler

Lower-Level Types

StreamEvent

ToolCall

StreamFinishInfo

Related