Furnizori și fallback-uri

Fiecare etapă din pipeline e umplută de un furnizor pe care îl alegi tu, iar alegerea e un compromis între latență, cost și calitate. CallAgent pune toate trei cifrele lângă furnizor chiar în momentul în care îl alegi, îți spune pentru care dintre ele poate garanta, și te lasă să ordonezi fallback-uri pentru când unul are o după-amiază proastă.

Registry-ul

Furnizorii nu sunt o listă scrisă în cod. Stau în tabele de registry pe care le ține platforma — llm_models, transcriber_models, voices și tabelele lor de furnizori — fiecare rând purtând flag-uri de capabilități, coloane de preț și latența tipică publicată (typical_ttft_ms, typical_first_partial_ms, typical_ttfa_ms). Adăugarea unui model e un rând de registry, nu o schimbare de cod.

Citește-l prin API:

cURL

curl "$CALLAGENT_API_URL/registry/models" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY"

Node

const registry = await fetch(`${process.env.CALLAGENT_API_URL}/registry`, {
  headers: { Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}` },
}).then((response) => response.json());

GET /registry, /registry/models, /registry/model-providers, /registry/voices, /registry/transcribers și /registry/telephony — vezi referința registry-ului de furnizori.

Ce e definit

Astea sunt identificatoarele de furnizor definite în contracte. Faptul că un furnizor e definit nu înseamnă că instalarea ta îl poate atinge — asta depinde de existența unei credențiale pentru organizație, iar workbench-ul marchează etapele fără credențială.

Etapă	Furnizori
model	openai · anthropic · anthropic_bedrock · azure_openai · google · groq · cerebras · mistral · deepseek · xai · perplexity · together_ai · anyscale · deepinfra · openrouter · inflection_ai · minimax · custom_llm
transcriber	deepgram · assemblyai · speechmatics · gladia · soniox · azure · google · openai · openai_realtime · elevenlabs · cartesia · talkscriber · xai · custom
voce	elevenlabs · cartesia · playht · rime_ai · deepgram · openai · azure · microsoft · lmnt · hume · inworld · neuphonic · minimax · sesame · smallest_ai · wellsaid · xai · callagent · custom
speech to speech	openai_realtime · google_realtime · elevenlabs_realtime · custom_realtime
telefonie	twilio · telnyx · didww · plivo · zadarma · didlogic · amazon_chime · byo_sip · custom_sip_gateway · freeswitch · web
storage	aws_s3 · cloudflare_r2 · azure_blob · gcp_cloud_storage · supabase_storage · callagent_managed

custom_llm acceptă orice endpoint compatibil OpenAI: un baseUrl, un model, un credentialRef opțional și headerele tale.

Definit, înregistrat, verificat — trei lucruri diferite

„Definit" înseamnă mai sus că identificatorul există în contracte. Alte trei întrebări decid dacă un apel o să funcționeze, și au răspunsuri diferite.

Definit	Identificatorul există și API-ul îl acceptă.
Înregistrat	Procesul gateway are un adaptor care știe protocolul.
Verificat	Formatul de pe fir a fost implementat din documentația curentă a vendorului și revizuit față de ea.

Etapă	Definiți	Înregistrați	Verificați
model	18	17 + un shim custom_llm	13
transcriber	14	13 + un shim custom	3
voce	19	16 + shim-uri	2 — ElevenLabs și OpenAI
speech to speech	4	1	1

verified nu înseamnă „testat pe vendor"

Definiția din SDK-ul de furnizori, cuvânt cu cuvânt:

verified: true înseamnă că formatul de pe fir e implementat din documentația de protocol curentă și autoritară a vendorului și a fost revizuit față de ea. Niciun adaptor din pachetul ăsta nu a fost rulat pe un endpoint real în CI.

Niciun test nu depinde de o credențială vie; toate testele sunt pe fixture-uri. Doisprezece furnizori de voce au clienți HTTP reali îndreptați spre URL-uri reale de vendor, cu format de fir neverificat, iar doi — sesame și xai — nu au nicio integrare cu vendorul și funcționează doar pe un endpoint pe care îl pui tu și care vorbește protocolul TTS al CallAgent. callagent ca furnizor de voce e un strat de indirectare al cărui catalog e livrat gol.

Dovedește-ți singur furnizorul cu POST /credentials/{id}/test, apoi cu un apel real, înainte să depinzi de el. Vezi Ce nu este construit.

Din cele patru identificatoare de speech-to-speech, doar openai_realtime are un adaptor, iar pipeline-ul de speech-to-speech nu e conectat deloc la sesiunea live de apel.

Workbench-ul

Builder-ul de asistenți arată pipeline-ul ca trei carduri — ureche, creier, gură — cu o bară de latență segmentată pe culorile etapelor și un cost estimat pe minut deasupra. Alegerea unui furnizor schimbă toate trei citirile înainte să salvezi ceva.

Trei dintre citirile alea înseamnă lucruri diferite, iar interfața spune care:

Citire	Ce e de fapt
Latență	Timpul tipic publicat de vendor până la primul token sau primul audio, pe o conexiune caldă. CallAgent nu îl măsoară, deci e prefixat cu ~. Citirea p50 observat din propriile call_metrics nu e încă implementată.
Calitate	Un indice editorial 0–100, nu un scor de benchmark. E marcat și el.
Cost	O cifră reală doar unde registry-ul are un preț verificat. Unde nu are, cardul arată o bandă relativă de cost, nu un număr.

O cifră cu ~ e o estimare

Estimarea de cost pe minut e derivată dintr-o formă presupusă a conversației — un număr fix de tokeni de intrare, de ieșire și de caractere rostite pe minut. E utilă ca să compari doi furnizori; nu e o ofertă. Numărul care ți se facturează efectiv vine din GET /calls/{call}/costs după apel, calculat din cantități măsurate. Vezi Analytics și costuri.

Când doar unele etape au un preț verificat, estimarea arată un avertisment de tarifare parțială, în loc să însumeze în tăcere ce are. Un preț greșit dar sigur pe el e mai rău decât unul vizibil incomplet, pentru că cineva o să facă buget pe baza lui.

Cheia ta, contul tău

Credențialele de furnizor sunt per organizație și criptate cu CREDENTIAL_ENCRYPTION_KEY — intenționat nu cu APP_KEY, ca rotirea cheii aplicației să nu însemne recriptarea secretelor fiecărui tenant.

curl -X POST "$CALLAGENT_API_URL/credentials" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "class": "model",
    "provider": "openai",
    "name": "Production OpenAI",
    "secrets": { "api_key": "sk-…" }
  }'

secrets e obligatoriu; numele câmpurilor din el sunt ale vendorului. Vezi Pornire rapidă, pasul 2.

POST /credentials/{credential}/test face un apel HTTP real către furnizor și înregistrează rezultatul, ca „cheia e salvată" și „cheia funcționează" să rămână afirmații separate. Întoarce 200 în ambele cazuri și pune verdictul în body — citește ok și verified. Un furnizor pentru care CallAgent nu are o sondă se întoarce cu verified: false, ceea ce înseamnă că nu a întrebat nimeni, nu că e cheia proastă.

Un asistent referă o credențială prin credentialRef, niciodată prin valoare. Gateway-ul primește doar credențialele de care are nevoie un singur apel, rezolvate la pornirea apelului — nu primește niciodată tabela de credențiale a organizației.

Cu chei proprii, furnizorul te facturează direct, iar CallAgent taxează doar taxa de platformă. Ambele cifre se rețin, pentru că „de ce e factura mea numărul ăsta" are nevoie de amândouă.

Fallback-uri

Fiecare dintre model, transcriber, voice și speechToSpeech acceptă o listă ordonată fallbacks, cu maximum două intrări fiecare. Indexul 0 se încearcă primul.

model:
  provider: openai
  model: gpt-4o-mini
  temperature: 0.4
fallbacks:
  model:
    - { provider: groq, model: llama-3.3-70b-versatile }
    - { provider: anthropic, model: claude-haiku-4-5 }

Un fallback emite provider.fallback, care poartă componenta, furnizorul de la care s-a mutat și cel la care, motivul (timeout, error, rate_limit, auth, circuit_open, health_check) și numărul încercării. Evenimentul acela e cel care face ca „apelul a fost lent ieri" să aibă un răspuns.

Circuit breaking

Un furnizor care eșuează în continuu e scos din rotație, nu reîncercat la nesfârșit. Valorile implicite ale breaker-ului sunt failureThreshold: 5, successThreshold: 2, openMs: 30000, slowCallMs: 5000, iar cât e deschis codul de eroare e circuit_open — care se poate reîncerca.

Cum alegi un transcriber

Calitatea endpointing-ului nu e același lucru cu acuratețea transcrierii, iar pentru un agent vocal contează mai mult prima. Un transcriber cu o rată de eroare pe cuvinte puțin mai mare, dar cu un semnal fiabil de sfârșit de enunț, produce un apel care se simte mai bine decât unul precis care lasă asistentul să ghicească momentul vorbirii. Vezi Preluarea turului.

Boostul de cuvinte-cheie e celălalt reglaj care merită: termeni, fiecare cu un boost de la -10 la 10, care înclină recunoașterea spre numele produselor tale și departe de ce sună ele a fi.

E custom_keywords, la nivelul de sus

Contractul îi spune transcriber.keywords, iar control plane-ul nu îl citește acolo. Convertorul construiește lista de cuvinte-cheie a transcriber-ului din câmpul custom_keywords de la nivelul de sus al asistentului. Pune-l acolo.

{
  "transcriber": { "provider": "deepgram", "model": "nova-3", "smart_format": true, "numerals": true },
  "custom_keywords": [
    { "term": "Sibiu", "boost": 4 },
    { "term": "CallAgent", "boost": 6 }
  ]
}

Mai departe

• Cum funcționează un apel — de ce e responsabil fiecare furnizor.
• Asistenți — unde stau blocurile astea.
• Analytics și costuri — cât a costat de fapt un apel.