Salt la conținutul principal
Română— Alege o limbă
Meniu

Configurați sesiunea cu session.update

Lecția 3 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Configurați agentul vocal
  2. Structura completă a session.update
  3. Detalierea setărilor
  4. Actualizarea sesiunii în timpul conversației
  5. Puncte cheie

Actualizat la 3 noiembrie 2026, pe baza paginilor xAI Speech to Speech și Text to Speech: 28 de voci integrate și turn_detection setat doar prin type (cu idle_timeout_ms opțional). Surse: Speech to Speech · Text to Speech.

Configurați agentul vocal

Odată ce conexiunea WebSocket este deschisă și ați primit evenimentul session.created, configurați sesiunea trimițând un mesaj session.update. Aici definiți comportamentul agentului vocal: personalitatea sa, vocea, instrumentele pe care le poate utiliza și modul în care detectează schimbarea vorbitorului.

Structura completă a session.update

Iată un exemplu detaliat de configurare:

{
  "type": "session.update",
  "session": {
    "instructions": "You are a professional voice assistant for a law firm. Answer concisely and precisely. Use a formal tone.",
    "voice": "Rex",
    "tools": [
      {"type": "web_search"},
      {
        "type": "function",
        "name": "look_up_case",
        "description": "Looks up a client case by number",
        "parameters": {
          "type": "object",
          "properties": {
            "case_number": {
              "type": "string",
              "description": "Client case number"
            }
          },
          "required": ["case_number"]
        }
      }
    ],
    "turn_detection": {
      "type": "server_vad"
    },
    "audio": {
      "input": {
        "format": {"type": "audio/pcm", "rate": 24000}
      },
      "output": {
        "format": {"type": "audio/pcm", "rate": 24000}
      }
    }
  }
}

Detalierea setărilor

Instrucțiuni (prompt de sistem)

Câmpul instructions echivalează cu promptul de sistem din API-urile text: acesta definește personalitatea, contextul și constrângerile agentului vocal. Redactarea sa implică totuși o constrângere specifică vocii: concizia. Fiecare token al promptului este procesat înainte de primul răspuns, iar un prompt excesiv de lung vă va costa o latență vizibilă imediat după conectarea apelului. Limitați-vă la esențial și mutați detaliile în logica aplicației dumneavoastră. În cadrul acestui buget restrâns, trei elemente merită incluse. Tonul (formal, prietenos, tehnic), deoarece agentul vocal întruchipează literalmente marca dumneavoastră la urechea clientului. Limba: specificați-o („răspundeți în engleză“), altfel agentul ar putea urma limba utilizatorului sau a întrebării. Și limitele: ce poate face agentul și, mai ales, ce trebuie să refuze sau să transfere unui operator uman, deoarece la telefon un răspuns care depășește domeniul de aplicare este emis înainte ca cineva să îl poată verifica.

Voce

Setarea voice acceptă una dintre cele 28 de voci integrate xAI (la data de 3 noiembrie 2026), partajate de agentul vocal și de text-to-speech, sau ID-ul unei voci personalizate create cu API-ul Custom Voices. ID-urile vocilor nu fac distincția între majuscule și minuscule: eve, Eve și EVE se referă toate la aceeași voce. Fiecare voce vorbește fiecare limbă suportată.

Cele cinci voci originale, așa cum sunt descrise de xAI:

  • eve: energică și optimistă, accent britanic
  • ara: caldă și prietenoasă
  • rex: încrezătoare și clară
  • sal: fluidă și echilibrată
  • leo: autoritară și puternică, accent britanic

Douăzeci și trei de voci noi li se alătură: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora și liora. Puteți obține lista actuală, cu tonalitatea și cazurile de utilizare pentru fiecare voce, din GET /v1/tts/voices sau de pe pagina xAI Text to Speech.

Instrumente

Tabloul tools definește instrumentele pe care agentul le poate apela în timpul conversației. Puteți combina mai multe tipuri: căutare web, căutare X, funcții personalizate, colecții RAG și servere MCP. Lecțiile următoare acoperă instrumentele în detaliu.

Configurarea audio

Obiectul audio setează formatele de intrare și de ieșire. Puteți utiliza formate diferite pentru intrare și ieșire dacă arhitectura dumneavoastră o impune (de exemplu, recepționarea G.711 de la un sistem telefonic și trimiterea PCM către un browser).

Actualizarea sesiunii în timpul conversației

Puteți trimite session.update de mai multe ori în timpul unei conversații. Acest lucru vă permite să schimbați comportamentul agentului din mers:

// Schimbă vocea în timpul conversației
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    voice: "Ara"
  }
}));

// Adaugă un alt instrument
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [
      { type: "web_search" },
      { type: "x_search" }
    ]
  }
}));

Documentația xAI suportă explicit modificările în timpul sesiunii pentru mai multe setări (limba de transcriere, cuvinte cheie, înlocuiri de pronunție, transport audio), iar session.updated le confirmă: verificați-l pentru a confirma configurația care a fost aplicată.

Puncte cheie

  • session.update este primul mesaj de trimis după session.created
  • Câmpul instructions definește personalitatea și constrângerile agentului
  • Sunt disponibile 28 de voci integrate (inclusiv eve, ara, rex, sal și leo), plus voci personalizate
  • Configurarea audio și instrumentele sunt personalizabile
  • Puteți trimite session.update de mai multe ori pentru a schimba comportamentul în timpul conversației