应用如何处理消息
BubFramework 将 Agent 接到应用所需的会话标识、本轮状态、prompt 准备和消息交付上。每个阶段都提供 hooks,插件可以在对应位置改变应用行为。
这条流程属于 bub[app]。直接调用 core.Agent.run() 时,Agent 使用你提供的 prompt、state 和 Tape 开始循环。
一条消息经过哪些阶段
Section titled “一条消息经过哪些阶段”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 参考说明首个有效结果、结果合并和优先级。
Agent 在哪里运行
Section titled “Agent 在哪里运行”内置 run_model_stream hook 调用 BubAgent.run_stream()。BubAgent 使用内核的模型与工具循环,并增加设置、skills、命令、运行中消息引导和应用工具策略。
框架负责适配流式和非流式 hook 结果。process_inbound(..., stream_output=True) 让渠道路由器消费增量输出,并在消费结束后返回已完成的 TurnResult。
插件替换 run_model 后,执行行为随之改变。例如,echo 插件可以直接返回文本,不创建 Agent 运行。只有选中的实现实际使用内核 Agent,才会产生相应的核心事件与 Tape 记录。
资源由谁管理,失败如何处理
Section titled “资源由谁管理,失败如何处理”当 hooks 提供存储或其他应用资源时,使用 async with framework.running(): 打开它们,并在退出时释放。内置的单条消息 lifespan 在加载状态时打开,在 save_state 中关闭。
执行到模型阶段后,无论该阶段是否抛出异常,都会运行 save_state。会话解析、状态加载或 prompt 构建失败发生在这个 finally 块之前,因此不会触发它。插件在较早阶段获取资源时,需要考虑这个边界。
内置 save_state 负责关闭单条消息 lifespan。应用会另外记录选定设置,保存其他状态需要明确的持久化方式。
模型阶段抛出未处理异常时,框架先运行 save_state,再跳过正常的渲染与分发。外层错误路径调用 on_error(stage="turn", ...) 后重新抛出异常。内置错误观察器可以通过出站分发发送错误响应。单个 on_error 观察器失败不会阻止其他观察器执行。