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

原创2026-09-26 15:44:271,822 阅读
文章标签:人工智能AI AgentAgent 框架工具调用MCP 服务大模型多智能体CLI

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

导读

本文以 Python SDK v1.28.0 变更日志(2026-02-25 发布)为主线,深入讲解该版本为 strands-agents Python SDK 带来的三组核心变化:全新的 Plugin 插件扩展体系(@hook/@tool 装饰器自动注册 + init_agent 初始化钩子)、add_hook 对联合类型与事件类型列表的支持(一个回调同时订阅多个生命周期事件)、以及 PyAudio 改为可选依赖(懒加载)与 Python 3.14 兼容性调整。通过结合 strands-py 下的源码实现与配置,你将能直接上手用 v1.28.0 的插件机制改造自己的 Agent,并理解其底层注册与分发原理。

说明:本文以仓库内该版本的发布记录为事实骨架,所有配置、API 与行为细节均对照 strands-py 当前源码进行印证,适用版本为 strands-agents 1.28.0。

版本概况:一次聚焦扩展性与安装体验的迭代

v1.28.0 共收录 10 条变更,全部为非破坏性(breaking: false),主要分布在 hooks、plugins、agent、steering、model 等领域。快速总览如下:

类型 变更内容 主要影响面
feat add_hook 支持联合类型与事件类型列表 hooks
feat 新增 Plugin Protocol 用于 Agent 扩展 plugins / agent
feat Agent 构造函数新增 plugins 参数 agent
refactor Plugin 由 Protocol 改为 ABC(抽象基类) plugins
feat SteeringHandler 从 HookProvider 迁移到 Plugin steering
feat PyAudio 改为可选依赖(懒加载) 安装 / bidi 音频
fix 移除在 Python 3.14 下失败的测试 兼容性
fix 更新 agentcore 新账号 region 基础设施
chore Anthropic 集成测试切换到 Sonnet 4.6 测试
chore init_plugin 更名为 init_agent API 命名

其中,最值得关注的是插件体系的落地——它把「钩子 + 工具 + 初始化逻辑」打包成可复用的组合单元,直接改变 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)、随后重构为 ABC(PR 1741)」的过程;ABC 方案使得插件可以持有实例状态、走标准初始化流程,并为后续 MultiAgentPlugin(见 strands-py/src/strands/plugins/multiagent_plugin.py)预留了多智能体编排的扩展空间。

推荐用法:用装饰器自动注册

插件最简洁的写法是利用 @hook 与 @tool 装饰器(两者从 strands-py/src/strands/plugins/init.py 导出),无需手工逐条注册。官方示例见 plugin.py:

from 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(f"Model called: {event}")

    @tool
    def my_tool(self, param: str) -> str:
        """A tool that does something."""
        return f"Result: {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_agent(PR 1765):

class 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_callback:

1) 从类型注解推断(event_type=None)

def log_model_call(event: BeforeModelCallEvent) -> None:
    print(f"Calling 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(f"Event: {type(event).__name__}")

agent.add_hook(log_event)

也可以传入事件类型列表,对同一回调注册到多个事件:

def multi_handler(event):
    print(f"Event: {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 -100 SDK 内部最先执行的逻辑
INTERVENTION_OUTPUT -90 干预输出阶段
DEFAULT 0 用户钩子默认优先级
MODEL_ROUTING 50 模型路由
INTERVENTION_INPUT 90 干预输入阶段
SDK_LAST 100 SDK 内部最后执行的逻辑

Agent.add_hook(见 agent.py)把 order 参数透传给 HookRegistry。另外两点需注意:

  • AgentInitializedEvent 只能注册同步回调,注册异步回调会抛出 ValueError(见 registry.py);
  • AfterInvocationEvent 这类清理型事件设置了 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 = ["pyaudio>=0.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<a href="https://link.gitcode.com/i/565a0e98973e546b3b4ea71a18e5873f" target="_blank">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 迁移到 Plugin(PR 1738),即引导(steering)能力现在以插件形态交付,与新的插件体系对齐;
  • Anthropic 提供方的集成测试模型切换为 Sonnet 4.6(PR 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(f"start request, messages={event.messages}")

    @tool
    def audit_note(self, note: str) -> str:
        """Record an audit note into the conversation."""
        return f"audited: {note}"

agent = Agent(model="...", plugins=[AuditPlugin()])

方式三:带初始化逻辑的插件

需要访问已构建完成的 Agent 实例(注册动态回调、校验配置等)时覆写 init_agent,可同步可异步。

结语与验证线索

v1.28.0 的核心价值在于:把「钩子 + 工具 + 初始化」统一成 Plugin 这一组合单元,并让钩子订阅从「一回调一事件」升级为「联合类型/列表一次订阅多个事件」,同时通过 PyAudio 懒加载降低了安装门槛。这三项能力在仓库源码中均有完整实现可查:

你可以基于以上路径自行验证:安装 strands-agents 后,用 @hook/@tool 编写一个自定义插件,再分别测试联合类型注册、init_agent 异步实现,以及 strands-agents[bidi-pyaudio] 与默认安装的差异,即可完整复现本版本的每一项增强。

登录后查看全文
harness-sdk