openJiuwen agent-core 异步回调框架 AsyncCallbackFramework 完全指南:事件驱动、过滤熔断、链式回滚与 I/O 变换

原创2026-10-11 11:14:491,434 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 编排多智能体工作流自动化RAGEmbeddingRerank向量数据库MCP 服务提示工程可观测性后端

openJiuwen agent-core 异步回调框架 AsyncCallbackFramework 完全指南:事件驱动、过滤熔断、链式回滚与 I/O 变换

openjiuwen.core.runner.callback.framework.AsyncCallbackFramework 是 openJiuwen agent-core 中面向 asyncio 的生产级异步回调框架,为 Agent 运行时(Runner)与业务代码提供事件注册、优先级执行、多级过滤、链式执行与回滚、性能指标与生命周期钩子等能力。读完本文,你将掌握该框架的全部 API 用法:既能用 @on 等装饰器快速接入事件,也能用 8 种触发模式编排并发、超时、流式与生成器聚合流程,还能通过 transform 管道全局拦截 Tool / LLM / Workflow 的入参与返回值,构建可观测、可回滚、可治理的 Agent 运行管线。

框架定位与核心能力

异步回调框架是 openJiuwen 中事件驱动机制的中枢。Runner 在初始化时即创建框架实例,并通过 Runner.callback_framework 暴露给上层使用;不依赖 Runner 时也可以直接实例化 AsyncCallbackFramework 独立运行。

框架的核心能力包括:

  • 异步优先:所有操作(注册、触发、过滤、回滚)均基于 asyncio 实现,天然支持高并发;
  • 优先级执行:priority 数值越大越先执行,便于安排鉴权、校验等关键步骤与通知、统计等辅助步骤;
  • 三级过滤系统:全局 / 事件 / 回调三级过滤器,内置限流、熔断、鉴权、校验等 8 种过滤器,支持自定义;
  • 回调链与回滚:trigger_chain 按优先级顺序执行并把上一步结果传给下一步,任一步失败可按逆序调用已注册的 rollback_handler;
  • 多种触发模式:顺序、并行、条件、超时、延迟、流式、生成器聚合等 8 种触发方式;
  • 装饰器生态:@on 注册以及 trigger_on_call、emits、emit_around、emits_stream、transform_io 等自动触发与 I/O 变换装饰器;
  • 性能监控:调用次数、平均/最慢耗时、错误率等指标,以及慢回调排查能力;
  • 生命周期钩子:BEFORE / AFTER / ERROR / CLEANUP 四种钩子;
  • 事件历史与重放:可记录事件触发历史并支持按时间重放;
  • 异步生成器支持:流式输入(trigger_stream)、流式/多源聚合输出(trigger_generator、emits_stream)。

从源码结构看,框架代码位于 openjiuwen/core/runner/callback/ 目录,各模块职责清晰:framework.py 为核心类实现,decorator.py 承载全部装饰器逻辑,enums.py 定义 FilterAction、ChainAction、HookType,models.py 定义 CallbackMetrics、FilterResult、ChainContext、ChainResult、CallbackInfo 等数据模型,filters.py 实现内置过滤器,chain.py 实现回调链与回滚,events.py 定义 Agent / Tool / LLM / Workflow 等预置事件名,utils.py 提供框架单例的简化访问。

快速开始

通过 Runner 使用回调框架(Runner 实例内部即持有框架实例,见 runner.py 中 callback_framework 属性):

import asyncio
from openjiuwen.core.runner import Runner

framework = Runner.callback_framework

@framework.on("user_login", priority=10)
async def send_welcome(username: str):
    print(f"Sending welcome to {username}")
    return f"welcome_{username}"

async def main():
    results = await framework.trigger("user_login", username="alice")
    print(results)  # ['welcome_alice']

asyncio.run(main())

不依赖 Runner 时,可单独创建框架实例:

from openjiuwen.core.runner.callback import AsyncCallbackFramework

framework = AsyncCallbackFramework(enable_metrics=True)
@framework.on("my_event", priority=5)
async def handler(x: int):
    return x * 2

results = await framework.trigger("my_event", 3)  # [6]

框架构造函数签名与参数如下:

class AsyncCallbackFramework(enable_metrics: bool = True, enable_logging: bool = True)
参数 类型 默认值 说明
enable_metrics bool True 是否收集回调性能指标(调用次数、耗时、错误率等)
enable_logging bool True 是否输出注册、触发、错误等日志

框架初始化时即建立如下只读视图属性,可在运行时检查注册状态:

  • callbacks -> Dict[str, List[CallbackInfo]]:事件名到回调信息列表的映射;
  • chains -> Dict[str, CallbackChain]:事件名到回调链的映射;
  • circuit_breakers -> Dict[str, CircuitBreakerFilter]:熔断器 key 到实例的映射(key 格式为 事件名:回调名);
  • callback_filters -> Dict[Callable, List[EventFilter]]:回调到其专属过滤器列表的映射。

事件、回调与优先级

框架的基本抽象是 事件 与 回调:

  • 事件:字符串标识(如 "user_login"、"order.created"),用于绑定一组回调。建议使用有语义的点分形式(如 user.login、order.created),避免 event1、do_something 等泛用名;
  • 回调:异步函数,在事件触发时按优先级执行;同一事件可注册多个回调;
  • 优先级:priority=N 中 N 越大越先执行,未指定时默认为 0。register_sync 在注册后即对回调列表按 priority 降序排序(见 framework.py)。

框架还提供了预置的标准事件名,定义在 events.py,按 Agent / Tool / LLM / Workflow / Context / Session / Memory / Retrieval / TaskManager 等类别组织,例如 AgentEvents.AGENT_STARTED、ToolCallEvents.TOOL_INVOKE_INPUT、LLMCallEvents.LLM_INVOKE_OUTPUT、WorkflowEvents.WORKFLOW_STARTED 等。事件名支持 scope:event_name 的作用域分隔格式,未指定作用域时默认使用 _framework。

注册回调:装饰器方式

@framework.on:普通事件回调

on 是核心注册装饰器,用于注册普通事件回调,支持所有触发模式:

def on(
    self,
    event: str,
    *,
    priority: int = 0,
    once: bool = False,
    namespace: str = "default",
    tags: Optional[Set[str]] = None,
    filters: Optional[List[EventFilter]] = None,
    max_retries: int = 0,
    retry_delay: float = 0.0,
    timeout: Optional[float] = None,
    callback_type: str = ""
)
参数 默认值 说明
event 必填 事件名,用于绑定回调函数
priority 0 执行优先级,数值越大越先执行
once False 是否仅执行一次,执行后自动禁用该回调
namespace "default" 命名空间,用于分组管理回调
tags None 标签集合(如 {"user", "login"}),用于分类和批量管理
filters None 该回调专属过滤器,仅对该回调生效
max_retries 0 最大重试次数(回调链场景下生效)
retry_delay 0.0 重试间隔(秒)
timeout None 单次执行超时(秒)
callback_type "" 语义类型标记,如 "transform"、"chain"

使用示例:

@framework.on("user_login", priority=10, once=False, namespace="auth", tags={"user", "login"})
async def handle_login(username: str, **kwargs):
    print(f"User {username} logged in")
    return f"welcome_{username}"

从源码实现看,on 委托给 create_on_decorator(decorator.py):它通过 framework.register_sync 完成同步注册,并返回一个 @wraps 包装的异步 wrapper,该 wrapper 记录了 callback_info.wrapper,因此 unregister 时既可以传入原始函数,也可以传入装饰器返回的包装函数。

@framework.on_transform:transform 类型回调

on_transform 是注册 transform 类型回调的便捷方式,等价于 on(event, callback_type="transform", priority=priority):

def on_transform(self, event: str, *, priority: int = 0)

此类回调仅被 trigger_transform 和 transform_io 的事件模式触发;普通 trigger 不会调用。在 trigger 的执行循环中,callback_type == "transform" 的回调会被直接跳过(见 framework.py 中 trigger 的实现)。示例:

@framework.on_transform(ToolCallEvents.TOOL_INVOKE_INPUT)
async def preprocess(inputs, **kwargs):
    return ((modified_inputs,), kwargs)

@framework.on_chain:回调链专用

on_chain 专门用于注册回调链的回调。与 on() 类似,但自动设置 filters=None(回调链不支持过滤器),更适合配置回滚与错误处理函数:

def on_chain(
    self,
    event: str,
    *,
    priority: int = 0,
    once: bool = False,
    namespace: str = "default",
    tags: Optional[Set[str]] = None,
    rollback_handler: Optional[Callable] = None,
    error_handler: Optional[Callable] = None,
    max_retries: int = 0,
    retry_delay: float = 0.0,
    timeout: Optional[float] = None,
    callback_type: str = ""
)
参数 默认值 说明
rollback_handler None 回滚处理函数,链执行失败时按执行顺序的逆序调用(仅回调链中有效)
error_handler None 错误处理函数,回调执行出错时调用(仅回调链中有效)

当提供了 rollback_handler 或 error_handler 时,register_sync 会自动为该事件创建 CallbackChain 并把回调及其处理器加入链中(见 framework.py 的 register_sync)。示例:

@framework.on_chain("order_process", priority=30, rollback_handler=rollback_payment)
async def process_payment(order: dict, **kwargs):
    order["paid"] = True
    return ChainResult(ChainAction.CONTINUE, result=order)

@framework.on_chain("order_process", priority=20, rollback_handler=rollback_inventory)
async def reserve_inventory(order: dict, **kwargs):
    if order.get("quantity", 0) > 100:
        return ChainResult(ChainAction.ROLLBACK, error=Exception("库存不足"))
    order["reserved"] = True
    return ChainResult(ChainAction.CONTINUE, result=order)

动态注册与注销回调

register:编程式注册

除装饰器外,可在运行时通过 register 动态注册回调,适用于配置驱动、插件扩展、按条件启用等场景:

async def register(
    self,
    event: str,
    callback: Callable[..., Awaitable[Any]],
    *,
    priority: int = 0,
    once: bool = False,
    namespace: str = "default",
    tags: Optional[Set[str]] = None,
    filters: Optional[List[EventFilter]] = None,
    rollback_handler: Optional[Callable] = None,
    error_handler: Optional[Callable] = None,
    max_retries: int = 0,
    retry_delay: float = 0.0,
    timeout: Optional[float] = None
) -> None

参数含义与 on 装饰器一致。register 内部通过 self._locks["registration"] 异步锁保护注册操作,并复用 register_sync 完成实际注册,保证并发注册的安全性。示例:

await framework.register(
    "user_signup",
    notify_email,
    priority=20,
    namespace="channels",
    tags={"email"},
)

注意:当前版本中,filters 参数在使用 trigger_chain 触发事件时不会生效;rollback_handler 与 error_handler 参数仅在使用 trigger_chain 触发事件时生效。

注销方式

框架提供四类注销操作,均通过异步锁保护:

  • unregister(event, callback) -> None:从事件上注销单个回调,支持传入原始回调或 @on 返回的包装函数(内部按「原始函数匹配 → 包装函数匹配 → __wrapped__ 指向原始函数」三种方式查找,见 framework.py 的 unregister_sync);
  • unregister_namespace(namespace) -> None:注销指定命名空间下的所有回调;
  • unregister_by_tags(tags) -> None:注销带有给定标签中任意一个的回调(标签集合求交集判断);
  • unregister_event(event) -> None:注销某事件的全部回调,并移除该事件关联的过滤器、链、钩子和熔断器。
await framework.unregister("temp_event", my_async_handler)   # 单个
await framework.unregister_namespace("temp")                 # 按命名空间整批收回
await framework.unregister_by_tags({"temporary"})            # 按标签收回
await framework.unregister_event("temp_event")               # 整事件清理

触发模式:8 种事件执行方式

框架通过 trigger 系列方法提供多种触发方式,覆盖顺序、并行、条件、超时、延迟、链式、流式与生成器聚合场景。

方法 说明 适用场景
trigger 按优先级顺序执行,收集所有结果 默认方式,有依赖或需顺序时
trigger_parallel 并发执行(asyncio.gather) 多路拉取、并行请求等 I/O 密集场景
trigger_until 按顺序执行,直到某回调返回值使 condition(result) 为 True 即返回 降级、首选/备选
trigger_chain 链式执行,上一步结果传下一步,支持回滚 订单/支付等事务流程
trigger_with_timeout 在给定总时间内执行,超时返回已收集结果 控制最大耗时、SLA
trigger_delayed 延迟指定秒数后执行 定时、延迟任务
trigger_stream 对异步输入流逐项触发事件并流式产出结果 大文件、日志流、传感器数据
trigger_generator 聚合各回调的异步生成器或普通返回值并逐项 yield 多源数据聚合、流式 API

trigger:顺序触发

async def trigger(self, event: str, *args, **kwargs) -> List[Any]

按优先级顺序执行所有已注册回调(经过滤、指标与钩子),返回所有被执行回调的返回值列表。底层执行流程(对应 framework.py 的 trigger 实现):

  1. 若开启事件历史,记录 {"event", "args", "kwargs", "timestamp"};
  2. 执行 BEFORE 钩子;
  3. 遍历该事件回调(callback_type == "transform" 的跳过),未启用则跳过;
  4. 依次经过全局过滤器 → 事件过滤器 → 该回调专属过滤器:STOP 停止整次触发,SKIP 跳过当前回调,MODIFY 用新参数继续;
  5. 通过 _narrow_call 按函数签名裁剪多余参数,并通过 _inject_session_if_needed 为需要 session 参数的回调自动注入当前会话(来自 openjiuwen.core.session.get_current_session);
  6. 执行回调并收集结果;回调返回异步生成器时不 await,直接作为结果返回;once=True 的回调执行后自动禁用;
  7. 单回调抛错不中断整次触发:记录指标、执行 ERROR 钩子后继续处理后续回调(AbortError 则会中止并向上抛出);
  8. 全部完成后执行 AFTER 钩子,最后输出整条回调链的耗时拆分日志([RailChain],慢回调超过 1.0 秒会以 INFO 单独上报)。

trigger_parallel:并行触发

async def trigger_parallel(self, event: str, *args, **kwargs) -> List[Any]

使用 asyncio.gather 并发执行所有回调,适用于 I/O 密集型场景(多路请求、数据库查询等)。每个回调独立应用过滤器与超时(anyio.fail_after);失败的执行被记录日志并排除在返回结果之外。典型场景下并行可比顺序快约 2~4 倍(例如 3 个 0.15s 的 I/O 回调:顺序约 0.45s,并行约 0.2s)。

trigger_until:条件触发

async def trigger_until(
    self,
    event: str,
    condition: Callable[[Any], bool],
    *args,
    **kwargs
) -> Optional[Any]

按优先级依次执行回调,直到某个返回值使 condition(result) 为 True 则停止并返回该结果;若无满足条件的结果返回 None。可用于首选/备选降级逻辑。

trigger_chain:链式执行与回滚

async def trigger_chain(self, event: str, *args, **kwargs) -> ChainResult

按链方式触发:按优先级顺序执行回调,将上一回调的返回值作为下一回调的第一个位置参数,其余 initial_kwargs 不变;链中可通过 kwargs["_chain_context"] 访问 ChainContext(如 get_last_result()、set_metadata()、get_metadata())。返回 ChainResult,包含最终动作、结果、上下文及可能的异常。

实现上,若该事件已有 CallbackChain(注册 on_chain 回调时创建)则直接复用,否则临时为事件下所有回调构建链(见 framework.py 的 trigger_chain)。链的执行逻辑位于 chain.py:每个回调可返回 ChainResult:

  • ChainResult(ChainAction.CONTINUE, result=...):继续下一回调;
  • ChainResult(ChainAction.BREAK, result=...):中断链并返回当前结果;
  • ChainResult(ChainAction.RETRY, ...):重试当前回调;
  • ChainResult(ChainAction.ROLLBACK, error=...):回滚所有已执行回调。

一旦返回 ROLLBACK 或回调抛错(且重试次数用尽),框架按执行顺序的逆序调用已执行回调注册的 rollback_handler(用于退款、恢复库存、释放资源等),并在 ChainContext 上标记 is_rolled_back = True。回调超时(timeout 参数)同样触发回滚。完整示例:

from openjiuwen.core.runner import Runner
from openjiuwen.core.runner.callback import ChainAction, ChainResult

framework = Runner.callback_framework

async def rollback_payment(ctx):
    print("Rollback payment")

async def rollback_inventory(ctx):
    print("Rollback inventory")

@framework.on_chain("order_create", priority=30, rollback_handler=rollback_payment)
async def pay(order: dict, **kwargs):
    order["paid"] = True
    return ChainResult(ChainAction.CONTINUE, result=order)

@framework.on_chain("order_create", priority=20, rollback_handler=rollback_inventory)
async def reserve(order: dict, **kwargs):
    if order.get("quantity", 0) > 100:
        return ChainResult(ChainAction.ROLLBACK, error=Exception("Insufficient stock"))
    order["reserved"] = True
    return ChainResult(ChainAction.CONTINUE, result=order)

result = await framework.trigger_chain("order_create", order={"quantity": 150})
if result.action == ChainAction.ROLLBACK:
    print("Order failed, rolled back")

链中数据传递:下一个回调的第一个位置参数是上一个回调的返回值;此外可通过 kwargs["_chain_context"](ChainContext)的 set_metadata(key, value) / get_metadata(key, default)、get_last_result()、get_all_results() 传递更多状态。

trigger_with_timeout:限时触发

async def trigger_with_timeout(
    self,
    event: str,
    timeout: float,
    *args,
    **kwargs
) -> List[Any]

在限定总时间内触发事件(底层用 anyio.fail_after 包裹 trigger);超时则中止并返回已收集的结果(可能不完整),同时记录 warning 日志。

trigger_delayed:延迟触发

async def trigger_delayed(self, event: str, delay: float, *args, **kwargs) -> List[Any]

先 await asyncio.sleep(delay) 延迟指定秒数,再执行 trigger。

trigger_stream:流式输入触发

async def trigger_stream(
    self,
    event: str,
    input_stream: AsyncIterator[Any],
    *args,
    **kwargs
) -> AsyncIterator[Any]

对异步输入流中的每一项触发事件,逐项执行回调并流式产出结果,无需将全部数据加载到内存。回调可返回普通值或异步生成器;若返回生成器,其 yield 出的每一项都会作为该次触发的产出。单个 item 处理失败不会中断整条流,错误被记录到日志和指标,失败的 item 不产生输出。适用于大文件逐行/逐块处理、实时日志分析、流式数据管道:

async def log_stream():
    with open("app.log") as f:
        for line in f:
            yield line.strip()

@framework.on("process_log")
async def analyze_log(line: str):
    if "ERROR" in line:
        return {"level": "error", "line": line}
    return {"level": "info", "line": line}

async for analysis in framework.trigger_stream("process_log", log_stream()):
    if analysis["level"] == "error":
        await alert_admin(analysis)

trigger_generator:生成器输出聚合

async def trigger_generator(self, event: str, *args, **kwargs) -> AsyncIterator[Any]

执行事件下所有回调并聚合产出:若回调返回异步生成器则迭代其产出,否则将其返回值作为单项产出;按优先级顺序逐项 yield。同时执行 BEFORE / AFTER / CLEANUP 钩子(CLEANUP 在 finally 中保证执行)。适用于多源数据聚合(DB + 缓存 + API)、流式 API 响应:

@framework.on("fetch_users")
async def from_database():
    users = await db.query("SELECT * FROM users")
    for user in users:
        yield user

@framework.on("fetch_users")
async def from_cache():
    for user in await redis.get_all("user:*"):
        yield user

async for user in framework.trigger_generator("fetch_users"):
    process(user)

trigger_transform:仅触发 transform 回调

async def trigger_transform(self, event: str, *args, **kwargs) -> Any

仅触发 callback_type="transform" 的回调,返回最后一个回调的结果。无 transform 回调时返回内部哨兵值 _TRANSFORM_NOOP,调用方应据此透传原始值。通常不需要直接调用此方法——transform_io 事件模式在内部使用它。

自动触发与 I/O 变换装饰器

除 @on 系列注册装饰器外,框架还提供了一组将事件触发"织入"普通函数调用的装饰器,均由 decorator.py 实现,支持异步函数、同步函数(自动提升为异步)、异步生成器与同步生成器(自动提升为异步生成器)。

trigger_on_call:函数被调用时触发

def trigger_on_call(
    self,
    event: str,
    pass_result: bool = False,
    pass_args: bool = True
)

在被装饰函数被调用时触发指定事件(函数执行前触发一次;若 pass_result 为 True 则在执行后再触发一次并传入返回值)。pass_args=True 时把函数参数传给回调。

emits:函数返回后触发

def emits(
    self,
    event: str,
    result_key: str = "result",
    include_args: bool = False
)

在被装饰函数返回后触发事件,并以 result_key 为键将返回值传给回调(默认键名 "result");include_args=True 时同时传入原始参数。对应的底层实现为 create_emit_after_decorator,支持普通函数与生成器,生成器默认按每项触发(stream_mode="per_item"),也可用 stream_mode="once" 收集全部项后触发一次。

emits_stream:异步生成器逐项触发

def emits_stream(self, event: str, item_key: str = "item") -> Callable

装饰异步生成器函数:每次 yield 时自动触发指定事件,并以 item_key(默认 "item")为键将该项传给该事件的回调;原生成器仍向调用方正常 yield。适用于实时指标发布、日志流监控、进度通知、事件溯源。流式相比批处理的特点:内存占用 O(1)、首字节延迟低、适合无限长数据、实时性好。

emit_around:前后环绕触发

def emit_around(
    self,
    before_event: str,
    after_event: str,
    pass_args: bool = True,
    pass_result: bool = True,
    on_error_event: Optional[str] = None
)

在函数执行前触发 before_event,执行成功后触发 after_event;若发生异常且指定了 on_error_event 则触发该事件(异常以 error 键传入),并重新抛出原异常。对于生成器函数,after_event 在全部项 yield 完成后触发(pass_result=True 时传入收集的结果列表)。

transform_io:输入输出变换

transform_io 是在调用被装饰函数前后对入参和返回值做变换的装饰器,适用于参数规范化、结果序列化、统一加解密等场景:

def transform_io(
    self,
    *,
    input_event: Optional[str] = None,
    output_event: Optional[str] = None,
    result_key: str = "result",
    input_transform: Optional[InputTransform] = None,
    output_transform: Optional[OutputTransform] = None,
    output_mode: Literal["frame", "generator"] = "frame",
)

支持两种变换方式:

  1. 事件模式:设置 input_event / output_event。调用被装饰函数前先触发 input_event,回调接收 (*args, **kwargs) 并返回 (new_args, new_kwargs),框架用最后一个回调结果作为新参数;返回后(或生成器每项)触发 output_event,回调接收 result_key=value 并返回新值,框架用最后一个回调结果作为最终结果。注意:事件模式中只触发 callback_type="transform" 的回调,必须用 @framework.on_transform(event) 或 @framework.on(event, callback_type="transform") 注册;普通 @framework.on 注册的回调不会被 transform_io 触发。
  2. 直接回调模式:设置 input_transform / output_transform。input_transform(*args, **kwargs) 返回 (new_args, new_kwargs);output_transform(value) 返回新值。支持同步/异步。

output_mode 控制对生成器函数的输出变换方式:

  • 'frame'(默认):逐帧模式,对每个 yield 项单独调用 output 变换;事件模式下 output_event 对每项触发一次;
  • 'generator':生成器模式,将整个 source 异步迭代器一次性传给 output 变换。直接回调模式下 output_transform 须为异步生成器函数 (source: AsyncIterator) -> AsyncIterator,可对每项 yield 0/1/多次,支持过滤、展开、有状态变换;事件模式下 output_event 触发一次、以 source 为参数,回调应返回可迭代对象;同步生成器自动提升为异步。对非生成器函数使用 generator 模式时抛出 ValueError。

事件模式示例:

@framework.on_transform("transform_input")
async def normalize_input(*args, **kwargs):
    return (args, {**kwargs, "limit": kwargs.get("limit", 10)})

@framework.on_transform("transform_output")
async def serialize_output(result):
    return json.dumps(result) if isinstance(result, dict) else result

@framework.transform_io(
    input_event="transform_input",
    output_event="transform_output",
)
async def fetch_data(limit: int):
    return {"count": limit}

生成器模式(直接回调)示例:

async def expand_chunks(source):
    """将每个分块拆分为独立 token。"""
    async for chunk in source:
        for token in chunk.split():
            yield token

@framework.transform_io(output_transform=expand_chunks, output_mode="generator")
async def stream_response():
    yield "hello world"
    yield "foo bar baz"

# 实际 yield: "hello", "world", "foo", "bar", "baz"

从源码实现看,transform_io 根据是否设置 input_event/output_event 分别委托 create_transform_io_by_events_decorator 或 create_transform_io_decorator;在传递变换后的参数时使用 _bind_args_no_duplicate 优先以关键字传递、避免出现 "multiple values for argument" 的重复传参错误,并通过 lru_cache 缓存函数签名解析结果以降低每次调用的开销(见 decorator.py)。

过滤器与熔断器

过滤器层级与执行顺序

过滤器在回调执行前拦截并决定是否执行、如何执行。共三级:

  • 全局过滤器:add_global_filter(filter),对所有事件生效,适合日志、监控;
  • 事件过滤器:add_filter(event, filter),仅对指定事件生效,适合限流、鉴权;
  • 回调过滤器:on(event, filters=[...]) 中传入,仅对该回调生效。

执行顺序为 全局 → 事件 → 回调;任一层返回 STOP 或 SKIP 会短路后续执行或跳过当前回调(见 framework.py 的 _apply_filters,过滤器按顺序执行,MODIFY 会逐层更新参数)。

过滤动作由 enums.py 中的 FilterAction 定义:

动作 含义
CONTINUE 继续执行回调
STOP 停止整个事件的处理
SKIP 跳过当前回调,继续下一个
MODIFY 修改参数后继续

内置过滤器一览

所有内置过滤器均位于 openjiuwen.core.runner.callback,继承自 EventFilter(见 filters.py):

过滤器 功能 典型用途
RateLimitFilter(max_calls, time_window) 在时间窗口内限制调用次数 防止回调执行过于频繁
CircuitBreakerFilter(failure_threshold, timeout) 失败次数达到阈值后熔断,超时后尝试恢复 保护下游服务
ValidationFilter(validator) 用自定义函数校验参数 参数合法性检查
LoggingFilter 记录事件、回调名、参数 审计、调试
AuthFilter(required_role) 要求 kwargs 中 user_role 等于指定角色 基于角色的访问控制
ParamModifyFilter(modifier) 用 modifier(*args, **kwargs) 返回 (new_args, new_kwargs) 修改参数 转换或增强参数
ConditionalFilter(condition, action_on_false) 根据 condition 决定 CONTINUE 或 action_on_false 条件执行

自定义过滤器可子类化 EventFilter 并实现 async def filter(self, event, callback, *args, **kwargs) -> FilterResult。RateLimitFilter 内部使用 deque(maxlen=max_calls) 与 asyncio.Lock 保证线程安全;CircuitBreakerFilter 以 事件名:回调名 为 key 维护失败计数、熔断状态与恢复时间。

限流与鉴权示例:

from openjiuwen.core.runner import Runner
from openjiuwen.core.runner.callback import RateLimitFilter, AuthFilter

framework = Runner.callback_framework
framework.add_filter("api_call", RateLimitFilter(max_calls=100, time_window=60.0))
framework.add_filter("admin_action", AuthFilter(required_role="admin"))

@framework.on("admin_action")
async def do_admin(user_id: str, user_role: str):
    return f"admin_ok_{user_id}"

await framework.trigger("admin_action", user_id="u1", user_role="admin")

熔断器 API

def add_circuit_breaker(
    self,
    event: str,
    callback: Callable,
    failure_threshold: int = 5,
    timeout: float = 60.0
) -> None

为指定事件的某个回调添加熔断保护。参数:failure_threshold(打开熔断的失败次数,默认 5)、timeout(恢复尝试前的等待时间秒数,默认 60.0)。实现上,框架以 事件名:回调名 为 key 创建 CircuitBreakerFilter 并注册到事件过滤器列表(见 framework.py 的 add_circuit_breaker);框架在回调成功/失败时自动调用 record_success / record_failure。失败次数达到阈值后该回调会被跳过(SKIP),直到超过 timeout 后再次尝试。

生命周期钩子

def add_hook(self, event: str, hook_type: HookType, hook: Callable) -> None

为事件添加生命周期钩子,hook 可为同步或异步函数。钩子类型(enums.py 的 HookType):

  • HookType.BEFORE:事件下所有回调执行前;
  • HookType.AFTER:所有回调执行完毕后(传入结果列表等);
  • HookType.ERROR:某个回调抛错时(传入异常等);
  • HookType.CLEANUP:在 finally 中执行,用于收尾(trigger_generator 中保证执行)。

钩子执行由 _execute_hooks 完成:遍历对应事件与类型的钩子列表,异步函数 await 执行、同步函数直接调用,单个钩子失败只记录日志、不影响主流程(见 framework.py)。

framework.add_hook("user_login", HookType.BEFORE, on_login_before)  # 同步或异步均可
framework.add_hook("user_login", HookType.AFTER, on_login_after)

指标、慢回调与性能监控

框架在 enable_metrics=True(默认开启)时,为每个回调收集 CallbackMetrics(models.py):call_count(调用次数)、total_time(累计耗时)、min_time / max_time、error_count(错误次数)、last_call_time(最近调用时间),派生 avg_time(平均耗时)与 error_rate(错误率)。

def get_metrics(
    self,
    event: Optional[str] = None,
    callback: Optional[str] = None
) -> Dict[str, Dict[str, Any]]

返回 key 到指标字典的映射(key 格式为 事件名:回调名),可按事件或回调名筛选:

metrics = framework.get_metrics(event="user_login")
# {'user_login:handle_login': {'call_count': 3, 'avg_time': 0.002, ...}}

其他指标相关 API:

  • reset_metrics() -> None:清空所有性能指标;
  • get_slow_callbacks(threshold: float = 1.0) -> List[Dict[str, Any]]:返回平均执行时间超过阈值的回调信息(含 callback、avg_time、max_time、call_count),按 avg_time 降序排列,便于性能排查。

建议在关键事件上开启 enable_metrics=True,并定期用 get_slow_callbacks 排查慢回调。另外,源码中定义了 SLOW_CALLBACK_SECONDS = 1.0 与 SLOW_CALLBACK_CHAIN_SECONDS = 0.05 两个内部阈值:单个回调超过 1 秒会以 INFO 单独上报,整条回调链合计超过 0.05 秒会输出 [RailChain] 逐回调耗时拆分日志,帮助定位是哪个 rail 钩子拖慢了事件链路。

事件历史与重放

def enable_event_history(self, enabled: bool = True) -> None
def get_event_history(
    self,
    event: Optional[str] = None,
    since: Optional[datetime] = None
) -> List[Dict[str, Any]]
async def replay_events(self, since: Optional[datetime] = None) -> None
  • enable_event_history(True):开启事件历史记录。历史使用 deque(maxlen=1000) 存储,最多保留最近 1000 条记录,每条包含 event、args、kwargs、timestamp;
  • get_event_history(event=None, since=None):获取已记录的事件历史,可按事件名与起始时间筛选;
  • replay_events(since=None):按记录顺序重新触发事件(依次调用 trigger),可用于故障复现、测试与补偿。has_subscribers 在开启历史时恒返回 True,因此事件总会被记录。
framework.enable_event_history(True)
# ... 运行若干事件 ...
history = framework.get_event_history(event="user_login", since=datetime(2025, 1, 1))
await framework.replay_events(since=datetime(2025, 1, 1))

状态持久化与查询

save_state:保存框架元数据

def save_state(self, filepath: str) -> None

将框架状态写入文件(JSON 格式)。仅保存元数据(回调名、优先级、命名空间、标签、enabled 状态、指标、事件历史),不包含回调函数本身,因此无法直接跨进程恢复执行,但可用于诊断、审计与统计归档。

查询 API

def list_events(self, namespace: Optional[str] = None) -> List[str]
def list_callbacks(self, event: str) -> List[Dict[str, Any]]
def get_statistics(self) -> Dict[str, Any]
  • list_events(namespace=None):列出已注册的事件名;传入 namespace 时仅列出该命名空间下存在回调的事件;
  • list_callbacks(event):列出某事件下所有回调的元信息(name、priority、enabled、namespace、tags、once、max_retries、timeout 等);
  • get_statistics():获取框架整体统计——total_events(事件数)、total_callbacks(回调总数)、namespaces(命名空间集合)、total_filters(过滤器数)、total_chains(链数)、history_size(历史长度)、metrics_collected(指标数)。

Tool / LLM / Workflow 的 invoke/stream 全局拦截

Tool、BaseModelClient、Workflow 在实例化时自动将 invoke 和 stream 方法包装进对应的 transform_io 管道。注册相应事件的 transform 回调即可全局拦截所有实例的调用,无需修改各实例代码(详见高阶用法:异步回调框架)。

可用事件(定义于 events.py):

类 输入事件 输出事件
Tool.invoke ToolCallEvents.TOOL_INVOKE_INPUT ToolCallEvents.TOOL_INVOKE_OUTPUT
Tool.stream ToolCallEvents.TOOL_STREAM_INPUT ToolCallEvents.TOOL_STREAM_OUTPUT
BaseModelClient.invoke LLMCallEvents.LLM_INVOKE_INPUT LLMCallEvents.LLM_INVOKE_OUTPUT
BaseModelClient.stream LLMCallEvents.LLM_STREAM_INPUT LLMCallEvents.LLM_STREAM_OUTPUT
Workflow.invoke WorkflowEvents.WORKFLOW_INVOKE_INPUT WorkflowEvents.WORKFLOW_INVOKE_OUTPUT
Workflow.stream WorkflowEvents.WORKFLOW_STREAM_INPUT WorkflowEvents.WORKFLOW_STREAM_OUTPUT

输入回调接收 (*args, **kwargs) 并返回 (new_args, new_kwargs);输出回调接收 result=<value> 并返回新值;stream 的输出事件对每个 yield item 独立触发一次。示例:

from openjiuwen.core.runner import Runner
from openjiuwen.core.runner.callback.events import ToolCallEvents

fw = Runner.callback_framework

# 拦截所有 Tool.invoke 的入参
@fw.on_transform(ToolCallEvents.TOOL_INVOKE_INPUT)
async def preprocess(inputs, **kwargs):
    # inputs 是 Tool.invoke 的第一个位置参数
    return ((inputs,), kwargs)

# 拦截所有 Tool.invoke 的返回值
@fw.on_transform(ToolCallEvents.TOOL_INVOKE_OUTPUT)
async def postprocess(result):
    return result  # 原样透传,或修改后返回

该机制同样覆盖 Agent 生命周期(AgentEvents.AGENT_STARTED 等)、LLM 调用(LLM_CALL_STARTED、LLM_CALL_ERROR、LLM_RESPONSE_RECEIVED、LLM_STREAM_COMPLETED、LLM_ROUTE 等)、上下文管理、会话、记忆、检索与任务管理等多类预置事件,可作为全局可观测性与横切治理的统一入口。

与 Runner 的配合

Runner 在初始化时创建框架实例,启动后通过 Runner.callback_framework 暴露同一套框架实例(同时支持类属性访问与实例属性访问,见 runner.py)。可在 Agent / Workflow 执行前后注册事件(如 workflow_started、agent_finished),用于日志、指标、审计或扩展业务流程。Runner 的配置仍通过 Runner.set_config / Runner.get_config 管理,与回调框架解耦。

不依赖 Runner 实例时,还可以使用 utils.py 提供的单例访问工具:

  • get_callback_framework() -> AsyncCallbackFramework:返回 Runner 持有的框架单例;
  • lazy_callback_framework:惰性代理对象,可在模块导入期安全使用 emit_before、emit_after、transform_io 等装饰器而不触发循环导入,属性访问在运行时才解析到真实框架;
  • trigger(event, **kwargs):便捷触发函数,先通过 has_subscribers 判断是否存在订阅者,无订阅者时直接返回、避免无谓开销。

最佳实践

  1. 事件命名:使用有语义的点分形式(如 user.login、order.created),或直接复用 events.py 中的预置事件常量,避免泛用名;
  2. 优先级:关键步骤(如鉴权、校验)设高 priority,辅助步骤(如通知、统计)设低 priority;
  3. I/O 与 CPU:I/O 密集用 trigger_parallel;CPU 密集或存在共享状态时用 trigger;
  4. 命名空间与标签:用 namespace、tags 组织回调,便于 unregister_namespace、unregister_by_tags 批量管理;
  5. 错误处理:对易失败的回调设置 error_handler,或在链中使用 rollback_handler 保证一致性;
  6. 事务型流程:多步且需"全成功或全回滚"时使用 trigger_chain 与 rollback_handler;
  7. 监控:定期用 get_slow_callbacks(threshold) 排查慢回调,必要时为回调设置 timeout;关注 [RailChain] 链路耗时日志定位瓶颈;
  8. 全局横切:通过 transform_io 事件统一拦截 Tool / LLM / Workflow 的入参出参,实现鉴权、脱敏、观测等横切关注点,避免逐实例改动。

常见问题

  • 何时用 trigger 还是 trigger_parallel? 有顺序依赖或共享状态时用 trigger;回调相互独立且 I/O 密集时用 trigger_parallel。
  • 过滤器执行顺序? 全局过滤器 → 事件过滤器 → 回调专属过滤器;任一层可返回 STOP(停止整次触发)或 SKIP(跳过当前回调)。
  • 链中数据如何传递? 下一个回调的第一个位置参数是上一个回调的返回值;此外可通过 kwargs["_chain_context"] 的 set_metadata / get_metadata、get_last_result() 传递更多状态。
  • 如何实现"仅当条件满足才执行"? 使用 ConditionalFilter,或使用 trigger_until 在找到第一个满足条件的结果后停止。
  • 流式处理中单条失败会怎样? 单条失败不会中断流;错误会记入日志和指标,该条不产生输出,后续 item 继续处理。
  • transform 回调为什么不执行? 普通 trigger 会跳过 callback_type="transform" 的回调,需使用 trigger_transform 或 transform_io 事件模式(且需用 @on_transform 或 on(callback_type="transform") 注册)。
  • unregister 时传什么? 可传原始回调函数,也可传 @on 装饰器返回的包装函数,框架会按三种方式匹配后移除。

参考

登录后查看全文
agent-core