Recherche Web - UBIK Public API

L’outil web_search permet aux agents de récupérer, d’analyser et de synthétiser des informations provenant du web en direct. Il va au-delà de la simple correspondance par mots-clés en employant un processus en plusieurs étapes : recherche, extraction du contenu complet (scraping), reclassement sémantique des résultats, et enfin génération d’une réponse sourcée.

Quand Utiliser Cet Outil

Utilisez web_search lorsque vous avez besoin de :

Accéder à des Données en Temps Réel : Trouver des informations sur des événements, des prix ou des sorties survenus récemment.
Vérifier des Faits : Recouper des connaissances internes avec des sources externes.
Élargir la Recherche : Explorer des sujets en dehors de votre base de connaissances interne.
Trouver de la Documentation : Consulter les dernières références API ou guides techniques qui pourraient ne pas être dans vos données d’entraînement.

Reranking & QualitéCet outil ne renvoie pas simplement une liste de liens. Il récupère le contenu réel des meilleurs résultats et utilise un modèle spécialisé de “reranker” pour les noter en fonction de la façon dont ils répondent à la requête spécifique de l’utilisateur. Cela garantit des réponses pertinentes et de haute qualité même si les mots-clés de recherche initiaux étaient imparfaits.

Paramètres d’Entrée

L’outil accepte les paramètres suivants :

Paramètre	Type	Requis	Description
`query`	`string`	Oui	La requête de recherche à envoyer au navigateur web. Soyez précis pour de meilleurs résultats.
`time_range`	`string`	Non	Filtrer les résultats par temps. Options : `day`, `month`, `year`, `none` (défaut). Utilisez ceci uniquement si l’utilisateur demande explicitement une période.
`whitelisted_domains`	`array of strings`	Non	Une liste de domaines pour filtrer strictement les résultats de recherche. Si fournie, seuls les résultats provenant de ces domaines seront renvoyés.

Structure de Sortie

L’outil renvoie un objet JSON contenant la réponse synthétisée et les sources utilisées.

{
  "query": "dernières avancées batteries solides 2024",
  "response": "L'utilisateur demande des informations sur les avancées récentes dans les batteries à l'état solide. Je dois trouver des informations spécifiques à 2024. En regardant les résultats de recherche, je vois plusieurs articles pertinents...\n\nLes avancées récentes dans les batteries à l'état solide en 2024 se sont concentrées sur l'amélioration de la densité énergétique et des vitesses de charge. Toyota a annoncé une percée revendiquant une autonomie de 745 miles et un temps de charge de 10 minutes <web_citation url=\"https://example.com/toyota-news\" title=\"Toyota News\">[1]</web_citation>. Pendant ce temps, QuantumScape a commencé à expédier des prototypes à des partenaires automobiles <web_citation url=\"https://example.com/quantumscape-update\" title=\"QuantumScape Update\">[2]</web_citation>.",
  "sources": [
    {
      "rank": 1,
      "title": "Feuille de route des batteries solides de Toyota",
      "url": "https://example.com/toyota-news",
      "snippet": "Toyota vise à commercialiser la technologie d'ici 2027...",
      "rerank_score": 0.92,
      "used_in_response": true
    },
    // ... autres sources
  ],
  "sources_used": [1, 2],
  "model": "claude-3-7-sonnet-20250219-thinking",
  "reranker": "llm_multimodal_tool_calling_binary_reranker::gpt-4o-mini",
  "total_results": 15,
  "reranked_results": 5,
  "execution_id": "call_zIsjIkJwvPrJTz2GbIRGg8DE"
}

Champs de Réponse

Champ	Description
`response`	La réponse en langage naturel générée par le modèle, incluant des citations en ligne et potentiellement un bloc “Réflexion” où le modèle planifie sa réponse.
`sources`	Une liste des pages web qui ont été analysées. Inclut l’`url`, le `title`, un `snippet`, et un `rerank_score` indiquant la pertinence.
`sources_used`	Un tableau d’entiers correspondant au `rank` des sources qui ont été explicitement citées dans la réponse.
`model`	Le LLM utilisé pour générer la réponse.
`reranker`	Le modèle utilisé pour réordonner les résultats de recherche par pertinence.
`execution_id`	L’identifiant unique pour cette exécution d’outil.

Exemple d’Utilisation

Recherche Basique

Entrée :

{
  "query": "prix actuel du bitcoin"
}

Résultat : L’agent renverra le prix actuel provenant d’un site d’actualités financières ou de données d’échange trouvées sur le web.

Recherche Filtrée par Temps

Entrée :

{
  "query": "tremblement de terre au japon",
  "time_range": "day"
}

Résultat : L’agent restreint les résultats aux dernières 24 heures, assurant que l’information concerne des événements récents plutôt que historiques.

Liste Blanche et Liste Noire de Domaines

L’outil de Recherche Web prend en charge les listes blanches et listes noires de domaines pour vous donner le contrôle sur les sources d’information. Il existe deux manières distinctes de gérer cela, selon votre configuration :

1. Liste Blanche Stricte (Niveau de l’Outil)

Lorsque vous configurez des domaines en liste blanche directement dans les paramètres de l’outil de l’agent, cela applique un filtre strict.

Si un domaine en liste blanche est fourni, l’outil renverra uniquement les résultats de ce domaine spécifique.
Si le moteur de recherche ne trouve aucun résultat provenant du domaine en liste blanche, aucun résultat ne sera affiché à l’agent.
C’est idéal lorsque vous voulez garantir absolument que l’agent n’utilise que des informations provenant d’une source spécifique et de confiance (par exemple, la documentation de votre propre entreprise).

2. Contrôle Granulaire et Score Bonus (Navigateur Sécurisé Auto-hébergé)

Si vous souhaitez une approche plus souple — où vous affichez toujours des résultats web généraux mais accordez un “score bonus” aux domaines de confiance, ou si vous souhaitez bloquer complètement certains domaines — vous pouvez utiliser un Navigateur Sécurisé Auto-hébergé. En déployant votre propre instance de navigateur, vous pouvez configurer WHITELISTED_DOMAINS et BLACKLISTED_DOMAINS au niveau du navigateur :

Domaines en Liste Blanche (Niveau Navigateur) : Le moteur de recherche priorisera activement et donnera un bonus aux résultats de ces domaines, mais il renverra quand même d’autres résultats pertinents si les domaines de confiance n’ont pas la réponse.
Domaines en Liste Noire : Le moteur de recherche filtrera complètement les résultats de ces domaines (par exemple, pour bloquer les spams connus ou les sites concurrents).

Cette approche permet un contrôle plus flexible et granulaire sur l’environnement de recherche sans limiter strictement la capacité de l’agent à trouver des réponses.

Comment Ça Marche

Recherche : L’outil interroge un moteur de recherche pour obtenir un large ensemble de résultats initiaux.
Scraping : Il visite les meilleures URL pour extraire le contenu textuel complet, pas seulement l’extrait de recherche.
Rerank : Un modèle spécialisé de “reranker” compare la requête de l’utilisateur au texte complet de chaque page pour déterminer lesquelles sont vraiment pertinentes. 4. Générer : Les morceaux de texte les plus pertinents sont passés à un LLM, qui synthétise la réponse finale et ajoute des citations.

Événements de Streaming

Lorsqu’il est utilisé en mode streaming, l’outil web_search émet des événements en temps réel via SSE (Server-Sent Events). Cela vous permet de suivre la progression du pipeline de recherche et d’afficher la réponse au fur et à mesure de sa génération.

Types d’Événements

Événement	Description
`tool_update`	Indique une mise à jour de progression (changement de phase) ou fournit des données intermédiaires comme les résultats de recherche.
`tool_partial_update`	Contient un nouveau fragment de texte de la réponse générée (streaming).
`error`	Signale qu’une erreur critique s’est produite pendant l’exécution (par exemple, délai d’attente du moteur de recherche).
`tool_end`	Signale la fin de l’exécution de l’outil et fournit le résultat final complet.

Phases du Pipeline (`tool_update`)

L’événement tool_update contient un champ data avec une phase et un status. Voici les phases possibles :

WEB_SEARCH

status: started / completed
data: { "results_count": <int>, "sources": [...] } (à la fin)

Indique la requête initiale au moteur de recherche. Le tableau sources contient les résultats bruts de la recherche :

// Exemple de structure 'sources' dans la phase WEB_SEARCH
[
  {
    "rank": 1,
    "title": "Recent Advances in AI",
    "url": "https://example.com/ai-news",
    "snippet": "A summary of the latest breakthroughs...",
    "engine": "google",
    "score": 1.0
  }
]

SCRAPING_URLS

status: started / completed
data: { "url_count": <int> } (au début), { "scraped_count": <int> } (à la fin)
Indique la récupération du contenu textuel complet à partir des meilleures URL.
Fonctionnalité AvancéeLe scraping du contenu complet de la page est une fonctionnalité avancée et est désactivé par défaut. Lorsqu’il est désactivé, l’outil s’appuie uniquement sur les extraits du moteur de recherche. Si vous souhaitez activer le scraping complet des pages pour votre espace de travail, veuillez contacter l’équipe UBIK à contact@ubik-agent.com.

RERANKING
- status: started / completed
- data: { "reranked_count": <int> } (à la fin). Note : Le tableau sources affiné est émis dans un événement tool_update séparé juste après.
- Indique que les résultats ont été reclassés par pertinence sémantique. Une fois cette phase terminée, des événements tool_update supplémentaires sont émis contenant le nombre final reranked_results et le tableau affiné sources avec les scores sémantiques :
  // Exemple de structure 'sources' après la phase RERANKING [ { "rank": 1, "title": "Recent Advances in AI", "url": "https://example.com/ai-news", "snippet": "A summary of the latest breakthroughs...", "rerank_score": 0.85, "used_in_response": false } ]
GENERATION
- status: started / completed
- Indique que la génération LLM de la réponse finale commence.

Streaming de Contenu (`tool_partial_update`)

Pendant la phase de génération, des événements tool_partial_update sont émis pour chaque fragment de texte généré.

content: <string> (Le fragment de texte)
output_key: "response"

Ces fragments doivent être concaténés pour former la réponse complète. Le texte peut contenir des balises de citation brutes comme <source_1> qui sont remplacées par des balises riches <web_citation> à la fin de la génération.

Gestion des Événements Volumineux (Chunking)Si la charge utile d’un événement (comme un grand tableau de résultats de recherche) dépasse la limite de taille SSE, elle sera divisée en plusieurs événements _delta_sse. Pour des instructions détaillées et des exemples de code sur la façon de mettre en mémoire tampon et de reconstruire ces événements fragmentés, veuillez consulter le Guide des Résultats en Streaming ou le Guide des Événements de Session d’Agent.

Exemple de Flux d’Événements

// Début de la Recherche Web
{ "event": "tool_update", "data": { "phase": "WEB_SEARCH", "status": "started", "query": "dernières avancées en IA" } }

// Recherche Web terminée
{ "event": "tool_update", "data": { "phase": "WEB_SEARCH", "status": "completed", "data": { "results_count": 10, "sources": [...] }, "output_key": "sources" } }

// Début du Scraping
{ "event": "tool_update", "data": { "phase": "SCRAPING_URLS", "status": "started", "data": { "url_count": 10 } } }

// Scraping terminé
{ "event": "tool_update", "data": { "phase": "SCRAPING_URLS", "status": "completed", "data": { "scraped_count": 8 } } }

// Début du Reranking
{ "event": "tool_update", "data": { "phase": "RERANKING", "status": "started" } }

// Reranking terminé
{ "event": "tool_update", "data": { "phase": "RERANKING", "status": "completed", "data": { "reranked_count": 8 } } }

// Sources finales émises
{ "event": "tool_update", "data": { "reranked_results": 5, "output_key": "reranked_results" } }
{ "event": "tool_update", "data": { "sources": [...], "output_key": "sources" } }

// Début de la Génération
{ "event": "tool_update", "data": { "phase": "GENERATION", "status": "started" } }

// Streaming de la réponse (tool_partial_update)
{ "event": "tool_partial_update", "data": { "content": "Selon", "output_key": "response" } }
{ "event": "tool_partial_update", "data": { "content": " les", "output_key": "response" } }
{ "event": "tool_partial_update", "data": { "content": " résultats <source_1>...", "output_key": "response" } }

// Génération terminée
{ "event": "tool_update", "data": { "phase": "GENERATION", "status": "completed" } }

// Fin
{ 
  "event": "tool_end", 
  "data": { 
    "query": "dernières avancées en IA",
    "response": "Selon les résultats <web_citation url=\"...\">[1]</web_citation>...",
    "sources": [
      {
        "rank": 1,
        "title": "Recent Advances in AI",
        "url": "https://example.com/ai-news",
        "snippet": "A summary of the latest breakthroughs...",
        "rerank_score": 0.85,
        "used_in_response": true
      }
    ],
    "sources_used": [1],
    "model": "claude-sonnet-4-20250514",
    "reranker": "bge_text_reranker",
    "total_results": 10,
    "reranked_results": 5
  } 
}

ConfigurationTout comme l’outil RAG, les modèles utilisés pour la génération et le reranking dans la Recherche Web respectent les paramètres configurés dans vos Préférences Utilisateur sous la section RAG.

Documentation Index

​Quand Utiliser Cet Outil

​Paramètres d’Entrée

​Structure de Sortie

​Champs de Réponse

​Exemple d’Utilisation

​Recherche Basique

​Recherche Filtrée par Temps

​Liste Blanche et Liste Noire de Domaines

​1. Liste Blanche Stricte (Niveau de l’Outil)

​2. Contrôle Granulaire et Score Bonus (Navigateur Sécurisé Auto-hébergé)

​Comment Ça Marche

​Événements de Streaming

​Types d’Événements

​Phases du Pipeline (tool_update)

​Streaming de Contenu (tool_partial_update)

​Exemple de Flux d’Événements

Quand Utiliser Cet Outil

Paramètres d’Entrée

Structure de Sortie

Champs de Réponse

Exemple d’Utilisation

Recherche Basique

Recherche Filtrée par Temps

Liste Blanche et Liste Noire de Domaines

1. Liste Blanche Stricte (Niveau de l’Outil)

2. Contrôle Granulaire et Score Bonus (Navigateur Sécurisé Auto-hébergé)

Comment Ça Marche

Événements de Streaming

Types d’Événements

Phases du Pipeline (`tool_update`)

Streaming de Contenu (`tool_partial_update`)

Exemple de Flux d’Événements