Recherche web

En plus des bases de connaissance, le modèle peut disposer d’outils web : il décide lui-même de chercher sur le web et de lire des pages, enchaîne plusieurs appels si besoin, puis répond — exactement comme le mode agentique du RAG.

Activez-les avec le paramètre tools_enabled :

curl https://api.miraca.fr/v1/chat/completions \
  -H "Authorization: Bearer $MIRACA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large",
    "messages": [{ "role": "user", "content": "Quelle est la dernière version stable de Next.js ? Cite une source." }],
    "tools_enabled": ["web_search", "web_fetch"],
    "tools_max_steps": 4
  }'

Paramètres

Paramètre	Type	Description
`tools_enabled`	`string[]`	Outils à activer : `"web_search"` (recherche) et/ou `"web_fetch"` (lecture de page). Vide ou absent = aucun outil web.
`tools_max_steps`	`number`	(optionnel, défaut `8`, max `99`) Nombre maximum de tours d’outils autorisés (borne le coût).
`miraca_plan`	`boolean`	(optionnel, défaut `false`) Checklist agentique — commun à tous les outils (web, KB, connecteurs, code). Si `true`, le modèle planifie ses étapes au 1ᵉʳ tour, coche sa liste au fil de l’eau et la revoit à chaque tour : il oublie moins d’étapes sur une tâche longue. Ajoute un tour de planification (à réserver aux requêtes à plusieurs étapes).

Les deux outils

web_search — recherche web (type moteur de recherche). Le modèle fournit une requête (query) et reçoit une liste de résultats (titre, url, extrait, et le plus souvent la date de publication et des passages du contenu de la page). Option : top_k (1–10). L’opérateur site:exemple.com restreint la recherche à un domaine ; il n’existe pas de filtre de date (écrivez la période dans la requête).

Pas de filtre de fraîcheur : l’index européen n’en propose pas, et nous préférons ne pas exposer un paramètre qui serait ignoré. Pour restreindre à une période, écrivez-la dans la requête (« … juillet 2026 »), ou lisez directement la page d’actualité de la source avec web_fetch.

Opérateur site: — il fonctionne sur un domaine, jamais sur un chemin : site:exemple.com annonce modèle renvoie des résultats, site:exemple.com/actualites annonce modèle n’en renvoie aucun, même avec des mots-clés. La plateforme corrige automatiquement cette forme (le chemin devient des mots-clés : site:exemple.com/a/b → site:exemple.com a b) et le signale dans le résultat de l’outil, pour que l’agent n’interprète pas une requête morte comme une absence d’actualité. Quand vous connaissez déjà l’URL d’une page, web_fetch reste plus direct et plus fiable qu’une recherche.

Opérateurs de date (after:, before:, daterange:) — ils n’existent pas. L’index ne les rejette pas : il les traite comme des mots ordinaires et renvoie des résultats non filtrés, ce qui est plus trompeur qu’une erreur. Ils sont donc retirés de la requête, et le résultat de l’outil précise qu’aucun filtre de date n’a été appliqué.
web_fetch — lit le contenu texte d’une page (URL http/https) trouvée via web_search. Lecture statique (pas d’exécution JavaScript) ; les pages privées/locales sont bloquées.

Lecture partielle des pages longues

Une page web peut peser des dizaines de milliers de caractères. Tout ce que l’agent charge reste dans son contexte jusqu’à la fin de sa réflexion : une page entière chargée au deuxième tour est relue à chaque tour suivant, ce qui ralentit la réponse et dilue la question.

web_fetch renvoie donc, par défaut, une portion d’une page longue (environ 10 000 caractères), accompagnée de ce qu’il faut pour aller plus loin :

Champ renvoyé	Sens
`total_chars`	Taille réelle de la page, même si elle n’est pas montrée en entier.
`next_offset`	Position de reprise, ou `null` si la fin est atteinte.
`mode`	`full` (page entière), `excerpts` (passages ciblés) ou `window` (lecture séquentielle).

L’agent pilote lui-même sa lecture avec trois paramètres :

query — ce qu’il cherche dans la page. Il reçoit alors les passages pertinents plutôt que le début, même si l’information se trouve en bas de page. C’est le mode à privilégier.
offset — reprend la lecture où elle s’est arrêtée (le next_offset précédent).
full: true — force la page entière, dans la limite de 50 000 caractères.

Aucun réglage n’est nécessaire de votre côté : le comportement est automatique, et les consignes données au modèle l’orientent vers query. Une page courte est toujours renvoyée en entier, sans découpage.

Combiner avec les bases de connaissance

tools_enabled et knowledge_base_mode: "agentic" coexistent : dans la même réflexion, l’agent peut interroger vos bases et le web, et choisir lui-même quel outil utiliser pour quelle sous-question.

curl https://api.miraca.fr/v1/chat/completions \
  -H "Authorization: Bearer $MIRACA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large",
    "messages": [{ "role": "user", "content": "Combien de dossiers en alerte dans notre base, et une actu récente sur notre secteur ?" }],
    "knowledge_base": "suivi-clients",
    "knowledge_base_mode": "agentic",
    "tools_enabled": ["web_search", "web_fetch"]
  }'

À savoir

Non-streaming : comme le mode agentique, la réponse arrive en une fois (stream: true est ignoré). Idéal pour les automatisations (Make/n8n).
Coût : deux composantes. (1) Les tokens des appels modèle (un par tour + la réponse) → tools_max_steps borne le nombre de tours. (2) Un forfait de 4,80 € pour 1 000 recherches (web_search) exécutées via Staan, soit 0,0048 € l’unité, et 6,00 € pour 1 000 via Brave Search (voir ci-dessous) ; web_fetch (lecture d’une page dont vous connaissez déjà l’adresse) est gratuit. Le forfait apparaît dans le coût de la requête au playground et est décompté de vos crédits comme le reste. Une recherche qui échoue n’est pas facturée.
Chercher coûte, lire ne coûte pas. Une recherche va chercher les pages pour vous en rapporter la date et des extraits : c’est ce travail qui est facturé. Si vous connaissez déjà l’adresse d’une page, faites-la lire directement (web_fetch) plutôt que chercher.
Réflexion : les appels d’outils de l’agent sont renvoyés dans miraca_steps (outil, requête, et le tour qui les a demandés) et les tours de modèle dans miraca_rounds (contexte, cache, durée, coût, empreinte carbone). Le portail les affiche ensemble, dans l’ordre réel. Les URL sources sont citées directement dans la réponse.
Souveraineté : la recherche est servie par Staan, l’API de recherche de European Search Perspective (coentreprise Qwant et Ecosia). L’index est européen, les données restent sous juridiction UE, dans des centres de données UE, hors portée du CLOUD Act américain. Le badge cloud du modèle s’applique comme d’habitude si vous routez vers un modèle cloud.

Une recherche web sort nécessairement de notre infrastructure : la requête est transmise au moteur qui détient l’index. Ce qui change avec Staan, c’est chez qui elle va — un acteur européen sous contrat, nommable dans votre registre de sous-traitants.
Fournisseurs de l’organisation : Staan est le fournisseur par défaut. Une organisation peut y ajouter Brave Search dans le portail, Gestion → Assistant → Outils → Recherche web (propriétaire ou administrateur). Son index est plus étendu et plus à jour, mais les requêtes partent alors aux États-Unis, chez Brave Software, Inc. Le choix vaut pour toute l’organisation : assistant, Slack, tâches, playground et clés d’API de l’organisation.
- Staan seul : comportement par défaut, rien ne quitte l’Union européenne.
- Brave seul : toutes les recherches passent par Brave.
- Les deux : Brave est interrogé d’abord ; si Brave ne répond pas, Staan prend le relais. Chaque recherche est facturée au tarif du fournisseur qui a répondu, indiqué dans miraca_steps (fournisseur). Une clé de compte, sans organisation, utilise toujours Staan. Dans les applications iPhone, iPad, Mac et Android, Brave apparaît dans l’écran « Où vos messages sont traités » dès que l’organisation l’a coché.
Sécurité : le contenu web est traité comme une donnée, jamais comme une instruction — les éventuelles consignes cachées dans une page ne sont pas exécutées.
Couverture réelle : dès qu’un outil web a servi, l’agent reçoit à chaque tour la liste des pages qu’il a effectivement ouvertes, avec la consigne de ne présenter comme « consultée » ou « vérifiée » aucune source absente de cette liste. Un extrait de résultat de recherche n’est pas une page consultée. Sans ce rappel, un agent chargé d’une veille reconstruit sa couverture de mémoire et affirme avoir vérifié des sources qu’il n’a jamais ouvertes.