庫(kù)中的 Pydantic AI 架構(gòu)決策指南：從決策樹(shù)到架構(gòu)總覽)
Docling 倉(cāng)庫(kù)中的 Pydantic AI 架構(gòu)決策指南從決策樹(shù)到架構(gòu)總覽【免費(fèi)下載鏈接】doclingGet your documents ready for gen AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 倉(cāng)庫(kù)在.agents/skills/building-pydantic-ai-agents/目錄下內(nèi)置了一套面向 AI 編程助手的開(kāi)發(fā)技能development skill其中的 ARCHITECTURE.md 是 Pydantic AI 框架的“架構(gòu)與決策指南”。本文以該文檔為核心完整梳理其六棵決策樹(shù)工具注冊(cè)、輸出模式、多智能體模式、行為擴(kuò)展、能力選擇、測(cè)試方案與五張對(duì)比表輸出模式、模型供應(yīng)商前綴、工具裝飾器、內(nèi)置能力、Agent 運(yùn)行方法并結(jié)合技能目錄中的入口文件 SKILL.md 與姊妹篇 AGENTS-CORE.md 的示例代碼把“選哪個(gè)抽象、為什么選它”講透讀完你可以根據(jù)任務(wù)特征直接定位到正確的 Pydantic AI 寫(xiě)法。1. 文檔定位為什么 Docling 倉(cāng)庫(kù)里放著一份 Pydantic AI 指南按 AGENTS.md 與 agent_skills.md 的說(shuō)明Docling 倉(cāng)庫(kù)中的技能分為兩類一類是隨 Python 包一起發(fā)布、教 Agent “使用 Docling”的 usage skill另一類存放在倉(cāng)庫(kù)根目錄 .agents/skills/ 下、供貢獻(xiàn)者“開(kāi)發(fā) Docling 時(shí)使用”的 development skillbuilding-pydantic-ai-agents即屬后者與dignified-python并列。building-pydantic-ai-agents技能的入口是 SKILL.md它聲明了技能的適用場(chǎng)景構(gòu)建 Agent、加工具/能力、結(jié)構(gòu)化輸出、流式、YAML 規(guī)格定義、測(cè)試并給出一張“任務(wù)路由表”。而 ARCHITECTURE.md 在該技能中承擔(dān)的角色是當(dāng)用戶要在多個(gè)抽象之間做選擇、或需要對(duì)比表與決策樹(shù)時(shí)才加載即它是整個(gè)技能包的“比較與選型參考”。SKILL.md 的路由表明確寫(xiě)道Compare abstractions, output modes, decorators, or model-string patterns → references/ARCHITECTURE.md。這一點(diǎn)很關(guān)鍵ARCHITECTURE.md 自身也強(qiáng)調(diào)自己是“comparison and abstraction choices”文件并列出姊妹文檔——若讀者已明確知道要做什么應(yīng)改讀更窄的任務(wù)指南AGENTS-CORE.md創(chuàng)建/配置 Agent、選擇輸出類型、deps、規(guī)格定義、運(yùn)行方法CAPABILITIES-AND-HOOKS.md可復(fù)用行為捆綁、生命周期事件攔截TOOLS-CORE.md函數(shù)工具、toolset、MCP、顯式搜索工具BUILTIN-TOOLS.md供應(yīng)商原生 web search / web fetch / 代碼執(zhí)行TOOLS-ADVANCED.md審批、重試、ToolReturn、校驗(yàn)器、超時(shí)INPUT-AND-HISTORY.md多模態(tài)輸入、消息歷史、上下文裁剪TESTING-AND-DEBUGGING.md測(cè)試與調(diào)試ORCHESTRATION-AND-INTEGRATIONS.md多 Agent 協(xié)同、圖工作流、A2A、持久執(zhí)行2. 決策樹(shù)一如何注冊(cè)工具工具注冊(cè)方式由“是否需要運(yùn)行上下文”驅(qū)動(dòng)文檔給出的決策樹(shù)為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對(duì)應(yīng)“何時(shí)用哪個(gè)裝飾器”的對(duì)比表場(chǎng)景選擇工具需要訪問(wèn) deps、用量統(tǒng)計(jì)、消息、重試信息agent.tool—— 首參必須是RunContext純函數(shù)不需要 Agent 上下文agent.tool_plain工具定義在獨(dú)立模塊中或在多個(gè) Agent 間共享Tool(fn)—— 通過(guò)tools[...]傳給 Agent 構(gòu)造器結(jié)合 SKILL.md 中的骰子游戲示例可以看到兩種裝飾器的實(shí)際分工roll_dice是無(wú)上下文純函數(shù)用agent.tool_plainget_player_name需要讀取注入的用戶名用agent.tool并以ctx: RunContext[str]作為首參讀取ctx.deps。SKILL.md 的 “Common Gotchas” 同時(shí)提醒a(bǔ)gent.tool要求首參是RunContext而agent.tool_plain絕不能帶這個(gè)參數(shù)混用會(huì)引發(fā)運(yùn)行時(shí)錯(cuò)誤。從技能包結(jié)構(gòu)看工具進(jìn)階特性審批、重試、校驗(yàn)器、超時(shí)、ToolReturn、動(dòng)態(tài)ToolPrepareFunc、FunctionToolset等的完整寫(xiě)法被拆分在 TOOLS-CORE.md 與 TOOLS-ADVANCED.md 中ARCHITECTURE.md 只負(fù)責(zé)“選型”不承載實(shí)現(xiàn)細(xì)節(jié)。3. 決策樹(shù)二如何選擇輸出模式Pydantic AI 的四種結(jié)構(gòu)化/文本輸出模式選擇邏輯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)配套的場(chǎng)景對(duì)比表場(chǎng)景模式需要結(jié)構(gòu)化數(shù)據(jù)且希望最大供應(yīng)商兼容性ToolOutput默認(rèn)—— 兼容所有供應(yīng)商支持流式希望供應(yīng)商原生強(qiáng)制 JSON schema 合規(guī)NativeOutput—— 僅限 OpenAI、Anthropic、Google流式支持有限供應(yīng)商既不支持工具也不支持 JSON modePromptedOutput—— 作為兜底到處可用LLM 返回非 JSON 的結(jié)構(gòu)化文本markdown、YAML、領(lǐng)域格式TextOutput—— 自定義解析函數(shù)AGENTS-CORE.md 給出了默認(rèn)用法output_typeMyModelPydantic 模型即觸發(fā)結(jié)構(gòu)化輸出output_typestr為純文本。SKILL.md 的 “Common Gotchas” 還指出一個(gè)實(shí)踐要點(diǎn)當(dāng)output_type是包含str的聯(lián)合類型或未設(shè)置output_type時(shí)模型可以用純文本提前結(jié)束運(yùn)行若必須走工具式輸出應(yīng)從聯(lián)合類型中剔除str。4. 決策樹(shù)三多智能體模式的選型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 調(diào)用結(jié)果回流父級(jí)、用輸出函數(shù)實(shí)現(xiàn)向?qū)＜?Agent 的永久性交接、在 Agent 之間插入應(yīng)用代碼的程序化交接、以及面向復(fù)雜狀態(tài)機(jī)的圖Graph式控制。多 Agent 委托的具體代碼模式如通過(guò)工具把整個(gè)子 Agent 作為工具暴露在 ORCHESTRATION-AND-INTEGRATIONS.md 的 “Coordinate Multiple Agents” 一節(jié)中展開(kāi)。5. 決策樹(shù)四如何擴(kuò)展 Agent 行為行為擴(kuò)展是 Capability 體系的主戰(zhàn)場(chǎng)決策樹(shù)如下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要點(diǎn)歸納可跨 Agent 復(fù)用的行為束工具 hooks 指令繼承AbstractCapability構(gòu)建自定義能力僅攔截生命周期事件用Hooks能力配合裝飾器無(wú)需子類化若攔截邏輯復(fù)雜到還需要注入工具或指令則升級(jí)為AbstractCapability子類從配置文件定義 AgentAgent.from_file()加載 YAML/JSON 規(guī)格只是加工具agent.tool或 Toolset否則直接把參數(shù)傳給 Agent 構(gòu)造器。SKILL.md 展示了Hooks的最小用法——hooks.on.before_model_request裝飾器可以在模型請(qǐng)求發(fā)出前打印消息數(shù)量并原樣返回ModelRequestContext然后把Hooks()實(shí)例放入capabilities[...]。其 Gotchas 還特別提醒hook 裝飾器名在.on上不重復(fù)on_前綴應(yīng)寫(xiě)hooks.on.run_error而不是hooks.on.on_run_error。同文檔的 YAML 規(guī)格示例也印證了“聲明式定義”路徑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)加載并通過(guò)depsUserContext(user_nameAlice)注入依賴見(jiàn) AGENTS-CORE.md 的 “Define Agents Declaratively with Specs” 一節(jié)。注意instructions中的{{user_name}}模板變量說(shuō)明規(guī)格文件中支持模板字符串。6. 決策樹(shù)五內(nèi)置能力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()內(nèi)置能力清單含“是否可用于 YAML 規(guī)格”一列能力提供什么可用于 YAML 規(guī)格Thinking可配置努力度的模型思考/推理是Hooks基于裝飾器的生命周期鉤子注冊(cè)否WebSearch網(wǎng)絡(luò)搜索——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則本地兜底是WebFetchURL 抓取——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則自定義兜底是ImageGeneration圖像生成——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則自定義兜底是MCPMCP 服務(wù)器——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則直連是PrepareTools按步驟過(guò)濾或修改工具定義否PrefixTools包裝一個(gè)能力并給其工具名加前綴是BuiltinTool向 Agent 注冊(cè)一個(gè)內(nèi)置工具是Toolset包裝一個(gè)AbstractToolset否HistoryProcessor包裝一個(gè)歷史處理函數(shù)否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 可調(diào)用對(duì)象裝飾器、函數(shù)、Toolset 實(shí)例的能力Hooks、PrepareTools、Toolset、HistoryProcessor無(wú)法寫(xiě)入聲明式規(guī)格只能以代碼方式裝配——這解釋了為什么 YAML 規(guī)格路徑天然適合“標(biāo)準(zhǔn)能力組合”而深度定制必須走代碼。7. 決策樹(shù)六測(cè)試方案怎么選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三檔測(cè)試策略確定性快測(cè)TestModelagent.override()、指定工具調(diào)用行為FunctionModel、以及對(duì)真實(shí) API 的集成回放pytest-recording VCR 磁帶。SKILL.md 提供了TestModel的標(biāo)準(zhǔn)寫(xiě)法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 強(qiáng)調(diào)TestModel必須經(jīng)agent.override()上下文管理器注入不能直接改agent.modelm.last_model_request_parameters.function_tools則允許測(cè)試斷言“本次請(qǐng)求實(shí)際攜帶了哪些工具”實(shí)現(xiàn)了對(duì)請(qǐng)求內(nèi)容的白盒校驗(yàn)。8. 對(duì)比表模型供應(yīng)商前綴模型字符串統(tǒng)一采用provider:model-name格式例如openai:gpt-5.2。ARCHITECTURE.md 給出的前綴對(duì)照表供應(yīng)商前綴示例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:。對(duì)于真正自定義的供應(yīng)商則繼承Model基類或用OpenAIChatModel配合自定義base_url。使用注意模型字符串必須帶供應(yīng)商前綴——寫(xiě)gpt-5.2而非openai:gpt-5.2會(huì)導(dǎo)致 Pydantic AI 無(wú)法解析供應(yīng)商SKILL.md 明確列為常見(jiàn)錯(cuò)誤。當(dāng)需要供應(yīng)商特有的構(gòu)造參數(shù)時(shí)應(yīng)傳入模型實(shí)例而非字符串例如 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)該示例體現(xiàn)了FallbackModel的用途主模型失敗時(shí)自動(dòng)切換到備用供應(yīng)商并保持同一提示/輸出契約。9. 對(duì)比表Agent 運(yùn)行方法與流式場(chǎng)景方法構(gòu)建聊天機(jī)器人/助手需實(shí)時(shí)展示工具調(diào)用、進(jìn)度與輸出agent.run(event_stream_handler...)—— 運(yùn)行到完成的同時(shí)流式消費(fèi)所有事件運(yùn)行自主 Agent、批處理作業(yè)或后臺(tái)任務(wù)agent.run()CLI 工具、腳本、Jupyter notebook無(wú) asyncagent.run_sync()向 UI 逐詞流式輸出最終文本agent.run_stream()CLI/腳本的同步流式無(wú) asyncagent.run_stream_sync()接收類型化事件的異步迭代器工具調(diào)用、結(jié)果、最終輸出agent.run_stream_events()在 Agent 步驟之間檢查/修改狀態(tài)、人工介入審批agent.iter()event_stream_handler的寫(xiě)法詳見(jiàn) 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)這個(gè)模式適合“不手動(dòng)消費(fèi)事件流但仍要在運(yùn)行時(shí)收到進(jìn)度”的交互界面把 handler 作為參數(shù)傳入后run()照常返回最終結(jié)果事件處理在后臺(tái)完成。10. 架構(gòu)總覽執(zhí)行流、泛型與擴(kuò)展點(diǎn)ARCHITECTURE.md 的 “Architecture Overview” 一節(jié)濃縮了整個(gè)框架的心智模型執(zhí)行流。Agent.run()→UserPromptNode→ModelRequestNode→CallToolsNode→循環(huán)或結(jié)束。即一次運(yùn)行是一條節(jié)點(diǎn)鏈注入用戶提示、請(qǐng)求模型、執(zhí)行模型要求的工具然后在“還有工具要調(diào)用”時(shí)回到模型請(qǐng)求節(jié)點(diǎn)形成循環(huán)直到模型給出最終輸出。關(guān)鍵泛型。Agent[AgentDepsT, OutputDataT]—— 綁定依賴類型與輸出類型RunContext[AgentDepsT]—— 在工具與系統(tǒng)提示中可用AbstractCapability[AgentDepsT]—— 可復(fù)用行為束的基類。Agent 構(gòu)建的兩條路徑。Python 代碼路徑Agent(model, instructions..., tools..., capabilities...)聲明式路徑Agent.from_file(agent.yaml)或Agent.from_spec({...})。Capability 是首要擴(kuò)展點(diǎn)——它把工具、生命周期鉤子、指令與模型設(shè)置捆綁為可復(fù)用單元。內(nèi)置能力包括Thinking、WebSearch、WebFetch、Hooks、MCP等完整清單見(jiàn)第 6 節(jié)表格。生命周期鉤子。通過(guò)Hooks或AbstractCapability可以攔截運(yùn)行的每個(gè)階段順序?yàn)閎efore_run→before_model_request→before_tool_execute→after_tool_execute→after_model_request→after_run。這套命名與第 7 節(jié)Hooks()裝飾器示例hooks.on.before_model_request相互印證裝飾器名與鉤子階段名一一對(duì)應(yīng)。輸出模式小結(jié)。ToolOutput經(jīng)工具調(diào)用的結(jié)構(gòu)化數(shù)據(jù)Pydantic 模型的默認(rèn)、NativeOutput供應(yīng)商原生結(jié)構(gòu)化輸出、PromptedOutput基于提示的結(jié)構(gòu)化抽取、TextOutput純文本響應(yīng)——與第 3 節(jié)決策樹(shù)形成閉環(huán)。11. 把決策樹(shù)落到代碼一個(gè)完整的選型示例把文檔中的選型結(jié)論串起來(lái)一個(gè)“帶依賴注入 結(jié)構(gòu)化輸出 能力 測(cè)試”的 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, # 決策樹(shù)三模型串必須帶前綴 deps_typestr, # Agent[AgentDepsT, OutputDataT] instructionsYou are a research assistant. Be thorough and cite sources., output_typeResearchResult, # 決策樹(shù)二ToolOutput(MyModel) 默認(rèn)路徑 capabilities[Thinking(efforthigh), WebSearch()], # 決策樹(shù)五 ) 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)各要素對(duì)應(yīng)的決策點(diǎn)需要RunContext的指令/工具用agent.instructions/agent.tool首參RunContext[str]不需要上下文的工具用agent.tool_plain結(jié)構(gòu)化輸出交給默認(rèn)ToolOutput路徑而非NativeOutput換取跨供應(yīng)商一致性思考與搜索通過(guò)capabilities裝配。測(cè)試時(shí)按第 7 節(jié)決策樹(shù)用TestModelagent.override()做確定性單測(cè)回歸真實(shí) API 行為時(shí)用FunctionModel或 VCR 回放。12. 小結(jié)與在倉(cāng)庫(kù)中的延伸閱讀ARCHITECTURE.md 的價(jià)值在于提供“選型而不實(shí)現(xiàn)”的一層六棵決策樹(shù)回答“該用哪個(gè)抽象”五張對(duì)比表給出“為什么用它、在什么約束下用它”例如NativeOutput僅限 OpenAI/Anthropic/Google 且流式受限、Hooks/PrepareTools等能力不可寫(xiě)入 YAML 規(guī)格。實(shí)現(xiàn)細(xì)節(jié)則由同一references/目錄下的八份任務(wù)指南承載入口路由規(guī)則寫(xiě)在 SKILL.md 的任務(wù)路由表中。對(duì) Docling 貢獻(xiàn)者而言這套技能包配合 AGENTS.md 的說(shuō)明構(gòu)成了在倉(cāng)庫(kù)內(nèi)構(gòu)建 Pydantic AI Agent 應(yīng)用時(shí)的標(biāo)準(zhǔn)參考路徑技能要求的運(yùn)行環(huán)境為 Python 3.10可觀測(cè)性方面 SKILL.md 推薦logfire.instrument_pydantic_ai()追蹤 Agent 運(yùn)行、工具調(diào)用與模型請(qǐng)求?！久赓M(fèi)下載鏈接】doclingGet your documents ready for gen AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/do/docling創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Docling 倉(cāng)庫(kù)中的 Pydantic AI 架構(gòu)決策指南：從決策樹(shù)到架構(gòu)總覽
Docling 倉(cāng)庫(kù)中的 Pydantic AI 架構(gòu)決策指南從決策樹(shù)到架構(gòu)總覽【免費(fèi)下載鏈接】doclingGet your documents ready for gen AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 倉(cāng)庫(kù)在.agents/skills/building-pydantic-ai-agents/目錄下內(nèi)置了一套面向 AI 編程助手的開(kāi)發(fā)技能development skill其中的 ARCHITECTURE.md 是 Pydantic AI 框架的“架構(gòu)與決策指南”。本文以該文檔為核心完整梳理其六棵決策樹(shù)工具注冊(cè)、輸出模式、多智能體模式、行為擴(kuò)展、能力選擇、測(cè)試方案與五張對(duì)比表輸出模式、模型供應(yīng)商前綴、工具裝飾器、內(nèi)置能力、Agent 運(yùn)行方法并結(jié)合技能目錄中的入口文件 SKILL.md 與姊妹篇 AGENTS-CORE.md 的示例代碼把“選哪個(gè)抽象、為什么選它”講透讀完你可以根據(jù)任務(wù)特征直接定位到正確的 Pydantic AI 寫(xiě)法。1. 文檔定位為什么 Docling 倉(cāng)庫(kù)里放著一份 Pydantic AI 指南按 AGENTS.md 與 agent_skills.md 的說(shuō)明Docling 倉(cāng)庫(kù)中的技能分為兩類一類是隨 Python 包一起發(fā)布、教 Agent “使用 Docling”的 usage skill另一類存放在倉(cāng)庫(kù)根目錄 .agents/skills/ 下、供貢獻(xiàn)者“開(kāi)發(fā) Docling 時(shí)使用”的 development skillbuilding-pydantic-ai-agents即屬后者與dignified-python并列。building-pydantic-ai-agents技能的入口是 SKILL.md它聲明了技能的適用場(chǎng)景構(gòu)建 Agent、加工具/能力、結(jié)構(gòu)化輸出、流式、YAML 規(guī)格定義、測(cè)試并給出一張“任務(wù)路由表”。而 ARCHITECTURE.md 在該技能中承擔(dān)的角色是當(dāng)用戶要在多個(gè)抽象之間做選擇、或需要對(duì)比表與決策樹(shù)時(shí)才加載即它是整個(gè)技能包的“比較與選型參考”。SKILL.md 的路由表明確寫(xiě)道Compare abstractions, output modes, decorators, or model-string patterns → references/ARCHITECTURE.md。這一點(diǎn)很關(guān)鍵ARCHITECTURE.md 自身也強(qiáng)調(diào)自己是“comparison and abstraction choices”文件并列出姊妹文檔——若讀者已明確知道要做什么應(yīng)改讀更窄的任務(wù)指南AGENTS-CORE.md創(chuàng)建/配置 Agent、選擇輸出類型、deps、規(guī)格定義、運(yùn)行方法CAPABILITIES-AND-HOOKS.md可復(fù)用行為捆綁、生命周期事件攔截TOOLS-CORE.md函數(shù)工具、toolset、MCP、顯式搜索工具BUILTIN-TOOLS.md供應(yīng)商原生 web search / web fetch / 代碼執(zhí)行TOOLS-ADVANCED.md審批、重試、ToolReturn、校驗(yàn)器、超時(shí)INPUT-AND-HISTORY.md多模態(tài)輸入、消息歷史、上下文裁剪TESTING-AND-DEBUGGING.md測(cè)試與調(diào)試ORCHESTRATION-AND-INTEGRATIONS.md多 Agent 協(xié)同、圖工作流、A2A、持久執(zhí)行2. 決策樹(shù)一如何注冊(cè)工具工具注冊(cè)方式由“是否需要運(yùn)行上下文”驅(qū)動(dòng)文檔給出的決策樹(shù)為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對(duì)應(yīng)“何時(shí)用哪個(gè)裝飾器”的對(duì)比表場(chǎng)景選擇工具需要訪問(wèn) deps、用量統(tǒng)計(jì)、消息、重試信息agent.tool—— 首參必須是RunContext純函數(shù)不需要 Agent 上下文agent.tool_plain工具定義在獨(dú)立模塊中或在多個(gè) Agent 間共享Tool(fn)—— 通過(guò)tools[...]傳給 Agent 構(gòu)造器結(jié)合 SKILL.md 中的骰子游戲示例可以看到兩種裝飾器的實(shí)際分工roll_dice是無(wú)上下文純函數(shù)用agent.tool_plainget_player_name需要讀取注入的用戶名用agent.tool并以ctx: RunContext[str]作為首參讀取ctx.deps。SKILL.md 的 “Common Gotchas” 同時(shí)提醒a(bǔ)gent.tool要求首參是RunContext而agent.tool_plain絕不能帶這個(gè)參數(shù)混用會(huì)引發(fā)運(yùn)行時(shí)錯(cuò)誤。從技能包結(jié)構(gòu)看工具進(jìn)階特性審批、重試、校驗(yàn)器、超時(shí)、ToolReturn、動(dòng)態(tài)ToolPrepareFunc、FunctionToolset等的完整寫(xiě)法被拆分在 TOOLS-CORE.md 與 TOOLS-ADVANCED.md 中ARCHITECTURE.md 只負(fù)責(zé)“選型”不承載實(shí)現(xiàn)細(xì)節(jié)。3. 決策樹(shù)二如何選擇輸出模式Pydantic AI 的四種結(jié)構(gòu)化/文本輸出模式選擇邏輯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)配套的場(chǎng)景對(duì)比表場(chǎng)景模式需要結(jié)構(gòu)化數(shù)據(jù)且希望最大供應(yīng)商兼容性ToolOutput默認(rèn)—— 兼容所有供應(yīng)商支持流式希望供應(yīng)商原生強(qiáng)制 JSON schema 合規(guī)NativeOutput—— 僅限 OpenAI、Anthropic、Google流式支持有限供應(yīng)商既不支持工具也不支持 JSON modePromptedOutput—— 作為兜底到處可用LLM 返回非 JSON 的結(jié)構(gòu)化文本markdown、YAML、領(lǐng)域格式TextOutput—— 自定義解析函數(shù)AGENTS-CORE.md 給出了默認(rèn)用法output_typeMyModelPydantic 模型即觸發(fā)結(jié)構(gòu)化輸出output_typestr為純文本。SKILL.md 的 “Common Gotchas” 還指出一個(gè)實(shí)踐要點(diǎn)當(dāng)output_type是包含str的聯(lián)合類型或未設(shè)置output_type時(shí)模型可以用純文本提前結(jié)束運(yùn)行若必須走工具式輸出應(yīng)從聯(lián)合類型中剔除str。4. 決策樹(shù)三多智能體模式的選型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 調(diào)用結(jié)果回流父級(jí)、用輸出函數(shù)實(shí)現(xiàn)向?qū)＜?Agent 的永久性交接、在 Agent 之間插入應(yīng)用代碼的程序化交接、以及面向復(fù)雜狀態(tài)機(jī)的圖Graph式控制。多 Agent 委托的具體代碼模式如通過(guò)工具把整個(gè)子 Agent 作為工具暴露在 ORCHESTRATION-AND-INTEGRATIONS.md 的 “Coordinate Multiple Agents” 一節(jié)中展開(kāi)。5. 決策樹(shù)四如何擴(kuò)展 Agent 行為行為擴(kuò)展是 Capability 體系的主戰(zhàn)場(chǎng)決策樹(shù)如下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要點(diǎn)歸納可跨 Agent 復(fù)用的行為束工具 hooks 指令繼承AbstractCapability構(gòu)建自定義能力僅攔截生命周期事件用Hooks能力配合裝飾器無(wú)需子類化若攔截邏輯復(fù)雜到還需要注入工具或指令則升級(jí)為AbstractCapability子類從配置文件定義 AgentAgent.from_file()加載 YAML/JSON 規(guī)格只是加工具agent.tool或 Toolset否則直接把參數(shù)傳給 Agent 構(gòu)造器。SKILL.md 展示了Hooks的最小用法——hooks.on.before_model_request裝飾器可以在模型請(qǐng)求發(fā)出前打印消息數(shù)量并原樣返回ModelRequestContext然后把Hooks()實(shí)例放入capabilities[...]。其 Gotchas 還特別提醒hook 裝飾器名在.on上不重復(fù)on_前綴應(yīng)寫(xiě)hooks.on.run_error而不是hooks.on.on_run_error。同文檔的 YAML 規(guī)格示例也印證了“聲明式定義”路徑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)加載并通過(guò)depsUserContext(user_nameAlice)注入依賴見(jiàn) AGENTS-CORE.md 的 “Define Agents Declaratively with Specs” 一節(jié)。注意instructions中的{{user_name}}模板變量說(shuō)明規(guī)格文件中支持模板字符串。6. 決策樹(shù)五內(nèi)置能力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()內(nèi)置能力清單含“是否可用于 YAML 規(guī)格”一列能力提供什么可用于 YAML 規(guī)格Thinking可配置努力度的模型思考/推理是Hooks基于裝飾器的生命周期鉤子注冊(cè)否WebSearch網(wǎng)絡(luò)搜索——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則本地兜底是WebFetchURL 抓取——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則自定義兜底是ImageGeneration圖像生成——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則自定義兜底是MCPMCP 服務(wù)器——供應(yīng)商支持時(shí)用原生實(shí)現(xiàn)否則直連是PrepareTools按步驟過(guò)濾或修改工具定義否PrefixTools包裝一個(gè)能力并給其工具名加前綴是BuiltinTool向 Agent 注冊(cè)一個(gè)內(nèi)置工具是Toolset包裝一個(gè)AbstractToolset否HistoryProcessor包裝一個(gè)歷史處理函數(shù)否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 可調(diào)用對(duì)象裝飾器、函數(shù)、Toolset 實(shí)例的能力Hooks、PrepareTools、Toolset、HistoryProcessor無(wú)法寫(xiě)入聲明式規(guī)格只能以代碼方式裝配——這解釋了為什么 YAML 規(guī)格路徑天然適合“標(biāo)準(zhǔn)能力組合”而深度定制必須走代碼。7. 決策樹(shù)六測(cè)試方案怎么選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三檔測(cè)試策略確定性快測(cè)TestModelagent.override()、指定工具調(diào)用行為FunctionModel、以及對(duì)真實(shí) API 的集成回放pytest-recording VCR 磁帶。SKILL.md 提供了TestModel的標(biāo)準(zhǔn)寫(xiě)法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 強(qiáng)調(diào)TestModel必須經(jīng)agent.override()上下文管理器注入不能直接改agent.modelm.last_model_request_parameters.function_tools則允許測(cè)試斷言“本次請(qǐng)求實(shí)際攜帶了哪些工具”實(shí)現(xiàn)了對(duì)請(qǐng)求內(nèi)容的白盒校驗(yàn)。8. 對(duì)比表模型供應(yīng)商前綴模型字符串統(tǒng)一采用provider:model-name格式例如openai:gpt-5.2。ARCHITECTURE.md 給出的前綴對(duì)照表供應(yīng)商前綴示例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:。對(duì)于真正自定義的供應(yīng)商則繼承Model基類或用OpenAIChatModel配合自定義base_url。使用注意模型字符串必須帶供應(yīng)商前綴——寫(xiě)gpt-5.2而非openai:gpt-5.2會(huì)導(dǎo)致 Pydantic AI 無(wú)法解析供應(yīng)商SKILL.md 明確列為常見(jiàn)錯(cuò)誤。當(dāng)需要供應(yīng)商特有的構(gòu)造參數(shù)時(shí)應(yīng)傳入模型實(shí)例而非字符串例如 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)該示例體現(xiàn)了FallbackModel的用途主模型失敗時(shí)自動(dòng)切換到備用供應(yīng)商并保持同一提示/輸出契約。9. 對(duì)比表Agent 運(yùn)行方法與流式場(chǎng)景方法構(gòu)建聊天機(jī)器人/助手需實(shí)時(shí)展示工具調(diào)用、進(jìn)度與輸出agent.run(event_stream_handler...)—— 運(yùn)行到完成的同時(shí)流式消費(fèi)所有事件運(yùn)行自主 Agent、批處理作業(yè)或后臺(tái)任務(wù)agent.run()CLI 工具、腳本、Jupyter notebook無(wú) asyncagent.run_sync()向 UI 逐詞流式輸出最終文本agent.run_stream()CLI/腳本的同步流式無(wú) asyncagent.run_stream_sync()接收類型化事件的異步迭代器工具調(diào)用、結(jié)果、最終輸出agent.run_stream_events()在 Agent 步驟之間檢查/修改狀態(tài)、人工介入審批agent.iter()event_stream_handler的寫(xiě)法詳見(jiàn) 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)這個(gè)模式適合“不手動(dòng)消費(fèi)事件流但仍要在運(yùn)行時(shí)收到進(jìn)度”的交互界面把 handler 作為參數(shù)傳入后run()照常返回最終結(jié)果事件處理在后臺(tái)完成。10. 架構(gòu)總覽執(zhí)行流、泛型與擴(kuò)展點(diǎn)ARCHITECTURE.md 的 “Architecture Overview” 一節(jié)濃縮了整個(gè)框架的心智模型執(zhí)行流。Agent.run()→UserPromptNode→ModelRequestNode→CallToolsNode→循環(huán)或結(jié)束。即一次運(yùn)行是一條節(jié)點(diǎn)鏈注入用戶提示、請(qǐng)求模型、執(zhí)行模型要求的工具然后在“還有工具要調(diào)用”時(shí)回到模型請(qǐng)求節(jié)點(diǎn)形成循環(huán)直到模型給出最終輸出。關(guān)鍵泛型。Agent[AgentDepsT, OutputDataT]—— 綁定依賴類型與輸出類型RunContext[AgentDepsT]—— 在工具與系統(tǒng)提示中可用AbstractCapability[AgentDepsT]—— 可復(fù)用行為束的基類。Agent 構(gòu)建的兩條路徑。Python 代碼路徑Agent(model, instructions..., tools..., capabilities...)聲明式路徑Agent.from_file(agent.yaml)或Agent.from_spec({...})。Capability 是首要擴(kuò)展點(diǎn)——它把工具、生命周期鉤子、指令與模型設(shè)置捆綁為可復(fù)用單元。內(nèi)置能力包括Thinking、WebSearch、WebFetch、Hooks、MCP等完整清單見(jiàn)第 6 節(jié)表格。生命周期鉤子。通過(guò)Hooks或AbstractCapability可以攔截運(yùn)行的每個(gè)階段順序?yàn)閎efore_run→before_model_request→before_tool_execute→after_tool_execute→after_model_request→after_run。這套命名與第 7 節(jié)Hooks()裝飾器示例hooks.on.before_model_request相互印證裝飾器名與鉤子階段名一一對(duì)應(yīng)。輸出模式小結(jié)。ToolOutput經(jīng)工具調(diào)用的結(jié)構(gòu)化數(shù)據(jù)Pydantic 模型的默認(rèn)、NativeOutput供應(yīng)商原生結(jié)構(gòu)化輸出、PromptedOutput基于提示的結(jié)構(gòu)化抽取、TextOutput純文本響應(yīng)——與第 3 節(jié)決策樹(shù)形成閉環(huán)。11. 把決策樹(shù)落到代碼一個(gè)完整的選型示例把文檔中的選型結(jié)論串起來(lái)一個(gè)“帶依賴注入 結(jié)構(gòu)化輸出 能力 測(cè)試”的 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, # 決策樹(shù)三模型串必須帶前綴 deps_typestr, # Agent[AgentDepsT, OutputDataT] instructionsYou are a research assistant. Be thorough and cite sources., output_typeResearchResult, # 決策樹(shù)二ToolOutput(MyModel) 默認(rèn)路徑 capabilities[Thinking(efforthigh), WebSearch()], # 決策樹(shù)五 ) 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)各要素對(duì)應(yīng)的決策點(diǎn)需要RunContext的指令/工具用agent.instructions/agent.tool首參RunContext[str]不需要上下文的工具用agent.tool_plain結(jié)構(gòu)化輸出交給默認(rèn)ToolOutput路徑而非NativeOutput換取跨供應(yīng)商一致性思考與搜索通過(guò)capabilities裝配。測(cè)試時(shí)按第 7 節(jié)決策樹(shù)用TestModelagent.override()做確定性單測(cè)回歸真實(shí) API 行為時(shí)用FunctionModel或 VCR 回放。12. 小結(jié)與在倉(cāng)庫(kù)中的延伸閱讀ARCHITECTURE.md 的價(jià)值在于提供“選型而不實(shí)現(xiàn)”的一層六棵決策樹(shù)回答“該用哪個(gè)抽象”五張對(duì)比表給出“為什么用它、在什么約束下用它”例如NativeOutput僅限 OpenAI/Anthropic/Google 且流式受限、Hooks/PrepareTools等能力不可寫(xiě)入 YAML 規(guī)格。實(shí)現(xiàn)細(xì)節(jié)則由同一references/目錄下的八份任務(wù)指南承載入口路由規(guī)則寫(xiě)在 SKILL.md 的任務(wù)路由表中。對(duì) Docling 貢獻(xiàn)者而言這套技能包配合 AGENTS.md 的說(shuō)明構(gòu)成了在倉(cāng)庫(kù)內(nèi)構(gòu)建 Pydantic AI Agent 應(yīng)用時(shí)的標(biāo)準(zhǔn)參考路徑技能要求的運(yùn)行環(huán)境為 Python 3.10可觀測(cè)性方面 SKILL.md 推薦logfire.instrument_pydantic_ai()追蹤 Agent 運(yùn)行、工具調(diào)用與模型請(qǐng)求?！久赓M(fèi)下載鏈接】doclingGet your documents ready for gen AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/do/docling創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考