Przejdź do głównej treści
Polski— Wybierz język
Menu

Konfiguracja sesji za pomocą session.update

Lekcja 3 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Skonfiguruj swojego agenta głosowego
  2. Pełna struktura session.update
  3. Szczegółowy opis ustawień
  4. Aktualizacja sesji w trakcie rozmowy
  5. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie stron xAI Speech to Speech oraz Text to Speech: 28 wbudowanych głosów, a parametr turn_detection ustawiany jest wyłącznie przez jego pole type (z opcjonalnym idle_timeout_ms). Źródła: Speech to Speech · Text to Speech.

Skonfiguruj swojego agenta głosowego

Gdy połączenie WebSocket zostanie nawiązane i otrzymasz zdarzenie session.created, skonfiguruj sesję, wysyłając wiadomość session.update. To tutaj definiujesz zachowanie swojego agenta głosowego: jego osobowość, głos, narzędzia, z których może korzystać, oraz sposób wykrywania zmian mówcy (turn detection).

Pełna struktura session.update

Oto szczegółowy przykład konfiguracji:

{
  "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}
      }
    }
  }
}

Szczegółowy opis ustawień

Instrukcje (monit systemowy)

Pole instructions odpowiada monitowi systemowemu (system prompt) w interfejsach API tekstowych: definiuje osobowość, kontekst i ograniczenia Twojego agenta głosowego. Pisanie go wiąże się jednak z ograniczeniem specyficznym dla głosu: zwięzłością. Każdy token monitu jest przetwarzany przed pierwszą odpowiedzią, a rozwlekły prompt powoduje zauważalne opóźnienia w momencie nawiązania połączenia. Trzymaj się essentials i przenoś szczegóły do logiki swojej aplikacji. W ramach tego ścisłego budżetu trzy elementy zasługują na uwagę. Ton (formalny, przyjazny, techniczny), ponieważ agent głosowy dosłownie uosabia Twoją markę w uchu klienta. Język: określ go („odpowiadaj po angielsku“), inaczej agent może podążać za językiem użytkownika lub pytaniem. I limity: co agent może zrobić, a przede wszystkim czego musi odmówić lub przekazać człowiekowi, ponieważ w rozmowie telefonicznej odpowiedź wykraczająca poza zakres zostaje wypowiedziana, zanim ktokolwiek zdąży ją zweryfikować.

Głos

Ustawienie voice akceptuje jeden z 28 wbudowanych głosów xAI (stan na 3 listopada 2026 r.), współdzielonych przez agenta głosowego i syntezę mowy (text-to-speech), lub identyfikator głosu niestandardowego utworzonego za pomocą interfejsu API Custom Voices. Identyfikatory głosów nie rozróżniają wielkości liter: eve, Eve i EVE odnoszą się do tego samego głosu. Każdy głos obsługuje każdy obsługiwany język.

Pięć oryginalnych głosów, zgodnie z opisem xAI:

  • eve: energiczny i radosny, brytyjski akcent
  • ara: ciepły i przyjazny
  • rex: pewny siebie i wyraźny
  • sal: gładki i zrównoważony
  • leo: autorytatywny i potężny, brytyjski akcent

Dołącza do nich dwadzieścia trzy nowsze głosy: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora oraz liora. Aktualną listę, wraz z tonem i przypadkami użycia dla każdego głosu, możesz uzyskać poprzez wywołanie GET /v1/tts/voices lub na stronie xAI Text to Speech.

Narzędzia

Tablica tools definiuje narzędzia, które agent może wywołać podczas rozmowy. Możesz łączyć różne typy: wyszukiwanie w sieci, wyszukiwanie w X, funkcje niestandardowe, kolekcje RAG i serwery MCP. Kolejne lekcje szczegółowo omawiają narzędzia.

Konfiguracja audio

Obiekt audio ustawia formaty wejścia i wyjścia. Możesz użyć różnych formatów dla wejścia i wyjścia, jeśli wymaga tego Twoja architektura (na przykład odbieranie G.711 z systemu telefonicznego i wysyłanie PCM do przeglądarki).

Aktualizacja sesji w trakcie rozmowy

Możesz wysyłać session.update wielokrotnie w trakcie rozmowy. Pozwala to na zmianę zachowania agenta w locie:

// Zmień głos w trakcie rozmowy
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    voice: "Ara"
  }
}));

// Dodaj kolejne narzędzie
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [
      { type: "web_search" },
      { type: "x_search" }
    ]
  }
}));

Dokumentacja xAI wyraźnie obsługuje zmiany w trakcie sesji dla kilku ustawień (język transkrypcji, słowa kluczowe, zamiany wymowy, transport audio), a zdarzenie session.updated potwierdza ich zastosowanie: sprawdź je, aby potwierdzić użytą konfigurację.

Kluczowe wnioski

  • session.update to pierwsza wiadomość do wysłania po otrzymaniu session.created
  • Pole instructions definiuje osobowość i ograniczenia agenta
  • Dostępnych jest 28 wbudowanych głosów (w tym eve, ara, rex, sal i leo) oraz głosy niestandardowe
  • Konfiguracja audio i narzędzia są konfigurowalne
  • Możesz wysyłać session.update wielokrotnie, aby zmienić zachowanie w trakcie rozmowy