web_search Tool: Real-Time Internet Search

Mistral’s Four Built-in Tools

This lesson kicks off the section on built-in tools. Before diving into the first one, take a minute to overview the four tools available in the Agents API and the needs they address.

These tools run in Mistral’s cloud environment—no infrastructure to manage on your end. This is a fundamental difference from classic function calling, where you handle execution: here, you declare a capability, and the provider handles the sandbox, dependencies, and scaling.

Web Search in Detail

The web_search tool lets your agent search for information on the internet in real time. It is the most widely used tool because it solves a fundamental LLM problem: the temporal gap with reality. A model knows nothing about events that occurred after its training, and it doesn’t even know that it doesn’t know—leading to confident answers based on an outdated view of the world.

Configuring an agent with this tool takes just a few lines.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Web Search Agent",
    instructions="You perform web searches to answer questions. Always cite your sources.",
    tools=[{"type": "web_search"}],
    completion_args={"temperature": 0.3, "top_p": 0.95}
)

Running a Search

You query this agent like any other: the decision to search belongs to the agent.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Who won the most recent European Football Championship?"
)

Behind this single call lies a whole chain of events. The agent first analyzes the question to determine whether its own knowledge is sufficient—here, the word “most recent” implies dated information, so it is not. It then formulates an optimized search query, often different from your sentence, stripped of conversational phrasing. It executes the search, then synthesizes the results with citations attached. You don’t control any of these steps, but you can see all of them in the response.

Anatomy of the Response

The response contains several sequential entries that you must iterate through in order.

for entry in response.outputs:
    print(f"--- {entry.type} ---")

    if entry.type == "tool.execution":
        # Details of the search performed
        print(f"Tool: {entry.tool_name}")

    elif entry.type == "message.output":
        # Response with citations
        for chunk in entry.content:
            if chunk.type == "text":
                print(chunk.text)
            elif chunk.type == "tool_reference":
                print(f"[Source] {chunk.title} — {chunk.url}")

You will first see a tool.execution entry, which carries the operation’s metadata, including the actual query sent to the search engine. This is the place to look when an answer seems off-topic, as you will often see that the reformulation drifted. The message.output entry then carries the synthesized response, split into text and tool_reference chunks—hence the nested loop in the code above.

Using Direct Mode (Without an Agent)

The tool also works without a registered agent, which is convenient for quick testing.

response = client.beta.conversations.start(
    model="mistral-large-latest",
    inputs=[{"role": "user", "content": "Latest news on Mistral AI"}],
    tools=[{"type": "web_search"}]
)

Best Practices That Make the Difference

Start by asking precise questions. The agent transforms your question into a search query: “tell me about AI” will yield generic results, while “what European AI regulations were adopted in 2026?” immediately targets actionable pages. This rule also applies to questions your users ask: if your interface allows vague requests, include a step in your instructions for reformulation or clarification questions.

Next, control the temperature. For factual tasks, a low value—between 0.2 and 0.4—reduces hallucinations during result synthesis. The search provides the raw material, but the model still does the writing, and nothing stops it from filling gaps if given too much freedom.

Finally, verify sources. Citations are automatic, but their relevance varies: a forum post and an official text look similar in a reference list. In critical contexts, open the returned URLs before adopting the information—and expose them to your users so they can do the same.

Key Takeaways

• web_search gives the agent real-time access to the internet
• Responses include automatic citations (title + URL)
• web_search_premium adds verified news sources
• The tool works with or without an agent (direct mode is possible)
• Low temperature is recommended for factual tasks