> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradium.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily

> Utilisez la recherche web Tavily avec les agents vocaux IA Gradium

Tavily donne aux applications d'IA un accès en temps réel à la recherche, à l'extraction, à la recherche approfondie et à l'exploration (crawling) du web. Dans un agent vocal Gradium, Tavily joue le rôle de couche de contexte web : l'utilisateur formule une demande à l'oral, l'agent la transforme en recherche structurée, Tavily renvoie des résultats web à jour, et Gradium énonce la réponse.

<CardGroup cols={2}>
  <Card title="Tavily" icon="arrow-up-right-from-square" href="https://www.tavily.com/">
    Découvrez les API de recherche web et de recherche approfondie de Tavily.
  </Card>

  <Card title="Agent vocal de location à Paris" icon="github" href="https://github.com/gradium-ai/gradbot/tree/main/demos/paris_rental_agent">
    Découvrez une démo Gradbot qui utilise l'IA vocale pour rechercher des locations à Paris.
  </Card>
</CardGroup>

## Recherche web à commande vocale

Un agent de recherche vocale suit généralement cette boucle :

1. L'utilisateur pose une question à l'oral, par exemple « Trouve des locations de deux chambres près du canal Saint-Martin à moins de 2 500 euros ».
2. La transcription (STT) Gradium transcrit la demande en temps réel.
3. Votre agent détermine s'il a besoin d'un contexte web récent et appelle Tavily avec une requête ciblée.
4. Tavily renvoie des résultats de recherche et le contenu des sources pour que l'agent les examine.
5. L'agent filtre, compare et résume les résultats.
6. La synthèse vocale (TTS) Gradium diffuse la réponse en streaming à l'utilisateur.

Ce modèle permet aux utilisateurs de piloter la recherche web sans taper au clavier. Ils peuvent affiner la recherche au fil de la conversation, demander les avantages et inconvénients, comparer des sources ou restreindre les résultats selon des critères comme le budget, le quartier, la date, la disponibilité ou le classement.

## Câblage de base

La démo Gradbot expose la recherche comme un outil de l'agent vocal. Gradium gère la session STT et TTS en direct ; l'agent décide quand appeler `run_apartment_search`.

### Configuration de la session de l'agent

```python theme={null}
def on_start(msg: dict) -> gradbot.SessionConfig:
    return gradbot.SessionConfig(
        voice_id="ubuXFxVQwVYnZQhy",
        instructions=SYSTEM_PROMPT,
        language=gradbot.LANGUAGES["en"],
        tools=build_tools(),
        silence_timeout_s=0.0,
        **config.session_kwargs,
    )

await gradbot.websocket.handle_session(
    websocket,
    config=config,
    on_start=on_start,
    on_tool_call=on_tool_call,
)
```

### Appel de l'outil de recherche

```python theme={null}
gradbot.ToolDef(
    name="run_apartment_search",
    description=(
        "Run a fresh apartment search and return top matches. "
        "Call only when the user explicitly asks to search."
    ),
    parameters_json=json.dumps({
        "type": "object",
        "properties": {
            "max_results": {"type": "integer"},
            "allow_unconfirmed_profile": {"type": "boolean"},
        },
        "required": [],
    }),
)
```

Lorsque le modèle appelle l'outil, le gestionnaire vocal le redirige vers la même logique de recherche que celle utilisée par l'API REST, puis renvoie un résultat compact à l'agent avant qu'il ne parle.

```python theme={null}
async def on_tool_call(handle, input_handle, websocket):
    if handle.name == "run_apartment_search":
        result = await assistant_tools.run_apartment_search(
            db,
            user_id,
            max_results=int((handle.args or {}).get("max_results") or 10),
            allow_unconfirmed_profile=bool(
                (handle.args or {}).get("allow_unconfirmed_profile")
            ),
        )
        await handle.send_json(_voice_summarize_search(result))
```

La logique de recherche partagée finit par appeler Tavily avec la requête ciblée construite à partir du profil confirmé de l'utilisateur.

```python theme={null}
response = await httpx.AsyncClient().post(
    "https://api.tavily.com/search",
    json={
        "api_key": tavily_api_key,
        "query": "location appartement Paris 2 chambres 2500 euros",
        "search_depth": "basic",
        "max_results": 5,
        "include_raw_content": True,
    },
    timeout=20.0,
)

results = response.json()["results"]
```

## Pourquoi utiliser Tavily avec Gradium ?

* **Des réponses à jour dans les sessions vocales en direct** : donnez aux agents Gradium accès à des résultats web actuels sans que les utilisateurs aient à quitter la conversation.
* **Une recherche qui respecte les contraintes énoncées à l'oral** : transformez des préférences exprimées en langage naturel, comme le budget, le lieu, le calendrier, la disponibilité ou le type de source, en requêtes Tavily ciblées.
* **Des boucles de recherche mains libres** : permettez aux utilisateurs de comparer les résultats, d'affiner leurs critères et de poser des questions de suivi pendant que l'agent rassemble un nouveau contexte.
* **Support et consultation de statut** : récupérez de la documentation publique, des notes de version, des pages de tarifs ou des informations de statut pour que les appelants obtiennent des réponses issues de sources à jour.

## Démo

L'[agent vocal de location à Paris](https://github.com/gradium-ai/gradbot/tree/main/demos/paris_rental_agent) montre comment une application Gradbot peut combiner une interface vocale et la recherche web. Utilisez-le comme référence pour la boucle de l'agent : écouter l'utilisateur, appeler un outil de recherche web, raisonner sur les résultats et répondre à l'oral.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.