Gérer les sessions d’agent

Une session correspond à une conversation avec un agent. init() renvoie une VoiceAgentSession : vous vous abonnez à ses événements, coupez ou réactivez le microphone, attendez sa fin et fermez-la. Cette page s'adresse aux développeurs qui veulent aller au-delà de la première démonstration avec un agent. Elle suppose qu'un agent est en cours d'exécution ; consultez le guide de démarrage. La session fonctionne de la même manière en Python, dans Node.js et dans le navigateur, où initSession() la renvoie.

Cycle de vie

Une session se connecte, échange de l'audio et des événements pendant que la conversation se déroule, puis se termine. Coupez le microphone avec set_input_enabled(False), attendez la fin avec wait(), et appelez toujours close() lorsque vous avez terminé.

await session.set_input_enabled(False)  # mute
await session.set_input_enabled(True)   # unmute

await session.wait()   # blocks until disconnected
await session.close()  # close the session, should always be called

await session.set_input_enabled(False)  # mute
await session.set_input_enabled(True)   # unmute

await session.wait()   # blocks until disconnected
await session.close()  # close the session, should always be called

init() crée la session avec POST /v1/audio/sessions, et close() la supprime avec DELETE /v1/audio/sessions/{id}. Pour appeler vous-même ces endpoints, utilisez client.audio.sessions.create(...) et client.audio.sessions.close(session_id).

Événements

Enregistrez un gestionnaire avec session.on(event, handler).

Événement	Données	Action à effectuer dans votre application
`connected`	`session_id`	Marquez la session comme prête.
`disconnected`	`session_id`, `reason`	Arrêtez l'audio et libérez les ressources.
`transcript`	`id`, `role`, `content`, `final`	Affichez les transcriptions partielles en direct (`final` est faux), et conservez les transcriptions finales.
`audio`	bytes	Lisez vous-même l'audio de l'agent si vous gérez l'audio manuellement. Consultez Audio personnalisé.
`audio_track`	`track`, `source`	Dans le navigateur, attachez la piste média.
`agent_state_changed`	`state` (`listening`, `thinking`, `speaking`, et d'autres)	Mettez à jour l'interface.
`tool_call_started`	`id`, `name`	Indiquez que l'agent travaille. Les arguments ne sont pas encore connus.
`tool_call_ended`	`id`, `name`, `arguments`, `result`	Affichez le résultat.
`unhandled_tool`	`name`, `arguments`	Écrivez-le dans les logs : l'agent a appelé un outil client qui n'a pas de gestionnaire.
`error`	`message`, `fatal`, `code`, `source`	Signalez-le. Si `fatal` est vrai, la session est en cours de fermeture ; consultez Erreurs et nettoyage.

disconnected n'a pas de reason après une fermeture normale. Sinon, reason vaut user_interrupt, start_failed, audio_input_error, audio_output_error ou error.

from mistralai.extra.voice_agents import (
    VoiceAgentErrorEvent,
    VoiceAgentStateChangedEvent,
    VoiceAgentToolCallEndedEvent,
    VoiceAgentToolCallStartedEvent,
    VoiceAgentTranscriptEvent,
)

def on_transcript(event: VoiceAgentTranscriptEvent) -> None:
    print(f"{event.role}: {event.content}")

def on_tool_call_started(event: VoiceAgentToolCallStartedEvent) -> None:
    print(f"tool call started: {event.name}")

def on_tool_call_ended(event: VoiceAgentToolCallEndedEvent) -> None:
    print(f"tool call ended: {event.name} -> {event.result!r}")

def on_agent_state_changed(event: VoiceAgentStateChangedEvent) -> None:
    print(f"state: {event.state}")

def on_error(event: VoiceAgentErrorEvent) -> None:
    print(f"error (fatal={event.fatal}): {event.message}")

session.on("transcript", on_transcript)
session.on("tool_call_started", on_tool_call_started)
session.on("tool_call_ended", on_tool_call_ended)
session.on("agent_state_changed", on_agent_state_changed)
session.on("error", on_error)

from mistralai.extra.voice_agents import (
    VoiceAgentErrorEvent,
    VoiceAgentStateChangedEvent,
    VoiceAgentToolCallEndedEvent,
    VoiceAgentToolCallStartedEvent,
    VoiceAgentTranscriptEvent,
)

def on_transcript(event: VoiceAgentTranscriptEvent) -> None:
    print(f"{event.role}: {event.content}")

def on_tool_call_started(event: VoiceAgentToolCallStartedEvent) -> None:
    print(f"tool call started: {event.name}")

def on_tool_call_ended(event: VoiceAgentToolCallEndedEvent) -> None:
    print(f"tool call ended: {event.name} -> {event.result!r}")

def on_agent_state_changed(event: VoiceAgentStateChangedEvent) -> None:
    print(f"state: {event.state}")

def on_error(event: VoiceAgentErrorEvent) -> None:
    print(f"error (fatal={event.fatal}): {event.message}")

session.on("transcript", on_transcript)
session.on("tool_call_started", on_tool_call_started)
session.on("tool_call_ended", on_tool_call_ended)
session.on("agent_state_changed", on_agent_state_changed)
session.on("error", on_error)

session.on() renvoie une fonction qui annule l'abonnement du gestionnaire. Vous pouvez aussi appeler session.off() avec le gestionnaire d'origine :

unsubscribe = session.on("transcript", on_transcript)

unsubscribe()  # stop receiving
# or, equivalently:
session.off("transcript", on_transcript)

unsubscribe = session.on("transcript", on_transcript)

unsubscribe()  # stop receiving
# or, equivalently:
session.off("transcript", on_transcript)

Erreurs et nettoyage

Chaque erreur comporte fatal :

Les erreurs récupérables (fatal est faux) laissent la session ouverte. Écrivez-les dans les logs et continuez.
Les erreurs fatales ferment la session : wait() rend la main, et l'audio s'arrête. Les échecs de démarrage et les déconnexions inattendues sont fatals.

Enregistrez un gestionnaire error pour décider du comportement de votre application. Sans gestionnaire, le SDK écrit l'erreur dans les logs (logging en Python, console.error dans Node.js), de sorte qu'aucune erreur ne passe inaperçue. Comme init() démarre la session avant de renvoyer, un échec de démarrage lève aussi VoiceAgentConnectionException, avec l'erreur dans error_event (Python) ou errorEvent (TypeScript).

Dans les deux cas, appelez close() dans un bloc finally, comme dans le guide de démarrage, afin que la session soit toujours libérée.

Aller plus loin

Outils

Webhooks

Interfaces audio personnalisées