Skip to content

pydantic_ai.common_tools

DuckDuckGoResult

Bases: TypedDict

A DuckDuckGo search result.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/duckduckgo.py 
24
25
26
27
28
29
30
31
32
class DuckDuckGoResult(TypedDict):
    """A DuckDuckGo search result."""

    title: str
    """The title of the search result."""
    href: str
    """The URL of the search result."""
    body: str
    """The body of the search result."""

title instance-attribute 

title: str

The title of the search result.

href instance-attribute 

href: str

The URL of the search result.

body instance-attribute 

body: str

The body of the search result.

DuckDuckGoSearchTool dataclass

The DuckDuckGo search tool.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/duckduckgo.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@dataclass
class DuckDuckGoSearchTool:
    """The DuckDuckGo search tool."""

    client: DDGS
    """The DuckDuckGo search client."""

    _: KW_ONLY

    max_results: int | None
    """The maximum number of results. If None, returns results only from the first response."""

    async def __call__(self, query: str) -> list[DuckDuckGoResult]:
        """Searches DuckDuckGo for the given query and returns the results.

        Args:
            query: The query to search for.

        Returns:
            The search results.
        """
        search = functools.partial(self.client.text, max_results=self.max_results)
        results = await anyio.to_thread.run_sync(search, query)
        return duckduckgo_ta.validate_python(results)

client instance-attribute 

client: DDGS

The DuckDuckGo search client.

max_results instance-attribute 

max_results: int | None

The maximum number of results. If None, returns results only from the first response.

__call__ async 

__call__(query: str) -> list[DuckDuckGoResult]

Searches DuckDuckGo for the given query and returns the results.

Parameters:

Name Type Description Default
query str

The query to search for.

 required

Returns:

Type Description
list[DuckDuckGoResult]

The search results.
Source code in pydantic_ai_slim/pydantic_ai/common_tools/duckduckgo.py 
50
51
52
53
54
55
56
57
58
59
60
61
async def __call__(self, query: str) -> list[DuckDuckGoResult]:
    """Searches DuckDuckGo for the given query and returns the results.

    Args:
        query: The query to search for.

    Returns:
        The search results.
    """
    search = functools.partial(self.client.text, max_results=self.max_results)
    results = await anyio.to_thread.run_sync(search, query)
    return duckduckgo_ta.validate_python(results)

duckduckgo_search_tool 

duckduckgo_search_tool(
    duckduckgo_client: DDGS | None = None,
    max_results: int | None = None,
)

Creates a DuckDuckGo search tool.

Parameters:

Name Type Description Default
duckduckgo_client DDGS | None

The DuckDuckGo search client.

 None
max_results int | None

The maximum number of results. If None, returns results only from the first response.

 None
Source code in pydantic_ai_slim/pydantic_ai/common_tools/duckduckgo.py 
64
65
66
67
68
69
70
71
72
73
74
75
def duckduckgo_search_tool(duckduckgo_client: DDGS | None = None, max_results: int | None = None):
    """Creates a DuckDuckGo search tool.

    Args:
        duckduckgo_client: The DuckDuckGo search client.
        max_results: The maximum number of results. If None, returns results only from the first response.
    """
    return Tool[Any](
        DuckDuckGoSearchTool(client=duckduckgo_client or DDGS(), max_results=max_results).__call__,
        name='duckduckgo_search',
        description='Searches DuckDuckGo for the given query and returns the results.',
    )

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.

ExaSearchResult

Bases: TypedDict

An Exa search result with content.

See Exa Search API documentation for more information.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class ExaSearchResult(TypedDict):
    """An Exa search result with content.

    See [Exa Search API documentation](https://docs.exa.ai/reference/search)
    for more information.
    """

    title: str
    """The title of the search result."""
    url: str
    """The URL of the search result."""
    published_date: str | None
    """The published date of the content, if available."""
    author: str | None
    """The author of the content, if available."""
    text: str
    """The text content of the search result."""

title instance-attribute 

title: str

The title of the search result.

url instance-attribute 

url: str

The URL of the search result.

published_date instance-attribute 

published_date: str | None

The published date of the content, if available.

author instance-attribute 

author: str | None

The author of the content, if available.

text instance-attribute 

text: str

The text content of the search result.

ExaAnswerResult

Bases: TypedDict

An Exa answer result with citations.

See Exa Answer API documentation for more information.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
58
59
60
61
62
63
64
65
66
67
68
class ExaAnswerResult(TypedDict):
    """An Exa answer result with citations.

    See [Exa Answer API documentation](https://docs.exa.ai/reference/answer)
    for more information.
    """

    answer: str
    """The AI-generated answer to the query."""
    citations: list[dict[str, Any]]
    """Citations supporting the answer."""

answer instance-attribute 

answer: str

The AI-generated answer to the query.

citations instance-attribute 

citations: list[dict[str, Any]]

Citations supporting the answer.

ExaContentResult

Bases: TypedDict

Content retrieved from a URL.

See Exa Contents API documentation for more information.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
class ExaContentResult(TypedDict):
    """Content retrieved from a URL.

    See [Exa Contents API documentation](https://docs.exa.ai/reference/get-contents)
    for more information.
    """

    url: str
    """The URL of the content."""
    title: str
    """The title of the page."""
    text: str
    """The text content of the page."""
    author: str | None
    """The author of the content, if available."""
    published_date: str | None
    """The published date of the content, if available."""

url instance-attribute 

url: str

The URL of the content.

title instance-attribute 

title: str

The title of the page.

text instance-attribute 

text: str

The text content of the page.

author instance-attribute 

author: str | None

The author of the content, if available.

published_date instance-attribute 

published_date: str | None

The published date of the content, if available.

ExaSearchTool dataclass

The Exa search tool.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@dataclass
class ExaSearchTool:
    """The Exa search tool."""

    client: AsyncExa
    """The Exa async client."""

    num_results: int
    """The number of results to return."""

    max_characters: int | None
    """Maximum characters of text content per result, or None for no limit."""

    async def __call__(
        self,
        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.

        Args:
            query: The search query to execute with Exa.
            search_type: 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.

        Returns:
            The search results with text content.
        """
        text_config: TextContentsOptions | Literal[True] = (
            {'max_characters': self.max_characters} if self.max_characters is not None else True
        )
        contents: ContentsOptions = {'text': text_config}
        response = await self.client.search(
            query,
            num_results=self.num_results,
            type=search_type,
            contents=contents,
        )

        return [
            ExaSearchResult(
                title=result.title or '',
                url=result.url,
                published_date=result.published_date,
                author=result.author,
                text=result.text or '',
            )
            for result in response.results
        ]

client instance-attribute 

client: AsyncExa

The Exa async client.

num_results instance-attribute 

num_results: int

The number of results to return.

max_characters instance-attribute 

max_characters: int | None

Maximum characters of text content per result, or None for no limit.

__call__ async 

__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.

Parameters:

Name Type Description Default
query str

The search query to execute with Exa.

 required
search_type Literal['auto', 'keyword', 'neural', 'fast', 'deep']

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.

 'auto'

Returns:

Type Description
list[ExaSearchResult]

The search results with text content.
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
async def __call__(
    self,
    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.

    Args:
        query: The search query to execute with Exa.
        search_type: 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.

    Returns:
        The search results with text content.
    """
    text_config: TextContentsOptions | Literal[True] = (
        {'max_characters': self.max_characters} if self.max_characters is not None else True
    )
    contents: ContentsOptions = {'text': text_config}
    response = await self.client.search(
        query,
        num_results=self.num_results,
        type=search_type,
        contents=contents,
    )

    return [
        ExaSearchResult(
            title=result.title or '',
            url=result.url,
            published_date=result.published_date,
            author=result.author,
            text=result.text or '',
        )
        for result in response.results
    ]

ExaFindSimilarTool dataclass

The Exa find similar tool.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
@dataclass
class ExaFindSimilarTool:
    """The Exa find similar tool."""

    client: AsyncExa
    """The Exa async client."""

    num_results: int
    """The number of results to return."""

    async def __call__(
        self,
        url: str,
        exclude_source_domain: bool = True,
    ) -> list[ExaSearchResult]:
        """Finds pages similar to the given URL and returns them with content.

        Args:
            url: The URL to find similar pages for.
            exclude_source_domain: Whether to exclude results from the same domain
                as the input URL. Defaults to True.

        Returns:
            Similar pages with text content.
        """
        contents: ContentsOptions = {'text': True}
        response = await self.client.find_similar(  # pyright: ignore[reportDeprecated]
            url,
            num_results=self.num_results,
            exclude_source_domain=exclude_source_domain,
            contents=contents,
        )

        return [
            ExaSearchResult(
                title=result.title or '',
                url=result.url,
                published_date=result.published_date,
                author=result.author,
                text=result.text or '',
            )
            for result in response.results
        ]

client instance-attribute 

client: AsyncExa

The Exa async client.

num_results instance-attribute 

num_results: int

The number of results to return.

__call__ async 

__call__(
    url: str, exclude_source_domain: bool = True
) -> list[ExaSearchResult]

Finds pages similar to the given URL and returns them with content.

Parameters:

Name Type Description Default
url str

The URL to find similar pages for.

 required
exclude_source_domain bool

Whether to exclude results from the same domain as the input URL. Defaults to True.

 True

Returns:

Type Description
list[ExaSearchResult]

Similar pages with text content.
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
async def __call__(
    self,
    url: str,
    exclude_source_domain: bool = True,
) -> list[ExaSearchResult]:
    """Finds pages similar to the given URL and returns them with content.

    Args:
        url: The URL to find similar pages for.
        exclude_source_domain: Whether to exclude results from the same domain
            as the input URL. Defaults to True.

    Returns:
        Similar pages with text content.
    """
    contents: ContentsOptions = {'text': True}
    response = await self.client.find_similar(  # pyright: ignore[reportDeprecated]
        url,
        num_results=self.num_results,
        exclude_source_domain=exclude_source_domain,
        contents=contents,
    )

    return [
        ExaSearchResult(
            title=result.title or '',
            url=result.url,
            published_date=result.published_date,
            author=result.author,
            text=result.text or '',
        )
        for result in response.results
    ]

ExaGetContentsTool dataclass

The Exa get contents tool.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
@dataclass
class ExaGetContentsTool:
    """The Exa get contents tool."""

    client: AsyncExa
    """The Exa async client."""

    async def __call__(
        self,
        urls: list[str],
    ) -> list[ExaContentResult]:
        """Gets the content of the specified URLs.

        Args:
            urls: A list of URLs to get content for.

        Returns:
            The content of each URL.
        """
        response = await self.client.get_contents(urls, text=True)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]

        return [
            ExaContentResult(
                url=result.url,  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
                title=result.title or '',  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
                text=result.text or '',  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
                author=result.author,  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
                published_date=result.published_date,  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
            )
            for result in response.results  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
        ]

client instance-attribute 

client: AsyncExa

The Exa async client.

__call__ async 

__call__(urls: list[str]) -> list[ExaContentResult]

Gets the content of the specified URLs.

Parameters:

Name Type Description Default
urls list[str]

A list of URLs to get content for.

 required

Returns:

Type Description
list[ExaContentResult]

The content of each URL.
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
async def __call__(
    self,
    urls: list[str],
) -> list[ExaContentResult]:
    """Gets the content of the specified URLs.

    Args:
        urls: A list of URLs to get content for.

    Returns:
        The content of each URL.
    """
    response = await self.client.get_contents(urls, text=True)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]

    return [
        ExaContentResult(
            url=result.url,  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
            title=result.title or '',  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
            text=result.text or '',  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
            author=result.author,  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
            published_date=result.published_date,  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
        )
        for result in response.results  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
    ]

ExaAnswerTool dataclass

The Exa answer tool.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
@dataclass
class ExaAnswerTool:
    """The Exa answer tool."""

    client: AsyncExa
    """The Exa async client."""

    async def __call__(
        self,
        query: str,
    ) -> ExaAnswerResult:
        """Generates an AI-powered answer to the query with citations.

        Args:
            query: The question to answer.

        Returns:
            An answer with supporting citations from web sources.
        """
        response = await self.client.answer(query, text=True)

        return ExaAnswerResult(
            answer=response.answer,  # pyright: ignore[reportUnknownMemberType,reportArgumentType,reportAttributeAccessIssue]
            citations=[
                {
                    'url': citation.url,  # pyright: ignore[reportUnknownMemberType]
                    'title': citation.title or '',  # pyright: ignore[reportUnknownMemberType]
                    'text': citation.text or '',  # pyright: ignore[reportUnknownMemberType]
                }
                for citation in response.citations  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType,reportAttributeAccessIssue]
            ],
        )

client instance-attribute 

client: AsyncExa

The Exa async client.

__call__ async 

__call__(query: str) -> ExaAnswerResult

Generates an AI-powered answer to the query with citations.

Parameters:

Name Type Description Default
query str

The question to answer.

 required

Returns:

Type Description
ExaAnswerResult

An answer with supporting citations from web sources.
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
async def __call__(
    self,
    query: str,
) -> ExaAnswerResult:
    """Generates an AI-powered answer to the query with citations.

    Args:
        query: The question to answer.

    Returns:
        An answer with supporting citations from web sources.
    """
    response = await self.client.answer(query, text=True)

    return ExaAnswerResult(
        answer=response.answer,  # pyright: ignore[reportUnknownMemberType,reportArgumentType,reportAttributeAccessIssue]
        citations=[
            {
                'url': citation.url,  # pyright: ignore[reportUnknownMemberType]
                'title': citation.title or '',  # pyright: ignore[reportUnknownMemberType]
                'text': citation.text or '',  # pyright: ignore[reportUnknownMemberType]
            }
            for citation in response.citations  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType,reportAttributeAccessIssue]
        ],
    )

exa_search_tool 

exa_search_tool(
    api_key: str,
    *,
    num_results: int = 5,
    max_characters: int | None = None
) -> Tool[Any]

exa_search_tool(
    *,
    client: AsyncExa,
    num_results: int = 5,
    max_characters: int | None = None
) -> Tool[Any]

exa_search_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None,
    num_results: int = 5,
    max_characters: int | None = None
) -> Tool[Any]

Creates an Exa search tool.

Parameters:

Name Type Description Default
api_key str | None

The Exa API key. Required if client is not provided.

You can get one by signing up at https://dashboard.exa.ai.

 None
client AsyncExa | None

An existing AsyncExa client. If provided, api_key is ignored. This is useful for sharing a client across multiple tools.

 None
num_results int

The number of results to return. Defaults to 5.

 5
max_characters int | None

Maximum characters of text content per result. Use this to limit token usage. Defaults to None (no limit).

 None
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
def exa_search_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None,
    num_results: int = 5,
    max_characters: int | None = None,
) -> Tool[Any]:
    """Creates an Exa search tool.

    Args:
        api_key: The Exa API key. Required if `client` is not provided.

            You can get one by signing up at [https://dashboard.exa.ai](https://dashboard.exa.ai).
        client: An existing AsyncExa client. If provided, `api_key` is ignored.
            This is useful for sharing a client across multiple tools.
        num_results: The number of results to return. Defaults to 5.
        max_characters: Maximum characters of text content per result. Use this to limit
            token usage. Defaults to None (no limit).
    """
    if client is None:
        if api_key is None:
            raise ValueError('Either api_key or client must be provided')
        client = AsyncExa(api_key=api_key)
    return Tool[Any](
        ExaSearchTool(
            client=client,
            num_results=num_results,
            max_characters=max_characters,
        ).__call__,
        name='exa_search',
        description='Searches Exa for the given query and returns the results with content. Exa is a neural search engine that finds high-quality, relevant results.',
    )

exa_find_similar_tool 

exa_find_similar_tool(
    api_key: str, *, num_results: int = 5
) -> Tool[Any]

exa_find_similar_tool(
    *, client: AsyncExa, num_results: int = 5
) -> Tool[Any]

exa_find_similar_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None,
    num_results: int = 5
) -> Tool[Any]

Creates an Exa find similar tool.

Parameters:

Name Type Description Default
api_key str | None

The Exa API key. Required if client is not provided.

You can get one by signing up at https://dashboard.exa.ai.

 None
client AsyncExa | None

An existing AsyncExa client. If provided, api_key is ignored. This is useful for sharing a client across multiple tools.

 None
num_results int

The number of similar results to return. Defaults to 5.

 5
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
def exa_find_similar_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None,
    num_results: int = 5,
) -> Tool[Any]:
    """Creates an Exa find similar tool.

    Args:
        api_key: The Exa API key. Required if `client` is not provided.

            You can get one by signing up at [https://dashboard.exa.ai](https://dashboard.exa.ai).
        client: An existing AsyncExa client. If provided, `api_key` is ignored.
            This is useful for sharing a client across multiple tools.
        num_results: The number of similar results to return. Defaults to 5.
    """
    if client is None:
        if api_key is None:
            raise ValueError('Either api_key or client must be provided')
        client = AsyncExa(api_key=api_key)
    return Tool[Any](
        ExaFindSimilarTool(client=client, num_results=num_results).__call__,
        name='exa_find_similar',
        description='Finds web pages similar to a given URL. Useful for discovering related content, competitors, or alternative sources.',
    )

exa_get_contents_tool 

exa_get_contents_tool(api_key: str) -> Tool[Any]

exa_get_contents_tool(*, client: AsyncExa) -> Tool[Any]

exa_get_contents_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None
) -> Tool[Any]

Creates an Exa get contents tool.

Parameters:

Name Type Description Default
api_key str | None

The Exa API key. Required if client is not provided.

You can get one by signing up at https://dashboard.exa.ai.

 None
client AsyncExa | None

An existing AsyncExa client. If provided, api_key is ignored. This is useful for sharing a client across multiple tools.

 None
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
def exa_get_contents_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None,
) -> Tool[Any]:
    """Creates an Exa get contents tool.

    Args:
        api_key: The Exa API key. Required if `client` is not provided.

            You can get one by signing up at [https://dashboard.exa.ai](https://dashboard.exa.ai).
        client: An existing AsyncExa client. If provided, `api_key` is ignored.
            This is useful for sharing a client across multiple tools.
    """
    if client is None:
        if api_key is None:
            raise ValueError('Either api_key or client must be provided')
        client = AsyncExa(api_key=api_key)
    return Tool[Any](
        ExaGetContentsTool(client=client).__call__,
        name='exa_get_contents',
        description='Gets the full text content of specified URLs. Useful for reading articles, documentation, or any web page when you have the exact URL.',
    )

exa_answer_tool 

exa_answer_tool(api_key: str) -> Tool[Any]

exa_answer_tool(*, client: AsyncExa) -> Tool[Any]

exa_answer_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None
) -> Tool[Any]

Creates an Exa answer tool.

Parameters:

Name Type Description Default
api_key str | None

The Exa API key. Required if client is not provided.

You can get one by signing up at https://dashboard.exa.ai.

 None
client AsyncExa | None

An existing AsyncExa client. If provided, api_key is ignored. This is useful for sharing a client across multiple tools.

 None
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
def exa_answer_tool(
    api_key: str | None = None,
    *,
    client: AsyncExa | None = None,
) -> Tool[Any]:
    """Creates an Exa answer tool.

    Args:
        api_key: The Exa API key. Required if `client` is not provided.

            You can get one by signing up at [https://dashboard.exa.ai](https://dashboard.exa.ai).
        client: An existing AsyncExa client. If provided, `api_key` is ignored.
            This is useful for sharing a client across multiple tools.
    """
    if client is None:
        if api_key is None:
            raise ValueError('Either api_key or client must be provided')
        client = AsyncExa(api_key=api_key)
    return Tool[Any](
        ExaAnswerTool(client=client).__call__,
        name='exa_answer',
        description='Generates an AI-powered answer to a question with citations from web sources. Returns a comprehensive answer backed by real sources.',
    )

ExaToolset

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])

Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
class ExaToolset(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:
    ```python
    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__(
        self,
        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.

        Args:
            api_key: The Exa API key.

                You can get one by signing up at [https://dashboard.exa.ai](https://dashboard.exa.ai).
            num_results: The number of results to return for search and find_similar. Defaults to 5.
            max_characters: Maximum characters of text content per result. Use this to limit
                token usage. Defaults to None (no limit).
            include_search: Whether to include the search tool. Defaults to True.
            include_find_similar: Whether to include the find_similar tool. Defaults to True.
            include_get_contents: Whether to include the get_contents tool. Defaults to True.
            include_answer: Whether to include the answer tool. Defaults to True.
            id: Optional ID for the toolset, used for durable execution environments.
        """
        client = AsyncExa(api_key=api_key)
        tools: list[Tool[Any]] = []

        if include_search:
            tools.append(exa_search_tool(client=client, num_results=num_results, max_characters=max_characters))

        if include_find_similar:
            tools.append(exa_find_similar_tool(client=client, num_results=num_results))

        if include_get_contents:
            tools.append(exa_get_contents_tool(client=client))

        if include_answer:
            tools.append(exa_answer_tool(client=client))

        super().__init__(tools, id=id)

__init__ 

__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.

Parameters:

Name Type Description Default
api_key str

The Exa API key.

You can get one by signing up at https://dashboard.exa.ai.

 required
num_results int

The number of results to return for search and find_similar. Defaults to 5.

 5
max_characters int | None

Maximum characters of text content per result. Use this to limit token usage. Defaults to None (no limit).

 None
include_search bool

Whether to include the search tool. Defaults to True.

 True
include_find_similar bool

Whether to include the find_similar tool. Defaults to True.

 True
include_get_contents bool

Whether to include the get_contents tool. Defaults to True.

 True
include_answer bool

Whether to include the answer tool. Defaults to True.

 True
id str | None

Optional ID for the toolset, used for durable execution environments.

 None
Source code in pydantic_ai_slim/pydantic_ai/common_tools/exa.py 
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
def __init__(
    self,
    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.

    Args:
        api_key: The Exa API key.

            You can get one by signing up at [https://dashboard.exa.ai](https://dashboard.exa.ai).
        num_results: The number of results to return for search and find_similar. Defaults to 5.
        max_characters: Maximum characters of text content per result. Use this to limit
            token usage. Defaults to None (no limit).
        include_search: Whether to include the search tool. Defaults to True.
        include_find_similar: Whether to include the find_similar tool. Defaults to True.
        include_get_contents: Whether to include the get_contents tool. Defaults to True.
        include_answer: Whether to include the answer tool. Defaults to True.
        id: Optional ID for the toolset, used for durable execution environments.
    """
    client = AsyncExa(api_key=api_key)
    tools: list[Tool[Any]] = []

    if include_search:
        tools.append(exa_search_tool(client=client, num_results=num_results, max_characters=max_characters))

    if include_find_similar:
        tools.append(exa_find_similar_tool(client=client, num_results=num_results))

    if include_get_contents:
        tools.append(exa_get_contents_tool(client=client))

    if include_answer:
        tools.append(exa_answer_tool(client=client))

    super().__init__(tools, id=id)

TavilySearchResult

Bases: TypedDict

A Tavily search result.

See Tavily Search Endpoint documentation for more information.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/tavily.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class TavilySearchResult(TypedDict):
    """A Tavily search result.

    See [Tavily Search Endpoint documentation](https://docs.tavily.com/api-reference/endpoint/search)
    for more information.
    """

    title: str
    """The title of the search result."""
    url: str
    """The URL of the search result.."""
    content: str
    """A short description of the search result."""
    score: float
    """The relevance score of the search result."""

title instance-attribute 

title: str

The title of the search result.

url instance-attribute 

url: str

The URL of the search result..

content instance-attribute 

content: str

A short description of the search result.

score instance-attribute 

score: float

The relevance score of the search result.

TavilySearchTool dataclass

The Tavily search tool.

Source code in pydantic_ai_slim/pydantic_ai/common_tools/tavily.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@dataclass
class TavilySearchTool:
    """The Tavily search tool."""

    client: AsyncTavilyClient
    """The Tavily search client."""

    _: KW_ONLY

    max_results: int | None = None
    """The maximum number of results. If None, the Tavily default is used."""

    async def __call__(
        self,
        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.

        Args:
            query: The search query to execute with Tavily.
            search_depth: The depth of the search.
            topic: The category of the search.
            time_range: The time range back from the current date to filter results.
            include_domains: List of domains to specifically include in the search results.
            exclude_domains: List of domains to specifically exclude from the search results.

        Returns:
            A list of search results from Tavily.
        """
        results: dict[str, Any] = await self.client.search(  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
            query,
            search_depth=search_depth,
            topic=topic,
            time_range=time_range,  # pyright: ignore[reportArgumentType]
            max_results=self.max_results,  # pyright: ignore[reportArgumentType]
            include_domains=include_domains,  # pyright: ignore[reportArgumentType]
            exclude_domains=exclude_domains,  # pyright: ignore[reportArgumentType]
        )
        return tavily_search_ta.validate_python(results['results'])

client instance-attribute 

client: AsyncTavilyClient

The Tavily search client.

max_results class-attribute instance-attribute 

max_results: int | None = None

The maximum number of results. If None, the Tavily default is used.

__call__ async 

__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.

Parameters:

Name Type Description Default
query str

The search query to execute with Tavily.

 required
search_depth Literal['basic', 'advanced', 'fast', 'ultra-fast']

The depth of the search.

 'basic'
topic Literal['general', 'news', 'finance']

The category of the search.

 'general'
time_range Literal['day', 'week', 'month', 'year'] | None

The time range back from the current date to filter results.

 None
include_domains list[str] | None

List of domains to specifically include in the search results.

 None
exclude_domains list[str] | None

List of domains to specifically exclude from the search results.

 None

Returns:

Type Description
list[TavilySearchResult]

A list of search results from Tavily.
Source code in pydantic_ai_slim/pydantic_ai/common_tools/tavily.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
async def __call__(
    self,
    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.

    Args:
        query: The search query to execute with Tavily.
        search_depth: The depth of the search.
        topic: The category of the search.
        time_range: The time range back from the current date to filter results.
        include_domains: List of domains to specifically include in the search results.
        exclude_domains: List of domains to specifically exclude from the search results.

    Returns:
        A list of search results from Tavily.
    """
    results: dict[str, Any] = await self.client.search(  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
        query,
        search_depth=search_depth,
        topic=topic,
        time_range=time_range,  # pyright: ignore[reportArgumentType]
        max_results=self.max_results,  # pyright: ignore[reportArgumentType]
        include_domains=include_domains,  # pyright: ignore[reportArgumentType]
        exclude_domains=exclude_domains,  # pyright: ignore[reportArgumentType]
    )
    return tavily_search_ta.validate_python(results['results'])

tavily_search_tool 

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]

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]

tavily_search_tool(
    api_key: str | None = None,
    *,
    client: AsyncTavilyClient | None = None,
    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.

Parameters:

Name Type Description Default
api_key str | None

The Tavily API key. Required if client is not provided.

You can get one by signing up at https://app.tavily.com/home.

 None
client AsyncTavilyClient | None

An existing AsyncTavilyClient. If provided, api_key is ignored. This is useful for sharing a client across multiple tool instances.

 None
max_results int | None

The maximum number of results. If None, the Tavily default is used.

 None
search_depth Literal['basic', 'advanced', 'fast', 'ultra-fast']

The depth of the search.

 _UNSET
topic Literal['general', 'news', 'finance']

The category of the search.

 _UNSET
time_range Literal['day', 'week', 'month', 'year'] | None

The time range back from the current date to filter results.

 _UNSET
include_domains list[str] | None

List of domains to specifically include in the search results.

 _UNSET
exclude_domains list[str] | None

List of domains to specifically exclude from the search results.

 _UNSET
Source code in pydantic_ai_slim/pydantic_ai/common_tools/tavily.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def tavily_search_tool(
    api_key: str | None = None,
    *,
    client: AsyncTavilyClient | None = None,
    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.

    Args:
        api_key: The Tavily API key. Required if `client` is not provided.

            You can get one by signing up at [https://app.tavily.com/home](https://app.tavily.com/home).
        client: An existing AsyncTavilyClient. If provided, `api_key` is ignored.
            This is useful for sharing a client across multiple tool instances.
        max_results: The maximum number of results. If None, the Tavily default is used.
        search_depth: The depth of the search.
        topic: The category of the search.
        time_range: The time range back from the current date to filter results.
        include_domains: List of domains to specifically include in the search results.
        exclude_domains: List of domains to specifically exclude from the search results.
    """
    if client is None:
        if api_key is None:
            raise ValueError('Either api_key or client must be provided')
        client = AsyncTavilyClient(api_key)
    func = TavilySearchTool(client=client, max_results=max_results).__call__

    kwargs: dict[str, Any] = {}
    if search_depth is not _UNSET:
        kwargs['search_depth'] = search_depth
    if topic is not _UNSET:
        kwargs['topic'] = topic
    if time_range is not _UNSET:
        kwargs['time_range'] = time_range
    if include_domains is not _UNSET:
        kwargs['include_domains'] = include_domains
    if exclude_domains is not _UNSET:
        kwargs['exclude_domains'] = exclude_domains

    if kwargs:
        original = func
        func = partial(func, **kwargs)
        func.__name__ = original.__name__  # type: ignore[union-attr]
        func.__qualname__ = original.__qualname__
        # partial with keyword args only updates defaults, not removes params.
        # Set __signature__ explicitly to exclude bound params from the tool schema.
        orig_sig = signature(original)
        func.__signature__ = orig_sig.replace(  # type: ignore[attr-defined]
            parameters=[p for name, p in orig_sig.parameters.items() if name not in kwargs]
        )

    return Tool[Any](
        func,  # pyright: ignore[reportArgumentType]
        name='tavily_search',
        description='Searches Tavily for the given query and returns the results.',
    )