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.
Any | None
default:"None"
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.int
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.FrameProcessor
The processor to pause.
FrameProcessorResumeFrame
Resumes a previously paused processor, releasing all buffered frames for processing.FrameProcessor
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.LLMContextSummaryConfig | None
default:"None"
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.
str
Unique identifier for this summarization request.
LLMContext
The conversation context to summarize.
int
Minimum number of recent messages to preserve after summarization.
int
Target token count for the summarized context.
str
Prompt instructing the LLM how to summarize.
float | None
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.
str
Matches the originating request.
str
The generated summary text.
int
Index of the last message included in the summary.
str | None
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.bool
default:"False"
Whether to append thought content to the conversation context. Raises
ValueError if set to True without specifying llm.str | None
default:"None"
Identifier for the LLM producing the thought. Required when
append_to_context is True.LLMThoughtEndFrame
Marks the end of LLM extended thinking content.Any
default:"None"
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.
str
Name of the function being called.
str
Unique identifier for this tool call.
Any
Arguments passed to the function.
bool
default:"False"
Whether the function call should be cancelled if the user interrupts. When
False, the call is treated as asynchronous: the LLM continues the
conversation immediately without waiting for the result, and the result is
injected later via a developer message.str | None
default:"None"
Shared identifier for all function calls from the same LLM response batch.
Used to determine when the last call in a group completes so the LLM can be
triggered exactly once.
TTS State
TTSStartedFrame
Signals the beginning of a TTS audio response.str | None
Identifier linking this TTS output to its originating context.
bool
default:"True"
Whether the spoken text for this response will be appended to the LLM
context. When
True, the assistant aggregator will track this output as an
assistant turn, firing on_assistant_turn_started and
on_assistant_turn_stopped events.TTSStoppedFrame
Signals the end of a TTS audio response.str | None
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.
Mapping[str, Any]
default:"{}"
Dictionary of settings to update.
ServiceSettings | None
default:"None"
Typed settings delta. Takes precedence over the
settings dict when both are
provided.FrameProcessor | None
default:"None"
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
AudioBufferStartRecordingFrame
InstructsAudioBufferProcessor to start recording audio. This frame can be pushed through the pipeline to start recording on demand. Alternatively, use AudioBufferProcessor.start_recording() or enable auto_start_recording in the constructor.
Inherits from UninterruptibleFrame.
AudioBufferStopRecordingFrame
InstructsAudioBufferProcessor to stop recording and flush any buffered audio. After flushing, triggers the on_recording_stopped event.
Inherits from UninterruptibleFrame.
VADParamsUpdateFrame
Update Voice Activity Detection parameters at runtime.VADParams
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.
Mapping[str, Any]
Filter settings to update.
FilterEnableFrame
Enable or disable an audio filter. Inherits fromFilterControlFrame.
bool
True to enable the filter, False to disable it.MixerControlFrame
Base frame for audio mixer control.MixerUpdateSettingsFrame
Update audio mixer settings. Inherits fromMixerControlFrame.
Mapping[str, Any]
Mixer settings to update.
MixerEnableFrame
Enable or disable an audio mixer. Inherits fromMixerControlFrame.
bool
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.
FrameProcessor
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.FrameProcessor
The service to request metadata from.
Pipeline Worker Frames
Pipeline worker frames are pushed upstream to the pipeline worker, which converts them into the appropriate downstream frame. This indirection lets processors request pipeline-level actions without needing direct access to the pipeline worker.WorkerFrame
Base frame for worker control.EndWorkerFrame
Request graceful pipeline shutdown. The pipeline worker converts this into anEndFrame and pushes it downstream. Inherits from WorkerFrame and UninterruptibleFrame.
Any | None
Optional reason for the shutdown request.
StopWorkerFrame
Request pipeline stop while keeping processors alive. Converted to aStopFrame downstream. Inherits from WorkerFrame and UninterruptibleFrame.