Event handlers allow you to respond to various agent events such as messages, tool calls, and state changes.

Stdout Event Handler¶

Configuration for built-in event handlers (simple, detailed).

Stdout Event Handler (YAML)
- type: builtin
  handler: simple  # Which builtin handler to use.
  enabled: true  # Whether this handler is enabled.

Callback Event Handler¶

Configuration for custom callback event handlers via import path.

Callback Event Handler (YAML)
- type: callback
  import_path: mymodule:my_handler  # Import path to the handler function (module:function format).
  enabled: true  # Whether this handler is enabled.

Text-to-Speech Event Handler¶

Configuration for Text-to-Speech event handler with OpenAI streaming.

Text-to-Speech Event Handler (YAML)
- type: tts-openai
  api_key: null  # OpenAI API key. If not provided, uses OPENAI_API_KEY env var.
  model: tts-1  # TTS model to use.
  voice: alloy  # Voice to use for synthesis.
  speed: 1.0  # Speed of speech (0.25 to 4.0, default 1.0).
  chunk_size: 1024  # Size of audio chunks to process (in bytes).
  sample_rate: 24000  # Audio sample rate in Hz (for PCM format).
  min_text_length: 20  # Minimum text length before synthesizing (in characters).
  mode: sync_run  # How TTS synthesis synchronizes with the event stream.
  enabled: true  # Whether this handler is enabled.

Edge TTS Event Handler¶

Configuration for Edge TTS event handler (free, no API key required).

Uses Microsoft Edge's TTS service via edge-tts library. Supports many voices and languages without requiring an API key.

Edge TTS Event Handler (YAML)
- type: tts-edge
  voice: en-US-AriaNeural  # Voice to use for synthesis.
  speed: 1.0  # Speed of speech (0.25 to 4.0, default 1.0).
  volume: 1.0  # Volume level (0.0 to 2.0, default 1.0 = normal).
  pitch: 0.0  # Pitch adjustment in Hz (default 0.0 = no change).
  sample_rate: 24000  # Audio sample rate in Hz for playback.
  min_text_length: 20  # Minimum text length before synthesizing (in characters).
  mode: sync_run  # How TTS synthesis synchronizes with the event stream.
  enabled: true  # Whether this handler is enabled.