Agent

[crisp phoenix]

What does saveStreamDelta do and why enabling it?

    const result = await agent.streamText(
      ctx,
      { threadId },
      {
        promptMessageId,
        experimental_transform: smoothStream({ chunking: 'word' }),
      }
      // more custom delta options (`true` uses defaults)
      // { saveStreamDeltas: true }
    );

[rare robin]

Hi @crisp phoenix. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

The option saveStreamDeltas in the Convex Agent's streamText method enables the saving of streamed response chunks (deltas) to the database as they are generated.

What does it do?

• When you set { saveStreamDeltas: true }, each chunk of the streaming response (for example, each word or line, depending on your chunking configuration) is persisted in the database as it is produced.
• This allows all clients subscribed to the relevant thread or message to receive live updates as the text is streamed, not just the client that initiated the request.
• The deltas are saved in a way that supports real-time, collaborative, and resilient chat or agent experiences—if a user refreshes the page or another user joins, they can see the current state of the stream.

Why enable it?

• Realtime collaboration: All clients can subscribe to the stream and see live-updating text, not just the original requester.
• Persistence: The streamed content is not lost if the client disconnects or reloads; it is stored in the database and can be resumed or replayed.
• Efficiency: The system debounces and chunks the deltas to avoid excessive bandwidth and database writes, and you can customize the granularity (e.g., by word, line, or custom function) and throttle interval.

Example usage:

const { thread } = await agent.continueThread(ctx, { threadId });
const result = await thread.streamText(
  { promptMessageId, experimental_transform: smoothStream({ chunking: 'word' }) },
  { saveStreamDeltas: true }
);
await result.consumeStream();

You can further customize chunking and throttling:

{ saveStreamDeltas: { chunking: "line", throttleMs: 1000 } }

• chunking: "word", "line", regex, or custom function.
• throttleMs: Minimum interval between saves.

Summary:
Enabling saveStreamDeltas is recommended when you want persistent, real-time streaming updates for all clients, not just the one making the request. It is especially useful for collaborative or resilient chat/agent applications built with Convex Agents > Messages > Streaming.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@crisp phoenix Kapa.ai is still learning and improving, please let me know how I did by reacting below.