How to Build a Web Search Agent with Phidata: A Step-by-Step Guide

Phidata is an open-source framework for building AI agents with capabilities like memory, tool use, and reasoning It’s model-agnostic and supports various large language models (LLMs), allowing developers to turn any LLM (like OpenAI GPT or local models) into a functional search agent. In this tutorial, we’ll walk through creating a web search agent using Phidata. The agent will be able to query the web (via a search API) and return answers with source citations. We’ll cover the setup, code structure, an example implementation, and tips for optimizing performance.

Overview of Phidata for Web Search Agents

Phidata simplifies the creation of AI agents by providing abstractions for models (LLMs), tools (for actions like web search), memory, and knowledge integration.For web search use cases, Phidata comes with pre-built toolkits such as DuckDuckGo, Google Search, SerpAPI, etc., enabling agents to retrieve real-time information from the web

Why Phidata?

Phidata is model-agnostic, so it supports different LLM providers (including OpenAI, local models, etc.). It also comes with built-in tools for common tasks like searching the web, extracting website content, or reading PDFs. By simply configuring your agent to use these tools, you can give it the power to find and summarize real-time information.

Setting Up the Environment and Dependencies

Before writing code, ensure your development environment is ready:

Python Environment: Make sure you have Python 3 installed. It’s recommended to use a virtual environment for isolation. For example, on macOS/Linux you can create one with:


python3 -m venv aienv
source aienv/bin/activate

Install Phidata and Tools: Phidata is available on PyPI. You’ll also need the OpenAI client library (if using OpenAI’s model) and a search toolkit. For a DuckDuckGo-based web agent, install the following:
pip install phidata openai duckduckgo-search
This installs Phidata, OpenAI’s Python SDK, and the DuckDuckGo search toolkit
github.com
Set API Keys: If you plan to use OpenAI’s GPT model, set your OpenAI API key as an environment variable. For example: export OPENAI_API_KEY=sk-<your_openai_key>
Phidata will use this key when calling OpenAI’s API
github.com
Optional Dependencies: Depending on customizations, you might install other toolkits. For instance, Phidata’s Google Search tool requires googlesearch-python and pycountry

For this tutorial, DuckDuckGo’s library is sufficient, which we already installed. With the environment ready and dependencies installed, we can proceed to build the agent.

Writing the Phidata Web Search Agent Code

Now, let’s create the search agent script. Open a text editor and create a file (e.g., web_search.py). Add the following code to define a web search agent:


from phi.agent import Agent
from phi.model.openai import OpenAIChat
from phi.tools.duckduckgo import DuckDuckG


#### Initialize the language model (OpenAI GPT-4 in this case)

    model = OpenAIChat(id="gpt-4o")

#### Initialize the web search agent with the DuckDuckGo tool

    web_agent = Agent(
        name="Web Search Agent",
        model=model,
        tools=[DuckDuckGo()],
        instructions=["Always include sources"],
        show_tool_calls=True,
        markdown=True,
    )

Ask the agent a sample question and print the response


query = "Tell me about OpenAI Sora?"
web_agent.print_response(query, stream=True)

Let’s break down this code and explain the key components:

Imports: We import Agent from phi.agent, the OpenAI chat model wrapper, and the DuckDuckGo tool class. These are provided by Phidata’s library
Model Setup: OpenAIChat(id="gpt-4o") creates an LLM instance for the agent

Here we chose an OpenAI GPT-4 model (denoted by `"gpt-4o"` in Phidata). You could switch this to a different model if needed (e.g., GPT-3.5 or a local model via Ollama as in the Dev example

Agent Initialization: We create an Agent with several parameters


`name`: A human-friendly name for the agent (optional, used for logging or UI).
`model`: The LLM to use (the `OpenAIChat` instance we created).
`tools`: A list of tools the agent can use. Here we pass `[DuckDuckGo()]`, enabling web search capability
    
  . The DuckDuckGo tool allows the agent to perform web queries and fetch news via DuckDuckGo’s API
   
`instructions`: A list of guidelines for the agent. We include `"Always include sources"` to prompt the agent to add source references in its answers
   
    These instructions are incorporated into the agent’s system prompt, influencing its behavior

Using the Agent: Finally, we use web_agent.print_response(query, stream=True) to run the agent on a query and print the answer

The stream=True option streams the response tokens as they are generated, which is handy for interactive use. You can set stream=False to wait and get the full response at once (the default is False if not specified).

Step 3: Run Your Agent

Simply execute:

python web_search.py

When prompted, the agent will search DuckDuckGo for the latest information on France, then generate a summarized answer. If you watch the console, you’ll notice output indicating when the agent makes a search call. Finally, you’ll get a response with a brief summary along with any relevant sources.

Best Practices for Optimizing Search Performance

Building a search agent is powerful, but to make it efficient and reliable, consider the following best practices:

Limit Search Results: By default, the DuckDuckGo toolkit will return a number of results (the exact number can vary). If you only need the top few hits, set the fixed_max_results parameter for the DuckDuckGo tool. For example, DuckDuckGo(fixed_max_results=5) will limit to 5 results
docs.phidata.com
- This can speed up the search and reduce noise. Similarly, other search tools like GoogleSearch have parameters like max_results
- docs.phidata.com
Use Caching for Repeated Queries: If your agent will handle recurring queries or is part of a larger workflow, caching results can improve performance. Phidata supports caching via its storage mechanism. For instance, you could store search results in a local SQLite database and reuse them to avoid calling the search API repeatedly
docs.phidata.com
This is especially useful for expensive operations or when running in batch workflows.
Optimize Tool Usage: Ensure your agent’s instructions are clear so it only calls the search tool when necessary. Ambiguous prompts might lead the LLM to make redundant searches or take irrelevant actions. During development, use show_tool_calls=True and even debug_mode=True (which prints raw logs) to understand the agent’s decision-making and refine its prompt or tools
Choose the Right Search Toolkit: Phidata offers multiple web search integrations. DuckDuckGo is handy for general use (no API key required), but you might consider alternatives:
- GoogleSearch: for more comprehensive results or news from Google’s index
- SerpAPI or SearxNG: if you need more control or a different search engine with an API
- BaiduSearch: if you need results from a different region/language (e.g., Chinese web).
  Each toolkit may have its own strengths, rate limits, or requirements, so pick one that fits your use case.

You can find the full code in this gist

Conclusion

Building a simple web search agent with Phidata only takes a few lines of code. By pairing a language model (like GPT-4 or GPT-3.5) with a search toolkit (DuckDuckGo in this case), you can quickly produce an agent that provides up-to-date information—complete with source citations. From here, you can extend its functionality by adding more tools or hooking up other models. Phidata’s flexibility and ease of use let you mix and match capabilities as your project grows.

Feel free to experiment with different instructions, additional data sources, or custom tools. Your search agent can evolve into a powerful assistant that tackles everything from quick fact checks to in-depth research.

About Author

Kartik Puri