aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/audio_interface/livekit_audio_session.py

@@ -0,0 +1,504 @@
+"""LiveKit-based audio session (local-only).
+
+This session:
+  - connects to a LiveKit server/room
+  - uses OpenAI STT/TTS via `livekit-plugins-openai` when enabled
+  - routes final user transcripts into an AIP agent
+  - speaks the agent reply back into the room
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import importlib.util
+import inspect
+import os
+import uuid
+from typing import Any
+
+from aip_agents.audio_interface.audio_agent_adapter import AIPAudioAgentAdapter
+from aip_agents.audio_interface.config import AudioSessionConfig, LiveKitConfig
+from aip_agents.audio_interface.errors import AudioConfigError, AudioSessionUnavailableError
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+_INTERRUPTED_SPEECH_NOTE = (
+    "[aip-audio] NOTE: speech was interrupted. If you are not hearing TTS, mute your mic after speaking "
+    "(or reduce background noise)."
+)
+_INTERRUPTED_SPEECH_RETRY_DELAY_S = 0.35
+_TRANSCRIPT_DEBOUNCE_S = 0.6
+_TOOL_WAIT_MESSAGE_DEFAULT = "Please wait a moment while I check that."
+_TOOL_WAIT_DELAY_S_DEFAULT = 0.0
+
+
+def _ensure_livekit_available() -> None:
+    if importlib.util.find_spec("livekit") is None or importlib.util.find_spec("livekit.agents") is None:
+        raise AudioSessionUnavailableError(
+            "LiveKit audio provider is unavailable. Install with: "
+            "pip install 'aip-agents[audio]' (or 'poetry install -E audio' in dev)"
+        )
+
+
+def _ensure_livekit_openai_plugin_available() -> None:
+    if importlib.util.find_spec("livekit.plugins.openai") is None:
+        raise AudioSessionUnavailableError(
+            "OpenAI STT/TTS requires livekit-plugins-openai. Install with: "
+            "pip install 'aip-agents[audio]' (or 'poetry install -E audio' in dev)"
+        )
+
+
+class LiveKitAudioSession:
+    """Manage a LiveKit room connection and stream audio to/from an agent."""
+
+    def __init__(self, config: AudioSessionConfig) -> None:
+        """Create a session for the given `AudioSessionConfig`."""
+        provider = (config.provider or "livekit").strip().lower()
+        if provider != "livekit":
+            raise AudioConfigError(
+                f"LiveKitAudioSession requires provider='livekit' (got provider={config.provider!r})"
+            )
+        self._config = config
+        self._session: Any | None = None
+        self._close_event = asyncio.Event()
+        self._room: Any | None = None
+        self._http_context_mod: Any | None = None
+        self._pending_tasks: set[asyncio.Task[Any]] = set()
+        self._adapter: AIPAudioAgentAdapter | None = None
+        self._room_name: str | None = None
+        self._pending_transcripts: list[str] = []
+        self._flush_task: asyncio.Task[Any] | None = None
+        # Serialize agent turns. This avoids concurrent calls into the agent/checkpointer
+        # which can corrupt conversation state and produce "generic" responses.
+        self._turn_lock = asyncio.Lock()
+
+    @staticmethod
+    def _debug_enabled() -> bool:
+        return os.environ.get("AIP_AUDIO_DEBUG") == "1"
+
+    def _resolve_livekit_config(self) -> LiveKitConfig:
+        cfg = self._config.provider_config
+        if isinstance(cfg, LiveKitConfig):
+            return cfg
+        if isinstance(cfg, dict):
+            url = cfg.get("url")
+            if not url:
+                raise AudioConfigError("livekit.url is required")
+            return LiveKitConfig(
+                url=str(url),
+                api_key=cfg.get("api_key"),
+                api_secret=cfg.get("api_secret"),
+                room_name=cfg.get("room_name"),
+                identity=cfg.get("identity"),
+                openai_stt_model=cfg.get("openai_stt_model"),
+                openai_tts_model=cfg.get("openai_tts_model"),
+                openai_voice=cfg.get("openai_voice"),
+                openai_use_realtime_stt=bool(cfg.get("openai_use_realtime_stt", True)),
+                openai_api_key=cfg.get("openai_api_key"),
+                openai_base_url=cfg.get("openai_base_url"),
+            )
+        raise AudioConfigError("provider_config must be LiveKitConfig or dict")
+
+    def _wants_openai_stt_tts(self, lk_cfg: LiveKitConfig) -> bool:
+        model_cfg = self._config.model
+        if model_cfg is not None and (model_cfg.provider or "").lower() == "openai":
+            return True
+        return bool(
+            lk_cfg.openai_stt_model
+            or lk_cfg.openai_tts_model
+            or lk_cfg.openai_voice
+            or lk_cfg.openai_api_key
+            or lk_cfg.openai_base_url
+        )
+
+    def _build_openai_stt_tts(self, lk_cfg: LiveKitConfig) -> tuple[Any, Any]:
+        _ensure_livekit_openai_plugin_available()
+        openai_plugin = importlib.import_module("livekit.plugins.openai")
+
+        api_key = lk_cfg.resolve_openai_api_key()
+        base_url = lk_cfg.openai_base_url
+        model_cfg = self._config.model
+
+        stt_model = lk_cfg.openai_stt_model or "gpt-4o-transcribe"
+        tts_model = lk_cfg.openai_tts_model or (model_cfg.model if model_cfg else None) or "gpt-4o-mini-tts"
+        voice = lk_cfg.openai_voice or (model_cfg.voice if model_cfg else None) or "echo"
+
+        STT = getattr(openai_plugin, "STT")
+        TTS = getattr(openai_plugin, "TTS")
+
+        stt_obj = STT(
+            model=stt_model,
+            api_key=api_key,
+            base_url=base_url,
+            use_realtime=bool(lk_cfg.openai_use_realtime_stt),
+        )
+        tts_obj = TTS(
+            model=tts_model,
+            voice=voice,
+            api_key=api_key,
+            base_url=base_url,
+        )
+        return stt_obj, tts_obj
+
+    async def start(self, aip_agent: Any, *, instructions: str) -> None:
+        """Connect to LiveKit and start the voice pipeline."""
+        # Reset close flag in case this instance is restarted.
+        self._close_event.clear()
+        _ensure_livekit_available()
+
+        lk_cfg = self._resolve_livekit_config()
+        rtc, room_options_cls, agent_cls, agent_session_cls, access_token_cls, video_grants_cls = (
+            self._resolve_livekit_runtime()
+        )
+
+        room_name, token = self._build_join_token(lk_cfg, access_token_cls, video_grants_cls)
+
+        room = rtc.Room()
+        await room.connect(lk_cfg.url, token)
+        self._room = room
+
+        session_kwargs = self._build_agent_session_kwargs(lk_cfg)
+
+        session: Any = agent_session_cls(**session_kwargs)
+        lk_agent: Any = agent_cls(instructions=instructions, llm=None)
+
+        # Initialize our adapter/handlers before starting the LiveKit session so that
+        # any early text input is routed to the AIP agent (instead of LiveKit's default
+        # text handler, which expects an internal LLM and will throw).
+        self._register_session_handlers(session=session, aip_agent=aip_agent, room_name=room_name)
+
+        # Route LiveKit Meet chat input into the AIP agent (and avoid LiveKit generating its own replies).
+        # This keeps text messages working even though we pass `llm=None` to LiveKit.
+        room_io = importlib.import_module("livekit.agents.voice.room_io")
+        text_input_options_cls = getattr(room_io, "TextInputOptions", None)
+
+        async def _text_input_cb(_: Any, ev: Any) -> None:
+            try:
+                session.interrupt()
+            except Exception:
+                # Best-effort; interruption is not critical.
+                pass
+
+            text = getattr(ev, "text", "") or ""
+            text = str(text).strip()
+            if text:
+                await self._handle_final_transcript(session=session, text=text)
+
+        await session.start(
+            lk_agent,
+            room=room,
+            room_options=room_options_cls(
+                text_input=(
+                    text_input_options_cls(text_input_cb=_text_input_cb) if callable(text_input_options_cls) else False
+                ),
+                audio_input=bool(self._config.io.input_enabled),
+                audio_output=bool(self._config.io.output_enabled),
+            ),
+        )
+
+        self._session = session
+        # Handlers already registered above.
+
+    def _resolve_livekit_runtime(self) -> tuple[Any, Any, Any, Any, Any, Any]:
+        rtc = importlib.import_module("livekit.rtc")
+        agents_mod = importlib.import_module("livekit.agents")
+        room_io = importlib.import_module("livekit.agents.voice.room_io")
+        api_mod = importlib.import_module("livekit.api")
+
+        agent_cls = getattr(agents_mod, "Agent", None)
+        agent_session_cls = getattr(agents_mod, "AgentSession", None)
+        access_token_cls = getattr(api_mod, "AccessToken", None)
+        video_grants_cls = getattr(api_mod, "VideoGrants", None)
+        room_options_cls = getattr(room_io, "RoomOptions", None)
+
+        if (
+            agent_cls is None
+            or agent_session_cls is None
+            or access_token_cls is None
+            or video_grants_cls is None
+            or room_options_cls is None
+        ):
+            raise AudioSessionUnavailableError("LiveKit packages installed but missing expected symbols")
+
+        return rtc, room_options_cls, agent_cls, agent_session_cls, access_token_cls, video_grants_cls
+
+    def _build_join_token(self, lk_cfg: LiveKitConfig, access_token_cls: Any, video_grants_cls: Any) -> tuple[str, str]:
+        api_key = lk_cfg.resolve_api_key()
+        api_secret = lk_cfg.resolve_api_secret()
+
+        room_name = lk_cfg.room_name or f"aip-audio-{uuid.uuid4().hex[:8]}"
+        identity = lk_cfg.identity or "aip-agent"
+
+        token = (
+            access_token_cls(api_key=api_key, api_secret=api_secret)
+            .with_identity(identity)
+            .with_grants(video_grants_cls(room_join=True, room=room_name, agent=True))
+            .to_jwt()
+        )
+        return room_name, token
+
+    def _build_agent_session_kwargs(self, lk_cfg: LiveKitConfig) -> dict[str, Any]:
+        session_kwargs: dict[str, Any] = {}
+        if not self._wants_openai_stt_tts(lk_cfg):
+            return session_kwargs
+
+        self._ensure_http_context_initialized()
+        stt_obj, tts_obj = self._build_openai_stt_tts(lk_cfg)
+        session_kwargs.update({"stt": stt_obj, "tts": tts_obj, "llm": None})
+        return session_kwargs
+
+    def _ensure_http_context_initialized(self) -> None:
+        # livekit-plugins-openai (realtime STT) uses livekit.agents.utils.http_context
+        # which is normally initialized by the worker/job runtime.
+        # Since we're running standalone, initialize it here.
+        http_context = importlib.import_module("livekit.agents.utils.http_context")
+        new_ctx = getattr(http_context, "_new_session_ctx", None)
+        if callable(new_ctx):
+            new_ctx()
+        self._http_context_mod = http_context
+
+    def _register_session_handlers(self, *, session: Any, aip_agent: Any, room_name: str) -> None:
+        self._adapter = AIPAudioAgentAdapter(aip_agent)
+        self._room_name = room_name
+        self._pending_transcripts = []
+        self._flush_task = None
+
+        @session.on("close")
+        def _on_close(_: Any) -> None:
+            self._close_event.set()
+
+        @session.on("user_input_transcribed")
+        def _on_transcript(ev: Any) -> None:
+            self._on_user_input_transcribed(session=session, ev=ev)
+
+    def _on_user_input_transcribed(self, *, session: Any, ev: Any) -> None:
+        if not getattr(ev, "is_final", False):
+            return
+
+        text = getattr(ev, "transcript", "") or ""
+        if not str(text).strip():
+            return
+
+        self._pending_transcripts.append(str(text).strip())
+
+        if self._flush_task is not None and not self._flush_task.done():
+            self._flush_task.cancel()
+
+        task = asyncio.create_task(self._flush_pending_transcripts(session=session))
+        self._flush_task = task
+        self._pending_tasks.add(task)
+
+        def _done(t: asyncio.Task[Any]) -> None:
+            self._pending_tasks.discard(t)
+
+        task.add_done_callback(_done)
+
+    async def _flush_pending_transcripts(self, *, session: Any) -> None:
+        """Wait briefly for STT to finish segmenting, then send one combined turn to the agent."""
+        try:
+            await asyncio.sleep(_TRANSCRIPT_DEBOUNCE_S)
+        except asyncio.CancelledError:
+            # Cancellation is expected when multiple final transcripts arrive quickly.
+            # Re-raise to preserve cancellation semantics.
+            raise
+        except Exception:
+            logger.exception("Unexpected error in flush task")
+            return
+
+        combined = " ".join(self._pending_transcripts).strip()
+        self._pending_transcripts.clear()
+        if combined:
+            await self._handle_final_transcript(session=session, text=combined)
+
+    async def _handle_final_transcript(self, *, session: Any, text: str) -> None:
+        async with self._turn_lock:
+            room_name = self._room_name or "unknown"
+            debug = self._debug_enabled()
+
+            if debug:
+                print(f"[aip-audio] room={room_name} user: {text}")
+                print(f"[aip-audio] room={room_name} user_repr={text!r} len={len(text)}")
+
+            if self._adapter is None:
+                return
+
+            final_received = asyncio.Event()
+            wait_task: asyncio.Task[Any] | None = None
+            turn_started = False
+            wait_scheduled = False
+
+            async def _on_a2a_event(ev: dict[str, Any]) -> None:
+                # Add await to satisfy 'async' keyword usage and ensure cooperative scheduling
+                await asyncio.sleep(0)
+                nonlocal wait_task, turn_started, wait_scheduled
+                if self._is_status_update_event(ev) or self._is_tool_call_event(ev):
+                    turn_started = True
+                    if not wait_scheduled:
+                        # Emit at most one wait message per turn.
+                        wait_task = self._schedule_wait_message(session, final_received, debug)
+                        wait_scheduled = wait_task is not None
+                elif turn_started and self._is_final_response_event(ev):
+                    # Some streams may include historical final_response events before
+                    # events belonging to the current turn. Ignore those stale finals.
+                    final_received.set()
+
+            reply = await self._adapter.generate_reply(text, prefer_a2a_stream=True, on_a2a_event=_on_a2a_event)
+
+            final_received.set()
+            # Avoid an "identity check" (`is not None`) here; Sonar can incorrectly
+            # infer `wait_task` is always None due to the nonlocal assignment.
+            if wait_task and not wait_task.done():
+                wait_task.cancel()
+
+            if debug:
+                print(f"[aip-audio] room={room_name} agent: {reply}")
+
+            await self._say_reply_if_enabled(session=session, reply=reply, debug=debug)
+
+    def _is_tool_call_event(self, ev: dict[str, Any]) -> bool:
+        raw_type = ev.get("event_type")
+        # Ensure raw_type is not None and has 'value' before accessing it, or use str conversion
+        event_type = raw_type.value if hasattr(raw_type, "value") else str(raw_type)
+        return event_type == "tool_call"
+
+    def _is_final_response_event(self, ev: dict[str, Any]) -> bool:
+        raw_type = ev.get("event_type")
+        event_type = raw_type.value if hasattr(raw_type, "value") else str(raw_type)
+        return event_type == "final_response"
+
+    def _is_status_update_event(self, ev: dict[str, Any]) -> bool:
+        raw_type = ev.get("event_type")
+        event_type = raw_type.value if hasattr(raw_type, "value") else str(raw_type)
+        return event_type == "status_update"
+
+    def _schedule_wait_message(
+        self, session: Any, final_received: asyncio.Event, debug: bool
+    ) -> asyncio.Task[Any] | None:
+        """Schedule a background task to speak the wait message if the tool takes too long."""
+        wait_message = os.environ.get("AIP_AUDIO_TOOL_WAIT_MESSAGE", _TOOL_WAIT_MESSAGE_DEFAULT).strip()
+        if not wait_message:
+            return None
+
+        try:
+            delay_s = float(os.environ.get("AIP_AUDIO_TOOL_WAIT_DELAY_S", str(_TOOL_WAIT_DELAY_S_DEFAULT)))
+        except Exception:
+            delay_s = _TOOL_WAIT_DELAY_S_DEFAULT
+
+        if debug:
+            print(f"[aip-audio] scheduling tool-wait message after {delay_s:.2f}s")
+
+        async def _delayed_say() -> None:
+            if delay_s > 0:
+                await asyncio.sleep(delay_s)
+            if final_received.is_set():
+                if debug:
+                    print("[aip-audio] tool-wait message suppressed (final already received)")
+                return
+            if debug:
+                print("[aip-audio] speaking tool-wait message")
+            await self._say_reply_if_enabled(session=session, reply=wait_message, debug=debug)
+
+        task = asyncio.create_task(_delayed_say())
+        self._pending_tasks.add(task)
+        task.add_done_callback(lambda t: self._pending_tasks.discard(t))
+        return task
+
+    async def _say_reply_if_enabled(self, *, session: Any, reply: str, debug: bool) -> None:
+        if not (self._config.io.output_enabled and reply):
+            return
+
+        handle = session.say(reply)
+        if not inspect.isawaitable(handle):
+            return
+
+        await handle
+        if debug:
+            await self._handle_interrupted_speech(handle, session, reply)
+
+    async def _handle_interrupted_speech(self, handle: Any, session: Any, reply: str) -> None:
+        """Retry speaking once if interrupted immediately."""
+        if not bool(getattr(handle, "interrupted", False)):
+            return
+
+        print(_INTERRUPTED_SPEECH_NOTE)
+        # Best-effort retry once; VAD/echo can cause immediate interruption on first attempt.
+        await asyncio.sleep(_INTERRUPTED_SPEECH_RETRY_DELAY_S)
+        retry_handle = session.say(reply)
+        if inspect.isawaitable(retry_handle):
+            await retry_handle
+            if bool(getattr(retry_handle, "interrupted", False)):
+                print(_INTERRUPTED_SPEECH_NOTE)
+
+    async def stop(self) -> None:
+        """Stop the session and release LiveKit resources."""
+        # Cancellation will naturally propagate; this wrapper exists mainly for API symmetry.
+        await self._stop_impl()
+
+    async def _stop_impl(self) -> None:
+        """Best-effort cleanup implementation for `stop()`."""
+        await self._cancel_pending_tasks()
+        await self._close_session()
+        await self._disconnect_room()
+        await self._cleanup_http_context()
+
+        self._close_event.set()
+
+        # Clear per-session state
+        self._adapter = None
+        self._room_name = None
+        self._pending_transcripts.clear()
+        self._flush_task = None
+
+    async def _cancel_pending_tasks(self) -> None:
+        if not self._pending_tasks:
+            return
+        tasks = tuple(self._pending_tasks)
+        for task in tasks:
+            task.cancel()
+        try:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.warning("Error cancelling pending tasks", exc_info=True)
+        finally:
+            self._pending_tasks.clear()
+
+    async def _close_session(self) -> None:
+        if self._session is None:
+            return
+        try:
+            await self._session.aclose()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.warning("Error closing LiveKit session", exc_info=True)
+        finally:
+            self._session = None
+
+    async def _disconnect_room(self) -> None:
+        if self._room is None:
+            return
+        try:
+            await self._room.disconnect()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.warning("Error disconnecting LiveKit room", exc_info=True)
+        finally:
+            self._room = None
+
+    async def _cleanup_http_context(self) -> None:
+        try:
+            if self._http_context_mod is not None and hasattr(self._http_context_mod, "_close_http_ctx"):
+                await self._http_context_mod._close_http_ctx()
+        except Exception:
+            logger.warning("Error closing http context", exc_info=True)
+        finally:
+            self._http_context_mod = None
+
+    async def wait_closed(self) -> None:
+        """Wait until the LiveKit session signals close."""
+        await self._close_event.wait()

aip_agents/audio_interface/livekit_realtime_audio_session.py

@@ -0,0 +1,142 @@
+"""Adapter over gllm_inference LiveKitRealtimeSession.
+
+This implementation ports the gllm-inference realtime session API to the local
+audio session interface used by `aip_agents.audio_interface`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+from typing import Any
+
+from aip_agents.audio_interface.config import AudioSessionConfig, LiveKitConfig
+from aip_agents.audio_interface.errors import AudioConfigError, AudioSessionUnavailableError
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _resolve_gllm_livekit_realtime_cls() -> type[Any]:
+    """Resolve gllm-inference LiveKitRealtimeSession and validate base interface."""
+    try:
+        realtime_mod = importlib.import_module("gllm_inference.realtime_session")
+        base_mod = importlib.import_module("gllm_inference.realtime_session.realtime_session")
+    except Exception as exc:
+        raise AudioSessionUnavailableError(
+            "gllm-inference realtime_session modules are unavailable. "
+            "Install/upgrade gllm-inference with livekit support."
+        ) from exc
+
+    livekit_cls = getattr(realtime_mod, "LiveKitRealtimeSession", None)
+    base_cls = getattr(base_mod, "BaseRealtimeSession", None)
+
+    if livekit_cls is None:
+        raise AudioSessionUnavailableError(
+            "Installed gllm-inference does not expose LiveKitRealtimeSession. "
+            "Upgrade gllm-inference to a version that includes "
+            "`gllm_inference.realtime_session.LiveKitRealtimeSession`."
+        )
+
+    if base_cls is not None and not issubclass(livekit_cls, base_cls):
+        raise AudioSessionUnavailableError("LiveKitRealtimeSession does not implement BaseRealtimeSession")
+
+    return livekit_cls
+
+
+class LiveKitRealtimeAudioSession:
+    """Bridge class for provider=`livekit_realtime`."""
+
+    def __init__(self, config: AudioSessionConfig) -> None:
+        """Initialize the LiveKit realtime audio session wrapper.
+
+        Args:
+            config (AudioSessionConfig): Session configuration including provider and provider config.
+
+        Returns:
+            None: This initializer returns None.
+        """
+        provider = (config.provider or "").strip().lower()
+        if provider != "livekit_realtime":
+            raise AudioConfigError(
+                f"LiveKitRealtimeAudioSession requires provider='livekit_realtime' "
+                f"(got provider={config.provider!r})"
+            )
+
+        self._config = config
+        self._close_event = asyncio.Event()
+        self._session: Any | None = None
+        self._run_task: asyncio.Task[Any] | None = None
+
+    def _resolve_livekit_config(self) -> LiveKitConfig:
+        cfg = self._config.provider_config
+        if isinstance(cfg, LiveKitConfig):
+            return cfg
+        if isinstance(cfg, dict):
+            url = cfg.get("url")
+            if not url:
+                raise AudioConfigError("livekit_realtime.url is required")
+            return LiveKitConfig(
+                url=str(url),
+                api_key=cfg.get("api_key"),
+                api_secret=cfg.get("api_secret"),
+                room_name=cfg.get("room_name"),
+                identity=cfg.get("identity"),
+            )
+        raise AudioConfigError("provider_config must be LiveKitConfig or dict")
+
+    async def start(self, aip_agent: Any, *, instructions: str) -> None:
+        """Start gllm-inference LiveKitRealtimeSession in a background task.
+
+        Note:
+            This provider adapts the transport/session layer only. The `aip_agent`
+            and `instructions` parameters are currently ignored by the underlying
+            gllm-inference LiveKit realtime session API.
+        """
+        del aip_agent, instructions
+
+        if self._run_task is not None and not self._run_task.done():
+            raise AudioConfigError("LiveKitRealtimeAudioSession is already started")
+
+        lk_cfg = self._resolve_livekit_config()
+        session_cls = _resolve_gllm_livekit_realtime_cls()
+        self._close_event.clear()
+
+        self._session = session_cls(
+            url=lk_cfg.url,
+            api_key=lk_cfg.resolve_api_key(),
+            api_secret=lk_cfg.resolve_api_secret(),
+            room_name=lk_cfg.room_name,
+            identity=lk_cfg.identity,
+        )
+
+        async def _run() -> None:
+            try:
+                await self._session.start()
+            finally:
+                self._close_event.set()
+
+        self._run_task = asyncio.create_task(_run())
+        await asyncio.sleep(0)
+        if self._run_task.done():
+            err = self._run_task.exception()
+            if err is not None:
+                raise err
+
+    async def stop(self) -> None:
+        """Stop background run task."""
+        task = self._run_task
+        if task is None:
+            self._close_event.set()
+            return
+
+        if not task.done():
+            task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+        self._run_task = None
+        self._session = None
+        self._close_event.set()
+
+    async def wait_closed(self) -> None:
+        """Wait for session termination."""
+        await self._close_event.wait()

aip_agents/audio_interface/session_factory.py

@@ -0,0 +1,40 @@
+"""Factory for transport-specific audio sessions."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Any, Protocol
+
+from aip_agents.audio_interface.config import AudioSessionConfig
+from aip_agents.audio_interface.errors import AudioConfigError
+from aip_agents.audio_interface.livekit_audio_session import LiveKitAudioSession
+from aip_agents.audio_interface.livekit_realtime_audio_session import LiveKitRealtimeAudioSession
+
+
+class AudioSession(Protocol):
+    """Minimal transport session contract for audio providers."""
+
+    def start(self, aip_agent: Any, *, instructions: str) -> Awaitable[None]:
+        """Start the session."""
+
+    def stop(self) -> Awaitable[None]:
+        """Stop the session and cleanup resources."""
+
+    def wait_closed(self) -> Awaitable[None]:
+        """Wait until the remote session closes."""
+
+
+def create_audio_session(config: AudioSessionConfig) -> AudioSession:
+    """Create an audio transport session for the configured provider.
+
+    This is the single entry point for "one interface, many implementations".
+    """
+    provider = (config.provider or "livekit").strip().lower()
+    if provider == "livekit":
+        return LiveKitAudioSession(config)
+    if provider == "livekit_realtime":
+        return LiveKitRealtimeAudioSession(config)
+
+    raise AudioConfigError(
+        f"Unsupported audio provider '{config.provider}'. Supported providers: livekit, livekit_realtime"
+    )