Agent Runtime · 四视图与执行流程

入口与三条执行路径

执行接口层向 Runtime 的调用方提供智能体 / 工作流运行 HTTP 接口。收到请求后完成校验、版本解析、历史与环境变量加载，准备执行上下文，再交给 ir_execute() 选择一个顶层 Runner。

Workflow：IRConverter 将 IR 转成 LazyWorkflow 壳对象。首次 invoke / stream 时，壳对象再调用转换器构建完整图，并委托底层 SDK Workflow 推进节点、分支及循环。同一个壳对象后续调用复用已构建的图。

Workflow 的“会话、恢复与流包装”合并三项协作职责：创建 Workflow Session；通过 CheckpointerFactory 查询检查点，并用 InteractiveInput 携带用户输入恢复中断；通过 WorkflowStreamDataWrapper 将执行产生的 chunk 包装为运行事件，再交给外层事件适配与输出。

ReAct：ReActAgent 配置模型、提示词与迭代限制，推进模型判断与工具调用循环。Runner 注册 Plugins、MCP、Skills 及 Workflow 能力，创建执行 Session，并使用 ReactStreamDataAdapter 适配 SDK 流事件。

Controller / PlanExecute：IRConverter 构建或恢复 HierarchicalAgentGroup。组内的 HierarchicalControlAgent 选择成员，通过 StandaloneRunner 调度消息；成员 Agent 的 ControllerMode 或 PlanExecuteMode 决定控制或规划执行策略，随后由 ControllerStreamDataAdapter 适配输出。

如何理解内部小框

小框表示该分支使用的主要组件或聚合职责；ReActAgent、IRConverter、LazyWorkflow、Workflow 和 HierarchicalAgentGroup 是具体类名，“工具与工作流能力”“会话与流适配”“会话、恢复与流包装”“执行策略”是逻辑分组。位置不表示独立进程，也不表示源码专属归属；成员执行策略实际属于 Group 中的成员 Agent。

IRConverter 实现在 Runtime 的 jiuwen 包中，被 Workflow 与 Controller 两条路径复用；ReAct 注册子工作流时也会调用它。图中将其在 ReAct 的用途合并进“工具与工作流能力”。顶层 Runner 择一，并不限制执行过程中组合调用其他能力。

共享能力合并为 4 组：知识库通过适配器接入，长期记忆可关闭或降级，沙箱按配置启用。省略管理、构建、日志与监控等旁路；DeepResearch 在当前执行入口被拒绝，不列为可执行模式。

依赖环与共享边界

agent_runtime.runner 引用 jiuwen 的 IR 加载与转换；jiuwen/ir_converter.py 又导入 runtime 的代码、知识检索、问题交互等节点。此处标的是包级依赖环，不代表每次导入都会报循环导入错误。

共享包完整名称：model_service、storage、common_utils。共享包到 SDK 的边具体由 model_service 提供。

独立服务与 SDK 来源

builder 与 runtime 的互不导入边界有仓库测试约束；两者复用共享能力，不是同一个运行服务。图中省略 builder 的内部依赖及 FastAPI、Pydantic 等通用依赖。

runtime 声明从 agent-core 的 develop 分支安装 openjiuwen；本地 agent-core/ 目录不等于已被当前环境加载的 SDK。

进程内执行

每个 Python worker 运行 FastAPI/Uvicorn 事件循环。Runner 的执行与事件包装是请求内的协程 / 异步生成器调用，模型和工具 I/O 可通过 await 让出事件循环。

每个 worker 在 lifespan 启动一个取消订阅协程，并维护本进程的 conversation_id → Task 注册表。图中合并在 A 这条进程生命线里；并非为每个 Runner 启动新进程。

取消语义与限制

取消接口校验归属后写标记并发布 runtime:cancel；只有持有任务的进程会命中注册表并执行 task.cancel()。HTTP 接受响应不保证任务已停止，广播与响应的先后可变化。

正常完成会在流末尾发送唯一 done；运行中被取消的 SSE 无 done，finally 注销。此图针对注册过的流式执行，不扩展为阻塞调用或单节点调试的统一保证。默认 Kubernetes 模板只有 1 个 Python worker，此时执行与取消请求由同一进程处理。

模板的实际值

replicas=1，NodePort / Service / targetPort 均为 31014，HTTPS 关闭。镜像标签取自 YAML。启用 Nginx 负载均衡后，启动脚本以 PORT+i 启动 Python worker：当前 worker 监听 0.0.0.0:31015，Nginx 经 127.0.0.1:31015 转发并关闭 SSE 缓冲。

CPU/内存 requests 与 limits 都为 2 CPU / 4 Gi；/dev/shm 为 2 Gi 的内存 emptyDir。健康探针走 31014；不代表生产容量或高可用承诺。

未声明的位置与合并项

Redis 主机、对象存储 endpoint 等需部署时填写。右侧只表示配置依赖，不能据此认定它们位于集群外或同一命名空间。HTTP(S) 的端口取各 endpoint；并未假设统一为 443。

模型、MCP 和可选沙箱合为一个端点组；OpenSearch 只用于可选长期记忆。省略 manager、builder、console、监控与代码执行子进程。Docker Compose 是另一套部署方案，未混入此图。

从流程反看逻辑模块

01 对应执行接口层；02、09 对应请求编排与模式分发。03 对应 Workflow 框内的 IRConverter；06、07 对应 LazyWorkflow / Workflow；04、05、08 及交互分支 对应会话、恢复与流包装；10 对应事件适配与输出。共享能力由具体节点按需调用，不是执行链末尾的串行步骤。

图展示实际执行及事件传递顺序。异步生成器与 EventHandler 的外层包装会提前建立，消费流时才驱动内部执行；因此不能把 08—10 理解为等待全部节点完成后的三个处理步骤。图未表示进程边界。

Workflow HTTP 入口构造的内部请求固定使用 streaming。调用方设置 stream=false 时，EventHandler 消费内部事件流并汇总 JSON；并不因此选择另一个 Runner。

恢复、取消与本图范围

交互中断由工作流检查点机制保存状态。下一次请求仍经过入口、分发、IR 转换与会话准备，随后通过 InteractiveInput 恢复检查点；不是让原来的 HTTP 请求一直等待。新请求可创建新的 LazyWorkflow 壳对象，图实例化后由检查点机制恢复执行状态。

stream_response 在内部事件流结束时发送唯一的末尾 done，并在 finally 中注销当前执行任务；done 是本轮流的结束信号，不单独证明业务工作流成功完成。运行中被取消时，原流没有 done，finally 仍注销。检查点已被取消的会话不会按 05B 正常续跑，Runner 会清理相应状态并按新执行处理。

为突出核心步骤，入口校验失败、输入审核拦截、IR 构建失败、节点异常与取消的独立分支合并为本说明。这些路径可能提前返回或中止，不保证走完整条主线。模型、工具、知识库及可选记忆不逐一展开；单节点调试与其他 Runner 不在本图范围。

调用与消费的先后

ir_execute() 返回内部 StreamingResponse 后，接口先建立 EventHandler 外层包装。真正消费外层 body iterator 时，内部异步生成器才持续推进 Runner。因此“事件适配与输出”在执行前已接入，在执行中持续处理结果。

03—07 合并了多次调用和 Runner 自身的准备动作，下一张图展开 IR 转换、输入分支与延迟构图。生命线表示逻辑调用角色，不是不同进程；激活条表示本段交互仍在进行，不表示持续占用 CPU。

本轮流结束的含义

这里展示外部 stream=true。外部设置 stream=false 时，EventHandler 同样消费内部流，但在最后汇总 JSON；不会逐帧把 SSE 发给调用方。

“末尾 done / 注销”合并两个相邻收尾动作：编排层先发内部唯一末尾 done，随后在 finally 注销执行。内部 done 还会经过 EventHandler 协议映射，不应理解为对外原样透传。取消时原流无 done，finally 仍执行。交互挂起时本轮结束也不代表整个工作流完成。

与三个内部小框的对应

调用 IRConverter 对应“IRConverter”小框；查询检查点、构造输入与会话对应“会话、恢复与流包装”；LazyWorkflow 与 SDK Workflow 对应“LazyWorkflow / Workflow”。Runner 会先读取 IR、提取节点定义，本图合并其本地准备过程。

“会话与检查点”合并会话创建辅助函数、CheckpointerFactory 及执行 / 追踪标识存储，不表示它们属于单一类。取消标记另由 Runner 查询；普通 inputs 或 InteractiveInput 由 Runner 本地构造，写在 ALT 条件中。

延迟构图与共享能力

LazyWorkflow.instantiate() 首次使用时回调 IRConverter.build_openjiuwen_workflow_from_ir() 构建 SDK Workflow。壳对象缓存该实例，同一对象后续调用复用；新 HTTP 请求不保证复用同一个壳对象。

模型、工具、知识记忆等共享能力由具体节点按需调用；本图将它们合并在 SDK Workflow 的执行中。这里只画第一个 chunk，主图的 LOOP 表示后续持续返回。已有检查点被取消时会进行状态清理，不进入正常恢复分支。

恢复的是执行状态

原请求收到交互问题后结束；用户提交答案时仍经过入口校验、模式分发、IR 转换、会话与输入准备。这里将这些重复准备合并为两条调用，细节见前两张图。

Runner 使用 req.resume_input or req.query 构造 InteractiveInput，检查点机制恢复中断位置；不会让已经完成的前置业务节点正常重跑一遍。新的 LazyWorkflow 可以重新构建图结构，图结构重建与业务节点重跑是不同的动作。

范围与异常

这张图只展示检查点有效且未被取消的正常续跑。检查点缺失、已取消、输入无效、节点执行失败等路径可能转为新执行或提前退出，没有画成这条成功路径的一部分。

整个页面合并了存储读取、具体工具 / 模型调用、可选记忆和日志细节。三张图共同覆盖主流程、首次 / 恢复输入以及挂起后的新请求，均沿用当前工作区源码结论。