openJiuwen agent-core-java Runner 全局回调框架(callback)机制详解与实战指南

原创2026-10-14 18:31:251,622 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流多智能体工具调用MCP 服务Agent 记忆RAG后端Agent 沙箱

openJiuwen agent-core-java Runner 全局回调框架(callback)机制详解与实战指南

com.openjiuwen.core.runner.callback 是 openJiuwen agent-core-java 提供的 Runner 级全局事件回调框架,用于在整个 Agent 运行期以装饰器风格注册、触发和管理事件回调。本文从主类 AsyncCallbackFramework 出发,完整梳理其注册、触发、过滤器、链式回滚、指标、hooks、断路器、延迟触发与历史记录等能力,并结合仓库源码(core/src/main/java/com/openjiuwen/core/runner/callback)与测试用例逐项展开。读完本文,你将掌握如何在 Runner 全局挂接回调、如何用过滤器控制执行流程、如何用链式回滚保证数据一致性,以及如何通过指标与历史记录观测回调运行状态。

一、框架定位:Runner 级全局事件回调

在 openJiuwen agent-core-java 中,Runner 是分布式运行与资源调度的核心入口,而 callback 包正是挂在 Runner 上的全局事件回调框架。与某个具体 Agent 或 Session 内部的生命周期回调不同,这里的回调是 Runner 级(全局) 的:注册之后,任何一次事件触发都会按规则分发给对应的回调函数,适合做全局埋点、观测、鉴权、限流、熔断等横切能力。

  • 对应 Python 版本的 AsyncCallbackFramework(源码注释明确标注 "Mirrors Python's AsyncCallbackFramework in openjiuwen/core/runner/callback/framework.py",见 AsyncCallbackFramework.java);
  • 真实主类是 AsyncCallbackFramework,它实现了 DecoratorFramework 接口(见 DecoratorFramework.java),因此天然支持装饰器风格(on(...)、wrap(...) 等)的注册写法;
  • 常用入口是 Runner.getCallbackFramework(),返回 AsyncCallbackFramework 实例(见 Runner.java),也可以直接读取静态字段 Runner.callbackFramework(Runner.java)。

从类结构看,AsyncCallbackFramework 内部用 ConcurrentHashMap 组织多类注册表:callbacks(事件 → 回调列表)、chains(事件 → 回调链)、filters(事件 → 过滤器列表)、hooks(事件 → HookType → hook 列表)、metrics(事件+回调 → 指标),并持有全局过滤器列表、断路器表和有界的历史队列(ArrayDeque,上限 1000 条),见 AsyncCallbackFramework.java。

二、核心主类 AsyncCallbackFramework

2.1 类声明与构造

public class AsyncCallbackFramework implements DecoratorFramework

构造函数有两个:

构造函数 说明
AsyncCallbackFramework() 默认开启 metrics 和 logging。
AsyncCallbackFramework(boolean enableMetrics, boolean enableLogging) 显式指定是否开启指标采集与回调日志。

对应源码实现为 AsyncCallbackFramework() 内部委托 this(true, true),见 AsyncCallbackFramework.java。框架还内置了共享的有界并行执行池(OpenJiuwenExecutors.newBoundedModulePool("callback-parallel", false))与延迟触发的调度器,供并行触发和延迟触发使用。

2.2 注册入口

框架提供了多种注册回调的方式:

方法 说明
on(event, ...) 返回装饰器风格的注册函数,可一次指定 priority、once、namespace、tags、eventFilters、maxRetries、retryDelay、timeout、callbackType 等全部参数。
onChain(event, ...) 注册链式回调,可同时配置 rollbackHandler 与 errorHandler。
registerSync(event, callback, ...) DecoratorFramework 接口要求的同步注册入口。
register(event, callback, ...) 直接注册回调并返回 CallbackInfo,是 registerSync 的便捷封装。
unregister(event, callback) 移除指定事件下的单个回调。
unregisterNamespace(namespace) 按命名空间批量移除回调。
unregisterByTags(tags) 按标签批量移除回调。
unregisterEvent(event) 移除某个事件下的全部回调(连同该事件的 chains、hooks、filters 一并清理)。

源码中 registerSync 做了几件关键事情(AsyncCallbackFramework.java):

  1. 用 CallbackInfo.builder() 构建回调元数据,namespace 缺省为 "default",tags 缺省为空集合;
  2. 写入 callbacks 对应事件的同步列表并 sortCallbacks(event) 按优先级排序;
  3. 若带了 eventFilters,则写入 callbackFilters(按回调函数为 key);
  4. 若带了 rollbackHandler 或 errorHandler,则将该回调加入该事件对应的 CallbackChain;
  5. 开启 logging 时输出 Registered callback: {event} -> {callbackName}。

2.3 触发入口

触发是回调框架最核心的运行时能力,源码中按用途划分了多种触发模式:

方法 说明
trigger(event, args, kwargs) DecoratorFramework 兼容入口,不返回结果(返回 void),内部委托 triggerResults(...)。
triggerResults(event, args, kwargs) 顺序触发事件并返回回调结果列表 List<Object>,是最常用的“要结果”入口。
triggerAsync(event, args, kwargs) 异步触发,返回 CompletableFuture<List<Object>>。
triggerDelayed(event, delaySeconds, args, kwargs) 延迟触发,返回 ScheduledFuture<List<Object>>。
triggerParallel(event, args, kwargs) 使用共享有界线程池并发执行当前事件的所有回调。
triggerUntil(event, condition, args, kwargs) 按顺序执行,直到传入的 Predicate<Object> 命中某个回调结果为止。
triggerWithTimeout(event, timeoutSeconds, args, kwargs) 给整个触发过程设置总超时,超时返回空列表并取消任务。
triggerStream(...) / triggerGenerator(...) 把结果整理成 Iterator,支持流式逐项处理。
triggerTransform(event, args, kwargs) 只执行 callbackType == "transform" 的回调,返回最后一个 transform 结果(无则返回 TRANSFORM_NOOP)。
triggerChain(event, args, kwargs) 以链式方式执行该事件的回调链,返回 ChainResult。

triggerResults 的完整执行流水线(AsyncCallbackFramework.java)为:

  1. 若开启 history,先记录本次触发历史;
  2. 执行 HookType.BEFORE 钩子;
  3. 遍历该事件下按优先级排序的回调快照:
    • 跳过被禁用(enabled=false)或 transform 类型的回调;
    • 执行过滤器链:STOP 直接终止整个事件处理;SKIP 跳过当前回调继续下一个;MODIFY 使用过滤器返回的修改后参数执行;
    • 调用 invokeCallback(...),并携带 CallbackInfo.timeout 作为单回调执行超时;
    • 更新指标、向对应断路器记录成功、收集结果;
    • once 回调执行后自动置为禁用;
    • 捕获到异常时更新指标、记录断路器失败并触发 HookType.ERROR 钩子;
  4. 执行 HookType.AFTER 钩子,返回结果列表。

2.4 过滤器、hooks 与状态管理

能力 方法 说明
过滤器 addFilter(event, filter) 为指定事件追加过滤器。
addGlobalFilter(filter) 追加全局过滤器,作用于所有事件。
removeFilter(...) 移除过滤器。
addCircuitBreaker(event, callback, failureThreshold, timeout) 为特定事件+回调绑定断路器(本质也是过滤器)。
hooks addHook(event, hookType, hook) 注册生命周期钩子,hookType 为 HookType 枚举(BEFORE/AFTER/ERROR/CLEANUP)。
removeHook(...) 移除钩子。
历史 enableEventHistory(boolean) 开关事件历史记录。
getEventHistory(event, since) 按事件与时间戳过滤查询历史。
replayEvents(since) 重放某时间点之后的历史事件。
持久化 saveState(filepath) 将回调注册信息、指标与历史序列化为 JSON 文件。
loadState(...) 从文件恢复回调框架状态。

从源码看,saveState 使用 Jackson ObjectMapper 以 pretty-print 形式写出 callbacks、metrics、history 三部分(AsyncCallbackFramework.java);getStatistics() 可汇总 total_events、total_callbacks、namespaces、total_filters、total_chains、history_size、metrics_collected 等运行统计(AsyncCallbackFramework.java)。

三、回调元数据 CallbackInfo

CallbackInfo 描述单个回调的元数据与运行配置,字段定义见 CallbackInfo.md 与 CallbackInfo.java:

Field Type Default 说明
callback Function<Map<String, Object>, Object> - 回调函数本体:接收 keyword-args Map,返回执行结果。
priority int 0 执行优先级,数值越大越先执行。
once boolean false 是否只执行一次,执行后自动禁用。
enabled boolean true 当前是否可用。
namespace String "default" 用于分组管理回调的命名空间。
tags Set<String> new HashSet<>() 标签集合,用于按标签过滤/批量注销。
maxRetries int 0 失败时的最大重试次数。
retryDelay double 0.0 重试间隔(秒)。
timeout Double - 单次执行超时(秒),为空表示不设超时。
createdAt double System.currentTimeMillis() / 1000.0 注册时间戳(epoch 秒)。
callbackName String - 回调名称,用于日志与指标标识。

其中 priority 的语义在测试 AsyncCallbackFrameworkTest.java 中有明确验证:注册 priority=1、priority=20(transform)与 priority=10 三个回调后,triggerResults 实际执行顺序是 high(10) → low(1),transform 回调被跳过不参与普通触发。CallbackInfo.getCallbackDisplayName() 用于日志与指标展示。

四、链式回调与回滚:CallbackChain 与相关模型

链式回调适用于“多个步骤必须按序执行、失败时需要补偿回滚”的场景,例如多阶段资源分配、多服务调用等。

4.1 CallbackChain

CallbackChain 管理回调的顺序执行并支持回滚(CallbackChain.java):

成员 类型 说明
name String 链名称。
callbacks List<CallbackInfo> 链内回调列表,add 时按优先级降序排序。
rollbackHandlers Map<Function, Consumer<ChainContext>> 每个回调对应的回滚处理器。
errorHandlers Map<Function, Function<ExceptionContext, Object>> 每个回调对应的错误处理器。

主要方法:

方法 说明
add(callbackInfo, rollbackHandler, errorHandler) 追加回调及对应的回滚/错误处理器。
remove(callback) 移除回调并同步清理其处理器映射。
execute(ChainContext context) 执行整条链,返回 CompletableFuture<ChainResult>。

add 与 remove 均为 synchronized 方法,保证并发注册/注销与链内排序互不交错(源码注释明确说明,见 CallbackChain.java)。

4.2 链式执行语义(ChainAction / ChainResult)

链内回调可以返回 ChainResult 来驱动控制流,ChainAction 枚举定义了四种动作(见 ChainAction.md):

值 说明
CONTINUE 继续执行链中的下一个回调。
BREAK 终止链式执行并返回当前结果。
RETRY 重新执行当前回调。
ROLLBACK 回滚已经执行过的回调。

CallbackChain.executeInternal 的执行逻辑(CallbackChain.java):

  1. 依次遍历链内回调,跳过禁用的;
  2. 每个回调最多执行 maxRetries + 1 次尝试:正常结果加入 context.results 并记录到已执行列表;返回 BREAK 立即终止;RETRY 重试当前回调;ROLLBACK 触发回滚流程;
  3. 回调抛异常时:若配置了 errorHandler 且其返回“真值”,视为已恢复并继续;否则在重试次数耗尽后调用 rollback(...),从已执行列表逆序调用各回调的 rollbackHandler 做补偿,最终返回 ChainAction.ROLLBACK 的 ChainResult;
  4. 全部成功则 context.setCompleted(true),返回 ChainAction.CONTINUE 与最后一个结果。

执行过程中,ChainContext 还向回调注入 _chain_context、_initial_args、_last_result、_args 等关键字(CallbackChain.java),便于回调读取链上下文与上一步结果。

4.3 ChainContext / ChainResult

ChainContext 是链式执行的运行时上下文(ChainContext.md):

Field 说明
event 正在处理的事件名。
initialArgs / initialKwargs 触发时传入的原始位置参数与关键字参数。
results 已执行回调的结果列表。
metadata 任意元数据,用于在链内各回调间共享数据。
currentIndex 当前正在执行的回调下标。
completed 链是否成功完成。
rolledBack 链是否已回滚。
startTime 链开始执行的时间戳(epoch millis)。

常用方法:getLastResult()(取上一个回调的结果)、getAllResults()、setMetadata(key, value) / getMetadata(key, defaultValue)、getElapsedTime()(自链开始以来的耗时)。

ChainResult 则封装链的最终结果(ChainResult.md):action(最终动作)、result(最终结果值)、context(完整执行上下文)、error(失败时的异常)。CallbackChain 还嵌套定义了 ExceptionContext(包含异常与链上下文),作为 errorHandler 的入参。

五、过滤器体系:事件控制的中枢

5.1 基类 EventFilter 与 FilterResult / FilterAction

EventFilter 是所有过滤器的基类(EventFilter.md):

public FilterResult filter(String event, CallbackInfo callback, Object[] args, Map<String, Object> kwargs)

自定义过滤器只需继承 EventFilter 并重写 filter(...) 方法。返回值 FilterResult 决定后续行为(FilterResult.md),其静态工厂方法覆盖了四种 FilterAction:

FilterAction 语义 推荐工厂方法
CONTINUE 继续执行当前回调 continueResult() / continueResult(args, kwargs)
STOP 停止整个事件处理流程 stopResult(reason)
SKIP 跳过当前回调,继续后续回调 skipResult(reason)
MODIFY 用修改后的参数继续执行 modifyResult(modifiedArgs, modifiedKwargs)

FilterResult 的四个字段(action、modifiedArgs、modifiedKwargs、reason)与工厂方法定义见 FilterResult.java。从 triggerResults 的过滤段(AsyncCallbackFramework.java)可以确认:STOP 直接 break 终止事件处理;SKIP 跳过当前回调;MODIFY/CONTINUE 的修改参数会替换最终传给回调的 args/kwargs。

过滤器可在三个层级生效:事件级(addFilter)、全局级(addGlobalFilter)、回调级(注册时传入 eventFilters,存入 callbackFilters)。执行时按“回调级 + 事件级 + 全局级”合并应用(见 applyFilters 实现,AsyncCallbackFramework.java)。

5.2 内置过滤器

框架开箱即用的过滤器如下(均继承 EventFilter,集中在 core/src/main/java/com/openjiuwen/core/runner/callback):

过滤器 职责 关键参数 判定行为
AuthFilter 基于角色的访问控制 requiredRole 从 kwargs 读取 user_role(缺省 "guest"),不匹配则 skipResult,见 AuthFilter.java。
RateLimitFilter 限流 maxCalls、timeWindow(秒) 以 event:callbackDisplayName 为维度做滑动窗口计数,窗口内超过 maxCalls 则 skipResult("Rate limit exceeded..."),见 RateLimitFilter.java。
CircuitBreakerFilter 断路器熔断 failureThreshold(默认 5)、timeout(默认 60 秒) 连续失败达到阈值后打开断路器,超时窗口内对后续调用 skipResult,窗口过期自动半开恢复;成功调用 recordSuccess 复位,见 CircuitBreakerFilter.java。
ValidationFilter 参数校验 validator: Predicate<Map<String, Object>> 校验 kwargs,不通过则返回失败结果。
ConditionalFilter 条件过滤 condition: ConditionPredicate、actionOnFalse 条件不满足时按 actionOnFalse 指定的动作处理。
LoggingFilter 日志 Logger(可选) 记录回调执行日志。
ParamModifyFilter 参数改写 modifier: BiFunction<Object[], Map<String, Object>, Object[]> 返回 [newArgs, newKwargs] 二元数组以替换调用参数。

其中 ConditionalFilter 的 ConditionPredicate 签名是 (event, callback, args, kwargs) -> boolean(见 ConditionalFilter.md)。断路器的默认参数在无参构造中体现:new CircuitBreakerFilter() 等价于 (5, 60.0)(CircuitBreakerFilter.java)。

典型的组合用法:鉴权 → 限流 → 断路器 → 参数校验/改写,依次挂在同一个事件上,形成一条“安全加固 + 可靠性保护”的过滤链。

六、生命周期钩子 HookType

HookType 枚举定义了回调框架支持的四类生命周期钩子(HookType.md):

值 触发时机
BEFORE 事件处理开始前。
AFTER 事件处理完成后。
ERROR 事件处理抛出异常时。
CLEANUP 清理阶段(例如生成器模式异常退出时的收尾)。

钩子通过 addHook(event, hookType, hook) 注册,hook 签名为 Consumer<Map<String, Object>>。从 triggerResults 与 triggerGenerator 的源码可以确认钩子的落点:BEFORE 在遍历回调前触发、AFTER 在所有回调完成后触发(携带结果列表)、ERROR 在捕获异常后触发、CLEANUP 在生成器流程异常时触发(AsyncCallbackFramework.java)。钩子适合做跨回调的埋点、耗时统计与资源清理。

七、指标与观测 CallbackMetrics

框架默认开启指标采集(enableMetrics=true)。CallbackMetrics 维护单条(事件+回调)的统计(CallbackMetrics.md):

Field 类型 默认值 说明
callCount int 0 调用次数。
totalTime double 0.0 累计耗时。
minTime double Double.MAX_VALUE 最小单次耗时。
maxTime double 0.0 最大单次耗时。
errorCount int 0 错误次数。
lastCallTime Double - 最近一次调用时间。

方法包括 update(executionTime, isError)(同步更新统计)、getAvgTime()(平均耗时 = 累计/次数)、toMap()(转 Map 便于导出)。框架层提供 getMetrics() / getMetrics(event, callback) 查询、resetMetrics() 清零,以及 getSlowCallbacks(threshold) 按平均耗时降序筛选慢回调(AsyncCallbackFramework.java)。这些数据可配合 getStatistics() 做全局观测与调优。

八、事件命名与 scope 机制

事件名支持作用域(scope)前缀。Events 工具类(Events.java)提供:

  • DEFAULT_SCOPE = "_framework":默认作用域;
  • buildEventName(scope, eventName):拼接形如 scope:eventName 的完整事件名;
  • parseEventName(scopedEvent):按第一个 : 拆分为 [scope, eventName],无 : 时按默认作用域处理;
  • getEvent(eventName) / getEvent(scope, eventName):便捷构造。

仓库还在 callback 包下预置了多组业务事件常量类,如 AgentEvents、AgentTeamEvents、ContextEvents、LLMCallEvents、MemoryEvents、RetrievalEvents、SessionEvents、TaskManagerEvents、ToolCallEvents、WorkflowEvents 等,方便按模块统一管理事件名,可作为挂接全局回调时的事件源参考。

九、Runner 集成:全局入口

Runner 将回调框架作为全局能力暴露,两种取用方式等价(Runner.java):

AsyncCallbackFramework framework = Runner.getCallbackFramework();
// 或
AsyncCallbackFramework framework = Runner.callbackFramework;

Runner 内部持有一个 AsyncCallbackFramework 实例(构建于 Runner 内部类,见 Runner.java),这意味着在 Agent 运行、工作流执行、工具调用等任何环节,只要拿到 Runner 入口即可注册全局回调,实现跨模块的统一横切逻辑。

十、并发模型与使用注意

从源码可以确认以下几点运行时事实:

  1. trigger(...) 不返回结果:它是 DecoratorFramework 接口的兼容入口(返回 void),内部仅调用 triggerResults(...)(AsyncCallbackFramework.java)。需要回调结果时务必使用 triggerResults(...),这是文档与测试反复强调的易错点;
  2. triggerParallel(...) 使用共享有界线程池,而非虚拟线程池:并行执行池为 OpenJiuwenExecutors.newBoundedModulePool("callback-parallel", false)(AsyncCallbackFramework.java),源码注释说明这是共享有界池而非每次触发的 cached 池,也不是虚拟线程池;
  3. 线程安全设计:各注册表使用 ConcurrentHashMap,事件回调列表使用 synchronizedList,过滤执行与链操作通过 synchronized 方法保证并发安全;CallbackChain.add/remove 专门注释了与并发注册/注销的互斥保证;
  4. 历史队列有界:eventHistory 为容量 1000 的 ArrayDeque,超限自动淘汰最旧记录;
  5. 延迟触发有调度裕量:DELAYED_TRIGGER_SCHEDULER_LEEWAY_MILLIS = 90L,用于保证延迟回调的实际完成时间不早于预定时间(见 AsyncCallbackFramework.java)。

十一、兼容性与版本演进:关于过期类名 CallbackFramework

文档特别提示:早期文档把 Runner 回调框架主类写作 CallbackFramework,这是过期命名习惯。从当前仓库源码看,真实主类是 AsyncCallbackFramework;CallbackFramework 在文档中标记为过期页面(见 CallbackFramework.md),并建议统一使用:

  • AsyncCallbackFramework
  • DecoratorFramework(接口)
  • Runner.getCallbackFramework()
  • Runner.callbackFramework

需要补充的源码事实是:当前仓库中仍保留 core/src/main/java/com/openjiuwen/core/runner/callback/CallbackFramework.java 作为 0.1.12 同步回调框架的兼容门面类,它继承 AsyncCallbackFramework 并提供旧的 register(event, callback, priority, callbackName) 便捷重载,用于老代码平滑迁移(见 CallbackFramework.java)。因此,新代码应以 AsyncCallbackFramework 为准,老代码可借助兼容门面过渡。

十二、测试验证:框架行为的可执行依据

仓库为回调框架配备了系统性的测试集,既是行为规范也是使用参考(路径 core/src/test/java/com/openjiuwen/core/runner/callback):

测试类 覆盖重点
AsyncCallbackFrameworkTest 优先级排序、transform 回调隔离、once 语义、过滤器参数改写、triggerTransform 返回值等。
CallbackChainTest 链式执行、回滚、错误恢复、重试与 ChainAction 控制流。
CallbackFiltersTest 各类内置过滤器的判定行为(Auth/RateLimit/CircuitBreaker/Validation/Conditional/Logging/ParamModify)。
CallbackModelsTest CallbackInfo、CallbackMetrics、FilterResult、ChainContext 等数据模型。
CallbackEnumsTest / ChainActionTest / HookTypeTest / FilterActionTest 枚举取值与语义。
CallbackFrameworkConcurrencyTest 并发注册/触发/注销的线程安全。
各类 *PythonParityTest 与 Python 版 AsyncCallbackFramework 行为对齐的一致性验证(注册、触发、hooks、metrics、wrap、transform-io、事件 scope、生成器、中断等)。

以 AsyncCallbackFrameworkTest.triggerRunsNonTransformCallbacksByPriority 为例(AsyncCallbackFrameworkTest.java),它同时验证了三件事:回调按优先级降序执行、transform 类型回调不参与普通 triggerResults、结果列表按执行顺序返回——这一测试可以直接作为自定义回调行为的参照。

结语

openJiuwen agent-core-java 的 com.openjiuwen.core.runner.callback 框架,以 AsyncCallbackFramework 为中枢,把回调注册、顺序/并行/延迟触发、过滤器控制、链式回滚、指标观测、生命周期钩子、事件历史与状态持久化整合为一套可投入生产的 Runner 级事件体系。无论是为 Agent 运行做全局日志与指标采集,还是用 AuthFilter + RateLimitFilter + CircuitBreakerFilter 构建可靠性保护链,都能在这个框架内以统一的装饰器风格完成。进一步深入可阅读 callback.README.md 及 callback 子文档目录,并对照 callback 源码目录 与 callback 测试目录 进行实践验证。

登录后查看全文
agent-core-java