InterruptionFrame unless combined with UninterruptibleFrame. See the frames overview for base class details and the full frame hierarchy.
Pipeline Lifecycle
EndFrame
Signals graceful pipeline shutdown.EndFrame is queued with other non-SystemFrames, which allows FrameProcessors to be shut down in order, allowing queued frames ahead of the EndFrame to be processed first.
Inherits from UninterruptibleFrame, meaning it cannot be cancelled by InterruptionFrame.
Optional reason for the shutdown, passed along for logging or inspection.
StopFrame
Stops the pipeline but keeps processors in a running state. LikeEndFrame, StopFrame is queued with other non-SystemFrames allowing frames preceding it to be processed first. Useful when you need to halt frame flow without tearing down the entire processor graph.
Inherits from UninterruptibleFrame.
OutputTransportReadyFrame
Indicates that the output transport is ready to receive frames. Processors waiting on transport availability can use this as their signal to begin sending.HeartbeatFrame
Used for pipeline health monitoring. Processors can observe these to detect stalls or measure latency.Timestamp value for the heartbeat.
Processor Pause/Resume
While a processor is paused, incoming frames accumulate in its internal queue rather than being dropped. Once the processor is resumed, it drains the queue and processes all buffered frames in the order they arrived. For example, the TTS service pauses itself while synthesizing aTTSSpeakFrame. If new text frames arrive during synthesis, they queue up instead of producing overlapping audio. The TTS resumes when BotStoppedSpeakingFrame (a SystemFrame) arrives, and the buffered frames are processed in order.
Internally, each processor has two queues: a high-priority input queue for SystemFrames and a process queue for everything else. Pausing blocks the process queue, but SystemFrames continue to flow through the input queue. This is why the typical pattern is for a processor to pause itself and then resume in response to a SystemFrame.
FrameProcessorResumeFrame is a ControlFrame, which means it enters the
same process queue that pausing blocks. If DataFrames have already queued up
ahead of it, the resume frame will be stuck behind them and the processor will
stay paused. To resume a paused processor from outside, use the SystemFrame
variant FrameProcessorResumeUrgentFrame instead — it bypasses the process
queue entirely. See System
Frames.FrameProcessorPauseFrame
Pauses a specific processor. Queued in order, so the processor finishes handling any frames ahead of it before pausing.The processor to pause.
FrameProcessorResumeFrame
Resumes a previously paused processor, releasing all buffered frames for processing.The processor to resume.
Because this is a
ControlFrame, it will be blocked behind any DataFrames
that queued up while the processor was paused. Use
FrameProcessorResumeUrgentFrame if the processor may have buffered frames.LLM Response Boundaries
These frames bracket LLM output, letting downstream processors (aggregators, TTS services, transports) know when a response starts and ends.LLMFullResponseStartFrame
Marks the beginning of an LLM response. Followed by one or moreTextFrames and terminated by LLMFullResponseEndFrame.
LLMFullResponseEndFrame
Marks the end of an LLM response.VisionFullResponseStartFrame
Beginning of a vision model response. Inherits fromLLMFullResponseStartFrame.
VisionFullResponseEndFrame
End of a vision model response. Inherits fromLLMFullResponseEndFrame.
LLMAssistantPushAggregationFrame
Forces the assistant aggregator to commit its buffered text to context immediately, rather than waiting for the normal end-of-response boundary.LLM Context Summarization
Frames that coordinate context summarization: compressing conversation history to stay within token limits.LLMSummarizeContextFrame
Triggers manual context summarization. Push this frame to request that the LLM summarize the current conversation context.Optional configuration controlling summarization behavior.
LLMContextSummaryRequestFrame
Internal request from the aggregator to the LLM service, asking it to produce a summary. You typically won’t push this yourself — the aggregator creates it in response toLLMSummarizeContextFrame or automatic summarization triggers.
Unique identifier for this summarization request.
The conversation context to summarize.
Minimum number of recent messages to preserve after summarization.
Target token count for the summarized context.
Prompt instructing the LLM how to summarize.
Optional timeout in seconds for the summarization request.
LLMContextSummaryResultFrame
The LLM’s summarization result, sent back to the aggregator. Inherits fromUninterruptibleFrame to ensure the result is never dropped.
Matches the originating request.
The generated summary text.
Index of the last message included in the summary.
Error message if summarization failed, otherwise
None.LLM Thought Frames
Bracket extended thinking output from LLMs that support it (e.g., Claude with extended thinking enabled).LLMThoughtStartFrame
Marks the beginning of LLM extended thinking content.Whether to append thought content to the conversation context. Raises
ValueError if set to True without specifying llm.Identifier for the LLM producing the thought. Required when
append_to_context is True.LLMThoughtEndFrame
Marks the end of LLM extended thinking content.Thought signature, if provided by the LLM. Anthropic models include a
signature that must be preserved when appending thoughts back to context.
Function Calling
FunctionCallInProgressFrame
Indicates that a function call is currently executing. Inherits fromUninterruptibleFrame, ensuring it reaches downstream processors even during interruption.
Name of the function being called.
Unique identifier for this tool call.
Arguments passed to the function.
Whether the function call should be cancelled if the user interrupts.
TTS State
TTSStartedFrame
Signals the beginning of a TTS audio response.Identifier linking this TTS output to its originating context.
TTSStoppedFrame
Signals the end of a TTS audio response.Identifier linking this TTS output to its originating context.
Service Settings
Runtime settings updates for LLM, TTS, STT, and other services. These let you change service configuration mid-conversation without rebuilding the pipeline. Push anLLMUpdateSettingsFrame, TTSUpdateSettingsFrame, or STTUpdateSettingsFrame to update the corresponding service. See the Changing Service Settings at Runtime pattern for an example.
ServiceUpdateSettingsFrame
Base frame for runtime service settings updates. Inherits fromUninterruptibleFrame.
Dictionary of settings to update.
Typed settings delta. Takes precedence over the
settings dict when both are
provided.Target a specific service instance. When
None, the frame applies to the
first matching service in the pipeline.LLMUpdateSettingsFrame
Update LLM service settings at runtime. Inherits fromServiceUpdateSettingsFrame.
TTSUpdateSettingsFrame
Update TTS service settings at runtime. Inherits fromServiceUpdateSettingsFrame.
STTUpdateSettingsFrame
Update STT service settings at runtime. Inherits fromServiceUpdateSettingsFrame.
Audio Processing
VADParamsUpdateFrame
Update Voice Activity Detection parameters at runtime.New VAD parameters to apply.
FilterControlFrame
Base frame for audio filter control. Subclass this for custom filter commands.FilterUpdateSettingsFrame
Update audio filter settings. Inherits fromFilterControlFrame.
Filter settings to update.
FilterEnableFrame
Enable or disable an audio filter. Inherits fromFilterControlFrame.
True to enable the filter, False to disable it.MixerControlFrame
Base frame for audio mixer control.MixerUpdateSettingsFrame
Update audio mixer settings. Inherits fromMixerControlFrame.
Mixer settings to update.
MixerEnableFrame
Enable or disable an audio mixer. Inherits fromMixerControlFrame.
True to enable the mixer, False to disable it.Service Switching
ServiceSwitcherFrame
Base frame for service switching operations.ManuallySwitchServiceFrame
Request a manual switch to a different service instance. Inherits fromServiceSwitcherFrame.
The service to switch to.
ServiceSwitcherRequestMetadataFrame
Request that a service re-emit its metadata. Useful after switching services to ensure downstream processors have current configuration.The service to request metadata from.
Task Frames
Task frames are pushed upstream to the pipeline task, which converts them into the appropriate downstream frame. This indirection lets processors request pipeline-level actions without needing direct access to the pipeline task.TaskFrame
Base frame for task control.EndTaskFrame
Request graceful pipeline shutdown. The pipeline task converts this into anEndFrame and pushes it downstream. Inherits from TaskFrame and UninterruptibleFrame.
Optional reason for the shutdown request.
StopTaskFrame
Request pipeline stop while keeping processors alive. Converted to aStopFrame downstream. Inherits from TaskFrame and UninterruptibleFrame.