Environment:Openai Openai agents python Voice Dependencies

Knowledge Sources	openai-agents-python
Domains	Infrastructure, Voice
Last Updated	2026-02-11 14:00 GMT

Overview

Optional dependency group for voice pipeline features: numpy and websockets, requiring Python 3.10+.

Description

The voice pipeline (`VoicePipeline`, STT, TTS) requires `numpy` for audio buffer manipulation and `websockets` for real-time WebSocket communication with OpenAI voice APIs. These are optional dependencies installed via the `[voice]` extra. The numpy dependency is restricted to Python 3.10+ in pyproject.toml.

Usage

Use this environment when building voice-enabled agents using `VoicePipeline`, `AudioInput`, `OpenAISTTTranscriptionSession`, or `OpenAITTSModel`. Not needed for text-only agent workflows.

System Requirements

Category	Requirement	Notes
Python	>= 3.10	numpy >= 2.2.0 requires Python 3.10+
Audio Hardware	Microphone/Speaker	Required for live voice interaction (optional for testing)

Dependencies

Python Packages

• `numpy` >= 2.2.0, < 3 (Python 3.10+ only)
• `websockets` >= 15.0, < 16

Credentials

• `OPENAI_API_KEY`: Required for OpenAI STT/TTS API access

Quick Install

pip install 'openai-agents[voice]'

Code Evidence

Import guard from `voice/imports.py:1-9`:

try:
    import numpy as np
    import numpy.typing as npt
    import websockets
except ImportError as _e:
    raise ImportError(
        "`numpy` + `websockets` are required to use voice. You can install them via the optional "
        "dependency group: `pip install 'openai-agents[voice]'`."
    ) from _e

Version constraint from `pyproject.toml:38`:

voice = ["numpy>=2.2.0, <3; python_version>='3.10'", "websockets>=15.0, <16"]

Common Errors

Error Message	Cause	Solution
`ImportError: numpy + websockets are required to use voice`	Voice dependencies not installed	`pip install 'openai-agents[voice]'`
`on_start() failed: {e}`	Voice pipeline initialization error	Check audio device availability and permissions

Compatibility Notes

• Python 3.9: Voice features are not available (numpy >= 2.2.0 requires Python 3.10+).
• Headless environments: Audio input/output may not work without physical audio devices; use mock inputs for testing.

Related Pages

• Implementation:Openai_Openai_agents_python_Runner_Run