# AgileAdapt 9-Layer Shield: Telnyx WebRTC Architecture Guide

**Date:** 2026-02-22  
**Purpose:** Master guidelines for all Genesis agents attempting to implement Telnyx WebRTC. Do not attempt "simple" AI Voice Widget deployments without adhering to this telephony architecture.

---

## 🛑 Why "Simple" Agents Fail at Telnyx WebRTC

Telnyx is not a simple "copy-paste" chatbot API. It is a professional-grade telephony stack requiring a complex "three-way handshake" between the Browser, the Telnyx Private Global Network, and the LLM. 

1. **Signalling vs. Media:** The command to speak (WebSocket) and the audio stream (STUN/TURN WebRTC) happen on different network paths.
2. **The Auth Token Trap:** You cannot expose an API key in the browser. You must build a backend "Token Exchange" to grant the WebRTC client a temporary `telephony_credential` via the Telnyx API.
3. **The "Anonymous" Toggle (Zero-Touch Mode):** If bypassing the token exchange for a talking website demo, you MUST explicitly enable `unauthenticated_web_calls` (or `anonymous_login: true`) on the Telnyx Assistant ID in the portal or via API, otherwise Australian servers will reject the connection 100% of the time.

---

## 🛠️ The "AgileAdapt WebRTC Fixer" Deep Research Prompt

If you encounter a "Media Connection Failed" or "Failed to Initialize AI Agent" loop, drop into "Telnyx Engineering Mode" using this prompt:

> **Role:** You are a Senior Telnyx WebRTC Architect specializing in Browser-to-Agent voice orchestration.
> 
> **Context:** I am building AgileAdapt, a talking website widget. We are using latest AI models and Australian servers. We need to bypass the phone network and connect the browser directly to a Telnyx AI Assistant.
> 
> **Your Task:** Research and provide the exact technical implementation for the following:
> 
> 1. **The Token Exchange:** Provide the Node.js/Python code to generate a `telephony_credential` via the Telnyx API so the browser can connect securely without exposing our main API Key.
> 2. **The Widget Configuration:** Define the exact JSON parameters for the `<telnyx-ai-agent>` component, specifically setting `voice_activity_detection` (VAD) and `anonymous_login: true`.
> 3. **The WebSocket Handshake:** Explain the sequence of the `conversation.started` and `conversation.ended` events to ensure the "Closer Agent" knows exactly when to start the pitch.
> 4. **Troubleshooting:** Identify the 3 most common reasons for a "Media Connection Failed" error on Australian servers and how to fix them using the Telnyx Debugging Portal.

---

## 🔑 The AgileAdapt "Cheat Sheet" for Agents

| Missing Component | Why It Matters |
| :--- | :--- |
| **On-Demand JWT** | The browser needs a fresh "ticket" for every session to talk to the AI securely (if not using the anonymous toggle). |
| **VAD Sensitivity** | If the Voice Activity Detection is too high, the agent won't hear the user over background noise. Must carefully tune `silenceDurationMs` and `minSpeechDurationMs`. |
| **ICE Servers** | Sometimes Australian corporate firewalls block WebRTC; you require Telnyx TURN servers to "punch through" the firewall successfully. |

## 🚀 The "Zero-Touch" Scaling Strategy

The final configuration must be hard-coded into the "Demo Scraper". 
Instead of Genesis agents attempting to configure WebRTC limits from scratch every time, the agent will simply **swap out the Assistant_ID** in a working, battle-tested `demo-landing.html` template.
