Introduction

If you already have an Astro frontend and you want to add a voice + video sales agent, the hard part is not rendering a UI. It is moving realtime audio and avatar state cleanly across the browser/server boundary without leaking credentials or introducing latency that makes the experience feel broken.

This post shows a practical integration pattern: keep Astro responsible for the web experience, keep the agent backend responsible for speech, turn-taking, and avatar streaming, and connect the two over a small, explicit API surface. By the end, you should understand where WebRTC fits, how to keep API keys off the client, how to hand off session state, and where Protoface fits into that architecture.

Start with the architecture, not the widget

A voice + video sales agent is usually three systems:

• Frontend — Astro renders the page and mounts the interaction surface.

• Agent backend — your voice agent handles STT, LLM turn logic, TTS, and business rules.

• Realtime avatar layer — the avatar consumes the agent’s audio and emits synchronized lip-synced video.

The important constraint is that the browser should not do privileged work. Your Astro app may request session metadata from your backend, but it should never hold long-lived API keys for avatar creation or session management. If the browser needs realtime media access, it should get narrowly scoped credentials or connect through a controlled embed flow.

For the media path, think in terms of one-directional responsibilities:

1. The user speaks into the browser.

2. The agent backend receives audio, transcribes it, and decides what to say.

3. The avatar service renders a talking face from the generated speech.

4. The browser plays the resulting audio/video stream with minimal buffering.

That separation matters because most bugs in these systems are boundary bugs: token leakage, mismatched session IDs, race conditions around connect/disconnect, or latency spikes caused by too much work in the page lifecycle.

How Astro should connect to the backend

Astro is good at composition, routing, and SSR, but a sales agent page typically needs a client-side island for realtime interaction. The usual pattern is:

1. Render the page and call a backend endpoint from Astro server code or a server action.

2. Receive a short-lived session token, embed URL, or connection config.

3. Mount a client component that opens the media connection only after user intent.

Do not fetch privileged session details directly from the browser with your secret key. Instead, let Astro call your server endpoint, and let that endpoint call the avatar/session API.

// Example: Astro endpoint that proxies session creation

}

// Example: Astro endpoint that proxies session creation

}

// Example: Astro endpoint that proxies session creation

}

In the browser, the page can request that endpoint when the user clicks “Start call.” That keeps your API key on the server and gives you one place to enforce policy: rate limits, customer routing, CRM lookups, or user authorization.

Build the realtime handoff carefully

The browser side usually needs three pieces of state: connection status, session identity, and media playback state. Treat them separately. A session may exist before the user grants camera/mic permission. The agent may be connected before the avatar has a render-ready stream. And reconnects can happen without re-creating the business session.

One useful pattern is to make the client lifecycle explicit:

• Idle — no session requested yet.

• Pending — backend session created, client is negotiating media.

• Live — audio and avatar are connected.

• Ended — session closed; show transcript or next-step CTA.

This is especially important in a sales flow, where you often want the agent to greet a visitor, qualify intent, and then hand off to a human or schedule follow-up. Those are business transitions, not UI transitions, so keep them in the backend state machine.

Using a plugin in the voice agent backend

If your agent is already built on LiveKit Agents, the simplest path is to add the Protoface plugin so the voice agent gains a synchronized talking face. That keeps your existing telephony or browser voice pipeline intact and adds the avatar as a rendering layer rather than rewriting the agent.

The shape is straightforward: create the agent as you already do, then attach the avatar plugin where the outbound speech stream is available. The exact configuration depends on your avatar/session settings, but the basic idea is to route agent speech through the plugin and let it maintain lip sync with the video face.

# illustrative only; check the docs for exact classes and fields

agent.attach_avatar(avatar)

# illustrative only; check the docs for exact classes and fields

agent.attach_avatar(avatar)

# illustrative only; check the docs for exact classes and fields

agent.attach_avatar(avatar)

If you are not on LiveKit, the same conceptual model still applies: your voice agent produces an audio stream, and the avatar layer consumes that stream and outputs synchronized video. The implementation details change, but the integration points do not.

Why an iframe embed is often the safest frontend option

For many marketing sites and lead-gen pages, the fastest and safest integration is an iframe embed rather than a custom browser media pipeline. The reason is simple: you avoid exposing API keys in the browser, and the avatar session logic stays on the server side of the embed. That reduces the amount of code you need to maintain in Astro and makes the security model much easier to reason about.

An iframe is also a good fit if you want a customer-managed experience with per-embed voice, custom instructions, parent-origin allowlisting, and rate limits enforced by the provider. In other words, the browser only gets a sandboxed surface; the backend still owns the sensitive parts of the interaction.

This does trade off some control. If you want deep page-level instrumentation, custom call routing, or a tightly integrated chat/video layout, a direct frontend integration is more flexible. If you want to ship quickly and keep the browser thin, the iframe is usually the right default.

REST and Python are the tools for orchestration

Even if your end user never touches them, the REST API and Python SDK are what make production integration sane. Use them for avatar provisioning, session creation, QA automation, and internal tooling. A small backend service can create sessions on demand, store metadata, and link a session to a CRM record or support ticket.

import requests

session = resp.json()

import requests

session = resp.json()

import requests

session = resp.json()

That same pattern works for testing and automation. If you need to create a set of avatars for a sales team, rotate keys, or inspect usage, keep it out of the browser and in a small server-side integration. The developer dashboard is useful for day-to-day inspection, but production logic should live in code.

Practical gotchas when wiring Astro to realtime media

A few details tend to bite teams the first time they connect a frontend to a voice/video agent:

• Don’t start media too early. Wait for user interaction where browsers require it, especially for audio playback and mic capture.

• Expect reconnects. Network interruptions happen. Session identity should survive transient media failures when possible.

• Keep payloads small. Astro should move identifiers and short-lived tokens, not full transcripts or large binary blobs.

• Separate business logic from transport. The fact that a WebRTC track disconnected should not mean the sales lead is lost.

• Measure latency end to end. The user experiences one conversation, not separate STT/LLM/TTS/avatar systems.

For debugging, watch the full chain: browser permission prompt, session creation, agent connect time, first audio packet, first video frame, and recovery time after a dropped connection. That is the difference between a demo and something you can put in front of prospects.

Where Protoface fits

If you want to attach a synchronized talking face to an existing LiveKit voice agent, the LiveKit plugin is the cleanest path. If you want your Astro app to stay thin and avoid browser-exposed secrets, the customer-managed iframe embed is the quickest production-safe option. And if you need custom orchestration, the REST API and Python SDK are the control plane. The docs at docs.protoface.com cover the exact request/response shapes and the current session fields.

Conclusion

The right way to connect an Astro frontend to a voice + video sales agent is to keep the frontend small, keep credentials server-side, and treat the avatar as a realtime media concern rather than a UI gimmick. Astro should request session state and render the experience; your backend should own agent logic; the avatar layer should render synchronized video from the agent’s speech stream.

That architecture gives you a clean security boundary, predictable latency, and a path from prototype to production without rewriting the page every time the agent changes. If you want implementation details, start with the docs and then pick the integration surface that matches your stack: iframe for fast deployment, REST/Python for orchestration, or the LiveKit plugin for an existing voice agent pipeline.