pydantic-ai 原生工具Native Tools架构指南从 AbstractNativeTool 到 Provider 自适应能力【免费下载链接】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 的原生工具Native Tools是一类直接由模型提供方Anthropic、OpenAI、Google、xAI 等在服务端执行的工具无需本地实现函数。本文以 pydantic_ai_slim/pydantic_ai/native_tools/AGENTS.md 中的开发指南为主线结合 native_tools 包 与 capabilities 能力层 的源码实现系统讲解原生工具的种类、字段语义、注册机制以及何时把功能做成能力Capability而非裸工具这一核心设计决策。读完本文你将理解WebSearchTool、XSearchTool、ImageGenerationTool等九个内置原生工具的内部结构与参数细节掌握本地回退与子代理回退两种跨提供者适配模式并了解为 pydantic-ai 新增一个原生工具时需要遵守的字段命名、校验与文档规范。一、什么是原生工具AbstractNativeTool基类原生工具在 pydantic-ai 中被建模为AbstractNativeTool抽象基类定义于 native_tools/init.py。它是一个kw_onlydataclass所有具体工具类如WebSearchTool都继承它。基类提供三个核心成员kind: str unknown_native_tool原生工具标识符作为判别器discriminator区分所有工具类型。每个具体工具都重写它例如web_search、x_search、code_execution、image_generation、mcp_server等。optional: bool False标记该实例是尽力而为的升级还是硬性要求。当为True时如果模型不支持该原生工具且没有本地回退实例会被静默丢弃而非报错为False默认时模型无法兑现该原生工具就会显式报错——用户明确要求了它就应该大声失败而不是悄悄替换成不同行为。unique_id与label属性前者给出唯一标识当同一类原生工具可能被传入多个实例时子类应重写以区分彼此如MCPServerTool返回mcp_server:id后者提供 UI 展示用的人类可读标签。自动注册机制源码中NATIVE_TOOL_TYPES是一个以kind字符串为键、工具类为值的注册表。它并非手工维护而是通过__init_subclass__在类定义时自动填充见 native_tools/init.py。同时基类实现了__get_pydantic_core_schema__把AbstractNativeTool本身变成一个按kind判别的 pydantic 联合类型因此可以直接用于配置文件的校验。包底部还导出了两个对用户有意义的集合SUPPORTED_NATIVE_TOOLS所有原生工具类型的集合frozenset由注册表派生。NATIVE_TOOLS_REQUIRING_CONFIG需要额外配置才能使用的工具集合包含FileSearchTool、MCPServerTool、MemoryTool、AdvisorTool以及内部工具ToolSearchTool见 native_tools/init.py。这类工具不能只靠kind就可用必须由用户显式提供 ID、URL 或模型名等参数。二、核心设计决策跨提供者功能优先做成 Capabilitynative_tools/AGENTS.md的第一条准则即全包的灵魂凡是代表跨提供者cross-provider特性的原生工具都应该有对应的能力Capability继承capabilities/中的NativeOrLocalTool。因为能力Capability才是用户向 agent 启用提供者自适应工具功能的首要公开 API。能力层的设计动机记录在 capabilities/AGENTS.md当行为涉及指令、设置、工具、原生工具、包装器、生命周期钩子或事件/历史处理时优先用 Capability 而不是给Agent构造函数新增 kwarg。能力是可组合的横切行为容器。NativeOrLocalTool原生工具 本地回退的配对基类NativeOrLocalTool定义于 capabilities/native_or_local.py其工作方式一目了然当模型支持该原生工具移除本地回退使用原生工具当模型不支持该原生工具移除原生工具保留本地工具。它暴露两个关键配置字段nativeTrue默认使用子类默认的原生工具实例、False禁用原生工具始终走本地工具、一个AbstractNativeTool实例使用该具体配置、或一个可调用对象每次运行通过RunContext动态创建原生工具返回None表示省略。localNone自动检测本地回退、True选择默认本地回退、False禁用本地回退只用原生工具、命名策略字符串如duckduckgo、一个Tool/AbstractToolset实例或一个裸可调用对象自动包装成Tool。__post_init__负责把声明解析为具体对象并做三类快速失败检查native_or_local.pynativeFalse且localFalse同时成立 → 报UserErrornativeFalse但约束字段要求原生工具如allowed_domains→ 报UserErrornativeFalse却没有显式本地回退 → 报UserError否则会静默变成一个什么都不做的空能力。内置的WebSearch、WebFetch、ImageGeneration能力都是该基类的子类分别通过重写_default_native()、_default_local()、_resolve_local_strategy()、_requires_native()等钩子定义各自行为。本地回退Local FallbackWebSearch与WebFetch文档明确举出的第一类回退是本地函数工具回退在提供者没有原生支持时能力自动回退到本地 function tool。以 capabilities/web_search.py 的WebSearch为例默认情况下它使用模型的原生 web search在原生不支持的模型上抛UserError。传入localduckduckgo或localTrue即可启用本地 DuckDuckGo 回退但需要安装可选依赖组pip install pydantic-ai-slim[duckduckgo]_resolve_local_strategy的实现web_search.py展示了命名策略的解析方式localTrue归一化为duckduckgo然后延迟导入pydantic_ai.common_tools.duckduckgo.duckduckgo_search_tool如果依赖缺失会抛出带安装提示的UserError。local同样接受任何可调用对象、Tool或AbstractToolset作为自定义回退。值得注意的细节是_requires_native()web_search.py当设置了blocked_domains、allowed_domains、max_uses或external_web_accessFalse时能力强制要求原生工具——因为这些约束只有原生工具能兑现此时本地回退被抑制模型不支持就会报错从而防止约束被静默违反。类似地capabilities/web_fetch.py 的WebFetch通过localTrue启用本地抓取回退需要pip install pydantic-ai-slim[web-fetch]其allowed_domains/blocked_domains在原生不可用时由本地强制。本地回退的实现细节体现在get_toolset()native_or_local.py当原生工具存在时本地工具集被包装进PreparedToolset其 prepare 函数给本地工具定义打上unless_nativenative 工具的 unique_id标记——这正是模型支持原生工具时移除本地工具的运行时机制。子代理回退Subagent FallbackXSearch与ImageGeneration文档指出的第二类回退是子代理回退通过fallback_subagent_model把任务委托给一个运行其他提供者模型的子代理。这类能力包括ImageGeneration和XSearch。以 capabilities/x_search.py 的XSearch为例在 xAI 模型上直接使用原生 X 搜索无需额外配置在非 xAI 模型上必须显式设置fallback_subagent_model为一个支持XSearchTool原生工具的 xAI 模型例如xai:grok-4.3否则使用XSearch会直接报错——没有默认的子代理模型。该能力还展示了互斥校验的实践__post_init__检查fallback_subagent_model与local不能同时指定x_search.py因为二者都是非 xAI 模型下的回退路径同时设置会让其中一个被静默忽略。_default_local()在设置fallback_subagent_model后从pydantic_ai.common_tools.x_search构建x_search_tool(model..., native_tool...)子代理内部依然运行原生XSearchTool因此allowed_x_handles等句柄约束在两条路径上都得到遵守_requires_native()在设置了fallback_subagent_model时返回False理由正是子代理也运行原生工具。ImageGeneration能力capabilities/image_generation.py更进一步提供三种互斥的回退实现同时指定多个会抛UserErrorlocal接受ImageGenerator走直接图像生成 API、自定义Tool、工具集或可调用对象fallback_image_model接受ImageGenerationModel或provider:model字符串如openai:gpt-image-2直接调用图像生成 API 而不是跑第二个 agentfallback_subagent_model运行一个具备图像生成能力的会话模型子代理如openai-responses:gpt-5.4、google:gemini-3-pro-image图像来自该模型的原生ImageGenerationTool。源码中还区分了两类几何/输出设置的去向dimensions与超出原生词汇表的aspect_ratio只能由直接生成器兑现原生工具无法表达nativeFalse才能保证生效否则对应路径会发出警告而background、input_fidelity、moderation、output_compression、output_format、quality、size等是原生工具专属设置直接生成器会忽略并警告。这些细节体现了能力层必须精确说明每个设置在哪条路径上生效的设计纪律。三、没有可靠跨提供者抽象的工具保持纯NativeTool指南第二条给出了反向的边界对于没有可靠跨提供者抽象、纯提供者专属的工具就作为包裹在NativeTool中的原生工具存在不要强行添加一层薄薄的 provider-agnostic 能力——除非该特性在多个提供者上有支持或有有意义的回退语义。NativeTool定义于 capabilities/native_tool.py它是一个简单能力把单个AgentNativeTool静态AbstractNativeTool实例或动态可调用对象注册到 agent 上等价于Agent(capabilities[NativeTool(my_tool)])。它还提供from_spec类方法支持两种 YAML 配置形式# 扁平形式 NativeTool: kind: web_search search_context_size: high # 显式形式 NativeTool: tool: kind: web_searchfrom_spec内部通过pydantic.TypeAdapter(AbstractNativeTool)校验配置得益于基类的判别联合 schema任何内置工具类型都能被正确解析。四、请求级参数暴露在工具类字段而非只放在 Model Settings指南的第三条针对提供者 API 中有控制原始工具输出是否包含的请求级参数例如 xAI 的include、OpenAI 的include这类参数应作为工具类的字段暴露而不是只放在 model settings 里。用户配置XSearchTool(...)时应该能发现所有相关选项model settings 保留为向后兼容的替代方案。一个教科书式的例子是XSearchTool.include_outputnative_tools/init.py默认False时模型只在内部使用搜索结果、返回文字摘要设为True后原始搜索结果会以NativeToolReturnPart形式出现在响应中程序可以访问搜到的帖子、来源与元数据。它同时也可以在XaiModelSettings.xai_include_x_search_output中设置——工具字段为主 APImodel settings 是向后兼容的备选二者并存。五、提供者支持的文档三处维护指南要求提供者支持情况必须记录在三个地方任何一处遗漏都视为违规工具类 docstring 中的 Supported by 列表每个工具类与每个提供者专属字段都带一个 Supported by: 小节。例如WebSearchTool类级列表写明 Anthropic、OpenAI Responses、Groq、Google、xAI、OpenRouter 六家而user_location字段级列表则进一步细分到 Anthropic、OpenAI Responses、xAI、OpenRouter还附上各提供者官方文档链接。docs/native-tools.md的提供者支持表格仓库根目录下的 docs/native-tools.md 集中维护一张工具 × 提供者支持矩阵供用户快速横向对比。字段级 docstring 中的提供者专属语义例如WebSearchTool.external_web_access明确说明OpenAI 的 legacyweb_search_preview工具会忽略此参数ImageGenerationTool.output_compression区分 OpenAI仅 jpeg/webp默认 100与 Google Vertex AI仅 jpeg默认 75。这套三处文档纪律保证了同一事实在不同入口类内省、API 参考、横向对比表保持同步。六、字段命名优先直通提供者 API 字段名指南进一步要求当工具字段直接映射提供者 API 的字段名时优先使用那个名字——用户可能正开着提供者的官方文档对照使用 pydantic-ai 文档。从 native_tools/init.py 的实现可以清晰看到这一原则WebSearchTool.search_context_size、user_location、blocked_domains、allowed_domains、max_uses、external_web_access均与 OpenAI Responses / Anthropic 等提供者的参数同名XSearchTool.allowed_x_handles、excluded_x_handles、from_date、to_date与 xAI X-search 的参数一致AdvisorTool.model、max_tokens、caching与 Anthropic advisor 工具定义的字段一一对应。FileSearchTool.file_store_ids则针对三家映射到不同概念OpenAI 的 vector store ID、Google 的 file search store 名、xAI 的 collection ID也在字段 docstring 中逐一说明。七、快速失败__post_init__校验互斥与上限指南要求在__post_init__中校验互斥性与数量上限用清晰的错误消息快速失败。源码中有两个典型实现XSearchTool.__post_init__native_tools/init.pydef __post_init__(self) - None: if self.allowed_x_handles is not None and self.excluded_x_handles is not None: raise ValueError(Cannot specify both allowed_x_handles and excluded_x_handles) if self.allowed_x_handles and len(self.allowed_x_handles) 20: raise ValueError(allowed_x_handles cannot contain more than 20 handles) if self.excluded_x_handles and len(self.excluded_x_handles) 20: raise ValueError(excluded_x_handles cannot contain more than 20 handles)AdvisorTool.__post_init__native_tools/init.pydef __post_init__(self) - None: if self.max_tokens is not None and self.max_tokens 1024: raise ValueError(AdvisorTool.max_tokens must be at least 1024)这种构造期即失败fail fast at construction的哲学还延伸到能力层ImageGeneration在__post_init__中同时拒绝dimensions与aspect_ratio并存、拒绝把裸ImageGenerationModel传给local、拒绝无 provider 前缀的fallback_image_model字符串错误消息都具体指明应该改用哪个字段。八、名称往返Round-Trip原生工具名的历史一致性最后一条准则最隐蔽也最关键pydantic-ai 中的原生工具名必须能在提供者 API 中往返round-trip。如果提供者 API 使用不同的函数名——例如 xAI 在线上发送的是x_keyword_search而不是 pydantic-ai 里的x_search——那么在回放历史replaying history时必须保留原始名称否则旧对话中的工具调用无法与新的工具定义对上。这一要求对应仓库中的历史回放与线缆契约wire contract测试体系例如 tests/test_ref_sibling_wire_contract.py 与 tests/test_thinking_wire_contract.py 所覆盖的场景agent 运行、暂停、恢复或导入历史消息时工具引用的命名必须与首次调用时一致。为新增工具设计时务必确认提供者是否会对工具名做改写并保证适配器在回放路径上保留提供者侧的真实名称。九、九个内置原生工具速查表当前仓库 native_tools/init.py 导出的原生工具及其要点如下工具类kind主要提供者关键字段WebSearchToolweb_searchAnthropic、OpenAI Responses、Groq、Google、xAI、OpenRoutersearch_context_sizelow/medium/high默认 medium、user_location、blocked_domains、allowed_domains、max_uses、external_web_accessXSearchToolx_searchxAIallowed_x_handles/excluded_x_handles互斥各限 20、from_date/to_datenaive 时间按 UTC 解释、enable_image_understanding、enable_video_understanding、include_outputCodeExecutionToolcode_executionAnthropic、OpenAI Responses、Google、Bedrock (Nova2.0)、xAIfiles上传文件仅匹配提供者的文件被使用WebFetchToolweb_fetchAnthropic、Googlemax_uses、allowed_domains/blocked_domains互斥、enable_citations、max_content_tokensImageGenerationToolimage_generationOpenAI Responses、Googleaction、background、input_fidelity、moderation、model如gpt-image-2、output_compression、output_format、partial_images0–3、quality、size、aspect_ratioMemoryToolmemoryAnthropic无参MCPServerToolmcp_serverOpenAI Responses、Anthropic、xAIid、urlOpenAI 支持x-openai-connector:connector_id、authorization_token、description、allowed_tools、headersFileSearchToolfile_searchOpenAI Responses、Google (Gemini)、xAIfile_store_ids、max_num_results、instructions、retrieval_modehybrid/semantic/keywordAdvisorTooladvisorAnthropic、OpenRoutermodelexecutor 咨询的更强模型、max_uses每请求上限、max_tokens≥1024、caching5m/1h临时缓存 TTL其中FileSearchTool是完全托管的 RAG由提供者处理文件存储、分块、嵌入生成与上下文注入pydantic-ai 侧只需传入 store ID。AdvisorTool的字段与 Anthropic advisor 工具定义 1:1 映射OpenRouter 作为网关 server tool 只接受model与max_tokens子集并忽略其余字段——这些差异都在字段级 docstring 中标注。此外_tool_search.py中还有框架内部的ToolSearchToolkindtool_search它不直接导出给用户而是由ToolSearch能力按提供者选择三种模式之一驱动原生服务端搜索Anthropic 的bm25/regex、OpenAI 的服务端执行tool_search、原生客户端执行Anthropic 的 tool-reference 块、OpenAI 的executionclient调用本地可调用对象、以及本地search_tools函数工具回退见 native_tools/_tool_search.py。十、新增原生工具八条检查清单综合 native_tools/AGENTS.md 与源码实现为 pydantic-ai 新增一个原生工具时应依次确认跨提供者判定该特性在多个提供者上有支持或合理回退语义吗是 → 创建继承NativeOrLocalTool的能力否 → 保持NativeTool包裹的纯原生工具。回退路径本地回退function tool还是子代理回退fallback_subagent_model无回退时不支持的模型必须显式报错optionalFalse语义。请求级参数提供者 API 的请求级参数如include要在工具类上暴露字段model settings 只作向后兼容备选。三处文档类 docstring 的 Supported by、docs/native-tools.md 提供者表格、字段级 docstring缺一不可。字段命名直通提供者 API 字段名方便用户对照提供者文档。快速失败校验在__post_init__中用清晰消息校验互斥与上限。名称往返确认提供者是否改写工具函数名保证历史回放时保留提供者侧原始名称。配置需求需要用户提供额外参数的工具FileSearch、MCP、Memory、Advisor、ToolSearch要进入NATIVE_TOOLS_REQUIRING_CONFIG集合避免用户以为只传kind即可用。遵循这八条既能保证用户通过能力层获得提供者自适应的统一体验又能让提供者专属细节在工具类与文档中透明可见——这正是 pydantic-ai 原生工具体系typed end to end设计哲学在工具层的落地。【免费下载链接】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 原生工具Native Tools架构指南从 AbstractNativeTool 到 Provider 自适应能力【免费下载链接】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 的原生工具Native Tools是一类直接由模型提供方Anthropic、OpenAI、Google、xAI 等在服务端执行的工具无需本地实现函数。本文以 pydantic_ai_slim/pydantic_ai/native_tools/AGENTS.md 中的开发指南为主线结合 native_tools 包 与 capabilities 能力层 的源码实现系统讲解原生工具的种类、字段语义、注册机制以及何时把功能做成能力Capability而非裸工具这一核心设计决策。读完本文你将理解WebSearchTool、XSearchTool、ImageGenerationTool等九个内置原生工具的内部结构与参数细节掌握本地回退与子代理回退两种跨提供者适配模式并了解为 pydantic-ai 新增一个原生工具时需要遵守的字段命名、校验与文档规范。一、什么是原生工具AbstractNativeTool基类原生工具在 pydantic-ai 中被建模为AbstractNativeTool抽象基类定义于 native_tools/init.py。它是一个kw_onlydataclass所有具体工具类如WebSearchTool都继承它。基类提供三个核心成员kind: str unknown_native_tool原生工具标识符作为判别器discriminator区分所有工具类型。每个具体工具都重写它例如web_search、x_search、code_execution、image_generation、mcp_server等。optional: bool False标记该实例是尽力而为的升级还是硬性要求。当为True时如果模型不支持该原生工具且没有本地回退实例会被静默丢弃而非报错为False默认时模型无法兑现该原生工具就会显式报错——用户明确要求了它就应该大声失败而不是悄悄替换成不同行为。unique_id与label属性前者给出唯一标识当同一类原生工具可能被传入多个实例时子类应重写以区分彼此如MCPServerTool返回mcp_server:id后者提供 UI 展示用的人类可读标签。自动注册机制源码中NATIVE_TOOL_TYPES是一个以kind字符串为键、工具类为值的注册表。它并非手工维护而是通过__init_subclass__在类定义时自动填充见 native_tools/init.py。同时基类实现了__get_pydantic_core_schema__把AbstractNativeTool本身变成一个按kind判别的 pydantic 联合类型因此可以直接用于配置文件的校验。包底部还导出了两个对用户有意义的集合SUPPORTED_NATIVE_TOOLS所有原生工具类型的集合frozenset由注册表派生。NATIVE_TOOLS_REQUIRING_CONFIG需要额外配置才能使用的工具集合包含FileSearchTool、MCPServerTool、MemoryTool、AdvisorTool以及内部工具ToolSearchTool见 native_tools/init.py。这类工具不能只靠kind就可用必须由用户显式提供 ID、URL 或模型名等参数。二、核心设计决策跨提供者功能优先做成 Capabilitynative_tools/AGENTS.md的第一条准则即全包的灵魂凡是代表跨提供者cross-provider特性的原生工具都应该有对应的能力Capability继承capabilities/中的NativeOrLocalTool。因为能力Capability才是用户向 agent 启用提供者自适应工具功能的首要公开 API。能力层的设计动机记录在 capabilities/AGENTS.md当行为涉及指令、设置、工具、原生工具、包装器、生命周期钩子或事件/历史处理时优先用 Capability 而不是给Agent构造函数新增 kwarg。能力是可组合的横切行为容器。NativeOrLocalTool原生工具 本地回退的配对基类NativeOrLocalTool定义于 capabilities/native_or_local.py其工作方式一目了然当模型支持该原生工具移除本地回退使用原生工具当模型不支持该原生工具移除原生工具保留本地工具。它暴露两个关键配置字段nativeTrue默认使用子类默认的原生工具实例、False禁用原生工具始终走本地工具、一个AbstractNativeTool实例使用该具体配置、或一个可调用对象每次运行通过RunContext动态创建原生工具返回None表示省略。localNone自动检测本地回退、True选择默认本地回退、False禁用本地回退只用原生工具、命名策略字符串如duckduckgo、一个Tool/AbstractToolset实例或一个裸可调用对象自动包装成Tool。__post_init__负责把声明解析为具体对象并做三类快速失败检查native_or_local.pynativeFalse且localFalse同时成立 → 报UserErrornativeFalse但约束字段要求原生工具如allowed_domains→ 报UserErrornativeFalse却没有显式本地回退 → 报UserError否则会静默变成一个什么都不做的空能力。内置的WebSearch、WebFetch、ImageGeneration能力都是该基类的子类分别通过重写_default_native()、_default_local()、_resolve_local_strategy()、_requires_native()等钩子定义各自行为。本地回退Local FallbackWebSearch与WebFetch文档明确举出的第一类回退是本地函数工具回退在提供者没有原生支持时能力自动回退到本地 function tool。以 capabilities/web_search.py 的WebSearch为例默认情况下它使用模型的原生 web search在原生不支持的模型上抛UserError。传入localduckduckgo或localTrue即可启用本地 DuckDuckGo 回退但需要安装可选依赖组pip install pydantic-ai-slim[duckduckgo]_resolve_local_strategy的实现web_search.py展示了命名策略的解析方式localTrue归一化为duckduckgo然后延迟导入pydantic_ai.common_tools.duckduckgo.duckduckgo_search_tool如果依赖缺失会抛出带安装提示的UserError。local同样接受任何可调用对象、Tool或AbstractToolset作为自定义回退。值得注意的细节是_requires_native()web_search.py当设置了blocked_domains、allowed_domains、max_uses或external_web_accessFalse时能力强制要求原生工具——因为这些约束只有原生工具能兑现此时本地回退被抑制模型不支持就会报错从而防止约束被静默违反。类似地capabilities/web_fetch.py 的WebFetch通过localTrue启用本地抓取回退需要pip install pydantic-ai-slim[web-fetch]其allowed_domains/blocked_domains在原生不可用时由本地强制。本地回退的实现细节体现在get_toolset()native_or_local.py当原生工具存在时本地工具集被包装进PreparedToolset其 prepare 函数给本地工具定义打上unless_nativenative 工具的 unique_id标记——这正是模型支持原生工具时移除本地工具的运行时机制。子代理回退Subagent FallbackXSearch与ImageGeneration文档指出的第二类回退是子代理回退通过fallback_subagent_model把任务委托给一个运行其他提供者模型的子代理。这类能力包括ImageGeneration和XSearch。以 capabilities/x_search.py 的XSearch为例在 xAI 模型上直接使用原生 X 搜索无需额外配置在非 xAI 模型上必须显式设置fallback_subagent_model为一个支持XSearchTool原生工具的 xAI 模型例如xai:grok-4.3否则使用XSearch会直接报错——没有默认的子代理模型。该能力还展示了互斥校验的实践__post_init__检查fallback_subagent_model与local不能同时指定x_search.py因为二者都是非 xAI 模型下的回退路径同时设置会让其中一个被静默忽略。_default_local()在设置fallback_subagent_model后从pydantic_ai.common_tools.x_search构建x_search_tool(model..., native_tool...)子代理内部依然运行原生XSearchTool因此allowed_x_handles等句柄约束在两条路径上都得到遵守_requires_native()在设置了fallback_subagent_model时返回False理由正是子代理也运行原生工具。ImageGeneration能力capabilities/image_generation.py更进一步提供三种互斥的回退实现同时指定多个会抛UserErrorlocal接受ImageGenerator走直接图像生成 API、自定义Tool、工具集或可调用对象fallback_image_model接受ImageGenerationModel或provider:model字符串如openai:gpt-image-2直接调用图像生成 API 而不是跑第二个 agentfallback_subagent_model运行一个具备图像生成能力的会话模型子代理如openai-responses:gpt-5.4、google:gemini-3-pro-image图像来自该模型的原生ImageGenerationTool。源码中还区分了两类几何/输出设置的去向dimensions与超出原生词汇表的aspect_ratio只能由直接生成器兑现原生工具无法表达nativeFalse才能保证生效否则对应路径会发出警告而background、input_fidelity、moderation、output_compression、output_format、quality、size等是原生工具专属设置直接生成器会忽略并警告。这些细节体现了能力层必须精确说明每个设置在哪条路径上生效的设计纪律。三、没有可靠跨提供者抽象的工具保持纯NativeTool指南第二条给出了反向的边界对于没有可靠跨提供者抽象、纯提供者专属的工具就作为包裹在NativeTool中的原生工具存在不要强行添加一层薄薄的 provider-agnostic 能力——除非该特性在多个提供者上有支持或有有意义的回退语义。NativeTool定义于 capabilities/native_tool.py它是一个简单能力把单个AgentNativeTool静态AbstractNativeTool实例或动态可调用对象注册到 agent 上等价于Agent(capabilities[NativeTool(my_tool)])。它还提供from_spec类方法支持两种 YAML 配置形式# 扁平形式 NativeTool: kind: web_search search_context_size: high # 显式形式 NativeTool: tool: kind: web_searchfrom_spec内部通过pydantic.TypeAdapter(AbstractNativeTool)校验配置得益于基类的判别联合 schema任何内置工具类型都能被正确解析。四、请求级参数暴露在工具类字段而非只放在 Model Settings指南的第三条针对提供者 API 中有控制原始工具输出是否包含的请求级参数例如 xAI 的include、OpenAI 的include这类参数应作为工具类的字段暴露而不是只放在 model settings 里。用户配置XSearchTool(...)时应该能发现所有相关选项model settings 保留为向后兼容的替代方案。一个教科书式的例子是XSearchTool.include_outputnative_tools/init.py默认False时模型只在内部使用搜索结果、返回文字摘要设为True后原始搜索结果会以NativeToolReturnPart形式出现在响应中程序可以访问搜到的帖子、来源与元数据。它同时也可以在XaiModelSettings.xai_include_x_search_output中设置——工具字段为主 APImodel settings 是向后兼容的备选二者并存。五、提供者支持的文档三处维护指南要求提供者支持情况必须记录在三个地方任何一处遗漏都视为违规工具类 docstring 中的 Supported by 列表每个工具类与每个提供者专属字段都带一个 Supported by: 小节。例如WebSearchTool类级列表写明 Anthropic、OpenAI Responses、Groq、Google、xAI、OpenRouter 六家而user_location字段级列表则进一步细分到 Anthropic、OpenAI Responses、xAI、OpenRouter还附上各提供者官方文档链接。docs/native-tools.md的提供者支持表格仓库根目录下的 docs/native-tools.md 集中维护一张工具 × 提供者支持矩阵供用户快速横向对比。字段级 docstring 中的提供者专属语义例如WebSearchTool.external_web_access明确说明OpenAI 的 legacyweb_search_preview工具会忽略此参数ImageGenerationTool.output_compression区分 OpenAI仅 jpeg/webp默认 100与 Google Vertex AI仅 jpeg默认 75。这套三处文档纪律保证了同一事实在不同入口类内省、API 参考、横向对比表保持同步。六、字段命名优先直通提供者 API 字段名指南进一步要求当工具字段直接映射提供者 API 的字段名时优先使用那个名字——用户可能正开着提供者的官方文档对照使用 pydantic-ai 文档。从 native_tools/init.py 的实现可以清晰看到这一原则WebSearchTool.search_context_size、user_location、blocked_domains、allowed_domains、max_uses、external_web_access均与 OpenAI Responses / Anthropic 等提供者的参数同名XSearchTool.allowed_x_handles、excluded_x_handles、from_date、to_date与 xAI X-search 的参数一致AdvisorTool.model、max_tokens、caching与 Anthropic advisor 工具定义的字段一一对应。FileSearchTool.file_store_ids则针对三家映射到不同概念OpenAI 的 vector store ID、Google 的 file search store 名、xAI 的 collection ID也在字段 docstring 中逐一说明。七、快速失败__post_init__校验互斥与上限指南要求在__post_init__中校验互斥性与数量上限用清晰的错误消息快速失败。源码中有两个典型实现XSearchTool.__post_init__native_tools/init.pydef __post_init__(self) - None: if self.allowed_x_handles is not None and self.excluded_x_handles is not None: raise ValueError(Cannot specify both allowed_x_handles and excluded_x_handles) if self.allowed_x_handles and len(self.allowed_x_handles) 20: raise ValueError(allowed_x_handles cannot contain more than 20 handles) if self.excluded_x_handles and len(self.excluded_x_handles) 20: raise ValueError(excluded_x_handles cannot contain more than 20 handles)AdvisorTool.__post_init__native_tools/init.pydef __post_init__(self) - None: if self.max_tokens is not None and self.max_tokens 1024: raise ValueError(AdvisorTool.max_tokens must be at least 1024)这种构造期即失败fail fast at construction的哲学还延伸到能力层ImageGeneration在__post_init__中同时拒绝dimensions与aspect_ratio并存、拒绝把裸ImageGenerationModel传给local、拒绝无 provider 前缀的fallback_image_model字符串错误消息都具体指明应该改用哪个字段。八、名称往返Round-Trip原生工具名的历史一致性最后一条准则最隐蔽也最关键pydantic-ai 中的原生工具名必须能在提供者 API 中往返round-trip。如果提供者 API 使用不同的函数名——例如 xAI 在线上发送的是x_keyword_search而不是 pydantic-ai 里的x_search——那么在回放历史replaying history时必须保留原始名称否则旧对话中的工具调用无法与新的工具定义对上。这一要求对应仓库中的历史回放与线缆契约wire contract测试体系例如 tests/test_ref_sibling_wire_contract.py 与 tests/test_thinking_wire_contract.py 所覆盖的场景agent 运行、暂停、恢复或导入历史消息时工具引用的命名必须与首次调用时一致。为新增工具设计时务必确认提供者是否会对工具名做改写并保证适配器在回放路径上保留提供者侧的真实名称。九、九个内置原生工具速查表当前仓库 native_tools/init.py 导出的原生工具及其要点如下工具类kind主要提供者关键字段WebSearchToolweb_searchAnthropic、OpenAI Responses、Groq、Google、xAI、OpenRoutersearch_context_sizelow/medium/high默认 medium、user_location、blocked_domains、allowed_domains、max_uses、external_web_accessXSearchToolx_searchxAIallowed_x_handles/excluded_x_handles互斥各限 20、from_date/to_datenaive 时间按 UTC 解释、enable_image_understanding、enable_video_understanding、include_outputCodeExecutionToolcode_executionAnthropic、OpenAI Responses、Google、Bedrock (Nova2.0)、xAIfiles上传文件仅匹配提供者的文件被使用WebFetchToolweb_fetchAnthropic、Googlemax_uses、allowed_domains/blocked_domains互斥、enable_citations、max_content_tokensImageGenerationToolimage_generationOpenAI Responses、Googleaction、background、input_fidelity、moderation、model如gpt-image-2、output_compression、output_format、partial_images0–3、quality、size、aspect_ratioMemoryToolmemoryAnthropic无参MCPServerToolmcp_serverOpenAI Responses、Anthropic、xAIid、urlOpenAI 支持x-openai-connector:connector_id、authorization_token、description、allowed_tools、headersFileSearchToolfile_searchOpenAI Responses、Google (Gemini)、xAIfile_store_ids、max_num_results、instructions、retrieval_modehybrid/semantic/keywordAdvisorTooladvisorAnthropic、OpenRoutermodelexecutor 咨询的更强模型、max_uses每请求上限、max_tokens≥1024、caching5m/1h临时缓存 TTL其中FileSearchTool是完全托管的 RAG由提供者处理文件存储、分块、嵌入生成与上下文注入pydantic-ai 侧只需传入 store ID。AdvisorTool的字段与 Anthropic advisor 工具定义 1:1 映射OpenRouter 作为网关 server tool 只接受model与max_tokens子集并忽略其余字段——这些差异都在字段级 docstring 中标注。此外_tool_search.py中还有框架内部的ToolSearchToolkindtool_search它不直接导出给用户而是由ToolSearch能力按提供者选择三种模式之一驱动原生服务端搜索Anthropic 的bm25/regex、OpenAI 的服务端执行tool_search、原生客户端执行Anthropic 的 tool-reference 块、OpenAI 的executionclient调用本地可调用对象、以及本地search_tools函数工具回退见 native_tools/_tool_search.py。十、新增原生工具八条检查清单综合 native_tools/AGENTS.md 与源码实现为 pydantic-ai 新增一个原生工具时应依次确认跨提供者判定该特性在多个提供者上有支持或合理回退语义吗是 → 创建继承NativeOrLocalTool的能力否 → 保持NativeTool包裹的纯原生工具。回退路径本地回退function tool还是子代理回退fallback_subagent_model无回退时不支持的模型必须显式报错optionalFalse语义。请求级参数提供者 API 的请求级参数如include要在工具类上暴露字段model settings 只作向后兼容备选。三处文档类 docstring 的 Supported by、docs/native-tools.md 提供者表格、字段级 docstring缺一不可。字段命名直通提供者 API 字段名方便用户对照提供者文档。快速失败校验在__post_init__中用清晰消息校验互斥与上限。名称往返确认提供者是否改写工具函数名保证历史回放时保留提供者侧原始名称。配置需求需要用户提供额外参数的工具FileSearch、MCP、Memory、Advisor、ToolSearch要进入NATIVE_TOOLS_REQUIRING_CONFIG集合避免用户以为只传kind即可用。遵循这八条既能保证用户通过能力层获得提供者自适应的统一体验又能让提供者专属细节在工具类与文档中透明可见——这正是 pydantic-ai 原生工具体系typed end to end设计哲学在工具层的落地。【免费下载链接】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），仅供参考
