Supafone Labs ยท Documentation

SDK Parity#

The Python and TypeScript SDKs should let developers do the same work with the same vocabulary. Use camelCase in TypeScript and snake_case in Python, but keep the payload concepts identical.

Install#

bash
pip install "supafone-labs[all]"
npm i supafone-labs

One-Line Framework#

Python:

python
import supafone_labs

brain = supafone_labs.supercharge(my_agent)

TypeScript developers usually call the hosted cloud/client surface directly:

ts
import { Supafone } from "supafone-labs";

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

Hosted Agent Factory#

TypeScript:

ts
const agent = await supafone.labs.agents.createInboundWithNumber({
  agentKey: "northline-intake",
  name: "Northline intake",
  assistantName: "Maya",
  websiteUrl: "https://northline.example",
  number: { search: { areaCode: "415" } },
  labs: { enabled: true, model: "gemma" },
});

Python:

python
agent = supafone.labs.agents.create_inbound_with_number({
    "agentKey": "northline-intake",
    "name": "Northline intake",
    "assistantName": "Maya",
    "websiteUrl": "https://northline.example",
    "number": {"search": {"areaCode": "415"}},
    "labs": {"enabled": True, "model": "gemma"},
})

Python also exposes camelCase aliases for developers copying TypeScript-shaped configs:

python
agent = supafone.labs.agents.createInboundWithNumber({
    "agentKey": "northline-intake",
    "name": "Northline intake",
    "number": {"search": {"areaCode": "415"}},
    "labs": {"enabled": True},
})

One Contract, Four Entry Points#

The stage planner and Agent Factory are public API capabilities. TypeScript is one client, not the implementation boundary:

Entry pointPreview a generated planCreate the runnable agent
RESTPOST /api/v1/labs/agent-plansPOST /api/v1/labs/agents
TypeScriptgenerateCallStages() / labs.agents.plan()labs.agents.create()
Pythongenerate_call_stages() / labs.agents.plan()labs.agents.create()
MCPgenerate_call_stageshosted-agent creation tools

Every entry point uses the same authenticated service, validation rules, fallback behavior, JSON plan shape, and executable multi-stage runtime. A team can prototype through MCP, ship the same operation through REST, and operate it with either SDK without translating the contract.

Method Map#

CapabilityTypeScriptPython
Create generic hosted agentsupafone.labs.agents.create()supafone.labs.agents.create()
Preview hosted call plansupafone.generateCallStages() / labs.agents.plan()supafone.generate_call_stages() / labs.agents.plan()
Discover capabilitiessupafone.labs.capabilities()supafone.labs.capabilities()
List agent presetssupafone.labs.presets.list()supafone.labs.presets.list()
List runtime toolssupafone.labs.tools.list()supafone.labs.tools.list()
List/filter hosted voicessupafone.labs.voices.list()supafone.labs.voices.list()
Read/configure Ultravox runtimesupafone.labs.runtime.get/configure()supafone.labs.runtime.get/configure()
Create inbound agentcreateInbound()create_inbound() / createInbound()
Create outbound agentcreateOutbound()create_outbound() / createOutbound()
Create inbound + numbercreateInboundWithNumber()create_inbound_with_number() / createInboundWithNumber()
Create outbound + numbercreateOutboundWithNumber()create_outbound_with_number() / createOutboundWithNumber()
Configure live language/voice routingAgent create config: languageVoiceRouting, routingLanguages, languageProfilesSame fields, plus snake_case aliases
Search numberssupafone.labs.phoneNumbers.search()supafone.labs.phone_numbers.search()
Buy and assign numberbuyAndAssign()buy_and_assign() / buyAndAssign()
Configure telephonysupafone.labs.telephony.configure()supafone.labs.telephony.configure()
List/fetch/delete hosted callssupafone.labs.calls.list/get/delete()supafone.labs.calls.list/get/delete()
Durable activity and generated planssupafone.labs.activity/plans.list()supafone.labs.activity/plans.list()
List/fetch/remove recordingssupafone.labs.recordings.list/get/delete()supafone.labs.recordings.list/get/delete()
List/fetch transcriptssupafone.labs.transcripts.list/get()supafone.labs.transcripts.list/get()
Usagesupafone.usage()supafone.usage()
Log snapshotsupafone.logs()supafone.logs()
Log streamsupafone.streamLogs()supafone.stream_logs() / streamLogs()
Start browser WebRTC sessionsupafone.startWebRtcCall() / startBrowserCall()supafone.start_webrtc_call() / startWebRtcCall()
Call a human from an owned agentsupafone.callFromAgent()supafone.call_from_agent()
Grade an existing phone agentsupafone.tester.gradeAgent()supafone.tester.grade_agent()
Fetch one call (live transcript)supafone.getCall()supafone.get_call()
Classify a finished callsupafone.classifyCall()supafone.classify_call()
Auto post-call analysispostCallAnalysis: truepost_call_analysis=True
Brand scansupafone.scanBrand()supafone.scan_brand()
Generate intake formsupafone.generateIntakeForm()supafone.generate_intake_form()
Campaign lifecyclesupafone.campaigns.create/get/list/update/launch/pause()same names, snake_case
Campaign live monitoringcampaigns.live/getCall()campaigns.live/get_call()
Campaign config (YAML)campaigns.validateConfig/applyConfig/exportConfig/generateConfig()campaigns.validate_config/apply_config/export_config/generate_config()
E-sign documentscampaigns.uploadSigningDocument/detectSignatureFields/setSignatureFields()campaigns.upload_signing_document/detect_signature_fields/set_signature_fields()
QA suites + SSR gradingsupafone.qa.generate/run/suite/history()supafone.qa.generate/run/suite/history()
Labs session loginsupafone.labsLogin()supafone.labs_login()

BYOK Parity#

The SDKs preserve independent provider domains:

LaneExamples
Agent/provider stackFourteen audited runtime adapters
TelephonyTwilio, Telnyx, Plivo, SignalWire, SIP/custom trunks
TTSCartesia, ElevenLabs, Inworld, Deepgram, custom TTS
STTDeepgram or provider-native transcript streams
Supervisor LLMSupafone hosted, Anthropic, OpenAI, xAI, custom LLM

TypeScript:

ts
await supafone.labs.agents.createOutbound({
  agentKey: "speed-to-lead",
  name: "Speed to lead",
  labs: {
    enabled: true,
    mode: "byok",
    managedInfrastructure: false,
    stt: { provider: "deepgram", model: "nova-3" },
    llm: { provider: "anthropic", model: "claude-3-5-sonnet" },
    tts: { provider: "cartesia", voiceId: "sonic-warm" },
  },
  byok: {
    agentProvider: {
      provider: "ultravox",
      apiKey: process.env.ULTRAVOX_API_KEY!,
    },
    telephony: {
      mode: "byok",
      provider: "telnyx",
      credentials: {
        apiKey: process.env.TELNYX_API_KEY!,
        connectionId: process.env.TELNYX_CONNECTION_ID!,
        fromNumber: "+14155550123",
      },
    },
    tts: {
      provider: "cartesia",
      apiKey: process.env.CARTESIA_API_KEY!,
    },
  },
});

Python:

python
supafone.labs.agents.create_outbound({
    "agentKey": "speed-to-lead",
    "name": "Speed to lead",
    "labs": {
        "enabled": True,
        "mode": "byok",
        "managedInfrastructure": False,
        "stt": {"provider": "deepgram", "model": "nova-3"},
        "llm": {"provider": "anthropic", "model": "claude-3-5-sonnet"},
        "tts": {"provider": "cartesia", "voiceId": "sonic-warm"},
    },
    "byok": {
        "agentProvider": {
            "provider": "ultravox",
            "apiKey": os.environ["ULTRAVOX_API_KEY"],
        },
        "telephony": {
            "mode": "byok",
            "provider": "telnyx",
            "credentials": {
                "apiKey": os.environ["TELNYX_API_KEY"],
                "connectionId": os.environ["TELNYX_CONNECTION_ID"],
                "fromNumber": "+14155550123",
            },
        },
        "tts": {
            "provider": "cartesia",
            "apiKey": os.environ["CARTESIA_API_KEY"],
        },
    },
})

Flat providerKeys remains supported for simple configs and older examples, but new docs and UI should prefer the structured byok object so agent platform, telephony, and TTS credentials do not get mixed together.

Parity Notes#

View raw Markdown