streaming

{{ $frontmatter.title }}

Stream responses from AI providers in real-time using ActiveAgent's streaming callbacks. This guide covers handling streaming responses with callbacks that execute at different points in the streaming lifecycle.

Overview

ActiveAgent provides three streaming callbacks:

• on_stream_open - Invoked when the stream begins
• on_stream - Invoked for every chunk received during streaming
• on_stream_close - Invoked when the stream completes

Callbacks automatically receive a StreamChunk object if they accept a parameter, providing access to the current message state and incremental delta content.

Basic Streaming

Enable streaming by passing stream: true to your agent or prompt:

<<< @/../test/docs/agents/streaming_examples_test.rb#basic_streaming_agent {ruby:line-numbers} [agent.rb]

<<< @/../test/docs/agents/streaming_examples_test.rb#basic_streaming_usage {ruby:line-numbers} [usage.rb]

StreamChunk Object

Each callback receives a StreamChunk with two attributes:

• message - The current message object from the provider (accumulated state)
• delta - The incremental content for this specific chunk (may be nil)

The delta contains only the new content received in the current chunk, while message contains the accumulated message state. Not all chunks contain a delta—some may only contain metadata updates.

def log_chunk(chunk)
  # Delta contains only new content for this chunk
  Rails.logger.debug("New content: #{chunk.delta}")

  # Message contains accumulated provider response
  Rails.logger.debug("Full message so far: #{chunk.message.inspect}")
end

Lifecycle Callbacks

Use callbacks to handle different points in the streaming lifecycle:

on_stream_open

Invoked when streaming begins. Use this to initialize state:

<<< @/../test/docs/agents/streaming_examples_test.rb#lifecycle_open {ruby:line-numbers}

on_stream

Invoked for every chunk. Keep processing lightweight:

<<< @/../test/docs/agents/streaming_examples_test.rb#lifecycle_chunk {ruby:line-numbers}