refactor: Abstract ExternalAgentProvider for upstream EVA contribution

[jamestwhedbee]

Summary

Refactors the Telnyx telephony bridge into a clean provider-based abstraction so that upstream ServiceNow/eva can easily extend EVA to support additional hosted voice agent APIs (ElevenLabs Conversational AI, Deepgram Voice Agent, OpenAI Realtime, etc.).

This is prep for an upstream issue targeting the Extended Leaderboard roadmap item:

More cascade and speech-to-speech systems evaluated and added to the findings including native voice agent APIs beyond Pipecat

Architecture

New eva.assistant.external package

src/eva/assistant/external/
├── __init__.py              # Factory: get_provider(config) → ExternalAgentProvider
├── base.py                  # ABCs: ExternalAgentProvider, BaseTelephonyTransport, BaseSegmentTranscriber
├── bridge.py                # ExternalAgentBridgeServer (provider-agnostic)
├── bridge_vad_observer.py   # VAD observer (already generic)
├── tool_webhook.py          # ToolWebhookService (provider routes injected)
└── providers/
    └── telnyx/
        ├── __init__.py      # TelnyxProvider implementation
        ├── config.py        # Re-export
        ├── transport.py     # CallControlTransport
        └── setup.py         # TelnyxAssistantManager

Key abstractions

• ExternalAgentProvider ABC — plugin interface for hosted voice agent APIs:

  • create_transport() — transport connection to the external agent
  • setup() / teardown() — run-level lifecycle (e.g., create/restore assistant config)
  • fetch_intended_speech() — post-call enrichment for metrics
  • register_webhook_routes() — provider-specific webhook endpoints (e.g., DV webhook)
  • get_active_transport() — media stream routing

• ExternalAgentBridgeServer — provider-agnostic bridge handling:

  • WebSocket ↔ transport audio routing
  • VAD observation and turn detection
  • Audio recording (user/assistant/mixed WAV)
  • Output persistence (transcript.jsonl, audit_log.json, pipecat_logs.jsonl)

• ExternalAgentConfig base + TelnyxExternalAgentConfig subclass with discriminator

Adding a new provider

Only requires a new providers/xxx/ directory with config, transport, and setup. No changes to bridge, worker, runner, or metrics pipeline.

Backward compatibility

• TelephonyBridgeConfig → alias for TelnyxExternalAgentConfig
• TelephonyBridgeServer → alias for ExternalAgentBridgeServer
• All old env vars (EVA_MODEL__SIP_URI, etc.) continue to work
• Old import paths preserved as thin re-exports
• Output format unchanged (pipecat_logs.jsonl filename kept for upstream metrics compat)

Context

• Upstream PR cleanup: Minimize upstream diff, remove Telnyx refs from core, rewrite docs #14 expressed concern about Pipecat log coupling — this abstraction cleanly separates framework-specific concerns
• Upstream CONTRIBUTING.md asks to open an issue before large changes — this PR demonstrates the abstraction we'd propose
• Aligns with the EVA_FRAMEWORK direction from PR cleanup: Minimize upstream diff, remove Telnyx refs from core, rewrite docs #14 but at the transport/provider level rather than the Pipecat server level