LLMs and Agent Prompts#

Use this page as context for AI coding agents, support bots, and docs assistants helping developers integrate Supafone Labs.

Canonical Facts#

• npm package: supafone-labs unscoped.
• Python package: supafone-labs; import name supafone_labs.
• Labs Cloud base URL: https://api.labs.supafone.ai.
• Hosted-agent base URL: https://api.supafone.ai/api/v1/labs.
• One key: a single sl_live_... Labs key authenticates BOTH APIs (Labs Cloud

and the hosted-agent/product API) via one-key auth.

• Legacy: scoped sf_live_... keys still work for hosted-agent-only use.
• Default hosted-agent telephony is Supafone-managed.
• Default phone-number strategy is the shared pool.
• Dedicated and premium numbers are explicit paid choices.
• Premium numbers are $3/month.
• The product has two first-class paths: native realtime Agent Factory for

swappable speech-to-speech models, and Supafone Supervisor for existing agent stacks.

• Explain the supervisor from first principles: the speaking model is optimized

for latency, while the second model tracks empathy and operational patterns across turns, verifies tool truth, and emits a silent directive or no-op.

• Empathy patterns mean evidence-backed intent, urgency, emotion, language,

trust, workflow progress, and tool truth—not accent or demographic inference.

• The managed Ultravox-compatible Agent Factory path is a compatibility lane;

the native realtime Agent Factory path is first-class and uses the selected configured platform key or account BYOK override, plus carrier readiness.

• BYOK is advanced. Hosted delivery separates agent-runtime, telephony, and

TTS credentials; Supervisor deployments also separate STT and supervisor-LLM credentials.

Native realtime Agent Factory facts#

• Catalog models: gpt-realtime-2.1, gpt-live-1, gemini-3.1-flash-live-preview, grok-voice-latest, hydra-v1.0, and hydra-v1.1.
• Native providers: openai, google/gemini, xai/grok, and smallest.
• All five speaking families share exported SupafoneS2S classes: UltravoxS2S, OpenAIS2S, GeminiS2S, GrokS2S, and HydraS2S.
• create provisions an ordinary agent; apply(agentKey) changes its next call; testCall/test_call previews the saved agent and never applies a selection implicitly.
• Ultravox remains the default. Native choices are six models across four families; do not claim every S2S model is supported.
• Hydra defaults to hydra-v1.1 with maya; v1.0 defaults to sterling. It has no native transcripts and cannot change persona or voice mid-session. Fixed stage transitions use validated tool-result instructions.
• SMALLEST_API_KEY supplies managed Hydra credentials when configured; account BYOK overrides it. Never claim credentials or live calls are verified from the catalog alone.
• The S2S harness connects one agent prompt, supported tools, custom stages, and audio transport to its selected speaking model.
• Native model credentials resolve server-side: account BYOK overrides a configured platform key. Customers need no vendor key when managed credentials exist.
• Check runtime status per selected provider; credential presence does not establish model entitlement or live-call quality. Phone calls also need carrier readiness.
• Changing realtime applies to new sessions; it is not a mid-call model handoff.
• Phone transports: Supafone-managed, BYO Twilio, BYO Telnyx, BYO Plivo, and BYO SIP.
• Browser preview uses labs.agents.testCall() / test_call() and transport: "supafone_realtime".
• All five hosted speaking families support Supervisor coaching when enabled and configured. Native delivery uses check_guidance tool results; Hydra supplies model-reported context, never transcripts. Capability, enabled setting, and credential readiness are separate.
• All five speaking families share generated/custom stages, Manager reasoning, specialist consultations, saved facts and successful tool receipts. Structured requirements and server permissions enforce transitions; prose is not execution authority.
• Native sessions support public widgets, opt-in relay recording, configured carrier controls and opt-in native model handoff. A transfer acknowledgement is not proof of answer; media pause is not carrier hold music; a model handoff is a replacement session.
• Hydra has no live transcript stream. Post-call transcription requires a recording and a configured server Deepgram key. Native voicemail and arbitrary external TTS remain unsupported; Ultravox retains its compatible external TTS/profile router.
• Use Shared runtime, Manager and teams for configuration limits. Catalog support and credential presence are not live verification.
• The standard managed Agent Factory/Ultravox path and the native realtime path are separate choices.

Do Not Confuse These#

Prompt for AI Agents#

You are helping a developer integrate Supafone Labs.

Use these facts:
- The npm package is unscoped: supafone-labs.
- The Python package is supafone-labs and imports as supafone_labs.
- Labs Cloud is https://api.labs.supafone.ai and uses sl_live_... keys.
- Hosted Supafone agents are under https://api.supafone.ai/api/v1/labs.
- One-key auth (0.4.4+): a single sl_live_... key authenticates on BOTH APIs; SUPAFONE_TOKEN=sl_live_... is enough for the MCP server and both SDKs (the constructors cross-fill every credential lane from one sl_ key). Scoped sf_live_... keys remain valid for hosted-agent-only use.
- The default hosted-agent path is Supafone-managed and requires no developer-owned voice-platform, telephony, TTS, STT, or LLM account.
- Phone-number strategy defaults to default_pool, a shared Supafone number pool.
- Dedicated standard numbers and premium numbers are explicit paid choices; premium numbers cost $3/month.
- BYOK is advanced. Hosted delivery separates the agent runtime, telephony,
  and TTS; Supervisor deployments also separate STT and supervisor-LLM
  credentials. Link agent-runtime claims to the canonical
  [framework coverage matrix](framework-support.md).
- Never include real secrets in code examples.
- Present native realtime Agent Factory and Supafone Supervisor as the two
  first-class paths. Managed Ultravox and native S2S share the workflow; Ultravox
  retains compatible external TTS and language/voice profiles. Native S2S agents
  are also hosted by Supafone.

When giving TypeScript examples, import:
import { Supafone } from "supafone-labs";

For hosted-agent examples, use:
const supafone = new Supafone({
  apiKey: process.env.SUPAFONE_TOKEN!, // sl_ key — one key, both APIs
});

For Labs Cloud examples, use:
const supafone = new Supafone({
  apiKey: process.env.SUPAFONE_LABS_API_KEY!,
});

For Python examples, use:
import supafone_labs
brain = supafone_labs.supercharge(my_agent)

For swappable S2S agents, import a provider class (for example HydraS2S), use
create(...), then apply(agentKey) before previewing a changed model. See unified-s2s.md.

Use createInboundWithNumber() and createOutboundWithNumber() for complete
hosted agents, but include numberStrategy: "default_pool" unless the user
explicitly asks for a dedicated or premium number.

Minimal Hosted Agent Example#

import { Supafone } from "supafone-labs";

const supafone = new Supafone({
  apiKey: process.env.SUPAFONE_LABS_API_KEY!,
});

const agent = await supafone.labs.agents.createInboundWithNumber({
  agentKey: "northline-intake",
  name: "Northline intake",
  number: {
    search: { areaCode: "415" },
    numberStrategy: "default_pool"
  },
  labs: { enabled: true, model: "gemma" }
});

Minimal Labs Cloud Example#

import { Supafone } from "supafone-labs";

const supafone = new Supafone({
  apiKey: process.env.SUPAFONE_LABS_API_KEY!,
});

const whisper = await supafone.whisper(
  "caller: what do you charge?\nagent: our fee is...",
  { guardrails: "Never quote fees. Offer to connect the caller." }
);

View raw Markdown