One-off vs Stream

One-off messages

A one-off message is a standard message that you can send entirely as you would do when you're chatting with a friend and hit send .

The entire message will be sent at once.

One-off messages are great for small content that you know in advance.3

For example, in our Ping-Pong recipe, we answer "pong" using a one-off message every time the user says "ping".

Streamed messages

Streamed messages are different from one-off messages.

When you send a streamed message, the user immediately sees a message box popping up.

However, every time you send a new stream on the same channel, it will aggregate to the same message box.

You can think of them as having this "typewriter" look and feel as you could have for example in ChatGPT.

Sending a stream works in 3 steps:

🔵 Open a stream channel using the createStream() method

const channel = agent.createStream(conversationId)

Note that starting from v0.0.51 openeing a stream triggers an event that will displays a smooth animation in the frontend (see Typewriter animation)

🔵 Write content to the stream as many times as you want

channel.write("this")
channel.write("is")
channel.write("a")
channel.write("streamed")
channel.write("message")

🔵 When you're done, close the channel

channel.streamEnd()

Et voilà 🎉 Here's an example of how a streamed response looks

Example streamed message with code execution

Which one to choose?

It's pretty rare to hesitate between both, but if you're in that situation, here's a quick recap that might help.

Solution	Info	Warning
One-off	✅ great when you know the content of the message upfront ✅ suited when you need to inform the user quickly about something	❌Generally not suited to send multiple messages in a row
Stream	✅ feel more natural / human-friendly ✅ suited for long-running tasks in the background	❌Be careful with very very long answers because it can become borring for the user to wait, especially if you know the whole response upfront.

Indeed, you have to test each solution on your own to make sure you decide which one is best suited to your specific use case. In general, you want to use a mix of both in your application anyway.