Developer Workflows#

One superclass, five providers#

Import SupafoneS2S and its provider classes: UltravoxS2S, OpenAIS2S, GeminiS2S, GrokS2S, and HydraS2S. Each offers create, apply, and testCall (Python test_call) through the same hosted agent contract. apply changes the next call on the existing agent; preview always uses the saved configuration. See complete Python and TypeScript examples.

Labs builder: open the agent workspace and choose Ultravox, OpenAI, Gemini, Grok, or Hydra directly in Setup. Native providers expose a model and voice selector on the same page. Speaking model & voice shows the selected native voice or the Ultravox-compatible TTS catalog. The Supafone dashboard also supports model selection for saved agents.

Build a durable agent with Agent Factory, then choose its speech-to-speech model through Supafone's S2S harness. The harness reuses the same prompt, supported tools, custom stages, team, and browser/carrier contracts when you switch among supported models.

Build, save and test in Labs#

1. Create an agent or open a saved one, then select its speaking provider,

model and voice in Setup. Switching the selection keeps the workflow and specialist configuration in the editor.

2. Open Workflow. Choose a managed plan with 3–8 stages, or customize the

stages, saved fields, tool permissions and progression rules. Enable Manager and a specialist team if the job needs them.

3. Save or create the agent. Start browser call uses the saved server

configuration; unsaved changes must be saved before a new test starts.

4. In Test browser voice, allow microphone access and start the call.

Check the actual connection status, available transcripts and Supervisor events, then use End call to close the session.

The model picker changes future calls after saving. It does not switch the speaker inside an active call. Opt-in native runtime handoff is a separate allowlisted configuration; see Shared runtime.

Choose the speaking model#

Every catalog model has browser and phone adapters for Supafone-managed phone, BYO Twilio, BYO Telnyx, BYO Plivo, and BYO SIP. Discover the current choices through supafone.labs.capabilities(); catalog support is distinct from your workspace's credential and carrier readiness.

Start with managed provider keys#

Authenticate with your Supafone API key. The selected model uses a configured Supafone platform key unless your account has supplied an encrypted BYOK key for that provider. Read GET /api/v1/labs/runtime?provider=openai (or google, xai, smallest) to check the source and status before calling. Customers do not need to paste a provider key when the platform supplies one.

source: platform means a server credential exists. source: account means an account key overrides it. none or invalid means setup is required. Readiness does not prove that a key has model access; run a real preview after selecting it. Keep model credentials separate from your Supafone application key and from carrier credentials. See Managed keys and BYOK.

Create and preview#

import { Supafone, HydraS2S } from "supafone-labs";

const supafone = new Supafone({ apiKey: process.env.SUPAFONE_TOKEN! });
const engine = new HydraS2S(supafone, { model: "hydra-v1.1", voice: "maya" });
const agent = await engine.create({
  agentKey: "northline-intake",
  name: "Northline intake",
  description: "Answer inquiries, capture the request, and book the next step.",
  telephony: { mode: "supafone_managed", provider: "supafone" },
});
const preview = await engine.testCall("northline-intake");

import os
from supafone_labs import Supafone, HydraS2S

supafone = Supafone(api_key=os.environ["SUPAFONE_TOKEN"])
engine = HydraS2S(supafone, model="hydra-v1.1", voice="maya")
agent = engine.create(
    agentKey="northline-intake",
    name="Northline intake",
    description="Answer inquiries, capture the request, and book the next step.",
    telephony={"mode": "supafone_managed", "provider": "supafone"},
)
preview = engine.test_call("northline-intake")

The returned browser session has a one-use ticket and sample rates. Use the Labs browser test, dashboard preview or a compatible audio client to speak to the agent; testCall alone creates the session. No provider secret is returned.

OpenAI, Gemini, Grok and Hydra use Supafone's native PCM audio connection over a WebSocket. Ultravox uses its existing WebRTC client and join URL. The builder selects the correct client from the returned session; a native session does not need an Ultravox join URL. All model keys remain server-side.

The transcript panel shows provider transcripts when available. Hydra has no native live transcript stream: an empty transcript panel is not a failed microphone or a silent call. Optional post-call transcription of a recording is a separate artifact, not a substitute live stream.

Switch an existing agent#

import { OpenAIS2S } from "supafone-labs";

const next = new OpenAIS2S(supafone, { model: "gpt-realtime-2.1", voice: "marin" });
await next.apply("northline-intake");
const preview = await next.testCall("northline-intake");

from supafone_labs import OpenAIS2S

next_engine = OpenAIS2S(supafone, model="gpt-realtime-2.1", voice="marin")
next_engine.apply("northline-intake")
preview = next_engine.test_call("northline-intake")

Use the same methods with GeminiS2S, GrokS2S, or HydraS2S. Applying UltravoxS2S returns to the managed default. Preview uses the saved agent; call apply before testing a new selection.

A model change takes effect on a new session and keeps the agent's phone assignment, configured tools, custom stages and team. Select a voice valid for the new model and compare behavior with the same tasks. Speech, timing and tool decisions can differ by provider. An active call uses its frozen workflow; opt-in native broker handoff is a separate control.

Move from browser to phone#

Keep the realtime selection and configure the phone lane. Supafone-managed phone uses approved managed infrastructure; BYO Twilio, Telnyx, Plivo, and SIP use their own account credentials and routing. Browser success does not prove carrier readiness. Test caller ID, webhook signatures, inbound routing, and outbound behavior for the selected carrier. Follow the native carrier guide.

Enable coaching for any speaking model#

Set supervisor: true or a managed/BYOK Supervisor configuration on the agent. All five hosted speaking families support coaching. Native OpenAI, Gemini, Grok, and Hydra request guidance through check_guidance; Hydra supplies model-reported context because it does not emit transcripts. The Supervisor model needs its own configured credentials. An enabled setting is not proof of a running coach. See hosted coaching.

The browser test's Supafone Supervisor feed shows actual server events. It distinguishes observed events from delivery acknowledgements and reports when coaching is disabled, no event has arrived, or the feed is unavailable. Showing the feed does not enable coaching or prove guidance was delivered. Hydra guidance uses model-reported context rather than a native transcript.

Configure the shared workflow#

All five speaking families share the 3–8 stage planner, server-side tools, durable facts and tool receipts, execution gates, Manager reasoning, specialist consultations and Supervisor coaching. The server checks account ownership and active stage/role permissions before tool execution.

Native sessions also support public widgets, opt-in recording, optional post-call transcription, configured carrier controls and opt-in native model handoff. These controls have explicit limits: a transfer acknowledgement is not an answered call, media pause is not carrier hold music, and a model handoff opens a replacement session rather than restoring provider-hidden state. Hydra has no live transcript stream. See Shared runtime, Manager and teams.

In the Workflow tab:

• Fields this agent can save defines the names allowed in captured facts.

Custom stages can require those saved fields and successful tool receipts before advancing. A spoken claim that a booking succeeded is not a receipt.

• Each custom stage has a stable key, goal, optional instructions, tool

permissions, allowed next stages and optional specialist ID. The default progression follows the next stage in order; an explicit empty next-stage list stops further transitions.

• Default tool permissions inherit the configured tools. An explicit empty

tool list permits no business tools; call controls have separate checks.

• Enable Manager adds bounded reasoning about stages and specialists.

The defaults are 12 tasks per call, 2 in parallel and a 6-second timeout; the controls allow 1–30 tasks, 1–4 in parallel and 1–15 seconds. These are enforced call budgets, including failed or timed-out work.

• Enable specialist team adds named roles, instructions and stage scopes.

Use a custom plan to bind a role to specific stage keys. A blank scope allows all configured stages. Specialist tool permissions can restrict, but cannot widen, a stage's permissions.

• Use the current date and time supplies server time. Leave Timezone

blank to inherit the account setting, or enter an IANA name such as America/New_York.

Manager proposes an assignment or legal stage change, specialists return private advice, and Supervisor coaches the speaking model. The selected S2S model remains the caller-facing speaker. The shared server runtime checks facts, tool receipts and permissions before an action takes effect.

Opt in to call artifacts#

Record calls and Transcribe recordings start off. For native S2S, post-call transcription requires recording and a configured Supafone Deepgram key. Live provider transcripts remain independent of these settings.

The saved recording contract accepts enabled, transcribe and optional max_duration_seconds (1–1800). The builder exposes the two toggles and preserves an existing duration cap; set the cap through the API or SDK:

{"recording": {"enabled": true, "transcribe": true, "max_duration_seconds": 900}}

The duration cap limits recorded audio, not the call's permitted duration. These settings do not configure retention deletion, PII redaction or a consent announcement. retention_days is not supported. Use Shared runtime for recording and artifact details.

Keep compatible Ultravox voice features#

Omitting realtime keeps the managed Ultravox runtime, including compatible external TTS and opt-in live language/voice routing. Native providers use their own voices and configured handoff languages; they do not use that same external-TTS profile router.

Agent Factory, custom tools, and campaigns as code describe their own setup and runtime boundaries.

Supervise an existing agent#

Supafone Supervisor is a separate offering for a supported agent you already run. It observes events and proposes bounded guidance; delivery capability varies by adapter.

import supafone_labs

brain = supafone_labs.supercharge(my_agent)
result = await brain.observe(raw_platform_event)

Check framework coverage and programmable directives. The presence of a Supervisor adapter for a provider is separate from hosted Agent Factory support. All five hosted speaking families support coaching; an individual agent must also have supervision enabled and a configured Supervisor model.

Key Routing#

One linked sl_ key can authenticate both APIs. See API keys and auth. Exports should contain the selected realtime provider/model/voice and phone configuration, never resolved provider secrets.

View raw Markdown