Outils
Les outils permettent à un agent d'agir pendant une conversation : effectuer une recherche sur le Web, interroger vos bibliothèques de documents, appeler vos connecteurs d'espace de travail ou exécuter vos propres fonctions. Transmettez-les à init(), ou enregistrez-les sur un agent. Les outils côté serveur s'exécutent côté Mistral. Les outils côté client exécutent votre propre handler dans votre code, puis envoient le résultat au modèle.
Outils côté serveur
Les outils côté serveur sont les outils d'agent intégrés et vos connecteurs d'espace de travail. Les connecteurs qui nécessitent une authentification doivent déjà être authentifiés dans votre espace de travail : l'agent les utilise ensuite en votre nom.
| Outil | Ce qu'il fait | Forme en dictionnaire |
|---|---|---|
WebSearchTool | Effectue une recherche sur le Web | {"type": "web_search"} |
DocumentLibraryTool | Interroge vos bibliothèques de documents | {"type": "document_library", "library_ids": ["id1", ...]} |
ConnectorTool | Appelle un connecteur d'espace de travail | {"type": "connector", "connector_id": "my-connector"} |
from mistralai.client.models import WebSearchTool
tools = [
WebSearchTool(),
{"type": "document_library", "library_ids": ["my-lib-id"]},
{"type": "connector", "connector_id": "my_connector"},
]Outils côté client
Les outils côté client exposent vos propres fonctions à l'agent. Le SDK envoie la déclaration (nom, description et paramètres) pour que le modèle sache que l'outil existe. Quand le modèle l'appelle, le SDK exécute votre handler dans votre code et renvoie le résultat au modèle, qui poursuit la conversation. Utilisez-les pour des données ou des actions propres à votre application : l'état actuel de l'interface, la position de l'utilisateur ou un appel authentifié à votre backend.
En Python, le décorateur @function_tool construit le schéma des paramètres à partir des type hints et la description à partir de la docstring. En TypeScript, functionTool prend un schéma zod, et le type des arguments du handler en découle.
from mistralai.extra.voice_agents import function_tool
@function_tool
def get_weather(city: str) -> dict:
"""Return the current weather for a city."""
return {"city": city, "temp_c": 21}
session = await client.audio.sessions.init(
llm={"model": "mistral-small-latest"},
tts={"voice_id": "gb_oliver_excited"},
tools=[get_weather],
)En Python, passez name et description pour remplacer les valeurs par défaut :
@function_tool(name="getWeather", description="Weather for a city.")
async def get_weather(city: str) -> dict: ...Le handler peut être synchrone ou asynchrone et renvoyer une valeur que le modèle peut utiliser.
Les handlers s'exécutent sur la même boucle d'événements que celle qui diffuse l'audio. Rendez asynchrone tout handler qui effectue des entrées-sorties, pour que la conversation ne se bloque pas. Dans le navigateur, les outils côté client ont un fonctionnement légèrement différent : voir Outils côté client dans le navigateur.
Enregistrer des outils côté client sur un agent
Vous pouvez stocker des outils côté client sur un agent enregistré en passant le même objet outil à audio.agents.create. Seule la déclaration est enregistrée : le handler est du code dans votre application et n'est jamais stocké. Quand vous démarrez une session à partir de cet agent, passez à nouveau l'outil à init() pour associer le handler. Le SDK établit la correspondance par nom.
# Persist the declaration on the agent
agent = await client.audio.agents.create(
name="Weather bot",
configuration={
"llm": {"model": "mistral-small-latest"},
"tts": {"voice_id": "gb_oliver_excited"},
"tools": [get_weather],
},
)
# Re-attach the handler when connecting
session = await client.audio.sessions.init(agent_id=agent.id, tools=[get_weather])Outils non gérés
Un agent enregistré peut déclarer un outil côté client que l'application actuelle n'implémente pas. Quand le modèle l'appelle, le SDK émet un événement unhandled_tool et signale l'échec de l'appel à l'agent, pour que la conversation ne reste pas bloquée.
session.on("unhandled_tool", lambda e: print(f"no handler for {e.name}"))Les outils côté client ne fonctionnent que là où votre code s'exécute. Si vous lancez le même agent depuis une interface qui ne peut pas enregistrer de handlers, comme un appel téléphonique ou un test dans le dashboard, ses outils côté client échouent quand le modèle les appelle. Utilisez des outils côté serveur pour tout ce qui doit fonctionner partout.
Fillers
Un appel d'outil peut prendre un moment, et le silence peut vite devenir gênant dans une conversation. Associez un filler à n'importe quel outil, côté serveur ou côté client : l'agent joue un court extrait au début de l'appel et l'arrête dès que le résultat arrive. Cet extrait est du texte, prononcé avec la voix de l'agent. Le SDK prépare les fillers à la connexion de la session, pour que le premier appel ne soit pas retardé. Un outil sans filler reste silencieux. L'utilisateur peut parler pendant un filler, comme pendant n'importe quelle autre réplique de l'agent. Les fillers se marient bien avec les événements de session tool_call_started et tool_call_ended.
from mistralai.client.models import WebSearchTool
from mistralai.extra.voice_agents import StaticToolFiller, function_tool
# Text filler on a server-side tool — synthesized in the agent's voice.
web_search = WebSearchTool(filler=StaticToolFiller(text="Searching the web…"))
# Text filler on a client-side tool.
@function_tool(filler=StaticToolFiller(text="Checking your order…"))
def check_order(order_id: str) -> dict:
"""Look up an order's delivery status."""
return lookup(order_id)