Reasoning and Tool Calls

Before an agent answers, it often reasons, and it may call tools: search the web, look up an order, or ask the user's device for their location. StreamChatAI shows these steps in the reply, in the order they happened, with the final answer after them.

An agent describes each step as a custom attachment on its reply message:

• ai_reasoning - a round of the model's reasoning.
• ai_tool_call - a tool the agent called, run by the agent's backend or by a user's device.

The order of the attachments is the order of the steps, and the final answer stays in the message text. The agent's backend adds the steps to the reply's attachments and updates them as it works, with the same message updates that stream the text.

Show the steps of a reply

AIMessagePart decodes the steps among a message's attachments, skipping attachments that aren't AI steps, such as images. AIMessagePartsView shows them in order. Render it before the reply's text:

let parts = AIMessagePart.parts(
    from: message.allAttachments.map { ($0.type.rawValue, $0.payload) }
)

VStack(alignment: .leading) {
    AIMessagePartsView(parts: parts)
    StreamingMessageView(content: message.text, isGenerating: isGenerating)
}

Each step shows through AIMessagePartView: a round of reasoning as a StreamingReasoningView, a tool call as an AIToolCallView, and a neutral placeholder ("A step this app version can't show") for a kind of step it doesn't know. The SwiftUI integration shows where to render it in the Chat SDK's message list.

Steps are an open set

New kinds of steps can appear without breaking your code. A part's kind is a string-backed value (.reasoning, .toolCall, or any other ai_ attachment type), and the kinds the SDK reads have typed views, part.reasoning and part.toolCall. Anything else keeps its JSON payload, which you can read with part.decode(_:). Statuses and executors are open in the same way, so switch over them with a default.

Decoding is lenient: missing fields get defaults, a field of the wrong type reads as missing, and a step in a newer format version (v) keeps its payload but has no typed view. Each step has a stable id (a tool call uses the model provider's tool-call ID), so the list updates smoothly while it streams.

To show some steps your own way, such as reasoning your backend streams in full, or a kind of step of your own, render each part yourself and fall back to AIMessagePartView for the rest:

AIMessagePartsView(parts: parts) { part in
    if let reasoning = part.reasoning {
        StreamingReasoningView(part: reasoning, text: fullReasoning[reasoning.id])
    } else if part.kind == "ai_citation", let citation = try? part.decode(Citation.self) {
        CitationView(citation: citation)
    } else {
        AIMessagePartView(part: part)
    }
}

Reasoning

A round of reasoning carries a capped preview of the model's thoughts (the latest ones while it streams, the opening once it's done) and a one-line summary. AIMessagePartView shows it with StreamingReasoningView: while the model thinks, the reasoning streams into an open panel under a "Thinking... 7s" header, and once it's done, the view folds into "Thought for 12s" and the summary. Tapping the header opens or closes the reasoning.

You can also use StreamingReasoningView on its own, with reasoning you get some other way, for example streamed from your backend:

StreamingReasoningView(
    text: reasoning,
    isThinking: answer.isEmpty,
    duration: thinkingDuration
)

Reasoning can run to tens of kilobytes and grow many times a second, so the view only lays out what changes: it renders one paragraph at a time, lazily, so only the paragraph still being written is laid out again. Blank lines separate paragraphs, and inline Markdown (bold, italics, code and links) is rendered.

Once the reader opens or closes the reasoning themselves, the view keeps their choice. StreamingReasoningView.foldAnimation is the animation the view folds and opens with: use it for your own changes that should move along with it. StreamingReasoningView.foldDuration is how long the fold takes, so a reply that shows its answer only after it lets the reasoning fold first, rather than the two moving against each other.

Tool calls

AIToolCallView shows a single tool call: what it's doing (its display_title, such as "Checking your location", or else its name), its outcome (summary), and its duration once it's finished. Its icon follows the status: a spinner while it runs, a hand while it waits for approval, a phone while it waits for the user's device, and a checkmark, an exclamation mark or a cross once it completed, failed or was cancelled.

if let call = part.toolCall {
    AIToolCallView(part: call)
}

When the agent asks a user's device to run a tool, AIClientToolRunner runs it there and sends the result back, as described in Client Side Tools.

Tool approvals

Some tool calls should wait for the user: the agent wants their location, or to send an email on their behalf. The agent's backend writes such a call with status awaiting_approval, addresses it to that user (target_user_id, and target_client_id for a client tool), and adds the question as its approval:

{
  "type": "ai_tool_call",
  "id": "toolu_01A",
  "name": "get_location",
  "status": "awaiting_approval",
  "executor": "client",
  "target_user_id": "u_123",
  "target_client_id": "ios-7F3A",
  "approval": {
    "title": "Share your location?",
    "message": "Only your city is shared.",
    "reason": "to check the local weather",
    "allow_title": "Share location",
    "decline_title": "Don't share"
  }
}

AIToolApprovalView asks the question under the call. It shows only to that user, on the install the call names (or on any of their devices, for a server tool), and only while the call waits. Give it an AIToolApprover, which says who is signed in on this device and sends their answer to your backend:

let approver = AIToolApprover(
    userID: currentUserID,
    clientID: AIClientIdentity.installID
) { call, allowed in
    try await backend.answer(call, allowed: allowed)
}

AIToolCallView(part: call)
AIToolApprovalView(call: call, approver: approver)

Passing the approver to AIMessagePartsView(parts: parts, approver: approver) does this for every tool call of the reply. While the answer is on its way, the buttons are disabled. If decide throws, the user can answer again.

Your backend holds the call until it gets the answer, and accepts one only from the targeted user (and install, for a client tool), only while the call waits, and only once. It then updates the step:

• Allowed: approval.decision becomes allowed and the call goes on. A client tool's call moves to awaiting_client, so the device's AIClientToolRunner runs it.
• Declined: the call becomes cancelled, with approval.decision set to declined, and never runs. isDeclined tells it apart from other cancelled calls, and AIToolCallView shows it as "Declined".

The question is visible to every channel member, so keep private data out of it.

To ask in your own design, pass the content. It gets the question, where the answer is, and a closure that answers:

AIToolApprovalView(call: call, approver: approver) { approval, state, decide in
    MyApprovalCard(
        title: approval.title,
        isBusy: state.isSending,
        onAllow: { decide(true) },
        onDecline: { decide(false) }
    )
}

AIToolApprovalCard is the default design.

Step format

The steps are custom attachments, with their fields at the top level of the attachment. Every step has:

A round of reasoning (ai_reasoning) also has:

A tool call (ai_tool_call) also has:

Every channel member can see the steps, their arguments and their summaries, so keep private data out of them.

Appearance

The colors of the steps are part of AIAppearance.colors: reasoningTitle, reasoningText, reasoningFootnote, reasoningShimmer and reasoningRule for the reasoning, toolCallTitle, toolCallDetail, toolCallAccent, toolCallSuccess and toolCallFailure for tool calls, and toolApprovalTitle, toolApprovalMessage, toolApprovalBackground, toolApprovalBorder, toolApprovalAccent and toolApprovalFailure for the approval card.

Their fonts are part of AIAppearance.fonts: messagePart for the steps themselves, reasoningFootnote, toolCallDetail, and toolApprovalMessage and toolApprovalFailure for the approval card. Their icons are part of AIAppearance.images, and their texts, such as "Waiting for approval" or the default "Allow" and "Don't Allow" buttons, go through AIAppearance.localizationProvider. See Customizing the appearance.