Docling 仓库中的 Pydantic AI 架构决策指南从决策树到架构总览【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 仓库在.agents/skills/building-pydantic-ai-agents/目录下内置了一套面向 AI 编程助手的开发技能development skill其中的 ARCHITECTURE.md 是 Pydantic AI 框架的“架构与决策指南”。本文以该文档为核心完整梳理其六棵决策树工具注册、输出模式、多智能体模式、行为扩展、能力选择、测试方案与五张对比表输出模式、模型供应商前缀、工具装饰器、内置能力、Agent 运行方法并结合技能目录中的入口文件 SKILL.md 与姊妹篇 AGENTS-CORE.md 的示例代码把“选哪个抽象、为什么选它”讲透读完你可以根据任务特征直接定位到正确的 Pydantic AI 写法。1. 文档定位为什么 Docling 仓库里放着一份 Pydantic AI 指南按 AGENTS.md 与 agent_skills.md 的说明Docling 仓库中的技能分为两类一类是随 Python 包一起发布、教 Agent “使用 Docling”的 usage skill另一类存放在仓库根目录 .agents/skills/ 下、供贡献者“开发 Docling 时使用”的 development skillbuilding-pydantic-ai-agents即属后者与dignified-python并列。building-pydantic-ai-agents技能的入口是 SKILL.md它声明了技能的适用场景构建 Agent、加工具/能力、结构化输出、流式、YAML 规格定义、测试并给出一张“任务路由表”。而 ARCHITECTURE.md 在该技能中承担的角色是当用户要在多个抽象之间做选择、或需要对比表与决策树时才加载即它是整个技能包的“比较与选型参考”。SKILL.md 的路由表明确写道Compare abstractions, output modes, decorators, or model-string patterns → references/ARCHITECTURE.md。这一点很关键ARCHITECTURE.md 自身也强调自己是“comparison and abstraction choices”文件并列出姊妹文档——若读者已明确知道要做什么应改读更窄的任务指南AGENTS-CORE.md创建/配置 Agent、选择输出类型、deps、规格定义、运行方法CAPABILITIES-AND-HOOKS.md可复用行为捆绑、生命周期事件拦截TOOLS-CORE.md函数工具、toolset、MCP、显式搜索工具BUILTIN-TOOLS.md供应商原生 web search / web fetch / 代码执行TOOLS-ADVANCED.md审批、重试、ToolReturn、校验器、超时INPUT-AND-HISTORY.md多模态输入、消息历史、上下文裁剪TESTING-AND-DEBUGGING.md测试与调试ORCHESTRATION-AND-INTEGRATIONS.md多 Agent 协同、图工作流、A2A、持久执行2. 决策树一如何注册工具工具注册方式由“是否需要运行上下文”驱动文档给出的决策树为Need RunContext (deps, usage, messages)? ├── Yes → Use agent.tool └── No → Pure function, no context needed? ├── Yes → Use agent.tool_plain └── Tools defined outside agent file? ├── Yes → Use tools[Tool(...)] in constructor └── Dynamic tools based on context? ├── Yes → Use ToolPrepareFunc └── Multiple related tools as a group? └── Yes → Use FunctionToolset对应“何时用哪个装饰器”的对比表场景选择工具需要访问 deps、用量统计、消息、重试信息agent.tool—— 首参必须是RunContext纯函数不需要 Agent 上下文agent.tool_plain工具定义在独立模块中或在多个 Agent 间共享Tool(fn)—— 通过tools[...]传给 Agent 构造器结合 SKILL.md 中的骰子游戏示例可以看到两种装饰器的实际分工roll_dice是无上下文纯函数用agent.tool_plainget_player_name需要读取注入的用户名用agent.tool并以ctx: RunContext[str]作为首参读取ctx.deps。SKILL.md 的 “Common Gotchas” 同时提醒agent.tool要求首参是RunContext而agent.tool_plain绝不能带这个参数混用会引发运行时错误。从技能包结构看工具进阶特性审批、重试、校验器、超时、ToolReturn、动态ToolPrepareFunc、FunctionToolset等的完整写法被拆分在 TOOLS-CORE.md 与 TOOLS-ADVANCED.md 中ARCHITECTURE.md 只负责“选型”不承载实现细节。3. 决策树二如何选择输出模式Pydantic AI 的四种结构化/文本输出模式选择逻辑Need structured data with Pydantic validation? ├── Yes → Does provider support native JSON mode? │ ├── Yes, and you want it → Use NativeOutput(MyModel) │ └── No, or prefer consistency → Use ToolOutput(MyModel) [default] └── No → Need custom parsing logic? ├── Yes → Use TextOutput(parser_fn) └── No → Just plain text? └── Yes → Use output_typestr [default] Dynamic schema at runtime? └── Yes → Use StructuredDict(json_schema)配套的场景对比表场景模式需要结构化数据且希望最大供应商兼容性ToolOutput默认—— 兼容所有供应商支持流式希望供应商原生强制 JSON schema 合规NativeOutput—— 仅限 OpenAI、Anthropic、Google流式支持有限供应商既不支持工具也不支持 JSON modePromptedOutput—— 作为兜底到处可用LLM 返回非 JSON 的结构化文本markdown、YAML、领域格式TextOutput—— 自定义解析函数AGENTS-CORE.md 给出了默认用法output_typeMyModelPydantic 模型即触发结构化输出output_typestr为纯文本。SKILL.md 的 “Common Gotchas” 还指出一个实践要点当output_type是包含str的联合类型或未设置output_type时模型可以用纯文本提前结束运行若必须走工具式输出应从联合类型中剔除str。4. 决策树三多智能体模式的选型Child agent returns result to parent? ├── Yes → Use agent delegation via tools └── No → Permanent hand-off to specialist? ├── Yes → Use output functions └── Application code between agents? ├── Yes → Use programmatic hand-off └── Complex state machine? └── Yes → Use Graph-based control四种模式可以概括为子 Agent 以工具形式被父 Agent 调用结果回流父级、用输出函数实现向专家 Agent 的永久性交接、在 Agent 之间插入应用代码的程序化交接、以及面向复杂状态机的图Graph式控制。多 Agent 委托的具体代码模式如通过工具把整个子 Agent 作为工具暴露在 ORCHESTRATION-AND-INTEGRATIONS.md 的 “Coordinate Multiple Agents” 一节中展开。5. 决策树四如何扩展 Agent 行为行为扩展是 Capability 体系的主战场决策树如下Need reusable behavior across agents (tools hooks instructions)? ├── Yes → Build a custom capability (subclass AbstractCapability) └── No → Just intercepting lifecycle events? ├── Yes → Complex interception needing tools/instructions too? │ ├── Yes → Subclass AbstractCapability │ └── No → Use Hooks capability with decorators └── No → Defining agents from config files? ├── Yes → Use Agent.from_file() with YAML/JSON specs └── No → Just adding tools? ├── Yes → Use agent.tool or Toolset └── Pass args directly to Agent constructor要点归纳可跨 Agent 复用的行为束工具 hooks 指令继承AbstractCapability构建自定义能力仅拦截生命周期事件用Hooks能力配合装饰器无需子类化若拦截逻辑复杂到还需要注入工具或指令则升级为AbstractCapability子类从配置文件定义 AgentAgent.from_file()加载 YAML/JSON 规格只是加工具agent.tool或 Toolset否则直接把参数传给 Agent 构造器。SKILL.md 展示了Hooks的最小用法——hooks.on.before_model_request装饰器可以在模型请求发出前打印消息数量并原样返回ModelRequestContext然后把Hooks()实例放入capabilities[...]。其 Gotchas 还特别提醒hook 装饰器名在.on上不重复on_前缀应写hooks.on.run_error而不是hooks.on.on_run_error。同文档的 YAML 规格示例也印证了“声明式定义”路径model: anthropic:claude-opus-4-6 instructions: You are helping {{user_name}} with research. capabilities: - WebSearch - Thinking: effort: high再用Agent.from_file(agent.yaml, deps_typeUserContext)加载并通过depsUserContext(user_nameAlice)注入依赖见 AGENTS-CORE.md 的 “Define Agents Declaratively with Specs” 一节。注意instructions中的{{user_name}}模板变量说明规格文件中支持模板字符串。6. 决策树五内置能力Capability怎么选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() └── Need lifecycle hooks only? ├── Yes → Use Hooks() └── Need to filter/modify tool defs per step? └── Yes → Use PrepareTools()内置能力清单含“是否可用于 YAML 规格”一列能力提供什么可用于 YAML 规格Thinking可配置努力度的模型思考/推理是Hooks基于装饰器的生命周期钩子注册否WebSearch网络搜索——供应商支持时用原生实现否则本地兜底是WebFetchURL 抓取——供应商支持时用原生实现否则自定义兜底是ImageGeneration图像生成——供应商支持时用原生实现否则自定义兜底是MCPMCP 服务器——供应商支持时用原生实现否则直连是PrepareTools按步骤过滤或修改工具定义否PrefixTools包装一个能力并给其工具名加前缀是BuiltinTool向 Agent 注册一个内置工具是Toolset包装一个AbstractToolset否HistoryProcessor包装一个历史处理函数否SKILL.md 的快速上手示例给出了能力的典型装配方式from pydantic_ai import Agent from pydantic_ai.capabilities import Thinking, WebSearch agent Agent( anthropic:claude-opus-4-6, instructionsYou are a research assistant. Be thorough and cite sources., capabilities[ Thinking(efforthigh), WebSearch(), ], )值得注意的是“可 YAML 化”这一列凡依赖 Python 可调用对象装饰器、函数、Toolset 实例的能力Hooks、PrepareTools、Toolset、HistoryProcessor无法写入声明式规格只能以代码方式装配——这解释了为什么 YAML 规格路径天然适合“标准能力组合”而深度定制必须走代码。7. 决策树六测试方案怎么选Need deterministic, fast tests? ├── Yes → Use TestModel with agent.override() └── Need specific tool call behavior? ├── Yes → Use FunctionModel └── Testing against real API (integration)? └── Yes → Use pytest-recording with VCR cassettes三档测试策略确定性快测TestModelagent.override()、指定工具调用行为FunctionModel、以及对真实 API 的集成回放pytest-recording VCR 磁带。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(): Unit test for my_agent, to be run by pytest. 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 []其中 Gotchas 强调TestModel必须经agent.override()上下文管理器注入不能直接改agent.modelm.last_model_request_parameters.function_tools则允许测试断言“本次请求实际携带了哪些工具”实现了对请求内容的白盒校验。8. 对比表模型供应商前缀模型字符串统一采用provider:model-name格式例如openai:gpt-5.2。ARCHITECTURE.md 给出的前缀对照表供应商前缀示例OpenAIopenai:openai:gpt-5.2Anthropicanthropic:anthropic:claude-sonnet-4-6Google (AI Studio)google-gla:google-gla:gemini-3-pro-previewGoogle (Vertex)google-vertex:google-vertex:gemini-3-pro-previewGroqgroq:groq:llama-3.3-70b-versatileMistralmistral:mistral:mistral-large-latestCoherecohere:cohere:command-r-plus-08-2024AWS Bedrockbedrock:bedrock:anthropic.claude-sonnet-4-6Azureazure:azure:gpt-5.2OpenRouteropenrouter:openrouter:anthropic/claude-sonnet-4-6xAIxai:xai:grok-3DeepSeekdeepseek:deepseek:deepseek-chatFireworksfireworks:fireworks:accounts/fireworks/models/llama-v3p3-70b-instructTogethertogether:together:meta-llama/Meta-Llama-3.1-70B-Instruct-TurboOllama本地ollama:ollama:llama3.2GitHub Modelsgithub:github:openai/gpt-5.2Hugging Facehuggingface:huggingface:meta-llama/Llama-3.3-70B-InstructCerebrascerebras:cerebras:llama-4-scout-17b-16e-instructHerokuheroku:heroku:claude-sonnet-4-6文档还列出附加前缀litellm:、nebius:、ovhcloud:、alibaba:、sambanova:、vercel:、outlines:、moonshotai:。对于真正自定义的供应商则继承Model基类或用OpenAIChatModel配合自定义base_url。使用注意模型字符串必须带供应商前缀——写gpt-5.2而非openai:gpt-5.2会导致 Pydantic AI 无法解析供应商SKILL.md 明确列为常见错误。当需要供应商特有的构造参数时应传入模型实例而非字符串例如 AGENTS-CORE.md 的故障切换示例from pydantic_ai import Agent from pydantic_ai.models.anthropic import AnthropicModel from pydantic_ai.models.fallback import FallbackModel from pydantic_ai.models.openai import OpenAIChatModel fallback FallbackModel( OpenAIChatModel(gpt-5.2), AnthropicModel(claude-sonnet-4-6), ) agent Agent(fallback)该示例体现了FallbackModel的用途主模型失败时自动切换到备用供应商并保持同一提示/输出契约。9. 对比表Agent 运行方法与流式场景方法构建聊天机器人/助手需实时展示工具调用、进度与输出agent.run(event_stream_handler...)—— 运行到完成的同时流式消费所有事件运行自主 Agent、批处理作业或后台任务agent.run()CLI 工具、脚本、Jupyter notebook无 asyncagent.run_sync()向 UI 逐词流式输出最终文本agent.run_stream()CLI/脚本的同步流式无 asyncagent.run_stream_sync()接收类型化事件的异步迭代器工具调用、结果、最终输出agent.run_stream_events()在 Agent 步骤之间检查/修改状态、人工介入审批agent.iter()event_stream_handler的写法详见 AGENTS-CORE.md 的 “Run Methods and Streaming”from collections.abc import AsyncIterable from pydantic_ai import Agent, AgentStreamEvent, FunctionToolCallEvent, RunContext agent Agent(openai:gpt-5.2) async def stream_handler(ctx: RunContext[None], events: AsyncIterable[AgentStreamEvent]): async for event in events: if isinstance(event, FunctionToolCallEvent): print(fCalling {event.part.tool_name}...) async def main(): await agent.run(Do the task, event_stream_handlerstream_handler)这个模式适合“不手动消费事件流但仍要在运行时收到进度”的交互界面把 handler 作为参数传入后run()照常返回最终结果事件处理在后台完成。10. 架构总览执行流、泛型与扩展点ARCHITECTURE.md 的 “Architecture Overview” 一节浓缩了整个框架的心智模型执行流。Agent.run()→UserPromptNode→ModelRequestNode→CallToolsNode→循环或结束。即一次运行是一条节点链注入用户提示、请求模型、执行模型要求的工具然后在“还有工具要调用”时回到模型请求节点形成循环直到模型给出最终输出。关键泛型。Agent[AgentDepsT, OutputDataT]—— 绑定依赖类型与输出类型RunContext[AgentDepsT]—— 在工具与系统提示中可用AbstractCapability[AgentDepsT]—— 可复用行为束的基类。Agent 构建的两条路径。Python 代码路径Agent(model, instructions..., tools..., capabilities...)声明式路径Agent.from_file(agent.yaml)或Agent.from_spec({...})。Capability 是首要扩展点——它把工具、生命周期钩子、指令与模型设置捆绑为可复用单元。内置能力包括Thinking、WebSearch、WebFetch、Hooks、MCP等完整清单见第 6 节表格。生命周期钩子。通过Hooks或AbstractCapability可以拦截运行的每个阶段顺序为before_run→before_model_request→before_tool_execute→after_tool_execute→after_model_request→after_run。这套命名与第 7 节Hooks()装饰器示例hooks.on.before_model_request相互印证装饰器名与钩子阶段名一一对应。输出模式小结。ToolOutput经工具调用的结构化数据Pydantic 模型的默认、NativeOutput供应商原生结构化输出、PromptedOutput基于提示的结构化抽取、TextOutput纯文本响应——与第 3 节决策树形成闭环。11. 把决策树落到代码一个完整的选型示例把文档中的选型结论串起来一个“带依赖注入 结构化输出 能力 测试”的 Agent 可以这样组织from datetime import date from pydantic import BaseModel from pydantic_ai import Agent, RunContext from pydantic_ai.capabilities import Thinking, WebSearch class ResearchResult(BaseModel): summary: str sources: list[str] agent Agent( anthropic:claude-sonnet-4-6, # 决策树三模型串必须带前缀 deps_typestr, # Agent[AgentDepsT, OutputDataT] instructionsYou are a research assistant. Be thorough and cite sources., output_typeResearchResult, # 决策树二ToolOutput(MyModel) 默认路径 capabilities[Thinking(efforthigh), WebSearch()], # 决策树五 ) agent.instructions def add_the_users_name(ctx: RunContext[str]) - str: return fThe users name is {ctx.deps}. agent.instructions def add_the_date() - str: return fThe date is {date.today()}. agent.tool_plain def get_now() - str: Return the current date as text. return date.today().isoformat() result agent.run_sync(Summarize recent AI safety research, depsFrank) print(result.output) print(result.usage()) # 如 RunUsage(input_tokens..., output_tokens..., requests1)各要素对应的决策点需要RunContext的指令/工具用agent.instructions/agent.tool首参RunContext[str]不需要上下文的工具用agent.tool_plain结构化输出交给默认ToolOutput路径而非NativeOutput换取跨供应商一致性思考与搜索通过capabilities装配。测试时按第 7 节决策树用TestModelagent.override()做确定性单测回归真实 API 行为时用FunctionModel或 VCR 回放。12. 小结与在仓库中的延伸阅读ARCHITECTURE.md 的价值在于提供“选型而不实现”的一层六棵决策树回答“该用哪个抽象”五张对比表给出“为什么用它、在什么约束下用它”例如NativeOutput仅限 OpenAI/Anthropic/Google 且流式受限、Hooks/PrepareTools等能力不可写入 YAML 规格。实现细节则由同一references/目录下的八份任务指南承载入口路由规则写在 SKILL.md 的任务路由表中。对 Docling 贡献者而言这套技能包配合 AGENTS.md 的说明构成了在仓库内构建 Pydantic AI Agent 应用时的标准参考路径技能要求的运行环境为 Python 3.10可观测性方面 SKILL.md 推荐logfire.instrument_pydantic_ai()追踪 Agent 运行、工具调用与模型请求。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考