docs/capabilities/web-search.md
The [WebSearch][pydantic_ai.capabilities.WebSearch] capability gives your agent web search. Like all provider-adaptive tools, it uses the provider's native web search when the model supports it and can fall back to a local implementation on other models.
[WebSearch][pydantic_ai.capabilities.WebSearch] defaults to native-only. Backed by [WebSearchTool][pydantic_ai.native_tools.WebSearchTool] on the native side (see Web Search Tool for provider support and configuration) — pass native=WebSearchTool(...) directly when you need full control over the native instance.
For the local side, pass local='duckduckgo' (or local=True) for a DuckDuckGo fallback (requires the duckduckgo optional group); for other search providers, use a [Tavily][pydantic_ai.common_tools.tavily.tavily_search_tool] or [Exa][pydantic_ai.common_tools.exa.ExaSearchTool] wrapper from common_tools, or any callable, [Tool][pydantic_ai.tools.Tool], or [AbstractToolset][pydantic_ai.toolsets.AbstractToolset].
Native constraint fields: search_context_size, user_location, blocked_domains, allowed_domains, max_uses. The domain and max_uses constraints require native support (the shipped DuckDuckGo fallback doesn't enforce them).
from pydantic_ai.capabilities import WebSearch
# Native-only — raises on models without native web search
WebSearch()
# Native preferred; DuckDuckGo fallback (needs `pydantic-ai-slim[duckduckgo]`)
WebSearch(local='duckduckgo')
# Native preferred; custom callable as fallback
def my_search(query: str) -> str: ...
WebSearch(local=my_search)