尧图网页设计 
pydantic-ai-slim 源码架构解析Agent 运行图、事件流缓冲区与首方取消的底层实现【免费下载链接】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 Slimpydantic-ai-slim是 Pydantic AI 的核心逻辑包以最少依赖实现 Agent、模型、工具集、消息历史、流式输出、UI 适配器与持久化执行等全部核心能力。本指南以仓库内 agent_docs/pydantic-ai-slim.md 为主线结合pydantic_ai_slim/pydantic_ai/下的实际源码逐层拆解其模块职责边界、运行事件流Run Event Stream的内部缓冲区机制、以及首方取消First-Party Cancellation的仲裁原理帮助你理解在pydantic-ai-slim上做非平凡改动时应当遵守的兼容性约束与设计规则。读完后你将掌握这套代码库的骨架脉络知道改什么、在哪改、以及如何用测试验证改动。一、模块职责边界谁拥有什么pydantic-ai-slim的包体位于 pydantic_ai_slim/pydantic_ai核心设计原则是职责归属清晰、provider 事实不下沉。以下是从 agent_docs/pydantic-ai-slim.md 继承并对照源码展开的模块所有权划分模块职责Agentagent/init.py面向用户的构建与运行 API。Agent.iter()是图运行的入口门面_prepare_run()把每次运行的输入解析为私有的_PreparedAgentRun其open()负责资源进入、能力生命周期、恢复与清理。凡是能建模为 capability、toolset、model setting 或 profile 事实的行为不要新增构造参数_agent_graph.py循环编排提示词组装、模型请求、工具/输出处理、重试、用量检查与收尾tool_manager.py、tools.py、toolsets/工具发现、校验、执行、重试、审批/延迟、包装器组合与稳定的工具身份output.py/_output.py公开输出 API / 内部输出 schema、处理器、输出工具与输出校验messages.py规范化协议。provider 适配器、UI 适配器、持久化包装器与历史记录都应以该形态往返而不是把 provider 事实编码进字符串或临时字段models/把规范化请求/响应映射到 provider 线上格式providers/认证、客户端、base URL、HTTP 生命周期、provider 级模型/profile 推断profiles/模型家族事实结构化输出默认值、schema 怪癖、原生工具支持、thinking 支持、return-schema 支持、提示输出模板与模型家族固有行为capabilities/可组合的横切行为指令、设置、工具集、原生工具、包装工具集以及 run/model/tool/output/event/history 各类钩子durable_exec/把 agent、模型与工具集适配到持久化运行时。这些集成应被视为核心语义的兼容性测试而非外围适配器ui/把规范化消息/事件翻译为前端协议跨往返保留消息历史与事件语义为什么这样划分设计规则要求 provider 事实只放在providers/、profiles/与模型适配器中禁止在 graph、tool、output、UI 代码里散落按 provider 名称的 if 分支provider 特有数据应保存在结构化的 metadata/provider-details 字段中不得重载规范化 ID、文本内容或工具参数。优先用通用原语而非一次性标志横切行为用 capability工具集合行为用包装工具集能力事实用 profileprovider API 旋钮用类型化设置。本地工具与 provider 原生工具在概念上必须分离若某功能二者皆可需把回退/选择行为显式化并测试其产生的消息历史。二、兼容性清单动手前先确认哪些契约会变pydantic-ai-slim的改动往往横跨多个子系统agent_docs/pydantic-ai-slim.md 要求编辑前先识别以下可变化契约公开 API构造参数、装饰器、设置、输出类型、工具/toolset API、导入路径与文档化名称Provider API 兼容性请求参数、响应部件、流式分片、原生工具、结构化输出、thinking/reasoning、提示缓存、token 计数、用量与 provider 元数据消息/事件协议持久化消息历史、部分响应、工具调用部件、输出事件、原生工具部件、重试提示与 UI 事件流持久化执行上下文传播、依赖序列化、工具顺序、重试、消息重放、toolset 生命周期、activity/task 边界与确定性行为Agent 规范/配置新状态是否可序列化、可安全加载、能否不依赖运行时闭包来表达。移除废弃 API 时需区分两类兼容性公开表面的清理可在主版本中移除旧构造函数/导入但已序列化的历史消息可能仍需反序列化。改动工具/输出执行时要把顺序、重试语义、延迟调用、输出收尾、流式事件与 durable 包装器放在一起检查。三、运行事件流的内部机制event_stream_buffer与事件家族3.1 缓冲区是什么GraphAgentState.event_stream_buffer是运行作用域的内部队列用于承载在模型/工具事件生成器直接路径之外产生的框架事件。它通过引用被共享进本次运行的每一个RunContext作为私有的_event_stream_buffer字段见 pydantic_ai_slim/pydantic_ai/_run_context.py框架代码通过RunContext._emit_event(event)追加事件该方法断言缓冲区存在events are only emitted during an agent run, which has a buffer。缓冲区上的公共表面是RunContext.emit以及驱动agent.iter()的AgentRun.emit见 pydantic_ai_slim/pydantic_ai/run.py应用代码发射CustomEvent子类能力发射CapabilityEvent子类emit从钩子上下文的_capability或正在执行的ToolManager的tool_def.capability_id解析其归属能力——因此能力贡献的工具所发出的事件无需工具自身知晓即可正确归属。3.2 事件家族是开放家族靠注册表重建联合AgentStreamEvent联合是封闭的判别联合但CustomEvent/CapabilityEvent是开放家族子类在类定义时注册__init_subclass__AgentStreamEvent联合随后由这些注册表重建实现见 pydantic_ai_slim/pydantic_ai/_event_registry.py。未注册的 tag 不会导致校验失败而是降级为UnknownCustomEvent/UnknownCapabilityEvent信封把原始载荷放进data字段相关类型定义见 pydantic_ai_slim/pydantic_ai/messages.py 与 messages.py序列化时再展平data使下游若导入了定义模块即可恢复出类型化事件。两个容易踩坑的细节快照语义event_family_schema构建时快照注册表之后才注册的类会降级为 unknown 信封——这对构建一次即丢弃的 schema 是正确的但任何基于含AgentStreamEvent的 hint 做适配器记忆化memoize的消费者如 Temporal 的 payload converter必须用event_registry_version()作为缓存键因为联合的 choices 在 schema 构建时被快照注册表变更会递增版本号使旧适配器失效见EventRegistry的__setitem__/__delitem__/pop均会 bump 版本。重放隔离Temporal 这类 durable 运行时会在隔离的解释器视图里重执行应用模块产生与宿主进程同模块同 qualname的事件类重定义。set_replay_isolation_guard使重定义保留已注册类为家族规范类canonical实例经_canonicalize规范化为宿主类后再序列化保证两侧isinstance检查与on_event(MyEvent)过滤一致。3.3 事件如何送达dispatch 与 drain监听监听器在事件流位置被消费时运行唯一的例外是声明了dispatchimmediate的CapabilityEvent家族——它在emit返回前被派发使发射者能读到监听器设置的决策字段。派发前先咨询AbstractCapability.listens_to(event)见 pydantic_ai_slim/pydantic_ai/capabilities/abstract.py因此能力只在某个on_event监听器点名的事件类上被唤醒裸标记或直接覆写on_event()会拓宽到所有事件CombinedCapability/WrapperCapability报告其内部包含的联合。drain节点流负责把缓冲区排入wrap_run_event_stream/event_stream_handler。ModelRequestNode把该职责委托给AgentStream经_event_stream_buffer_getter见 pydantic_ai_slim/pydantic_ai/_agent_graph.py每次从模型流 pull 之前先 drain——pull 在途期间产生的事件在下次 pull 时浮出或模型流耗尽后经响应处理节点的流送达。CallToolsNode用_with_event_stream_buffer包装其 handle-response 事件迭代器见 pydantic_ai_slim/pydantic_ai/_agent_graph.py仅在节点流开始与结束时 drain末尾 drain 负责投递一步中最后一个模型/工具事件之后产生的事件。流存活期间事件经_iter_completed_or_buffered见 pydantic_ai_slim/pydantic_ai/_tool_execution.py与工具完成交错送达此处若再 drain可能把缓冲事件提到流即将投递的更早事件之前颠倒发射顺序。一个典型样例待处理消息pending messages遵循公开事件语义成立后才发射的模式——PendingMessageDrainCapability在每次 drain 的enqueue调用把消息送入历史时为该调用发射一个EnqueuedMessagesEvent一个调用可携带多条消息事件描述的是消息已按送达呈现刻意不携带索引因为_clean_message_history可能跨运行合并相邻请求使索引失效。3.4 不同持久化运行时下的事件语义emit的行为依赖持久化运行时的执行模型详见 pydantic_ai_slim/pydantic_ai/durable_exec/AGENTS.mdTemporal从工具或事件流处理器内emit会抛错——它们运行在无法触达缓冲区的 activity 中DBOS / Prefect缓冲区在进程内emit可用但在 durable 单元内发射的事件是运行它的副作用——被重放的步骤或命中的缓存任务不会重新发射该事件。四、首方取消的内部机制RunCancellation与三种关键簿记4.1 控制器形态_cancel.RunCancellation是运行作用域的首方取消控制器实现见 pydantic_ai_slim/pydantic_ai/_cancel.py持有于GraphAgentDeps.cancellation以引用方式共享进每个RunContext的私有_cancellation字段——与_event_stream_buffer一样遵守绝不 replace的不变式。首方取消AgentRun.cancel()、RunContext.cancel()通过取消驱动运行的 asyncio task 实现因此完整复用外部取消的拆除链路流被关闭、在途工具任务被取消并排空、挂起的服务端任务尽力取消、已完成工作写入消息历史在_PreparedAgentRun.open()退出栈的外缘_translate_cancellationCancelledError恰好被分类一次此时所有产生历史的拆除均已提交。CancellationToken是线程安全的取消句柄可同时传给多个并发运行cancel()幂等且可从任意线程调用在同一事件循环线程上同步投递否则经call_soon_threadsafe编排。4.2 三块承重的簿记文档明确点名以下三处簿记是承重的_agent_graph.py/run.py的改动极易破坏它们发号计数issuance counting控制器精确消费它自己发出的取消。resolve()中每次Task.cancel()都记账_issued捕获CancelledError后在外缘用Task.uncancel()精确消费同等数量镜像asyncio.timeout()的做法若此后Task.cancelling()仍为正说明外部取消竞速进来并获胜绝不翻译。仲裁刻意无基线baseline-free——在外部获胜方向上保守。注意Python 3.10 没有Task.cancelling()/Task.uncancel()无法消歧竞态此时请求的首方取消即使在同时有外部取消到达时也翻译为RunCancelled文档化的降级行为。bind()上的重新发号bind()在运行开始与每个步骤边界执行它把已发号计数钳制到任务当前的cancelling()若调用方 uncancel 过则接管了簿记并重新投递仍被请求的取消——这使首方取消对吞掉/uncancel 它的钩子或调用方保持粘性sticky无需在每个站点做cancel_requested检查。由不同任务手动驱动AgentRun.next()也能被正确取消。翻译边缘 finally 中的release_issued()任何退出路径包括非取消错误抢先于请求的取消都必须释放未解析的发号否则泄漏的Task.cancelling()计数会虚假地取消同一任务上后续无关工作污染asyncio.timeout()与 AnyIO 取消作用域的外层簿记。4.3 两层检查为何必须分离_utils.raise_if_cancelling()电平触发的外部后备与RunCancellation.cancel_requested首方终止性标志是刻意分离的两类检查——agent/init.py 的_finalize_result处注释说明合并它们会重新引入各自要捕获的吞掉取消缺陷。_finalize_result也确认首方取消请求即使钩子消耗了任务的取消计数仍然保持终止性越过raise_if_cancelling后备继续生效。五、测试形态用公开行为与快照锁定契约agent_docs/pydantic-ai-slim.md 的测试准则如下大多数测试使用公开的 agent/model/toolset 行为消息历史、事件流、provider 请求载荷与协议形状优先用快照snapshot断言行为依赖 provider API 或 SDK 时使用 provider cassette 或真实集成测试仓库的 cassettes 存放在 tests/cassettes 与 tests/models/cassettesdurable 运行时行为依赖序列化、重放或 activity/task 边界时使用工作流级测试如 tests/durable_exec 下的用例在用户发现功能的文档与示例处同步更新而不只是更新 docstring。六、给贡献者的实战检查单综合文档与源码在pydantic-ai-slim上做非平凡改动前请逐条核对新行为能否建模为 capability、toolset、model setting 或 profile 事实能则不新增Agent构造参数见 agent/init.py 的_prepare_run与_PreparedAgentRun装配逻辑provider 事实是否仍留在providers//profiles//模型适配器内未下沉到 graph/tool/output/UI涉及事件家族时新增事件类是否走注册表注册而非手工塞进联合并考虑event_registry_version()对记忆化消费者的影响改动工具/输出执行时是否同时验证顺序、重试、延迟调用、输出收尾、流式事件与 durable 包装器涉及取消时_issued计数、bind()钳制、release_issued()三处簿记是否完好两层取消检查是否保持分离持久化运行时Temporal/DBOS/Prefect/Restate 等的序列化、重放与 activity/task 边界是否受影响是否补充了工作流级测试移除废弃 API 时是否区分公开表面清理与已序列化历史兼容遵循这些边界与规则pydantic-ai-slim的改动就能保持其模块化架构的完整性——这正是每个模型、每个接口、端到端类型化这一项目定位的工程根基。【免费下载链接】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-slim 源码架构解析：Agent 运行图、事件流缓冲区与首方取消的底层实现
pydantic-ai-slim 源码架构解析Agent 运行图、事件流缓冲区与首方取消的底层实现【免费下载链接】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 Slimpydantic-ai-slim是 Pydantic AI 的核心逻辑包以最少依赖实现 Agent、模型、工具集、消息历史、流式输出、UI 适配器与持久化执行等全部核心能力。本指南以仓库内 agent_docs/pydantic-ai-slim.md 为主线结合pydantic_ai_slim/pydantic_ai/下的实际源码逐层拆解其模块职责边界、运行事件流Run Event Stream的内部缓冲区机制、以及首方取消First-Party Cancellation的仲裁原理帮助你理解在pydantic-ai-slim上做非平凡改动时应当遵守的兼容性约束与设计规则。读完后你将掌握这套代码库的骨架脉络知道改什么、在哪改、以及如何用测试验证改动。一、模块职责边界谁拥有什么pydantic-ai-slim的包体位于 pydantic_ai_slim/pydantic_ai核心设计原则是职责归属清晰、provider 事实不下沉。以下是从 agent_docs/pydantic-ai-slim.md 继承并对照源码展开的模块所有权划分模块职责Agentagent/init.py面向用户的构建与运行 API。Agent.iter()是图运行的入口门面_prepare_run()把每次运行的输入解析为私有的_PreparedAgentRun其open()负责资源进入、能力生命周期、恢复与清理。凡是能建模为 capability、toolset、model setting 或 profile 事实的行为不要新增构造参数_agent_graph.py循环编排提示词组装、模型请求、工具/输出处理、重试、用量检查与收尾tool_manager.py、tools.py、toolsets/工具发现、校验、执行、重试、审批/延迟、包装器组合与稳定的工具身份output.py/_output.py公开输出 API / 内部输出 schema、处理器、输出工具与输出校验messages.py规范化协议。provider 适配器、UI 适配器、持久化包装器与历史记录都应以该形态往返而不是把 provider 事实编码进字符串或临时字段models/把规范化请求/响应映射到 provider 线上格式providers/认证、客户端、base URL、HTTP 生命周期、provider 级模型/profile 推断profiles/模型家族事实结构化输出默认值、schema 怪癖、原生工具支持、thinking 支持、return-schema 支持、提示输出模板与模型家族固有行为capabilities/可组合的横切行为指令、设置、工具集、原生工具、包装工具集以及 run/model/tool/output/event/history 各类钩子durable_exec/把 agent、模型与工具集适配到持久化运行时。这些集成应被视为核心语义的兼容性测试而非外围适配器ui/把规范化消息/事件翻译为前端协议跨往返保留消息历史与事件语义为什么这样划分设计规则要求 provider 事实只放在providers/、profiles/与模型适配器中禁止在 graph、tool、output、UI 代码里散落按 provider 名称的 if 分支provider 特有数据应保存在结构化的 metadata/provider-details 字段中不得重载规范化 ID、文本内容或工具参数。优先用通用原语而非一次性标志横切行为用 capability工具集合行为用包装工具集能力事实用 profileprovider API 旋钮用类型化设置。本地工具与 provider 原生工具在概念上必须分离若某功能二者皆可需把回退/选择行为显式化并测试其产生的消息历史。二、兼容性清单动手前先确认哪些契约会变pydantic-ai-slim的改动往往横跨多个子系统agent_docs/pydantic-ai-slim.md 要求编辑前先识别以下可变化契约公开 API构造参数、装饰器、设置、输出类型、工具/toolset API、导入路径与文档化名称Provider API 兼容性请求参数、响应部件、流式分片、原生工具、结构化输出、thinking/reasoning、提示缓存、token 计数、用量与 provider 元数据消息/事件协议持久化消息历史、部分响应、工具调用部件、输出事件、原生工具部件、重试提示与 UI 事件流持久化执行上下文传播、依赖序列化、工具顺序、重试、消息重放、toolset 生命周期、activity/task 边界与确定性行为Agent 规范/配置新状态是否可序列化、可安全加载、能否不依赖运行时闭包来表达。移除废弃 API 时需区分两类兼容性公开表面的清理可在主版本中移除旧构造函数/导入但已序列化的历史消息可能仍需反序列化。改动工具/输出执行时要把顺序、重试语义、延迟调用、输出收尾、流式事件与 durable 包装器放在一起检查。三、运行事件流的内部机制event_stream_buffer与事件家族3.1 缓冲区是什么GraphAgentState.event_stream_buffer是运行作用域的内部队列用于承载在模型/工具事件生成器直接路径之外产生的框架事件。它通过引用被共享进本次运行的每一个RunContext作为私有的_event_stream_buffer字段见 pydantic_ai_slim/pydantic_ai/_run_context.py框架代码通过RunContext._emit_event(event)追加事件该方法断言缓冲区存在events are only emitted during an agent run, which has a buffer。缓冲区上的公共表面是RunContext.emit以及驱动agent.iter()的AgentRun.emit见 pydantic_ai_slim/pydantic_ai/run.py应用代码发射CustomEvent子类能力发射CapabilityEvent子类emit从钩子上下文的_capability或正在执行的ToolManager的tool_def.capability_id解析其归属能力——因此能力贡献的工具所发出的事件无需工具自身知晓即可正确归属。3.2 事件家族是开放家族靠注册表重建联合AgentStreamEvent联合是封闭的判别联合但CustomEvent/CapabilityEvent是开放家族子类在类定义时注册__init_subclass__AgentStreamEvent联合随后由这些注册表重建实现见 pydantic_ai_slim/pydantic_ai/_event_registry.py。未注册的 tag 不会导致校验失败而是降级为UnknownCustomEvent/UnknownCapabilityEvent信封把原始载荷放进data字段相关类型定义见 pydantic_ai_slim/pydantic_ai/messages.py 与 messages.py序列化时再展平data使下游若导入了定义模块即可恢复出类型化事件。两个容易踩坑的细节快照语义event_family_schema构建时快照注册表之后才注册的类会降级为 unknown 信封——这对构建一次即丢弃的 schema 是正确的但任何基于含AgentStreamEvent的 hint 做适配器记忆化memoize的消费者如 Temporal 的 payload converter必须用event_registry_version()作为缓存键因为联合的 choices 在 schema 构建时被快照注册表变更会递增版本号使旧适配器失效见EventRegistry的__setitem__/__delitem__/pop均会 bump 版本。重放隔离Temporal 这类 durable 运行时会在隔离的解释器视图里重执行应用模块产生与宿主进程同模块同 qualname的事件类重定义。set_replay_isolation_guard使重定义保留已注册类为家族规范类canonical实例经_canonicalize规范化为宿主类后再序列化保证两侧isinstance检查与on_event(MyEvent)过滤一致。3.3 事件如何送达dispatch 与 drain监听监听器在事件流位置被消费时运行唯一的例外是声明了dispatchimmediate的CapabilityEvent家族——它在emit返回前被派发使发射者能读到监听器设置的决策字段。派发前先咨询AbstractCapability.listens_to(event)见 pydantic_ai_slim/pydantic_ai/capabilities/abstract.py因此能力只在某个on_event监听器点名的事件类上被唤醒裸标记或直接覆写on_event()会拓宽到所有事件CombinedCapability/WrapperCapability报告其内部包含的联合。drain节点流负责把缓冲区排入wrap_run_event_stream/event_stream_handler。ModelRequestNode把该职责委托给AgentStream经_event_stream_buffer_getter见 pydantic_ai_slim/pydantic_ai/_agent_graph.py每次从模型流 pull 之前先 drain——pull 在途期间产生的事件在下次 pull 时浮出或模型流耗尽后经响应处理节点的流送达。CallToolsNode用_with_event_stream_buffer包装其 handle-response 事件迭代器见 pydantic_ai_slim/pydantic_ai/_agent_graph.py仅在节点流开始与结束时 drain末尾 drain 负责投递一步中最后一个模型/工具事件之后产生的事件。流存活期间事件经_iter_completed_or_buffered见 pydantic_ai_slim/pydantic_ai/_tool_execution.py与工具完成交错送达此处若再 drain可能把缓冲事件提到流即将投递的更早事件之前颠倒发射顺序。一个典型样例待处理消息pending messages遵循公开事件语义成立后才发射的模式——PendingMessageDrainCapability在每次 drain 的enqueue调用把消息送入历史时为该调用发射一个EnqueuedMessagesEvent一个调用可携带多条消息事件描述的是消息已按送达呈现刻意不携带索引因为_clean_message_history可能跨运行合并相邻请求使索引失效。3.4 不同持久化运行时下的事件语义emit的行为依赖持久化运行时的执行模型详见 pydantic_ai_slim/pydantic_ai/durable_exec/AGENTS.mdTemporal从工具或事件流处理器内emit会抛错——它们运行在无法触达缓冲区的 activity 中DBOS / Prefect缓冲区在进程内emit可用但在 durable 单元内发射的事件是运行它的副作用——被重放的步骤或命中的缓存任务不会重新发射该事件。四、首方取消的内部机制RunCancellation与三种关键簿记4.1 控制器形态_cancel.RunCancellation是运行作用域的首方取消控制器实现见 pydantic_ai_slim/pydantic_ai/_cancel.py持有于GraphAgentDeps.cancellation以引用方式共享进每个RunContext的私有_cancellation字段——与_event_stream_buffer一样遵守绝不 replace的不变式。首方取消AgentRun.cancel()、RunContext.cancel()通过取消驱动运行的 asyncio task 实现因此完整复用外部取消的拆除链路流被关闭、在途工具任务被取消并排空、挂起的服务端任务尽力取消、已完成工作写入消息历史在_PreparedAgentRun.open()退出栈的外缘_translate_cancellationCancelledError恰好被分类一次此时所有产生历史的拆除均已提交。CancellationToken是线程安全的取消句柄可同时传给多个并发运行cancel()幂等且可从任意线程调用在同一事件循环线程上同步投递否则经call_soon_threadsafe编排。4.2 三块承重的簿记文档明确点名以下三处簿记是承重的_agent_graph.py/run.py的改动极易破坏它们发号计数issuance counting控制器精确消费它自己发出的取消。resolve()中每次Task.cancel()都记账_issued捕获CancelledError后在外缘用Task.uncancel()精确消费同等数量镜像asyncio.timeout()的做法若此后Task.cancelling()仍为正说明外部取消竞速进来并获胜绝不翻译。仲裁刻意无基线baseline-free——在外部获胜方向上保守。注意Python 3.10 没有Task.cancelling()/Task.uncancel()无法消歧竞态此时请求的首方取消即使在同时有外部取消到达时也翻译为RunCancelled文档化的降级行为。bind()上的重新发号bind()在运行开始与每个步骤边界执行它把已发号计数钳制到任务当前的cancelling()若调用方 uncancel 过则接管了簿记并重新投递仍被请求的取消——这使首方取消对吞掉/uncancel 它的钩子或调用方保持粘性sticky无需在每个站点做cancel_requested检查。由不同任务手动驱动AgentRun.next()也能被正确取消。翻译边缘 finally 中的release_issued()任何退出路径包括非取消错误抢先于请求的取消都必须释放未解析的发号否则泄漏的Task.cancelling()计数会虚假地取消同一任务上后续无关工作污染asyncio.timeout()与 AnyIO 取消作用域的外层簿记。4.3 两层检查为何必须分离_utils.raise_if_cancelling()电平触发的外部后备与RunCancellation.cancel_requested首方终止性标志是刻意分离的两类检查——agent/init.py 的_finalize_result处注释说明合并它们会重新引入各自要捕获的吞掉取消缺陷。_finalize_result也确认首方取消请求即使钩子消耗了任务的取消计数仍然保持终止性越过raise_if_cancelling后备继续生效。五、测试形态用公开行为与快照锁定契约agent_docs/pydantic-ai-slim.md 的测试准则如下大多数测试使用公开的 agent/model/toolset 行为消息历史、事件流、provider 请求载荷与协议形状优先用快照snapshot断言行为依赖 provider API 或 SDK 时使用 provider cassette 或真实集成测试仓库的 cassettes 存放在 tests/cassettes 与 tests/models/cassettesdurable 运行时行为依赖序列化、重放或 activity/task 边界时使用工作流级测试如 tests/durable_exec 下的用例在用户发现功能的文档与示例处同步更新而不只是更新 docstring。六、给贡献者的实战检查单综合文档与源码在pydantic-ai-slim上做非平凡改动前请逐条核对新行为能否建模为 capability、toolset、model setting 或 profile 事实能则不新增Agent构造参数见 agent/init.py 的_prepare_run与_PreparedAgentRun装配逻辑provider 事实是否仍留在providers//profiles//模型适配器内未下沉到 graph/tool/output/UI涉及事件家族时新增事件类是否走注册表注册而非手工塞进联合并考虑event_registry_version()对记忆化消费者的影响改动工具/输出执行时是否同时验证顺序、重试、延迟调用、输出收尾、流式事件与 durable 包装器涉及取消时_issued计数、bind()钳制、release_issued()三处簿记是否完好两层取消检查是否保持分离持久化运行时Temporal/DBOS/Prefect/Restate 等的序列化、重放与 activity/task 边界是否受影响是否补充了工作流级测试移除废弃 API 时是否区分公开表面清理与已序列化历史兼容遵循这些边界与规则pydantic-ai-slim的改动就能保持其模块化架构的完整性——这正是每个模型、每个接口、端到端类型化这一项目定位的工程根基。【免费下载链接】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），仅供参考