Skip to main content
Tavily gives AI applications access to real-time web search, extraction, research, and crawling. In a Gradium voice agent, Tavily acts as the web context layer: the user speaks a request, the agent turns it into a structured search, Tavily returns current web results, and Gradium speaks the answer back.

Tavily

Explore Tavily’s web search and research APIs.

Paris rental voice agent

See a Gradbot demo that uses voice AI to search for Paris rentals.
A voice search agent usually follows this loop:
  1. The user asks a spoken question, such as “Find two-bedroom rentals near Canal Saint-Martin under 2,500 euros.”
  2. Gradium Speech-to-Text transcribes the request in real time.
  3. Your agent decides whether it needs fresh web context and calls Tavily with a focused query.
  4. Tavily returns search results and source content for the agent to inspect.
  5. The agent filters, compares, and summarizes the results.
  6. Gradium Text-to-Speech streams the answer back to the user.
This pattern lets users control web search without typing. They can refine the search conversationally, ask for tradeoffs, compare sources, or narrow results by criteria like budget, neighborhood, date, availability, or ranking.

​
Core wiring

The Gradbot demo exposes search as a voice-agent tool. Gradium handles the live STT and TTS session; the agent decides when to call run_apartment_search.

​
Agent session config

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,
)

​
Search tool call

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": [],
    }),
)
When the model calls the tool, the voice handler routes it into the same search logic used by the REST API and sends a compact result back to the agent before it speaks. 
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))
The shared search logic eventually calls Tavily with the focused query built from the user’s confirmed profile. 
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"]

​
Why use Tavily with Gradium?

  • Fresh answers in live voice sessions: give Gradium agents access to current web results without making users leave the conversation.
  • Search that follows spoken constraints: turn natural-language preferences like budget, location, timing, availability, or source type into focused Tavily queries.
  • Hands-free research loops: let users compare results, refine criteria, and ask follow-up questions while the agent gathers new context.
  • Support and status lookups: fetch public docs, release notes, pricing pages, or status information so callers get answers from up-to-date sources.

​
Demo

The Paris rental voice agent shows how a Gradbot application can combine a spoken interface with web search. Use it as a reference for the agent loop: listen to the user, call a web search tool, reason over the results, and respond with speech.