Linkup

​

Recherche web à commande vocale

1. L’appelant pose une question à voix haute, par exemple « Trouve-moi un hôtel de charme à Lisbonne à moins de 150 euros la nuit. »
2. La transcription (STT) Gradium transcrit la demande en temps réel.
3. L’agent appelle un outil de recherche avec une requête ciblée construite à partir des préférences énoncées par l’appelant.
4. Linkup renvoie des résultats classés avec titres, sources, extraits et images.
5. L’agent filtre, compare et résume les résultats.
6. La synthèse vocale (TTS) Gradium renvoie la réponse en streaming à l’appelant.

​

Câblage de base

​

Définition de l’outil de recherche

gradbot.ToolDef(
    name="search_hotels",
    description=(
        "Search the web for available hotels in a destination. Takes some "
        "time to search. Keep chatting with the caller about the destination "
        "while waiting for results! IMPORTANT: Always include the caller's "
        "preferences (budget, style, etc.) in the preferences field so the "
        "search is targeted."
    ),
    parameters_json=json.dumps({
        "type": "object",
        "properties": {
            "destination": {
                "type": "string",
                "description": "The city or destination to search hotels in",
            },
            "preferences": {
                "type": "string",
                "description": (
                    "Caller's requirements: budget range, style, amenities, "
                    "etc. (e.g. 'under 100 euros per night, boutique style')"
                ),
            },
        },
        "required": ["destination"],
    }),
)

​

Appeler l’API Search de Linkup

import asyncio
from linkup import LinkupClient

linkup_client = LinkupClient(api_key=os.environ["LINKUP_API_KEY"])

async def do_search(query: str, include_images: bool = True) -> dict:
    loop = asyncio.get_running_loop()
    result = await loop.run_in_executor(
        None,
        lambda: linkup_client.search(
            query=query,
            depth="standard",
            output_type="searchResults",
            include_images=include_images,
        ),
    )

    sources, images = [], []
    for item in result.results or []:
        if item.type == "image":
            images.append({"title": item.name, "url": item.url})
        else:
            sources.append({
                "title": item.name,
                "href": item.url,
                "body": item.content[:300] if item.content else "",
            })

    answer = "\n".join(f"- {s['title']}: {s['body']}" for s in sources[:5])
    return {"answer": answer, "sources": sources, "images": images}

• depth arbitre entre latence et exhaustivité. fast est une recherche par mots-clés en moins d’une seconde, destinée aux chemins critiques en latence comme la voix ; standard est une recherche agentique en une seule itération, d’environ une à trois secondes, adaptée à la plupart des recherches d’agent ; et deep exécute jusqu’à dix itérations en cinq à trente secondes pour des investigations complexes multi-sources. La démo utilise standard.
• output_type détermine la forme de la valeur renvoyée. searchResults renvoie des URL classées et des extraits sur lesquels l’agent peut raisonner, sourcedAnswer renvoie une réponse générée avec citations, et structured renvoie du JSON conforme à un schéma que vous fournissez. La démo utilise searchResults pour que l’agent puisse filtrer et résumer lui-même les sources.

​

Renvoyer les résultats à l’agent

async def handle_search_hotels(destination, preferences, tool_handle, input_handle, websocket):
    query = f"hotels in {destination} {preferences or ''} with star ratings, prices per night, and brief descriptions"
    result = await do_search(query)

    # Stream source cards and images to the frontend
    await websocket.send_json({
        "type": "search_results",
        "query": f"Hotels in {destination}",
        "results": result["sources"],
        "images": result.get("images", []),
    })

    await tool_handle.send(json.dumps({
        "success": True,
        "destination": destination,
        "answer": result["answer"],
        "sources": result["sources"],
        "message": (
            "Hotel search results are ready. Present the top options based on "
            "the search results, highlighting star ratings, price ranges, and "
            "key features. Ask which one interests the caller."
        ),
    }))

​

Configuration de la session de l’agent

def make_config(instructions: str) -> gradbot.SessionConfig:
    return gradbot.SessionConfig(
        voice_id="cLONiZ4hQ8VpQ4Sz",
        instructions=instructions,
        language=gradbot.Lang.En,
        tools=build_tools(),
        silence_timeout_s=0.0,
    )

await gradbot.websocket.handle_session(
    websocket,
    on_start=on_start,
    on_config=on_config,
    on_tool_call=handle_tool_call,
)

​

Garder la boucle vocale rapide

• Recherchez en dehors de la boucle d’événements. Le client Linkup est synchrone : exécutez-le dans un pool de threads avec run_in_executor pour éviter de bloquer l’audio pendant qu’une requête est en cours.
• Adaptez la profondeur au tour de parole. La démo utilise la profondeur standard et comble l’attente par la conversation. Pour les recherches qui doivent aboutir pendant une pause dans la conversation, depth="fast" renvoie des résultats par mots-clés en moins d’une seconde ; réservez deep aux questions de type recherche approfondie, où quelques secondes de plus sont acceptables.
• Comblez l’attente par la conversation. Demandez à l’agent de continuer à parler de la destination pendant la recherche, afin que l’appelant n’entende jamais de blanc.
• Limitez et tronquez les résultats. Une poignée de sources avec des extraits réduits à environ 300 caractères suffit au LLM pour répondre sans alourdir le prompt.
• Affichez les sources en flux à l’écran. Envoyez les fiches de sources et les images au navigateur au fur et à mesure que les résultats arrivent, pour que l’appelant voie ce dont parle l’agent.
• Gérez les échecs avec la voix de l’agent. Si une recherche échoue, renvoyez un résultat vide et demandez à l’agent de dire qu’il ne peut pas accéder au web pour le moment, plutôt que de laisser le modèle deviner.

​

Authentification

​

Pourquoi utiliser Linkup avec Gradium ?

• Des réponses à jour dans les sessions vocales en temps réel : donnez aux agents Gradium accès à des résultats web actuels sans obliger les appelants à quitter la conversation.
• Une recherche qui suit les contraintes énoncées à l’oral : transformez des préférences exprimées en langage naturel, comme le budget, le lieu, le style ou les dates, en requêtes Linkup ciblées.
• Sources et images réunies : les résultats arrivent sous forme de données structurées propres, avec sources textuelles et images, prêtes à être résumées, énoncées et affichées en flux à l’écran.
• Des réponses orales fondées : l’agent répond à partir de résultats web en temps réel plutôt que de la mémoire figée du modèle, et peut citer la source naturellement.

​

Démo