Docling 仓库内嵌 Pydantic AI 技能参考函数工具、工具集与 MCP 服务器的组织实战【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本篇围绕 Docling 仓库中随仓分发的开发技能参考文件 TOOLS-CORE.md 展开系统讲解 Pydantic AI 的函数工具注册agent.tool/agent.tool_plain/Tool、工具集Toolset组织方式、RunContext运行时上下文、MCP 服务器接入以及 DuckDuckGo/Tavily/Exa 显式搜索工具的选型与用法。读完后你能在自己的项目里为 Agent 正确挂接工具、约束其可用工具范围并判断何时该用工具、何时该用内建能力Capability。文档在 Docling 仓库中的定位TOOLS-CORE.md 并不是 Docling 转换引擎自身的文档而是仓库根目录.agents/skills/下building-pydantic-ai-agents开发技能的一份主题参考。根据 AGENTS.md 的说明仓库中的技能分为两类Development skills开发技能面向参与 Docling 开发的贡献者/Agent放在仓库根目录的.agents/skills/下dignified-python与building-pydantic-ai-agents即属此类Usage skills使用技能面向用 Docling 转换文档的 Agent随 Python 包一起分发在docling/.agents/skills/docling/详见 docs/usage/agent_skills.md。该技能的入口是 SKILL.md它是一张任务路由表当用户的任务是添加函数工具、工具集、MCP 服务器或显式搜索工具时就加载本参考文件 TOOLS-CORE.md若涉及审批、重试、ToolReturn、超时或工具搜索等进阶特性则路由到 TOOLS-ADVANCED.md若需要 provider 原生工具WebSearchTool、CodeExecutionTool等则路由到 BUILTIN-TOOLS.md。这种SKILL.md 做短路由、references 按需加载的组织方式让 Agent 只读取当前任务所需的文件避免上下文膨胀。适用前提技能声明要求Python 3.10pydantic-ai是外部依赖用于构建 Agent 应用而 Docling 主包自身的依赖见 pyproject.toml只包含pydantic2.0.0,3.0.0并不直接依赖pydantic-ai。因此本文内容适用于在 Docling 生态周边用 Pydantic AI 构建 Agent 应用的场景。为 Agent 添加工具参考文件给出的核心规则一句话纯函数用agent.tool_plain需要RunContext的工具用agent.tool。import random from pydantic_ai import Agent, RunContext agent Agent(google-gla:gemini-3-flash-preview, deps_typestr) agent.tool_plain def roll_dice() - str: return str(random.randint(1, 6)) agent.tool def get_player_name(ctx: RunContext[str]) - str: return ctx.deps两个装饰器的分工很清晰agent.tool_plain挂载一个普通Python 函数函数签名中不能出现RunContext适合无状态、无依赖的纯函数如掷骰子agent.tool函数首参必须是RunContext[deps]通过ctx.deps拿到 Agent 构造时声明的依赖本例中deps_typestr运行期传入depsAnne。技能入口 SKILL.md 中的骰子游戏完整示例正是这一模式的落地Agent 同时挂载roll_diceplain与get_player_name带RunContextinstructions要求模型先掷骰子、再取玩家名字最后用agent.run_sync(My guess is 4, depsAnne)得到Congratulations Anne, you guessed correctly!。这说明两种注册方式可以共存于同一个 Agent各自承担不同职责。当工具定义在 Agent 文件之外、或需要在多个 Agent 之间复用时不要使用装饰器而应构造独立的Tool(fn)实例并放进tools[...]参数这样工具的生命周期与具体 Agent 解耦。选择工具注册方式四种默认选项参考文件给出了明确的选型默认值default choices方式适用场景agent.tool工具需要访问 deps、用量统计、重试次数或消息历史agent.tool_plain工具是一个普通函数无需任何运行期上下文Tool(...)放入tools[...]工具需要在多个 Agent 之间复用FunctionToolset多个相关工具需要作为一组统一管理SKILL.md 的Common Gotchas一节还补充了一个容易踩的运行时错误agent.tool要求RunContext作为首参而agent.tool_plain不能带RunContext混用会直接导致运行期报错——这与上文选型表互为印证。组织与限制 Agent 可用的工具Toolset当工具数量增多或希望给一组工具施加统一的横切行为cross-cutting behavior如审批、延迟加载时参考文件建议使用toolset而非零散挂载。它列举了三个典型形态FunctionToolset把一组 Python 工具打包成一个整体MCP 服务器MCP server 本身就是一种 toolsetwrapper toolset用于审批approval、延迟加载deferred loading等横切行为。进阶特性requires_approvalTrue、DeferredToolRequests审批流、ModelRetry重试、args_validator参数校验、ToolReturn富返回值、timeout、sequentialTrue等不在本参考的范围内而是放在姊妹文件 TOOLS-ADVANCED.md 中例如其中展示了如何通过output_type[str, DeferredToolRequests]让运行暂停等待人工批准。本文只继承 TOOLS-CORE.md 的边界负责注册、分组、限制把审批与重试留给进阶参考。在工具中访问用量统计、消息历史与重试计数如果工具内部需要读取ctx.deps、ctx.usage、ctx.messages或ctx.retry参考文件的结论是直接路由到agent.toolRunContext方案。这四个字段分别对应ctx.deps运行期依赖在run(..., deps...)时注入类型由deps_type声明ctx.usage本次运行的 token/请求用量统计ctx.messages当前消息历史可据此感知上下文长度或检索历史ctx.retry当前重试计数配合agent.tool(retriesN)与ModelRetry使用重试用法细节见 TOOLS-ADVANCED.md。也就是说要不要用带RunContext的工具这一判断本质上等价于这个工具是否需要这四个字段中的任意一个。使用 MCP 服务器MCPModel Context Protocol服务器以 toolset 的身份挂到 Agent 上。参考文件给出的完整示例stdio 传输、本地子进程方式from pydantic_ai import Agent from pydantic_ai.mcp import MCPServerStdio server MCPServerStdio(python, args[mcp_server.py], timeout10) agent Agent(openai:gpt-5.2, toolsets[server]) async def main(): async with agent: result await agent.run(What is the weather in Paris?) print(result.output)要点拆解MCPServerStdio(python, args[mcp_server.py], timeout10)以python mcp_server.py拉起本地子进程作为 MCP 服务器timeout控制连接超时toolsets[server]注意参数名是toolsets而非tools与前面tools[...]挂载单个Tool相区分async with agent:MCP 服务器属于需要管理生命周期的工具源要拉起/回收子进程因此运行前必须进入 Agent 的异步上下文确保agent.run(...)在连接建立之后执行。传输方式的选择参考文件给出默认建议MCPServerStdio本地子进程服务器MCPServerStreamableHTTPHTTP 服务器MCPServerSSE仍然存在但 Streamable HTTP 是更好的默认选择。显式搜索工具DuckDuckGo、Tavily、Exa当用户想要的是明确指定搜索引擎的工具而不是让模型自适应 provider 能力时使用pydantic_ai.common_tools中的显式搜索工具。参考文件示例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., )Tavily、Exa 同理作为可替换的引擎工具挂入tools[...]。这里也解释了与能力的边界instructions明确告诉模型该用哪个引擎从而保证行为确定。参考文件给出了一个良好的默认切分用户希望模型无关的搜索、且可接受内建回退builtin fallback时用WebSearch()capability写法见 SKILL.md 中的capabilities[Thinking(efforthigh), WebSearch()]示例用户明确点名DuckDuckGo / Tavily / Exa 这些引擎时用duckduckgo_search_tool()等显式工具。这一切分与 BUILTIN-TOOLS.md 的原则一致需要 provider 原生行为如WebSearchTool且模型串使用openai-responses:前缀时用builtin_tools[...]需要跨 provider、可本地回退时用 capability。三者显式工具 / capability / builtin tool覆盖了搜索需求从最具体到最抽象的三个层次。验证工具行为用 TestModel 做确定性测试技能入口 SKILL.md 提供了与工具直接相关的测试范式TestModel替换真实模型断言工具是否被正确注册到请求中from pydantic_ai import Agent from pydantic_ai.models.test import TestModel my_agent Agent(openai:gpt-5.2, instructions...) async def test_my_agent(): m TestModel() with my_agent.override(modelm): result await my_agent.run(Testing my agent...) assert result.output success (no tool calls) assert m.last_model_request_parameters.function_tools []两个规则值得注意同样来自 SKILL.md 的 Common GotchasTestModel必须通过agent.override(model...)上下文管理器替换不要直接给agent.model赋值last_model_request_parameters.function_tools让你能断言这一次模型请求实际携带了哪些函数工具是验证agent.tool/Tool(...)注册是否生效的直接依据。更多调试手段见 TESTING-AND-DEBUGGING.md。小结从 TOOLS-CORE 出发的一条决策路径把参考文件的规则串起来得到一个可执行的选择路径工具是纯函数→agent.tool_plain需要 deps / usage / messages / retry 之一→agent.toolRunContext工具要跨 Agent 复用→Tool(fn)放入tools[...]一组相关工具要统一管理或施加横切行为→FunctionToolset/ MCP 服务器 / wrapper toolset挂入toolsets[...]需要外部工具生态→MCPServerStdio本地或MCPServerStreamableHTTPHTTP配合async with agent:运行需要搜索→ 模型无关用WebSearch()capability点名引擎用duckduckgo_search_tool()/ Tavily / Exa需要审批、重试、ToolReturn、超时、延迟加载→ 转入 TOOLS-ADVANCED.md。以上规则均可在 Docling 仓库的 .agents/skills/building-pydantic-ai-agents/ 技能目录中按SKILL.md 路由 references 细分的方式逐文件核对配合TestModel断言即可在不调用真实模型的情况下验证你的工具组织是否符合预期。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考