AI SDK Kotlin/ai.torad.aisdk.ui/UIMessagePart/ToolUI

ToolUI

@SerialName(value = "tool")

class ToolUI(val toolCallId: String, val toolName: String, val state: ToolCallState, val input: JsonElement? = null, val output: JsonElement? = null, val error: String? = null, val preliminary: Boolean = false, val approvalId: String? = null, val signature: String? = null, val providerMetadata: ProviderMetadata = ProviderMetadata.None) : UIMessagePart(source)

One tool call's full lifecycle in the UI. State progresses InputStreaming → InputAvailable → OutputAvailable (or Error, or ApprovalRequired when the loop is paused on user decision). Component renderers can show the same card across states ("Looking up lineup..." → "Found 12 sets" → final card).

Per v6 naming: this is the equivalent of part.type === 'tool-X' in TypeScript. We discriminate on toolName string at the render site since Kotlin lacks TypeScript's literal-type narrowing.

Constructors

ToolUI

constructor(toolCallId: String, toolName: String, state: ToolCallState, input: JsonElement? = null, output: JsonElement? = null, error: String? = null, preliminary: Boolean = false, approvalId: String? = null, signature: String? = null, providerMetadata: ProviderMetadata = ProviderMetadata.None)

Properties

approvalId

val approvalId: String?

Approval identity for ApprovalRequested/ApprovalResponded states — carried so a UI round-trip (convert to model messages, resume) preserves the approval's correlation key. Null outside the approval states. Mirrors v6's approval.id.

error

val error: String?

input

val input: JsonElement?

output

val output: JsonElement?

preliminary

val preliminary: Boolean

True when output is an intermediate snapshot from a streamingTool executor and a final value is still pending. False (default) for one-shot tool outputs and for the final emission from a streaming tool. UI uses this to show a "loading more" indicator on a still-incomplete card without collapsing back to InputAvailable. Mirrors v6's preliminary?: boolean on output-available.

providerMetadata

@EncodeDefault(mode = EncodeDefault.Mode.NEVER)

val providerMetadata: ProviderMetadata

signature

val signature: String?

HMAC-SHA256 approval signature (v6.0.202, approval.signature). Must survive the UI round-trip untouched: with a configured approval secret, a replay missing it is denied fail-closed.

state

val state: ToolCallState

toolCallId

val toolCallId: String

toolName

val toolName: String

Functions

inputAs

inline fun <TInput> inputAs(): TInput?

fun <TInput> inputAs(serializer: KSerializer<TInput>): TInput?

Type-safe extraction of input args while the tool is mid-flight or complete. Returns null if input isn't yet available.

outputAs

inline fun <TOutput> outputAs(): TOutput?

fun <TOutput> outputAs(serializer: KSerializer<TOutput>): TOutput?

Type-safe extraction of output. Returns null if state isn't OutputAvailable (caller should branch on state first).