Pydantic AI common_tools 實戰指南為 Agent 一鍵接入 DuckDuckGo、Tavily、Web Fetch 與圖像生成能力【免費下載鏈接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.項目地址: https://gitcode.com/GitHub_Trending/py/pydantic-aiPydantic AI 在pydantic_ai.common_tools中內置了一批開箱即用的通用工具涵蓋網頁搜索DuckDuckGo、Tavily、Exa、X/Twitter、網頁抓取Web Fetch與圖像生成讓 Agent 無需自行實現工具即可聯網檢索、閱讀網頁和生成圖片。本文以 docs/common-tools.md 用戶指南為主體深入 pydantic_ai_slim/pydantic_ai/common_tools/ 目錄下六個模塊的源碼實現逐一講解安裝方式、工廠函數參數、底層調用鏈與安全設計。讀完本文你將掌握如何在 5 分鐘內為 Agent 接入一個可用的搜索或抓取工具并理解這些工具的參數如何影響 LLM 工具 Schema 與調用行為。一、common_tools 模塊總覽pydantic_ai.common_tools是 Pydantic AI 預置通用工具的聚合命名空間其 API 參考入口位于 docs/api/common_tools.md共導出六個子模塊子模塊核心工廠函數用途common_tools.duckduckgoduckduckgo_search_tool基于ddgs的免費網頁搜索common_tools.exaexa_search_tool、exa_find_similar_tool、exa_get_contents_tool、exa_answer_tool、ExaToolsetExa 神經搜索引擎已棄用v3 移除common_tools.image_generationimage_generation_tool通過子代理調用原生圖像生成能力common_tools.tavilytavily_search_toolTavily 網頁搜索支持深度/主題/域名過濾common_tools.web_fetchweb_fetch_tool抓取 URL 并轉為 Markdown含 SSRF 防護common_tools.x_searchx_search_tool通過子代理搜索 X/Twitter所有工廠函數最終都返回 Tool 實例可直接放入Agent(tools[...])使用。值得注意的是除image_generation與x_search兩個基于子代理subagent的工具外其余工具均由pydantic-ai-slim的可選依賴組optional group提供安裝時需按需選擇對應 extras。二、DuckDuckGo 搜索工具2.1 安裝duckduckgo_search_tool依賴ddgs包舊版包名duckduckgo_search源碼在 duckduckgo.py 中做了向后兼容的兜底導入。安裝時使用duckduckgo可選組pip install pydantic-ai-slim[duckduckgo] # 或 uv uv add pydantic-ai-slim[duckduckgo]2.2 快速上手from pydantic_ai import Agent from pydantic_ai.common_tools.duckduckgo import duckduckgo_search_tool agent Agent( openai:gpt-5.2, tools[duckduckgo_search_tool()], instructionsSearch DuckDuckGo for the given query and return the results., ) result agent.run_sync(Can you list the top five highest-grossing animated films of 2025?) print(result.output)無需任何 API Key是零成本接入網頁搜索的最快路徑。2.3 工廠函數與參數duckduckgo_search_tool(duckduckgo_client: DDGS | None None, max_results: int | None None)duckduckgo_client可傳入自定義的DDGS客戶端實例用于共享會話或注入代理等配置不傳時內部創建默認實例duckduckgo_client or DDGS()。max_results返回結果的最大條數。默認None表示只取第一個響應頁的結果不會翻頁聚合。2.4 源碼實現細節從 duckduckgo.py 可以看出該工具的三個關鍵設計結果 Schema 明確DuckDuckGoResult是一個 TypedDict包含title標題、hrefURL、body正文摘要三個字段并通過duckduckgo_ta TypeAdapter(list[DuckDuckGoResult])對搜索結果做運行時驗證保證進入 Agent 上下文的數據結構穩定。同步客戶端橋接異步ddgs是同步庫工具內部用functools.partial(self.client.text, max_results...)構造搜索調用再交給anyio.to_thread.run_sync放入線程池執行從而在異步 Agent 運行循環中不阻塞事件循環。工具元信息固定最終包裝為Tool(..., nameduckduckgo_search, descriptionSearches DuckDuckGo for the given query and returns the results.)工具名與描述作為 LLM 可見的 Schema 元數據。三、Web Fetch 工具3.1 安裝web_fetch_tool依賴markdownifyHTML 轉 Markdown與httpx2使用web-fetch可選組pip install pydantic-ai-slim[web-fetch] # 或 uv uv add pydantic-ai-slim[web-fetch]3.2 快速上手from pydantic_ai import Agent from pydantic_ai.common_tools.web_fetch import web_fetch_tool agent Agent( openai:gpt-5.2, tools[web_fetch_tool()], instructionsFetch web pages and summarize their content., ) result agent.run_sync(What is on https://ai.pydantic.dev?) print(result.output)3.3 能力提醒WebFetch capability 的自動回退不需要手動把web_fetch_tool掛在tools上——WebFetch capability 在模型不支持原生 URL 抓取時會自動使用本工具作為本地回退實現WebFetch(localTrue)相當于提供了一次原生優先、本地兜底的體驗。只有需要完全掌控參數如allowed_domains、headers時才直接使用工廠函數。3.4 工廠函數與全部參數web_fetch_tool(*, ...)的全部參數及默認值如下源碼見 web_fetch.py參數默認值說明max_content_length50_000返回文本的最大字符數約 12,500 tokens超長截斷并追加[Content truncated]傳None不限制allow_local_urlsFalse是否允許抓取私有/內網 IP 地址默認關閉timeout30請求超時秒max_download_bytes50 * 1024 * 102450 MiB響應體最大下載字節數緩沖前生效傳None允許任意大小讀入內存allowed_domainsNone僅允許抓取這些域名精確主機名匹配違規拋ModelRetryblocked_domainsNone禁止抓取這些域名精確主機名匹配違規拋ModelRetryheadersNone附加 HTTP 請求頭覆蓋默認的Accept頭3.5 SSRF 防護與請求安全該工具最大的安全亮點是內置 SSRF服務端請求偽造防護所有抓取請求都經pydantic_ai._ssrf.safe_download發出web_fetch.py默認禁止訪問內網/私網地址allow_local_urlsFalse。由于 URL 由 LLM 決定文檔 common-tools.md 特別給出兩條安全紅線憑據頭要配域名白名單通過headers傳入Authorization之類的憑據時務必同時用allowed_domains限定可接收它的主機。且域名過濾只匹配主機名不校驗 scheme 和端口——模型仍可能把憑據發給白名單主機的http://明文端口。敏感頭重定向剝離Authorization、Cookie、Proxy-Authorization等敏感頭只在同源重定向或同主機 http→https 默認端口升級時轉發其余任何跨源重定向都會被剝離。3.6 內容處理管線從源碼可以看到抓取后的四級內容處理邏輯web_fetch.py按 Content-Type 分流文本類HTML/JSON/純文本走轉換管線二進制類PDF、圖片等直接返回 BinaryContent讓模型原生處理。Markdown 優先默認請求頭攜帶Accept: text/markdown對支持直接返回 Markdown 的站點如 Cloudflare、Vercel、Mintlify直接使用原文降低 token 消耗否則用markdownify將 HTML 轉為 Markdownstrip[img, script, style]。JSON 美化application/json響應會json.dumps(indent2)后包進 json 代碼塊便于模型閱讀。標題提取與空白折疊用_TITLE_RE正則從 HTML 中提取titleweb_fetch.py并將連續 3 個以上換行折疊為 2 個換行_clean_whitespace。WebFetchResult返回結構為urltitlecontent三個字段。測試 tests/test_web_fetch.py 覆蓋了 HTML 轉 Markdown、標題空白剝離、無標題頁返回空串、二進制回退等核心路徑是理解各分支行為的最佳參考。四、Tavily 搜索工具4.1 安裝與準備Tavily 是付費服務但提供免費額度需要先在 app.tavily.com 注冊獲取 API Key。安裝使用tavily可選組pip install pydantic-ai-slim[tavily] # 或 uv uv add pydantic-ai-slim[tavily]4.2 快速上手import os from pydantic_ai import Agent from pydantic_ai.common_tools.tavily import tavily_search_tool api_key os.getenv(TAVILY_API_KEY) assert api_key is not None agent Agent( openai:gpt-5.2, tools[tavily_search_tool(api_key)], instructionsSearch Tavily for the given query and return the results., ) result agent.run_sync(Tell me the top news in the GenAI world, give me links.) print(result.output)4.3 參數詳解tavily_search_tool(api_keyNone, *, clientNone, max_resultsNone, search_depth..., topic..., time_range..., include_domains..., exclude_domains...)源碼見 tavily.pyapi_keyTavily API Key不傳client時必填。client可傳入共享的AsyncTavilyClient實例傳了則忽略api_key適合多個工具復用同一客戶端。max_results返回結果條數上限None時用 Tavily 服務端默認值。search_depth搜索深度可選basic/advanced/fast/ultra-fast。topic搜索主題可選general/news/finance。time_range時間范圍過濾可選day/week/month/year或None。include_domains/exclude_domains指定包含/排除的域名列表。4.4 開發者鎖定 vs LLM 自由參數模型這是 Tavily 工具最值得注意的設計common-tools.md 與 tavily.py 均明確說明max_results始終由開發者控制永不進入 LLM 工具 Schema其他參數一旦由開發者提供就被固定為每次搜索的默認值并從 LLM 可見的 Schema 中移除參數保持未設置時才作為該次調用可變的參數暴露給 LLM 自由填寫。實現上依賴_UNSET哨兵對象區分未提供與顯式Nonetavily.py固定參數通過functools.partial綁定并通過重寫func.__signature__把已綁定的參數從工具 Schema 中剔除。例如鎖定max_results5與include_domains[arxiv.org]同時保留exclude_domains讓 LLM 每次自行決定import os from pydantic_ai import Agent from pydantic_ai.common_tools.tavily import tavily_search_tool api_key os.getenv(TAVILY_API_KEY) assert api_key is not None agent Agent( openai:gpt-5.2, tools[tavily_search_tool(api_key, max_results5, include_domains[arxiv.org])], instructionsSearch for information and return the results., ) result agent.run_sync(Find recent papers about transformer architectures) print(result.output)返回結果TavilySearchResult為title/url/content/score四字段其中score是 Tavily 給出的相關性評分最終經TypeAdapter驗證后交給模型tavily.py。五、Exa 搜索工具已棄用5.1 棄用狀態exa子模塊下的全部工具——exa_search_tool、exa_find_similar_tool、exa_get_contents_tool、exa_answer_tool與ExaToolset——均已標記棄用將在 v3 移除源碼中每個函數都帶有deprecated(..., categoryPydanticAIDeprecationWarning)裝飾器見 exa.py。官方推薦遷移到 Pydantic AI Harness 的ExaSearchcapabilitypip install pydantic-ai-harness[exa] # 或 uv uv add pydantic-ai-harness[exa]from pydantic_ai_harness.exa import ExaSearch from pydantic_ai import Agent agent Agent(openai:gpt-5.2, capabilities[ExaSearch()]) result agent.run_sync(What are the latest developments in quantum computing?) print(result.output)5.2 遺留 API 速覽遷移參考若仍需了解舊接口其能力矩陣如下依賴exa-py包工廠函數工具名能力exa_search_tool(api_key 或 client, num_results5, max_charactersNone)exa_search神經搜索search_type支持auto/keyword/neural/fast/deep結果附帶全文exa_find_similar_tool(api_key 或 client, num_results5)exa_find_similar按 URL 找相似頁面exclude_source_domainTrue默認排除同域結果exa_get_contents_tool(api_key 或 client)exa_get_contents按 URL 列表批量抓取全文exa_answer_tool(api_key 或 client)exa_answer生成帶引用的 AI 答案ExaToolset(api_key, num_results5, max_charactersNone, include_*)—共享同一客戶端的工具集include_search/include_find_similar/include_get_contents/include_answer四個開關控制包含哪些工具所有工廠函數都支持傳api_key或傳共享client二選一二者皆缺時拋ValueErrorexa.py。六、圖像生成工具6.1 設計思路子代理委托image_generation_tool與x_search_tool是 common_tools 中的兩個子代理型工具它們不直接調用外部 API而是當外層 Agent 的模型不支持某項原生能力時內部再啟動一個專用子代理subagent去完成。image_generation_tool(model, native_tool, *, instructionsGenerate an image based on the user prompt. Do not ask clarifying questions.)源碼見 image_generation.pymodel負責生成圖像的子代理模型可以是模型名如openai-responses:gpt-5.4、Model實例或接收RunContext返回模型的工廠可調用對象ImageGenerationFallbackModelFunc用于按運行上下文動態解析支持字符串在調用期解析。native_tool子代理使用的圖像生成原生工具配置可以是ImageGenerationTool實例或從外層RunContext解析出該工具的工廠函數。注意與 capability 層的native不同此處工廠不允許返回None否則拋UserError。instructions子代理的系統指令默認要求直接生成、不做澄清追問。6.2 模型白名單檢查純圖像生成模型無法支撐子代理所需的對話式 Agent 循環因此工廠函數內置了_check_image_only_model校驗image_generation.py內置映射_IMAGE_ONLY_MODELS收錄了gpt-image-1/1.5/2、dall-e-2/3、imagen-3.0-*、grok-imagine-*等純圖像模型并給出對應的對話式替代建議如gpt-image-1→openai-responses:gpt-5.4。傳入此類模型時直接拋UserError提示改用fallback_image_model參數或推薦的對話式模型。6.3 容錯設計子代理執行時UnexpectedModelBehavior內容審核攔截即其一會被轉換為ModelRetry重新拋出image_generation.py——這是為了讓編排層含 durable engine把失敗當作可重試的工具調用處理而不是對未知錯誤類終止任務。工具固定命名為generate_image描述為 Generate an image based on the given prompt.。七、X/Twitter 搜索工具x_search_tool(model, native_tool, *, instructionsSearch X/Twitter based on the user query. Return a comprehensive summary of the results.)源碼見 x_search.py與圖像生成工具同構model必須是原生支持XSearchTool原生工具的 xAI 模型如xai:grok-4.3同樣支持工廠可調用形式XSearchFallbackModelFunc。native_toolXSearchTool實例或其外層工廠不允許返回None。instructions子代理指令默認要求返回結果的綜合摘要。執行時子代理以output_typestr運行x_search.py即返回一段文本摘要而非原始列表UnexpectedModelBehavior同樣轉換為ModelRetry。工具固定命名為x_search描述為 Search X/Twitter for posts and content based on the given query.。八、選型與源碼級小結六個工具模塊展示了 Pydantic AI 通用工具層的三種典型模式外部 API 直連型DuckDuckGo、Tavily同步或異步客戶端 TypeAdapter結果驗證 固定工具名/描述最直接的掛上即用體驗安全抓取型Web Fetchsafe_downloadSSRF 防護 域名黑白名單 敏感頭重定向剝離 文本/二進制分流安全考慮貫穿始終子代理委托型圖像生成、X 搜索把原生能力封裝進專用子代理用ModelRetry統一失敗語義并借助RunContext工廠實現按運行動態解析模型與工具配置。選型建議零成本快速聯網檢索duckduckgo_search_tool()無需 Key更高質量、可控性強的檢索tavily_search_tool(api_key)善用開發者鎖定參數模型約束域名與結果數需要抓取指定網頁正文/PDFweb_fetch_tool()或直接用 WebFetch capability 享受原生優先自動回退圖像生成與 X 搜索讓外層模型不具備原生能力時通過image_generation_tool/x_search_tool的子代理橋接能力Exa 系列新項目不再使用遷移到 Pydantic AI Harness 的ExaSearch。各工具的測試覆蓋如 tests/test_web_fetch.py、tests/test_tavily.py、tests/test_exa.py與 docs/common-tools.md 用戶指南是繼續深入每個工具的權威參考。【免費下載鏈接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.項目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Pydantic AI common_tools 實戰指南：為 Agent 一鍵接入 DuckDuckGo、Tavily、Web Fetch 與圖像生成能力
Pydantic AI common_tools 實戰指南為 Agent 一鍵接入 DuckDuckGo、Tavily、Web Fetch 與圖像生成能力【免費下載鏈接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.項目地址: https://gitcode.com/GitHub_Trending/py/pydantic-aiPydantic AI 在pydantic_ai.common_tools中內置了一批開箱即用的通用工具涵蓋網頁搜索DuckDuckGo、Tavily、Exa、X/Twitter、網頁抓取Web Fetch與圖像生成讓 Agent 無需自行實現工具即可聯網檢索、閱讀網頁和生成圖片。本文以 docs/common-tools.md 用戶指南為主體深入 pydantic_ai_slim/pydantic_ai/common_tools/ 目錄下六個模塊的源碼實現逐一講解安裝方式、工廠函數參數、底層調用鏈與安全設計。讀完本文你將掌握如何在 5 分鐘內為 Agent 接入一個可用的搜索或抓取工具并理解這些工具的參數如何影響 LLM 工具 Schema 與調用行為。一、common_tools 模塊總覽pydantic_ai.common_tools是 Pydantic AI 預置通用工具的聚合命名空間其 API 參考入口位于 docs/api/common_tools.md共導出六個子模塊子模塊核心工廠函數用途common_tools.duckduckgoduckduckgo_search_tool基于ddgs的免費網頁搜索common_tools.exaexa_search_tool、exa_find_similar_tool、exa_get_contents_tool、exa_answer_tool、ExaToolsetExa 神經搜索引擎已棄用v3 移除common_tools.image_generationimage_generation_tool通過子代理調用原生圖像生成能力common_tools.tavilytavily_search_toolTavily 網頁搜索支持深度/主題/域名過濾common_tools.web_fetchweb_fetch_tool抓取 URL 并轉為 Markdown含 SSRF 防護common_tools.x_searchx_search_tool通過子代理搜索 X/Twitter所有工廠函數最終都返回 Tool 實例可直接放入Agent(tools[...])使用。值得注意的是除image_generation與x_search兩個基于子代理subagent的工具外其余工具均由pydantic-ai-slim的可選依賴組optional group提供安裝時需按需選擇對應 extras。二、DuckDuckGo 搜索工具2.1 安裝duckduckgo_search_tool依賴ddgs包舊版包名duckduckgo_search源碼在 duckduckgo.py 中做了向后兼容的兜底導入。安裝時使用duckduckgo可選組pip install pydantic-ai-slim[duckduckgo] # 或 uv uv add pydantic-ai-slim[duckduckgo]2.2 快速上手from pydantic_ai import Agent from pydantic_ai.common_tools.duckduckgo import duckduckgo_search_tool agent Agent( openai:gpt-5.2, tools[duckduckgo_search_tool()], instructionsSearch DuckDuckGo for the given query and return the results., ) result agent.run_sync(Can you list the top five highest-grossing animated films of 2025?) print(result.output)無需任何 API Key是零成本接入網頁搜索的最快路徑。2.3 工廠函數與參數duckduckgo_search_tool(duckduckgo_client: DDGS | None None, max_results: int | None None)duckduckgo_client可傳入自定義的DDGS客戶端實例用于共享會話或注入代理等配置不傳時內部創建默認實例duckduckgo_client or DDGS()。max_results返回結果的最大條數。默認None表示只取第一個響應頁的結果不會翻頁聚合。2.4 源碼實現細節從 duckduckgo.py 可以看出該工具的三個關鍵設計結果 Schema 明確DuckDuckGoResult是一個 TypedDict包含title標題、hrefURL、body正文摘要三個字段并通過duckduckgo_ta TypeAdapter(list[DuckDuckGoResult])對搜索結果做運行時驗證保證進入 Agent 上下文的數據結構穩定。同步客戶端橋接異步ddgs是同步庫工具內部用functools.partial(self.client.text, max_results...)構造搜索調用再交給anyio.to_thread.run_sync放入線程池執行從而在異步 Agent 運行循環中不阻塞事件循環。工具元信息固定最終包裝為Tool(..., nameduckduckgo_search, descriptionSearches DuckDuckGo for the given query and returns the results.)工具名與描述作為 LLM 可見的 Schema 元數據。三、Web Fetch 工具3.1 安裝web_fetch_tool依賴markdownifyHTML 轉 Markdown與httpx2使用web-fetch可選組pip install pydantic-ai-slim[web-fetch] # 或 uv uv add pydantic-ai-slim[web-fetch]3.2 快速上手from pydantic_ai import Agent from pydantic_ai.common_tools.web_fetch import web_fetch_tool agent Agent( openai:gpt-5.2, tools[web_fetch_tool()], instructionsFetch web pages and summarize their content., ) result agent.run_sync(What is on https://ai.pydantic.dev?) print(result.output)3.3 能力提醒WebFetch capability 的自動回退不需要手動把web_fetch_tool掛在tools上——WebFetch capability 在模型不支持原生 URL 抓取時會自動使用本工具作為本地回退實現WebFetch(localTrue)相當于提供了一次原生優先、本地兜底的體驗。只有需要完全掌控參數如allowed_domains、headers時才直接使用工廠函數。3.4 工廠函數與全部參數web_fetch_tool(*, ...)的全部參數及默認值如下源碼見 web_fetch.py參數默認值說明max_content_length50_000返回文本的最大字符數約 12,500 tokens超長截斷并追加[Content truncated]傳None不限制allow_local_urlsFalse是否允許抓取私有/內網 IP 地址默認關閉timeout30請求超時秒max_download_bytes50 * 1024 * 102450 MiB響應體最大下載字節數緩沖前生效傳None允許任意大小讀入內存allowed_domainsNone僅允許抓取這些域名精確主機名匹配違規拋ModelRetryblocked_domainsNone禁止抓取這些域名精確主機名匹配違規拋ModelRetryheadersNone附加 HTTP 請求頭覆蓋默認的Accept頭3.5 SSRF 防護與請求安全該工具最大的安全亮點是內置 SSRF服務端請求偽造防護所有抓取請求都經pydantic_ai._ssrf.safe_download發出web_fetch.py默認禁止訪問內網/私網地址allow_local_urlsFalse。由于 URL 由 LLM 決定文檔 common-tools.md 特別給出兩條安全紅線憑據頭要配域名白名單通過headers傳入Authorization之類的憑據時務必同時用allowed_domains限定可接收它的主機。且域名過濾只匹配主機名不校驗 scheme 和端口——模型仍可能把憑據發給白名單主機的http://明文端口。敏感頭重定向剝離Authorization、Cookie、Proxy-Authorization等敏感頭只在同源重定向或同主機 http→https 默認端口升級時轉發其余任何跨源重定向都會被剝離。3.6 內容處理管線從源碼可以看到抓取后的四級內容處理邏輯web_fetch.py按 Content-Type 分流文本類HTML/JSON/純文本走轉換管線二進制類PDF、圖片等直接返回 BinaryContent讓模型原生處理。Markdown 優先默認請求頭攜帶Accept: text/markdown對支持直接返回 Markdown 的站點如 Cloudflare、Vercel、Mintlify直接使用原文降低 token 消耗否則用markdownify將 HTML 轉為 Markdownstrip[img, script, style]。JSON 美化application/json響應會json.dumps(indent2)后包進 json 代碼塊便于模型閱讀。標題提取與空白折疊用_TITLE_RE正則從 HTML 中提取titleweb_fetch.py并將連續 3 個以上換行折疊為 2 個換行_clean_whitespace。WebFetchResult返回結構為urltitlecontent三個字段。測試 tests/test_web_fetch.py 覆蓋了 HTML 轉 Markdown、標題空白剝離、無標題頁返回空串、二進制回退等核心路徑是理解各分支行為的最佳參考。四、Tavily 搜索工具4.1 安裝與準備Tavily 是付費服務但提供免費額度需要先在 app.tavily.com 注冊獲取 API Key。安裝使用tavily可選組pip install pydantic-ai-slim[tavily] # 或 uv uv add pydantic-ai-slim[tavily]4.2 快速上手import os from pydantic_ai import Agent from pydantic_ai.common_tools.tavily import tavily_search_tool api_key os.getenv(TAVILY_API_KEY) assert api_key is not None agent Agent( openai:gpt-5.2, tools[tavily_search_tool(api_key)], instructionsSearch Tavily for the given query and return the results., ) result agent.run_sync(Tell me the top news in the GenAI world, give me links.) print(result.output)4.3 參數詳解tavily_search_tool(api_keyNone, *, clientNone, max_resultsNone, search_depth..., topic..., time_range..., include_domains..., exclude_domains...)源碼見 tavily.pyapi_keyTavily API Key不傳client時必填。client可傳入共享的AsyncTavilyClient實例傳了則忽略api_key適合多個工具復用同一客戶端。max_results返回結果條數上限None時用 Tavily 服務端默認值。search_depth搜索深度可選basic/advanced/fast/ultra-fast。topic搜索主題可選general/news/finance。time_range時間范圍過濾可選day/week/month/year或None。include_domains/exclude_domains指定包含/排除的域名列表。4.4 開發者鎖定 vs LLM 自由參數模型這是 Tavily 工具最值得注意的設計common-tools.md 與 tavily.py 均明確說明max_results始終由開發者控制永不進入 LLM 工具 Schema其他參數一旦由開發者提供就被固定為每次搜索的默認值并從 LLM 可見的 Schema 中移除參數保持未設置時才作為該次調用可變的參數暴露給 LLM 自由填寫。實現上依賴_UNSET哨兵對象區分未提供與顯式Nonetavily.py固定參數通過functools.partial綁定并通過重寫func.__signature__把已綁定的參數從工具 Schema 中剔除。例如鎖定max_results5與include_domains[arxiv.org]同時保留exclude_domains讓 LLM 每次自行決定import os from pydantic_ai import Agent from pydantic_ai.common_tools.tavily import tavily_search_tool api_key os.getenv(TAVILY_API_KEY) assert api_key is not None agent Agent( openai:gpt-5.2, tools[tavily_search_tool(api_key, max_results5, include_domains[arxiv.org])], instructionsSearch for information and return the results., ) result agent.run_sync(Find recent papers about transformer architectures) print(result.output)返回結果TavilySearchResult為title/url/content/score四字段其中score是 Tavily 給出的相關性評分最終經TypeAdapter驗證后交給模型tavily.py。五、Exa 搜索工具已棄用5.1 棄用狀態exa子模塊下的全部工具——exa_search_tool、exa_find_similar_tool、exa_get_contents_tool、exa_answer_tool與ExaToolset——均已標記棄用將在 v3 移除源碼中每個函數都帶有deprecated(..., categoryPydanticAIDeprecationWarning)裝飾器見 exa.py。官方推薦遷移到 Pydantic AI Harness 的ExaSearchcapabilitypip install pydantic-ai-harness[exa] # 或 uv uv add pydantic-ai-harness[exa]from pydantic_ai_harness.exa import ExaSearch from pydantic_ai import Agent agent Agent(openai:gpt-5.2, capabilities[ExaSearch()]) result agent.run_sync(What are the latest developments in quantum computing?) print(result.output)5.2 遺留 API 速覽遷移參考若仍需了解舊接口其能力矩陣如下依賴exa-py包工廠函數工具名能力exa_search_tool(api_key 或 client, num_results5, max_charactersNone)exa_search神經搜索search_type支持auto/keyword/neural/fast/deep結果附帶全文exa_find_similar_tool(api_key 或 client, num_results5)exa_find_similar按 URL 找相似頁面exclude_source_domainTrue默認排除同域結果exa_get_contents_tool(api_key 或 client)exa_get_contents按 URL 列表批量抓取全文exa_answer_tool(api_key 或 client)exa_answer生成帶引用的 AI 答案ExaToolset(api_key, num_results5, max_charactersNone, include_*)—共享同一客戶端的工具集include_search/include_find_similar/include_get_contents/include_answer四個開關控制包含哪些工具所有工廠函數都支持傳api_key或傳共享client二選一二者皆缺時拋ValueErrorexa.py。六、圖像生成工具6.1 設計思路子代理委托image_generation_tool與x_search_tool是 common_tools 中的兩個子代理型工具它們不直接調用外部 API而是當外層 Agent 的模型不支持某項原生能力時內部再啟動一個專用子代理subagent去完成。image_generation_tool(model, native_tool, *, instructionsGenerate an image based on the user prompt. Do not ask clarifying questions.)源碼見 image_generation.pymodel負責生成圖像的子代理模型可以是模型名如openai-responses:gpt-5.4、Model實例或接收RunContext返回模型的工廠可調用對象ImageGenerationFallbackModelFunc用于按運行上下文動態解析支持字符串在調用期解析。native_tool子代理使用的圖像生成原生工具配置可以是ImageGenerationTool實例或從外層RunContext解析出該工具的工廠函數。注意與 capability 層的native不同此處工廠不允許返回None否則拋UserError。instructions子代理的系統指令默認要求直接生成、不做澄清追問。6.2 模型白名單檢查純圖像生成模型無法支撐子代理所需的對話式 Agent 循環因此工廠函數內置了_check_image_only_model校驗image_generation.py內置映射_IMAGE_ONLY_MODELS收錄了gpt-image-1/1.5/2、dall-e-2/3、imagen-3.0-*、grok-imagine-*等純圖像模型并給出對應的對話式替代建議如gpt-image-1→openai-responses:gpt-5.4。傳入此類模型時直接拋UserError提示改用fallback_image_model參數或推薦的對話式模型。6.3 容錯設計子代理執行時UnexpectedModelBehavior內容審核攔截即其一會被轉換為ModelRetry重新拋出image_generation.py——這是為了讓編排層含 durable engine把失敗當作可重試的工具調用處理而不是對未知錯誤類終止任務。工具固定命名為generate_image描述為 Generate an image based on the given prompt.。七、X/Twitter 搜索工具x_search_tool(model, native_tool, *, instructionsSearch X/Twitter based on the user query. Return a comprehensive summary of the results.)源碼見 x_search.py與圖像生成工具同構model必須是原生支持XSearchTool原生工具的 xAI 模型如xai:grok-4.3同樣支持工廠可調用形式XSearchFallbackModelFunc。native_toolXSearchTool實例或其外層工廠不允許返回None。instructions子代理指令默認要求返回結果的綜合摘要。執行時子代理以output_typestr運行x_search.py即返回一段文本摘要而非原始列表UnexpectedModelBehavior同樣轉換為ModelRetry。工具固定命名為x_search描述為 Search X/Twitter for posts and content based on the given query.。八、選型與源碼級小結六個工具模塊展示了 Pydantic AI 通用工具層的三種典型模式外部 API 直連型DuckDuckGo、Tavily同步或異步客戶端 TypeAdapter結果驗證 固定工具名/描述最直接的掛上即用體驗安全抓取型Web Fetchsafe_downloadSSRF 防護 域名黑白名單 敏感頭重定向剝離 文本/二進制分流安全考慮貫穿始終子代理委托型圖像生成、X 搜索把原生能力封裝進專用子代理用ModelRetry統一失敗語義并借助RunContext工廠實現按運行動態解析模型與工具配置。選型建議零成本快速聯網檢索duckduckgo_search_tool()無需 Key更高質量、可控性強的檢索tavily_search_tool(api_key)善用開發者鎖定參數模型約束域名與結果數需要抓取指定網頁正文/PDFweb_fetch_tool()或直接用 WebFetch capability 享受原生優先自動回退圖像生成與 X 搜索讓外層模型不具備原生能力時通過image_generation_tool/x_search_tool的子代理橋接能力Exa 系列新項目不再使用遷移到 Pydantic AI Harness 的ExaSearch。各工具的測試覆蓋如 tests/test_web_fetch.py、tests/test_tavily.py、tests/test_exa.py與 docs/common-tools.md 用戶指南是繼續深入每個工具的權威參考。【免費下載鏈接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.項目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考