Runtime Hooks

Runtime hooks let you intercept and process data at each stage of the Pipeline without subclassing it. Register them with the @pipeline.on() decorator.

Audio Processing Hooks

The stt and tts hooks replace the built-in component processing. Each receives an async iterator and yields processed results. Only one of each can be registered.

The stt and tts hooks fully replace the built-in component processing: you receive the raw stream and yield the processed result yourself.

STT hook: clean up transcripts

A common use case is preprocessing the audio and normalizing the transcript before it reaches the LLM. This hook drops tiny audio chunks, then strips filler words from the transcribed text.

@pipeline.on("stt")
async def stt_hook(audio_stream):
    # Drop very small audio chunks before transcribing
    async def filtered():
        async for audio in audio_stream:
            if len(audio) >= 300:
                yield audio

    # Transcribe, then remove filler words from the text
    async for event in run_stt(filtered()):
        if event.data and event.data.text:
            text = re.sub(r"\b(uh|um|like)\b", "", event.data.text)
            event.data.text = " ".join(text.split())
        yield event

TTS hook: fix pronunciation

A common use case is reshaping text so the voice reads it correctly. This hook spells out abbreviations so the TTS pronounces them as expected.

@pipeline.on("tts")
async def tts_hook(text_stream):
    # Rewrite text before it is synthesized
    async def preprocess():
        async for text in text_stream:
            yield text.replace("AM", "A M").replace("PM", "P M")

    async for audio in run_tts(preprocess()):
        yield audio

Lifecycle Hooks

Lifecycle hooks are side-effect-only. Use them for logging, analytics, and triggering external actions. You can register multiple per event.

user_turn_start(transcript: str): user’s final transcript is available.
user_turn_end(): agent finished responding for the turn.
agent_turn_start(): agent starts speaking.
agent_turn_end(): agent finishes speaking.

user_turn_start
user_turn_end
agent_turn_start
agent_turn_end

Fetch context for the turn. The final transcript is available here, so it is a good place to run a knowledge-base lookup before the LLM responds.

    @pipeline.on("user_turn_start")
    async def on_user_start(transcript: str):
        docs = await knowledge_base.search(transcript)
        agent.metadata["retrieved"] = docs

Save the completed turn. Fires once the agent has finished responding, so the turn is complete. Use it to persist the exchange.

    @pipeline.on("user_turn_end")
    async def on_user_end():
        await db.save_turn(session_id, turn_count)

Show a speaking indicator. Fires when the agent starts speaking. Push a status update so the client UI can show the agent is talking.

    from zrt import PubSubPublishConfig

    @pipeline.on("agent_turn_start")
    async def on_agent_start():
        await agent.session.publish_message(
            PubSubPublishConfig(topic="AGENT_STATUS", message="speaking")
        )

Clear the indicator. Fires when the agent finishes speaking. Use it to reset UI state or measure response latency.

    from zrt import PubSubPublishConfig

    @pipeline.on("agent_turn_end")
    async def on_agent_end():
        await agent.session.publish_message(
            PubSubPublishConfig(topic="AGENT_STATUS", message="idle")
        )

What’s Next

Pipeline Overview

Review how the pipeline is configured before hooking into it.

Run Your Agent

Run the pipeline with an agent.

References

Python

Examples

Pipeline Hooks

Hook into a cascade pipeline at runtime.

SDK Reference

Pipeline Hooks

Pipeline Hooks in the Python API reference.

Get started

Modalities

Configure Pipeline

Tools and Capabilities

Turn Detection and Interruptions

Telephony Agents

Context Management

Observability and Monitoring

Audio Processing Hooks

STT hook: clean up transcripts

TTS hook: fix pronunciation

Lifecycle Hooks

What’s Next

Pipeline Overview

Run Your Agent

References

Examples

Pipeline Hooks

SDK Reference

Pipeline Hooks

​Audio Processing Hooks

​STT hook: clean up transcripts

​TTS hook: fix pronunciation

​Lifecycle Hooks

​What’s Next

Pipeline Overview

Run Your Agent

​References

​Examples

Pipeline Hooks

​SDK Reference

Pipeline Hooks

Audio Processing Hooks

STT hook: clean up transcripts

TTS hook: fix pronunciation

Lifecycle Hooks

What’s Next

References

Examples

SDK Reference