pydantic_ai.common_tools
Bases: TypedDict
A DuckDuckGo search result.
The title of the search result.
Type: str
The URL of the search result.
Type: str
The body of the search result.
Type: str
The DuckDuckGo search tool.
The DuckDuckGo search client.
Type: DDGS
The maximum number of results. If None, returns results only from the first response.
@async
def __call__(query: str) -> list[DuckDuckGoResult]
Searches DuckDuckGo for the given query and returns the results.
list[DuckDuckGoResult] — The search results.
query : str
The query to search for.
def duckduckgo_search_tool(
duckduckgo_client: DDGS | None = None,
max_results: int | None = None,
)
Creates a DuckDuckGo search tool.
duckduckgo_client : DDGS | None Default: None
The DuckDuckGo search client.
The maximum number of results. If None, returns results only from the first response.
Exa tools for Pydantic AI agents.
Provides web search, content retrieval, and AI-powered answer capabilities using the Exa API, a neural search engine that finds high-quality, relevant results across billions of web pages.
Bases: TypedDict
An Exa search result with content.
See Exa Search API documentation for more information.
The title of the search result.
Type: str
The URL of the search result.
Type: str
The published date of the content, if available.
The author of the content, if available.
The text content of the search result.
Type: str
Bases: TypedDict
An Exa answer result with citations.
See Exa Answer API documentation for more information.
The AI-generated answer to the query.
Type: str
Citations supporting the answer.
Bases: TypedDict
Content retrieved from a URL.
See Exa Contents API documentation for more information.
The URL of the content.
Type: str
The title of the page.
Type: str
The text content of the page.
Type: str
The author of the content, if available.
The published date of the content, if available.
The Exa search tool.
The Exa async client.
Type: AsyncExa
The number of results to return.
Type: int
Maximum characters of text content per result, or None for no limit.
@async
def __call__(
query: str,
search_type: Literal['auto', 'keyword', 'neural', 'fast', 'deep'] = 'auto',
) -> list[ExaSearchResult]
Searches Exa for the given query and returns the results with content.
list[ExaSearchResult] — The search results with text content.
query : str
The search query to execute with Exa.
search_type : Literal[‘auto’, ‘keyword’, ‘neural’, ‘fast’, ‘deep’] Default: 'auto'
The type of search to perform. ‘auto’ automatically chooses the best search type, ‘keyword’ for exact matches, ‘neural’ for semantic search, ‘fast’ for speed-optimized search, ‘deep’ for comprehensive multi-query search.
The Exa find similar tool.
The Exa async client.
Type: AsyncExa
The number of results to return.
Type: int
@async
def __call__(url: str, exclude_source_domain: bool = True) -> list[ExaSearchResult]
Finds pages similar to the given URL and returns them with content.
list[ExaSearchResult] — Similar pages with text content.
url : str
The URL to find similar pages for.
exclude_source_domain : bool Default: True
Whether to exclude results from the same domain as the input URL. Defaults to True.
The Exa get contents tool.
The Exa async client.
Type: AsyncExa
@async
def __call__(urls: list[str]) -> list[ExaContentResult]
Gets the content of the specified URLs.
list[ExaContentResult] — The content of each URL.
A list of URLs to get content for.
The Exa answer tool.
The Exa async client.
Type: AsyncExa
@async
def __call__(query: str) -> ExaAnswerResult
Generates an AI-powered answer to the query with citations.
ExaAnswerResult — An answer with supporting citations from web sources.
query : str
The question to answer.
Bases: FunctionToolset
A toolset that provides Exa search tools with a shared client.
This is more efficient than creating individual tools when using multiple Exa tools, as it shares a single API client across all tools.
Example:
from pydantic_ai import Agent
from pydantic_ai.common_tools.exa import ExaToolset
toolset = ExaToolset(api_key='your-api-key')
agent = Agent('openai:gpt-5.2', toolsets=[toolset])
def __init__(
api_key: str,
num_results: int = 5,
max_characters: int | None = None,
include_search: bool = True,
include_find_similar: bool = True,
include_get_contents: bool = True,
include_answer: bool = True,
id: str | None = None,
)
Creates an Exa toolset with a shared client.
api_key : str
The Exa API key.
You can get one by signing up at https://dashboard.exa.ai.
num_results : int Default: 5
The number of results to return for search and find_similar. Defaults to 5.
Maximum characters of text content per result. Use this to limit token usage. Defaults to None (no limit).
include_search : bool Default: True
Whether to include the search tool. Defaults to True.
include_find_similar : bool Default: True
Whether to include the find_similar tool. Defaults to True.
include_get_contents : bool Default: True
Whether to include the get_contents tool. Defaults to True.
include_answer : bool Default: True
Whether to include the answer tool. Defaults to True.
Optional ID for the toolset, used for durable execution environments.
def exa_search_tool(
api_key: str,
num_results: int = 5,
max_characters: int | None = None,
) -> Tool[Any]
def exa_search_tool(
client: AsyncExa,
num_results: int = 5,
max_characters: int | None = None,
) -> Tool[Any]
Creates an Exa search tool.
The Exa API key. Required if client is not provided.
You can get one by signing up at https://dashboard.exa.ai.
client : AsyncExa | None Default: None
An existing AsyncExa client. If provided, api_key is ignored.
This is useful for sharing a client across multiple tools.
num_results : int Default: 5
The number of results to return. Defaults to 5.
Maximum characters of text content per result. Use this to limit token usage. Defaults to None (no limit).
def exa_find_similar_tool(api_key: str, num_results: int = 5) -> Tool[Any]
def exa_find_similar_tool(client: AsyncExa, num_results: int = 5) -> Tool[Any]
Creates an Exa find similar tool.
The Exa API key. Required if client is not provided.
You can get one by signing up at https://dashboard.exa.ai.
client : AsyncExa | None Default: None
An existing AsyncExa client. If provided, api_key is ignored.
This is useful for sharing a client across multiple tools.
num_results : int Default: 5
The number of similar results to return. Defaults to 5.
def exa_get_contents_tool(api_key: str) -> Tool[Any]
def exa_get_contents_tool(client: AsyncExa) -> Tool[Any]
Creates an Exa get contents tool.
The Exa API key. Required if client is not provided.
You can get one by signing up at https://dashboard.exa.ai.
client : AsyncExa | None Default: None
An existing AsyncExa client. If provided, api_key is ignored.
This is useful for sharing a client across multiple tools.
def exa_answer_tool(api_key: str) -> Tool[Any]
def exa_answer_tool(client: AsyncExa) -> Tool[Any]
Creates an Exa answer tool.
The Exa API key. Required if client is not provided.
You can get one by signing up at https://dashboard.exa.ai.
client : AsyncExa | None Default: None
An existing AsyncExa client. If provided, api_key is ignored.
This is useful for sharing a client across multiple tools.
Bases: TypedDict
A Tavily search result.
See Tavily Search Endpoint documentation for more information.
The title of the search result.
Type: str
The URL of the search result..
Type: str
A short description of the search result.
Type: str
The relevance score of the search result.
Type: float
The Tavily search tool.
The Tavily search client.
Type: AsyncTavilyClient
The maximum number of results. If None, the Tavily default is used.
Type: int | None Default: None
@async
def __call__(
query: str,
search_depth: Literal['basic', 'advanced', 'fast', 'ultra-fast'] = 'basic',
topic: Literal['general', 'news', 'finance'] = 'general',
time_range: Literal['day', 'week', 'month', 'year'] | None = None,
include_domains: list[str] | None = None,
exclude_domains: list[str] | None = None,
) -> list[TavilySearchResult]
Searches Tavily for the given query and returns the results.
list[TavilySearchResult] — A list of search results from Tavily.
query : str
The search query to execute with Tavily.
search_depth : Literal[‘basic’, ‘advanced’, ‘fast’, ‘ultra-fast’] Default: 'basic'
The depth of the search.
topic : Literal[‘general’, ‘news’, ‘finance’] Default: 'general'
The category of the search.
The time range back from the current date to filter results.
List of domains to specifically include in the search results.
List of domains to specifically exclude from the search results.
def tavily_search_tool(
api_key: str,
max_results: int | None = None,
search_depth: Literal['basic', 'advanced', 'fast', 'ultra-fast'] = _UNSET,
topic: Literal['general', 'news', 'finance'] = _UNSET,
time_range: Literal['day', 'week', 'month', 'year'] | None = _UNSET,
include_domains: list[str] | None = _UNSET,
exclude_domains: list[str] | None = _UNSET,
) -> Tool[Any]
def tavily_search_tool(
client: AsyncTavilyClient,
max_results: int | None = None,
search_depth: Literal['basic', 'advanced', 'fast', 'ultra-fast'] = _UNSET,
topic: Literal['general', 'news', 'finance'] = _UNSET,
time_range: Literal['day', 'week', 'month', 'year'] | None = _UNSET,
include_domains: list[str] | None = _UNSET,
exclude_domains: list[str] | None = _UNSET,
) -> Tool[Any]
Creates a Tavily search tool.
max_results is always developer-controlled and does not appear in the LLM tool schema.
Other parameters, when provided, are fixed for all searches and hidden from the LLM’s
tool schema. Parameters left unset remain available for the LLM to set per-call.
The Tavily API key. Required if client is not provided.
You can get one by signing up at https://app.tavily.com/home.
client : AsyncTavilyClient | None Default: None
An existing AsyncTavilyClient. If provided, api_key is ignored.
This is useful for sharing a client across multiple tool instances.
The maximum number of results. If None, the Tavily default is used.
search_depth : Literal[‘basic’, ‘advanced’, ‘fast’, ‘ultra-fast’] Default: _UNSET
The depth of the search.
topic : Literal[‘general’, ‘news’, ‘finance’] Default: _UNSET
The category of the search.
The time range back from the current date to filter results.
List of domains to specifically include in the search results.
List of domains to specifically exclude from the search results.