---
title: "Web Search Tool Agents"
category: 11-web
level: basic
stability: stable
description: "Equip agents with web search capabilities using hosted or custom search tools."
added: "2026-04"
version: v2
---

# Web Search Tool Agents
Category: web | Level: beginner | Stability: stable | Version: v2

## Description
Web search tools give agents real-time access to the internet. In the OpenAI Agents SDK, `WebSearchTool()` is a hosted tool that queries the web and returns ranked results without requiring external API keys. For custom search, agents can call Bing, Brave, or Serper APIs as function tools. Web search is critical for agents that need up-to-date information beyond their training cutoff.

## Inputs
- `query`: search string generated by the agent
- `tool`: `WebSearchTool()` (hosted) or custom function tool wrapping a search API
- `max_results`: integer limit on results returned

## Outputs
- List of search result objects with `title`, `url`, `snippet`
- Agent synthesises final answer from results

## Example
```python
from agents import Agent, Runner, WebSearchTool

agent = Agent(
    name="ResearchAgent",
    instructions="Answer questions using current web information.",
    tools=[WebSearchTool()]
)

result = Runner.run_sync(agent, "What is the current price of Bitcoin?")
print(result.final_output)
```

## Failure Modes
| Cause | Symptom | Mitigation |
|---|---|---|
| Query too vague | Irrelevant results | Instruct agent to generate specific, targeted queries |
| Rate limit hit | Tool call fails | Add retry with exponential backoff |
| Results outdated | Stale information returned | Append current date to query to bias freshness |

## Prompt Patterns
**Basic:** `"Search the web to find the most current answer."`

**Chain-of-Thought:** `"Formulate a precise search query, retrieve results, then synthesise an answer with source citations."`

**Constrained Output:** `"Cite the URL for every factual claim you make from search results."`

## Model Comparison
| Capability | GPT-4o | Claude 3.7 Sonnet | Gemini 2.0 Flash |
|---|---|---|---|
| Query formulation quality | ✅ High | ✅ High | ✅ Good |
| Result synthesis | ✅ Strong | ✅ Strong | ✅ Good |
| Citation accuracy | ✅ Reliable | ✅ Reliable | ⚠️ Occasional hallucination |
| Native search tool | ✅ WebSearchTool | ⚠️ Requires custom | ✅ Google Search grounding |
| Cost | Moderate | Moderate | Low |

## Related
- `web-search.md` · `url-fetching.md` · `web-scraping.md` · `agent-handoffs.md`

## Changelog
- v2 (2026-04): Full expansion
