跳转到内容

应用如何处理消息

BubFramework 将 Agent 接到应用所需的会话标识、本轮状态、prompt 准备和消息交付上。每个阶段都提供 hooks,插件可以在对应位置改变应用行为。

这条流程属于 bub[app]。直接调用 core.Agent.run() 时,Agent 使用你提供的 prompt、state 和 Tape 开始循环。

framework.process_inbound(message) 依次执行以下阶段:

阶段 职责
resolve_session 为入站消息选择会话 ID。
load_state 汇集各 hook 提供的本轮状态。
build_prompt 将入站内容转换为 prompt。
run_model / run_model_stream 通过完整结果或流生成模型输出。
save_state 完成与模型阶段关联的收尾工作,在该阶段的 finally 块中运行。
render_outbound 将结果转换为出站 envelope。
dispatch_outbound 交付每个出站 envelope。

内置插件提供应用默认行为。其他插件按各 hook 的规则补充或替换行为;Hooks 参考说明首个有效结果、结果合并和优先级。

内置 run_model_stream hook 调用 BubAgent.run_stream()。BubAgent 使用内核的模型与工具循环,并增加设置、skills、命令、运行中消息引导和应用工具策略。

框架负责适配流式和非流式 hook 结果。process_inbound(..., stream_output=True) 让渠道路由器消费增量输出,并在消费结束后返回已完成的 TurnResult。

插件替换 run_model 后,执行行为随之改变。例如,echo 插件可以直接返回文本,不创建 Agent 运行。只有选中的实现实际使用内核 Agent,才会产生相应的核心事件与 Tape 记录。

当 hooks 提供存储或其他应用资源时,使用 async with framework.running(): 打开它们,并在退出时释放。内置的单条消息 lifespan 在加载状态时打开,在 save_state 中关闭。

执行到模型阶段后,无论该阶段是否抛出异常,都会运行 save_state。会话解析、状态加载或 prompt 构建失败发生在这个 finally 块之前,因此不会触发它。插件在较早阶段获取资源时,需要考虑这个边界。

内置 save_state 负责关闭单条消息 lifespan。应用会另外记录选定设置,保存其他状态需要明确的持久化方式。

模型阶段抛出未处理异常时,框架先运行 save_state,再跳过正常的渲染与分发。外层错误路径调用 on_error(stage="turn", ...) 后重新抛出异常。内置错误观察器可以通过出站分发发送错误响应。单个 on_error 观察器失败不会阻止其他观察器执行。

按照插件指南注册实现,通过 Hooks 示例完成具体修改,精确签名和顺序见 Hooks 参考。