Docling 开发技能参考详解Pydantic AI 提供方原生内置工具builtin_tools实战指南【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文基于 Docling 仓库自带的开发技能参考文件 BUILTIN-TOOLS.md系统讲解 Pydantic AI 中提供方原生内置工具built-in tools的启用方式、可用工具清单、基于RunContext的动态配置模式以及内置工具与跨提供方 capabilities 之间的选型决策。读完本文你能在构建 Pydantic AI Agent 时正确区分builtin_tools[...]与capabilities[...]两条路径并写出可动态按用户/请求调整工具配置的 Agent 代码。参考文件的定位Docling 的 Agent 技能体系在展开技术内容之前需要先说明这份文件在 Docling 仓库中的位置因为它直接决定了文件的适用场景与分发方式。Docling 采用技能skills机制向 AI 编码代理coding agent提供使用与开发指导。根据 AGENTS.md 的说明仓库中存在两类技能开发技能development skills供参与 Docling 开发的代理使用位于仓库根目录 .agents/skills/ 下包括dignified-pythonPython 风格规范与building-pydantic-ai-agentsPydantic AI 代理构建模式使用技能usage skills供外部代理使用 Docling 转换文档随 Python 包一起分发位于docling/.agents/skills/docling/内。docs/usage/agent_skills.md 进一步解释了两者的边界使用技能会打包进 wheel/sdist安装 Docling 后即可通过library-skills发现而开发技能仅保存在仓库内不随包发布。本文讲解的 BUILTIN-TOOLS.md 属于前者即building-pydantic-ai-agents技能的 10 个按需加载参考文件之一。技能入口 SKILL.md 通过任务路由表决定何时加载哪个参考文件。与内置工具相关的路由条目为我想要……参考文件添加函数工具、toolsets、MCP 服务器或显式搜索工具Tools Core使用提供方原生的 web search、web fetch、code executionBuilt-in Tools也就是说当任务涉及provider-native 行为例如 OpenAI 原生联网搜索、Anthropic 原生代码执行沙箱时代理才会读取本文档若只需要跨提供方一致的搜索/抓取能力则路由到 capabilities 相关参考。这一设计保证了代理每次只加载当前任务所需的最小上下文。该技能元数据声明了Python 3.10的兼容性前提见 SKILL.md 头部 front-matter技能版本为 1.1.0。文中的 API 示例如openai-responses:gpt-5.2、google-gla:gemini-3-flash-preview等模型串以技能文件记载为准实际使用时应以你所使用的 Pydantic AI 版本支持的模型名与提供方前缀为准。核心原则capabilities 优先builtin tools 兜底BUILTIN-TOOLS.md 开篇即给出使用原则BUILTIN-TOOLS.md当用户想要 provider-native tools如 web search、web fetch、code execution、memory、file search时读取本文件。 如果用户想要提供方无关provider-agnostic的解决方案优先使用WebSearch()、WebFetch()等 capabilities只有当用户明确要求提供方原生行为或提供方专属配置时才直接使用内置工具。这一原则在仓库内的架构参考 ARCHITECTURE.md 中有直接佐证。其能力capability对照表显示capabilities 层本身就内建了能走原生就走原生、否则回退的策略Capability提供能力可用于 YAML SpecWebSearch联网搜索——支持时走 builtin否则本地回退是WebFetchURL 抓取——支持时走 builtin否则自定义回退是ImageGeneration图像生成——支持时走 builtin否则自定义回退是MCPMCP 服务器——支持时走 builtin否则直连是BuiltinTool在 Agent 上注册一个内置工具是从源码结构看可以推断 Pydantic AI 的抽象层级设计为capabilities是意图层我要联网搜索框架负责判断当前提供方是否有对应的原生实现builtin tool有则透传、无则降级为本地实现而builtin_tools[...]是实现层我就是要这个提供方的这个原生工具跳过意图抽象、直接绑定提供方行为。因此capabilities 优先原则的收益在于代码在提供方之间可移植且自动获得回退能力。ARCHITECTURE.md 中的决策树同样体现了这一优先级见 ARCHITECTURE.md 决策树片段Need model thinking/reasoning? ├── Yes → Use Thinking(efforthigh) └── Need web search? ├── Yes → Use WebSearch() (auto-fallback to local) └── Need URL fetching? ├── Yes → Use WebFetch() └── Need MCP servers? ├── Yes → Use MCP()启用内置工具builtin_tools 参数与模型前缀内置工具通过Agent构造参数的builtin_tools[...]传入。BUILTIN-TOOLS.md 给出的最小示例BUILTIN-TOOLS.mdfrom pydantic_ai import Agent, WebSearchTool agent Agent(openai-responses:gpt-5.2, builtin_tools[WebSearchTool()]) result agent.run_sync(Give me a sentence with the biggest news in AI this week.) print(result.output)这个示例中有两个容易被忽略的关键点内置工具类直接从pydantic_ai顶层导入WebSearchTool与Agent同源导入与 capabilities 的导入路径pydantic_ai.capabilities如 SKILL.md 中from pydantic_ai.capabilities import Thinking, WebSearch的写法不同。模型串前缀决定了 API 通道。文档明确指出OpenAI 的 web search 必须使用 Responses API 模型前缀openai-responses:而不是普通的openai:。这与 SKILL.md Common Gotchas 中模型串必须带提供方前缀openai:gpt-5.2而非gpt-5.2的通用规则一脉相承——内置工具往往依赖提供方特定的 API 端点如 OpenAI 的 Responses API、Anthropic 的原生工具前缀选错会导致工具不可用或解析失败。内置工具清单七个提供方原生工具类BUILTIN-TOOLS.md 列出在提供方支持时可以直接使用的内置工具默认清单BUILTIN-TOOLS.mdWebSearchTool—— 提供方原生联网搜索WebFetchTool—— 提供方原生 URL 抓取CodeExecutionTool—— 提供方原生代码执行沙箱ImageGenerationTool—— 提供方原生图像生成MemoryTool—— 提供方原生记忆MCPServerTool—— 提供方原生 MCP 服务器接入FileSearchTool—— 提供方原生文件检索。从技能内其他参考文件可以印证这些工具与 capabilities 的对应关系WebSearchTool/WebFetchTool/ImageGenerationTool/MCPServerTool分别对应 capability 表中的WebSearch、WebFetch、ImageGeneration、MCP——capability 在提供方支持时走的正是同名 builtin 实现。此外BuiltinTool这一 capability 本身的作用就是在 Agent 上注册一个内置工具并且可用于 YAML 声明式 Agent specAgent.from_file/Agent.from_spec这意味着原生工具不仅能在 Python 构造时通过builtin_tools[...]传入也可以声明在 YAML 配置中。动态内置工具配置基于 RunContext 的按需装配当内置工具的参数取决于当前用户是谁或本次请求携带了什么上下文时可以在builtin_tools中放置一个可调用对象框架在每次运行run时以RunContext调用它根据返回值决定本次是否装配该工具、以何种参数装配。BUILTIN-TOOLS.md 给出的完整示例BUILTIN-TOOLS.mdfrom pydantic_ai import Agent, RunContext, WebSearchTool async def prepared_web_search(ctx: RunContext[dict]) - WebSearchTool | None: if not ctx.deps.get(location): return None return WebSearchTool(user_location{city: ctx.deps[location]}) agent Agent( openai-responses:gpt-5.2, builtin_tools[prepared_web_search], deps_typedict, )这段代码体现了三个配合点deps_typedict声明依赖类型运行时通过agent.run_sync(..., deps{...})注入SKILL.md 的Dependency Injection模式同样基于deps_type与ctx.deps例如agent.run_sync(What is the date?, depsFrank)返回None表示本次运行不装配该工具——例如请求中没有location字段时联网搜索工具直接缺席而不是装配一个缺少位置信息的工具工具实例是每请求现构造的user_location{city: ...}这类提供方专属参数得以按用户动态填充这正是文档开头所说provider-specific configuration matters场景的标准解法。可调用对象返回类型WebSearchTool | None的联合签名明确了契约返回工具实例或None二选一。决策矩阵什么时候用 builtin tools什么时候用 capabilitiesBUILTIN-TOOLS.md 末尾给出了两条并列的决策清单BUILTIN-TOOLS.md完整保留如下使用内置工具builtin tools当用户明确想要提供方原生行为provider-native behavior提供方专属配置provider-specific configuration很重要用户已经选定了支持该工具的提供方。使用 capabilities 当代码需要跨提供方工作希望在 builtin 支持缺失时有本地回退用户尚未承诺使用某个特定提供方。结合前文的能力表与决策树可以归纳出一条清晰的判断路径先看是否锁定提供方——锁定且需要原生特性原生搜索质量、原生代码执行沙箱、原生记忆语义等时走builtin_tools[...]未锁定或要求可移植时走capabilities[WebSearch(), ...]由框架自动选择有原生走原生、无原生走回退。在 Docling 仓库中的使用与延伸阅读最后说明这份参考在 Docling 仓库内的实际使用方式与边界它是开发技能不随 Docling 包分发。按 docs/usage/agent_skills.md 与 AGENTS.md 的区分.agents/skills/下的技能面向开发 Docling 本身的代理外部用户通过uvx library-skills安装的是包内使用技能docling/.agents/skills/docling/其中不包含 Pydantic AI 内容。因此如果你是在 Docling 仓库内做贡献、并且任务涉及为项目添加基于 Pydantic AI 的代理功能例如构建文档分析助手这份参考才会被你的开发代理加载。配套参考按需加载。与内置工具相关的完整知识图谱分布在技能目录内函数工具与 toolsets 见 TOOLS-CORE.md审批/重试/超时等高级工具特性见 TOOLS-ADVANCED.md抽象对比与决策树见 ARCHITECTURE.md测试与调试TestModel、请求检查见 TESTING-AND-DEBUGGING.md。与 Python 风格技能配合。Docling 仓库同时捆绑了 dignified-python 技能约束贡献代码的 Python 风格类型注解、pathlib优先等与 AGENTS.md 的Code standards一致编写使用builtin_tools的代理代码时两类技能会同时约束实现质量。运行环境技能声明 Python 3.10模型串、内置工具类名与参数如user_location以技能文件记载的当前 Pydantic AI API 为准切换 Pydantic AI 版本时建议对照该版本的官方文档核对。小结BUILTIN-TOOLS.md 作为 Docling 开发技能building-pydantic-ai-agents的按需参考回答了一个非常具体的问题当代理需要提供方原生能力联网搜索、网页抓取、代码执行、记忆、文件检索、图像生成、MCP时如何把内置工具正确接入 Pydantic AI Agent。核心要点可以浓缩为四条通过builtin_tools[...]传入内置工具类OpenAI 原生联网搜索须用openai-responses:前缀走 Responses API依赖请求上下文的工具用RunContext可调用对象动态装配返回None即本次不装配跨提供方、需要回退、未锁定提供方时优先选择 capabilitiesWebSearch()等由框架自动处理有原生走原生、无原生走回退。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Docling 开发技能参考详解：Pydantic AI 提供方原生内置工具（builtin_tools）实战指南
Docling 开发技能参考详解Pydantic AI 提供方原生内置工具builtin_tools实战指南【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文基于 Docling 仓库自带的开发技能参考文件 BUILTIN-TOOLS.md系统讲解 Pydantic AI 中提供方原生内置工具built-in tools的启用方式、可用工具清单、基于RunContext的动态配置模式以及内置工具与跨提供方 capabilities 之间的选型决策。读完本文你能在构建 Pydantic AI Agent 时正确区分builtin_tools[...]与capabilities[...]两条路径并写出可动态按用户/请求调整工具配置的 Agent 代码。参考文件的定位Docling 的 Agent 技能体系在展开技术内容之前需要先说明这份文件在 Docling 仓库中的位置因为它直接决定了文件的适用场景与分发方式。Docling 采用技能skills机制向 AI 编码代理coding agent提供使用与开发指导。根据 AGENTS.md 的说明仓库中存在两类技能开发技能development skills供参与 Docling 开发的代理使用位于仓库根目录 .agents/skills/ 下包括dignified-pythonPython 风格规范与building-pydantic-ai-agentsPydantic AI 代理构建模式使用技能usage skills供外部代理使用 Docling 转换文档随 Python 包一起分发位于docling/.agents/skills/docling/内。docs/usage/agent_skills.md 进一步解释了两者的边界使用技能会打包进 wheel/sdist安装 Docling 后即可通过library-skills发现而开发技能仅保存在仓库内不随包发布。本文讲解的 BUILTIN-TOOLS.md 属于前者即building-pydantic-ai-agents技能的 10 个按需加载参考文件之一。技能入口 SKILL.md 通过任务路由表决定何时加载哪个参考文件。与内置工具相关的路由条目为我想要……参考文件添加函数工具、toolsets、MCP 服务器或显式搜索工具Tools Core使用提供方原生的 web search、web fetch、code executionBuilt-in Tools也就是说当任务涉及provider-native 行为例如 OpenAI 原生联网搜索、Anthropic 原生代码执行沙箱时代理才会读取本文档若只需要跨提供方一致的搜索/抓取能力则路由到 capabilities 相关参考。这一设计保证了代理每次只加载当前任务所需的最小上下文。该技能元数据声明了Python 3.10的兼容性前提见 SKILL.md 头部 front-matter技能版本为 1.1.0。文中的 API 示例如openai-responses:gpt-5.2、google-gla:gemini-3-flash-preview等模型串以技能文件记载为准实际使用时应以你所使用的 Pydantic AI 版本支持的模型名与提供方前缀为准。核心原则capabilities 优先builtin tools 兜底BUILTIN-TOOLS.md 开篇即给出使用原则BUILTIN-TOOLS.md当用户想要 provider-native tools如 web search、web fetch、code execution、memory、file search时读取本文件。 如果用户想要提供方无关provider-agnostic的解决方案优先使用WebSearch()、WebFetch()等 capabilities只有当用户明确要求提供方原生行为或提供方专属配置时才直接使用内置工具。这一原则在仓库内的架构参考 ARCHITECTURE.md 中有直接佐证。其能力capability对照表显示capabilities 层本身就内建了能走原生就走原生、否则回退的策略Capability提供能力可用于 YAML SpecWebSearch联网搜索——支持时走 builtin否则本地回退是WebFetchURL 抓取——支持时走 builtin否则自定义回退是ImageGeneration图像生成——支持时走 builtin否则自定义回退是MCPMCP 服务器——支持时走 builtin否则直连是BuiltinTool在 Agent 上注册一个内置工具是从源码结构看可以推断 Pydantic AI 的抽象层级设计为capabilities是意图层我要联网搜索框架负责判断当前提供方是否有对应的原生实现builtin tool有则透传、无则降级为本地实现而builtin_tools[...]是实现层我就是要这个提供方的这个原生工具跳过意图抽象、直接绑定提供方行为。因此capabilities 优先原则的收益在于代码在提供方之间可移植且自动获得回退能力。ARCHITECTURE.md 中的决策树同样体现了这一优先级见 ARCHITECTURE.md 决策树片段Need model thinking/reasoning? ├── Yes → Use Thinking(efforthigh) └── Need web search? ├── Yes → Use WebSearch() (auto-fallback to local) └── Need URL fetching? ├── Yes → Use WebFetch() └── Need MCP servers? ├── Yes → Use MCP()启用内置工具builtin_tools 参数与模型前缀内置工具通过Agent构造参数的builtin_tools[...]传入。BUILTIN-TOOLS.md 给出的最小示例BUILTIN-TOOLS.mdfrom pydantic_ai import Agent, WebSearchTool agent Agent(openai-responses:gpt-5.2, builtin_tools[WebSearchTool()]) result agent.run_sync(Give me a sentence with the biggest news in AI this week.) print(result.output)这个示例中有两个容易被忽略的关键点内置工具类直接从pydantic_ai顶层导入WebSearchTool与Agent同源导入与 capabilities 的导入路径pydantic_ai.capabilities如 SKILL.md 中from pydantic_ai.capabilities import Thinking, WebSearch的写法不同。模型串前缀决定了 API 通道。文档明确指出OpenAI 的 web search 必须使用 Responses API 模型前缀openai-responses:而不是普通的openai:。这与 SKILL.md Common Gotchas 中模型串必须带提供方前缀openai:gpt-5.2而非gpt-5.2的通用规则一脉相承——内置工具往往依赖提供方特定的 API 端点如 OpenAI 的 Responses API、Anthropic 的原生工具前缀选错会导致工具不可用或解析失败。内置工具清单七个提供方原生工具类BUILTIN-TOOLS.md 列出在提供方支持时可以直接使用的内置工具默认清单BUILTIN-TOOLS.mdWebSearchTool—— 提供方原生联网搜索WebFetchTool—— 提供方原生 URL 抓取CodeExecutionTool—— 提供方原生代码执行沙箱ImageGenerationTool—— 提供方原生图像生成MemoryTool—— 提供方原生记忆MCPServerTool—— 提供方原生 MCP 服务器接入FileSearchTool—— 提供方原生文件检索。从技能内其他参考文件可以印证这些工具与 capabilities 的对应关系WebSearchTool/WebFetchTool/ImageGenerationTool/MCPServerTool分别对应 capability 表中的WebSearch、WebFetch、ImageGeneration、MCP——capability 在提供方支持时走的正是同名 builtin 实现。此外BuiltinTool这一 capability 本身的作用就是在 Agent 上注册一个内置工具并且可用于 YAML 声明式 Agent specAgent.from_file/Agent.from_spec这意味着原生工具不仅能在 Python 构造时通过builtin_tools[...]传入也可以声明在 YAML 配置中。动态内置工具配置基于 RunContext 的按需装配当内置工具的参数取决于当前用户是谁或本次请求携带了什么上下文时可以在builtin_tools中放置一个可调用对象框架在每次运行run时以RunContext调用它根据返回值决定本次是否装配该工具、以何种参数装配。BUILTIN-TOOLS.md 给出的完整示例BUILTIN-TOOLS.mdfrom pydantic_ai import Agent, RunContext, WebSearchTool async def prepared_web_search(ctx: RunContext[dict]) - WebSearchTool | None: if not ctx.deps.get(location): return None return WebSearchTool(user_location{city: ctx.deps[location]}) agent Agent( openai-responses:gpt-5.2, builtin_tools[prepared_web_search], deps_typedict, )这段代码体现了三个配合点deps_typedict声明依赖类型运行时通过agent.run_sync(..., deps{...})注入SKILL.md 的Dependency Injection模式同样基于deps_type与ctx.deps例如agent.run_sync(What is the date?, depsFrank)返回None表示本次运行不装配该工具——例如请求中没有location字段时联网搜索工具直接缺席而不是装配一个缺少位置信息的工具工具实例是每请求现构造的user_location{city: ...}这类提供方专属参数得以按用户动态填充这正是文档开头所说provider-specific configuration matters场景的标准解法。可调用对象返回类型WebSearchTool | None的联合签名明确了契约返回工具实例或None二选一。决策矩阵什么时候用 builtin tools什么时候用 capabilitiesBUILTIN-TOOLS.md 末尾给出了两条并列的决策清单BUILTIN-TOOLS.md完整保留如下使用内置工具builtin tools当用户明确想要提供方原生行为provider-native behavior提供方专属配置provider-specific configuration很重要用户已经选定了支持该工具的提供方。使用 capabilities 当代码需要跨提供方工作希望在 builtin 支持缺失时有本地回退用户尚未承诺使用某个特定提供方。结合前文的能力表与决策树可以归纳出一条清晰的判断路径先看是否锁定提供方——锁定且需要原生特性原生搜索质量、原生代码执行沙箱、原生记忆语义等时走builtin_tools[...]未锁定或要求可移植时走capabilities[WebSearch(), ...]由框架自动选择有原生走原生、无原生走回退。在 Docling 仓库中的使用与延伸阅读最后说明这份参考在 Docling 仓库内的实际使用方式与边界它是开发技能不随 Docling 包分发。按 docs/usage/agent_skills.md 与 AGENTS.md 的区分.agents/skills/下的技能面向开发 Docling 本身的代理外部用户通过uvx library-skills安装的是包内使用技能docling/.agents/skills/docling/其中不包含 Pydantic AI 内容。因此如果你是在 Docling 仓库内做贡献、并且任务涉及为项目添加基于 Pydantic AI 的代理功能例如构建文档分析助手这份参考才会被你的开发代理加载。配套参考按需加载。与内置工具相关的完整知识图谱分布在技能目录内函数工具与 toolsets 见 TOOLS-CORE.md审批/重试/超时等高级工具特性见 TOOLS-ADVANCED.md抽象对比与决策树见 ARCHITECTURE.md测试与调试TestModel、请求检查见 TESTING-AND-DEBUGGING.md。与 Python 风格技能配合。Docling 仓库同时捆绑了 dignified-python 技能约束贡献代码的 Python 风格类型注解、pathlib优先等与 AGENTS.md 的Code standards一致编写使用builtin_tools的代理代码时两类技能会同时约束实现质量。运行环境技能声明 Python 3.10模型串、内置工具类名与参数如user_location以技能文件记载的当前 Pydantic AI API 为准切换 Pydantic AI 版本时建议对照该版本的官方文档核对。小结BUILTIN-TOOLS.md 作为 Docling 开发技能building-pydantic-ai-agents的按需参考回答了一个非常具体的问题当代理需要提供方原生能力联网搜索、网页抓取、代码执行、记忆、文件检索、图像生成、MCP时如何把内置工具正确接入 Pydantic AI Agent。核心要点可以浓缩为四条通过builtin_tools[...]传入内置工具类OpenAI 原生联网搜索须用openai-responses:前缀走 Responses API依赖请求上下文的工具用RunContext可调用对象动态装配返回None即本次不装配跨提供方、需要回退、未锁定提供方时优先选择 capabilitiesWebSearch()等由框架自动处理有原生走原生、无原生走回退。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考