Streaming

Two-Tier Streaming API

The SDK provides two levels of abstraction for streaming:

sendMessage() — High-level API with a callback DSL. Handles tool calls automatically (up to 10 iterations). Recommended for most use cases.
sendMessageStream() — Low-level API returning a Flow<ChatStreamEvent>. Tool calls are not handled automatically, giving you full control over event processing.

sendMessage

interface ChatbaseClient — Package: com.chatbase.sdk

suspend fun sendMessage(
    message: String,
    conversationId: String? = null,
    callbacks: StreamCallbacks.() -> Unit = {}
): ChatResponse

Sends a message, streams the response in real time, and automatically handles tool calls (up to 10 iterations). Returns the aggregated ChatResponse when the stream completes.

String

required

The user message to send to the agent.

String?

Continue an existing conversation. Omit to use currentConversationId or start a new one.

StreamCallbacks.() -> Unit

Streaming callback DSL.

val response = client.sendMessage("Tell me a story") {
    onStart {
        println("Stream started...")
    }
    onTextDelta { delta ->
        // Called for each text chunk — append to your UI
        print(delta)
    }
    onToolCall { toolCall ->
        println("Agent is calling: ${toolCall.toolName}")
    }
    onToolResult { result ->
        println("Tool result: ${result.outputAsString()}")
    }
    onFinish { response ->
        println("\nDone! Message ID: ${response.id}")
    }
    onError { error ->
        println("Error: ${error.message}")
    }
}

StreamCallbacks

class StreamCallbacks — Package: com.chatbase.sdk

All callbacks are invoked on Dispatchers.Main — it is safe to update UI directly from any callback without explicit dispatching.

fun onStart(handler: () -> Unit)

Called when the connection opens and streaming begins.

fun onTextDelta(handler: (text: String) -> Unit)

Called for each incremental text chunk received.

fun onToolCall(handler: (toolCall: ToolCallInfo) -> Unit)

Called when a tool call’s full input is available (before execution).

fun onToolResult(handler: (result: ToolResultInfo) -> Unit)

Called after a tool handler executes and returns a result.

fun onFinish(handler: (response: ChatResponse) -> Unit)

Called when the stream completes successfully.

fun onError(handler: (error: ChatbaseException) -> Unit)

Called when an error occurs during streaming.

ChatResponse

data class ChatResponse — Package: com.chatbase.sdk.model The aggregated result after streaming completes.

String

required

Server-assigned message ID.

String

required

Always "assistant".

List<Part>

required

The response content — text, tool calls, and tool results. See ChatResponse.

ResponseMetadata

required

Show properties

String?

Same as ChatResponse.id.

String?

Server-assigned ID for the user’s message.

String?

The conversation ID. Pass this to continue the conversation.

FinishReason

Why the stream ended: STOP, ERROR, TOOL_CALLS, or UNKNOWN.

Usage?

Show properties

Double

Credits consumed by this request.

sendMessageStream

fun sendMessageStream(
    message: String,
    conversationId: String? = null
): Flow<ChatStreamEvent>

Returns a cold Flow of raw streaming events. Tool calls are not handled in Flow mode — registered tool handlers are not invoked, and the SDK exposes no API for submitting tool results manually.

String

required

The user message to send to the agent.

String?

Continue an existing conversation. Omit to use currentConversationId or start a new one.

Tool calls are not executed in Flow mode — tool events are informational only, and the stream finishes with finishReason == "tool-calls" without a final answer. If your agent uses client-side tools, use sendMessage with callbacks instead. See Client-Side Tools for details.

client.sendMessageStream("Tell me about Kotlin").collect { event ->
    when (event) {
        is ChatStreamEvent.TextDelta -> print(event.delta)
        is ChatStreamEvent.Finish -> println("\nDone: ${event.finishReason}")
        is ChatStreamEvent.Error -> println("Error: ${event.exception.message}")
        else -> { /* handle other events as needed */ }
    }
}

You can also filter for specific event types:

client.sendMessageStream("Hello")
    .filterIsInstance<ChatStreamEvent.TextDelta>()
    .collect { event -> print(event.delta) }

Stream Events

The Flow returned by sendMessageStream emits ChatStreamEvent objects — text deltas, tool input/output, step lifecycle, and errors. See Streaming Events for the full type reference.

Continuing a Conversation

The SDK automatically tracks the current conversation. After sending a message, subsequent calls reuse the same conversation:

// First message — starts a new conversation
client.sendMessage("My name is Alice.")
println(client.currentConversationId) // "conv_abc123"

// Subsequent messages continue the same conversation
client.sendMessage("What is my name?") // Agent remembers: "Alice"

To start a fresh conversation:

client.newConversation()
client.sendMessage("Fresh start!") // Creates a new conversation

See Conversations & History for listing conversations and loading message history.

retry

suspend fun retry(
    conversationId: String,
    messageId: String,
    callbacks: StreamCallbacks.() -> Unit = {}
): ChatResponse

Retry a failed assistant message. Same streaming and tool-loop behavior as sendMessage.

String

required

The conversation containing the failed message.

String

required

The ID of the assistant message to retry.

StreamCallbacks.() -> Unit

Streaming callback DSL.

A convenience extension extracts the IDs from a ChatResponse:

suspend fun ChatbaseClient.retry(
    response: ChatResponse,
    callbacks: StreamCallbacks.() -> Unit = {}
): ChatResponse

val response = client.sendMessage("Hello")
// ... later:
val retried = client.retry(response) {
    onTextDelta { delta -> print(delta) }
}

retryStream

fun retryStream(
    conversationId: String,
    messageId: String
): Flow<ChatStreamEvent>

Raw streaming variant of retry. Tool calls are not handled automatically.

client.retryStream(conversationId, messageId).collect { event ->
    when (event) {
        is ChatStreamEvent.TextDelta -> print(event.delta)
        is ChatStreamEvent.Finish -> println("\nDone")
        is ChatStreamEvent.Error -> println("Error: ${event.exception.message}")
        else -> {}
    }
}

Client-Side Tools

Error Handling

Exception hierarchy and error handling patterns

Getting Started

Reference

Two-Tier Streaming API

sendMessage

StreamCallbacks

ChatResponse

sendMessageStream

Stream Events

Continuing a Conversation

retry

retryStream

Client-Side Tools

Error Handling

​Two-Tier Streaming API

​sendMessage

​StreamCallbacks

​ChatResponse

​sendMessageStream

​Stream Events

​Continuing a Conversation

​retry

​retryStream

​Related

Client-Side Tools

Error Handling

Two-Tier Streaming API

sendMessage

StreamCallbacks

ChatResponse

sendMessageStream

Stream Events

Continuing a Conversation

retry

retryStream

Related