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），仅供参考