Strands SDK Python v1.28.0 发布解读：Plugin 插件体系、add_hook 联合类型支持与依赖精简

人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载导读本文以 Python SDK v1.28.0 变更日志2026-02-25 发布为主线深入讲解该版本为strands-agentsPython SDK 带来的三组核心变化全新的Plugin 插件扩展体系hook/tool装饰器自动注册 init_agent初始化钩子、add_hook对联合类型与事件类型列表的支持一个回调同时订阅多个生命周期事件、以及PyAudio 改为可选依赖懒加载与 Python 3.14 兼容性调整。通过结合 strands-py 下的源码实现与配置你将能直接上手用 v1.28.0 的插件机制改造自己的 Agent并理解其底层注册与分发原理。说明本文以仓库内该版本的发布记录为事实骨架所有配置、API 与行为细节均对照 strands-py 当前源码进行印证适用版本为strands-agents1.28.0。版本概况一次聚焦扩展性与安装体验的迭代v1.28.0 共收录 10 条变更全部为非破坏性breaking: false主要分布在 hooks、plugins、agent、steering、model 等领域。快速总览如下类型变更内容主要影响面featadd_hook支持联合类型与事件类型列表hooksfeat新增 Plugin Protocol 用于 Agent 扩展plugins / agentfeatAgent构造函数新增plugins参数agentrefactorPlugin 由 Protocol 改为 ABC抽象基类pluginsfeatSteeringHandler 从 HookProvider 迁移到 PluginsteeringfeatPyAudio 改为可选依赖懒加载安装 / bidi 音频fix移除在 Python 3.14 下失败的测试兼容性fix更新 agentcore 新账号 region基础设施choreAnthropic 集成测试切换到 Sonnet 4.6测试choreinit_plugin更名为init_agentAPI 命名其中最值得关注的是插件体系的落地——它把「钩子 工具 初始化逻辑」打包成可复用的组合单元直接改变 Agent 扩展的编写方式。插件体系从 HookProvider 到 Plugin 的演进插件是什么v1.28.0 之前的扩展方式主要依赖HookProvider见 strands-py/src/strands/hooks/registry.py 中的register_hooks协议它只能注册钩子。v1.28.0 引入的Plugin在此基础上更进一步一个插件可以同时携带钩子回调、工具和自定义初始化逻辑并以name作为稳定标识符。在 strands-py/src/strands/plugins/plugin.py 中Plugin被定义为抽象基类ABC要求子类必须提供name属性from abc import ABC, abstractmethod class Plugin(ABC): property abstractmethod def name(self) - str: A stable string identifier for the plugin. ...从源码结构看v1.28.0 经历了「先以 Protocol 定义PR 1733、随后重构为 ABCPR 1741」的过程ABC 方案使得插件可以持有实例状态、走标准初始化流程并为后续MultiAgentPlugin见 strands-py/src/strands/plugins/multiagent_plugin.py预留了多智能体编排的扩展空间。推荐用法用装饰器自动注册插件最简洁的写法是利用hook与tool装饰器两者从 strands-py/src/strands/plugins/init.py 导出无需手工逐条注册。官方示例见 plugin.pyfrom strands.plugins import Plugin, hook from strands.hooks import BeforeModelCallEvent from strands import tool class MyPlugin(Plugin): name my-plugin hook def on_model_call(self, event: BeforeModelCallEvent): print(fModel called: {event}) tool def my_tool(self, param: str) - str: A tool that does something. return fResult: {param}hook装饰器见 strands-py/src/strands/plugins/decorator.py在装饰时通过infer_event_types从回调第一个参数的类型注解推断事件类型并把结果以_hook_event_types元数据挂在函数上因此hook与hook()两种写法都可用。若无法从类型注解推断会抛出ValueError提示显式指定事件类型。实例化插件时Plugin.init会调用 discover_hooks / discover_tools 扫描类的 MRO自动收集所有被装饰的方法并存入_hooks、_tools。这里有几个值得注意的细节父类方法先于子类方法注册按 MRO 逆序扫描若子类覆盖了父类的被装饰方法只注册子类版本使用多重继承如同时继承Plugin与MultiAgentPlugin时通过hasattr守卫避免重复发现。自定义初始化init_agent如果插件需要在 Agent 构建完成后执行额外逻辑如注册动态钩子、校验策略、附加中间件可以覆写init_agent方法见 plugin.py。注意 v1.28.0 中该方法已由init_plugin更名为init_agentPR 1765class MyPlugin(Plugin): name my-plugin def init_agent(self, agent: Agent) - None: # 自定义初始化逻辑无需调用 super() # 被装饰的 hook/tool 已由插件注册表自动注册 agent.add_hook(self.custom_hook) def custom_hook(self, event: BeforeModelCallEvent): print(event)init_agent同时支持同步与异步实现在 strands-py/src/strands/plugins/_discovery.py 的call_init_method中如果发现方法是协程函数会通过run_async执行。仓库中_context_manager、_agent_delegation、background_tasks等内置模块都采用了「实现init_agent注册钩子/中间件」的同一模式可见这是插件与内部组件共享的初始化入口。挂载插件Agent 的 plugins 参数v1.28.0 在Agent构造函数中新增了plugins参数PR 1734。在 strands-py/src/strands/agent/agent.py 中可以看到它与其他扩展点并列agent Agent( model..., plugins[MyPlugin()], # v1.28.0 新增 hooks[...], # 原有的 HookProvider / HookCallback interventions[...], # 干预处理器 session_manager..., )一个 Agent 可同时挂载多个插件也可以与既有的hooks、interventions混用插件内部自动发现的钩子与工具会由插件注册表统一注册到 Agent 上。add_hook 增强联合类型与事件类型列表三种注册形态v1.28.0 让Agent.add_hook支持三种调用形态PR 1719核心实现位于 strands-py/src/strands/hooks/registry.py 的HookRegistry.add_callback1) 从类型注解推断event_typeNonedef log_model_call(event: BeforeModelCallEvent) - None: print(fCalling model for agent: {event.agent.name}) agent.add_hook(log_model_call)2) 显式指定单一事件类型agent.add_hook(log_model_call, BeforeModelCallEvent)3) 联合类型注解v1.28.0 新增——一个回调同时订阅多个事件def log_event(event: BeforeModelCallEvent | AfterModelCallEvent) - None: print(fEvent: {type(event).__name__}) agent.add_hook(log_event)也可以传入事件类型列表对同一回调注册到多个事件def multi_handler(event): print(fEvent: {type(event).__name__}) agent.add_hook(multi_handler, [BeforeModelCallEvent, AfterModelCallEvent])底层推断逻辑联合类型与列表展开的实现位于 strands-py/src/strands/hooks/_type_inference.py通过get_type_hints读取回调第一个参数的类型注解自动跳过self/cls若注解是联合类型A | B或Union[A, B]会逐个展开并校验每个成员必须是BaseHookEvent子类联合中出现None会被拒绝None is not a valid event type in union注册时会对事件类型去重保留顺序空列表会抛出ValueError。在registry.py的add_callback中最终每个事件类型都会被bisect.insort按order值插入到有序回调列表中同一优先级内保持注册顺序。因此联合类型回调在不同事件上的执行顺序由各事件自身的优先级队列决定。事件类型与执行顺序钩子事件定义于 strands-py/src/strands/hooks/events.py例如AgentInitializedEvent、BeforeInvocationEvent、AfterInvocationEvent、MessageAddedEvent、BeforeModelCallEvent、AfterModelCallEvent等覆盖请求开始、消息写入、模型调用、结果返回等生命周期节点。执行顺序通过 HookOrder 常量控制数值越小越先执行常量值用途SDK_FIRST-100SDK 内部最先执行的逻辑INTERVENTION_OUTPUT-90干预输出阶段DEFAULT0用户钩子默认优先级MODEL_ROUTING50模型路由INTERVENTION_INPUT90干预输入阶段SDK_LAST100SDK 内部最后执行的逻辑Agent.add_hook见 agent.py把order参数透传给HookRegistry。另外两点需注意AgentInitializedEvent只能注册同步回调注册异步回调会抛出ValueError见 registry.pyAfterInvocationEvent这类清理型事件设置了should_reverse_callbacks True同一优先级内按注册顺序逆序执行见 registry.py。同步/异步回调都可以注册若通过invoke_callbacks同步路径调用而存在异步回调会抛出RuntimeError提示改用invoke_callbacks_async。依赖与兼容性调整PyAudio 改为可选依赖懒加载v1.28.0 将 PyAudio 从硬依赖中移除改为按需导入PR 1731。PyAudio 的 C 依赖 PortAudio 需要系统级安装因此被排除在聚合 extras 之外——在 strands-py/pyproject.toml 的[project.optional-dependencies]中# Excluded from aggregate extras because PyAudio requires PortAudio as a system level install. bidi-pyaudio [pyaudio0.2.0,0.3.0] bidi-all [strands-agents[a2a,bidi,bidi-aec,bidi-google,bidi-io,bidi-openai,docs,otel]]即bidi-all不包含bidi-pyaudio需要音频输入输出功能时需显式安装strands-agents[bidi-pyaudio]。源码中音频 I/O 模块 strands-py/src/strands/experimental/bidi/io/audio.py 通过顶层import pyaudio实现懒加载仅在真正使用麦克风/扬声器设备时才触发导入bidi-aec回声消除与bidi-pyaudio分开配置说明音频链路可按需组合。对普通用户而言默认安装不再背负 PyAudio 的编译/系统依赖负担安装体积与失败率都会下降对语音类应用开发者则需按上面方式显式安装对应 extras。Python 3.14 兼容性该版本同时移除了一个在 Python 3.14 下失败的测试PR 1717并已在pyproject.toml中注明 litellm v1.92.0 暂不支持 Python 3.14 的限制。也就是说v1.28.0 对 Python 3.14 采取了「主流程可用、个别第三方依赖仍需等待上游跟进」的姿态升级到 3.14 前建议先确认所依赖的模型提供方 extra 是否已适配。SteeringHandler 迁移与其余变更SteeringHandler从HookProvider迁移到PluginPR 1738即引导steering能力现在以插件形态交付与新的插件体系对齐Anthropic 提供方的集成测试模型切换为 Sonnet 4.6PR 1754属于测试基础设施变更不影响 API一条针对 agentcore 新账号 region 的修复PR 1715属于基础设施内部调整。从 v1.28.0 上手的三种落地方式方式一纯钩子扩展无插件如果只是给现有 Agent 加日志或校验联合类型注册让代码更紧凑from strands import Agent from strands.hooks import BeforeModelCallEvent, AfterModelCallEvent agent Agent(model...) def trace_models(event: BeforeModelCallEvent | AfterModelCallEvent) - None: phase before if isinstance(event, BeforeModelCallEvent) else after print(f[{phase}] model call for agent{event.agent.name}) agent.add_hook(trace_models) # 联合类型自动展开注册方式二插件打包钩子 工具把相关扩展点打包为可复用单元跨 Agent 共享from strands import Agent, tool from strands.plugins import Plugin, hook from strands.hooks import BeforeInvocationEvent class AuditPlugin(Plugin): name audit hook def log_request(self, event: BeforeInvocationEvent) - None: print(fstart request, messages{event.messages}) tool def audit_note(self, note: str) - str: Record an audit note into the conversation. return faudited: {note} agent Agent(model..., plugins[AuditPlugin()])方式三带初始化逻辑的插件需要访问已构建完成的 Agent 实例注册动态回调、校验配置等时覆写init_agent可同步可异步。结语与验证线索v1.28.0 的核心价值在于把「钩子 工具 初始化」统一成 Plugin 这一组合单元并让钩子订阅从「一回调一事件」升级为「联合类型/列表一次订阅多个事件」同时通过 PyAudio 懒加载降低了安装门槛。这三项能力在仓库源码中均有完整实现可查插件基类与装饰器strands-py/src/strands/plugins/plugin.py、strands-py/src/strands/plugins/decorator.py自动发现与初始化strands-py/src/strands/plugins/_discovery.py钩子注册与分发strands-py/src/strands/hooks/registry.py、strands-py/src/strands/hooks/_type_inference.py事件定义strands-py/src/strands/hooks/events.py依赖声明strands-py/pyproject.toml。你可以基于以上路径自行验证安装strands-agents后用hook/tool编写一个自定义插件再分别测试联合类型注册、init_agent异步实现以及strands-agents[bidi-pyaudio]与默认安装的差异即可完整复现本版本的每一项增强。赞分享人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载相关推荐Apache DolphinScheduler 项目级别参数作用域、创建与任务使用实战指南Apache DolphinScheduler 项目级别参数作用域、创建与任务使用实战指南 本文以 Apache DolphinScheduler 的 项目级人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务flipper-plugin 插件 SDK 深度指南Flipper 现代插件的开发依赖、运行时 API 与测试体系flipper plugin 插件 SDK 深度指南Flipper 现代插件的开发依赖、运行时 API 与测试体系 导读 flipper plugin 是 F开发工具调试器移动开发前端为什么你的Godot游戏节点之间沟通不畅信号机制快速上手指南为什么你的Godot游戏节点之间沟通不畅信号机制快速上手指南 当你在用 Godot Engine 开发游戏时是否遇到过这样的困境子弹击中了敌人但计分板毫人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考