Agent Runtime · 四视图

五条生命线：分别代表哪些参与者

图中从左到右有五个参与者：

A、B 是本次交互中的角色名称。它们运行同一类 Runtime 服务代码。某个进程这次接到执行请求，下次也可以接到取消请求，没有固定分工。

如何阅读时间与消息

• 竖向虚线是参与者的生命线，时间从上往下推进。
• 横向箭头表示调用、返回或通知，具体线型由图底部图例说明。
• 橙色箭头突出向调用方发送 SSE 的主响应。
• OPT 框表示可选情形：只有执行期间发生取消，才走这段流程。

模型调用、片段返回和 SSE 输出在实际运行中可能重复很多次，图中只画了一组代表性消息。

进程、worker、Runner、Task：各自处于什么层次

在当前 Agent Runtime 中，一个 worker 就是一个负责处理请求的 Python 工作进程。“进程”强调操作系统中的运行单位，“worker”强调服务中承担工作的角色。

选择 WorkflowRunner 后，通常是在当前 worker 内调用它的异步方法，继续完成 IR 转换、Session 准备和工作流执行。选择某个 Runner，不会因此启动一个新的 Python 进程。

一个 worker 内可以同时有哪些任务

• 请求 1 的任务：等待模型返回。
• 请求 2 的任务：调用工具。
• 请求 3 的任务：处理取消请求。
• 后台任务：持续订阅 Redis 的取消通知。

这些任务由同一进程的事件循环调度。某个任务等待支持异步操作的模型或工具 I/O 时，可以通过 await 让出执行机会，让其他就绪任务继续运行。一个 worker 因而可以同时处理多个等待外部响应的请求。

请求数量、Task 数量和进程数量是三回事。收到新请求通常不会新建进程；一个请求也可能在内部创建多个 Task。CPU 密集计算或同步阻塞调用能否并行，要看具体实现。

多 worker 时，A、B 可以是两个独立 Python 进程，B 无法直接操作 A 内存中的 Task，因此需要 Redis 传递信号。单 worker 时，两次请求由同一 Python 进程中的不同任务处理。

worker 是通用角色名称，在其他系统中也可能由线程承担。这里的 Runtime worker 特指 Python 工作进程；其数量也不等于容器的进程总数，容器里还可能运行 Nginx 等进程。

源码：agent-runtime/agent_runtime/EIStart_base.py:9,45；agent-runtime/agent_runtime/serve/server.py:196。

正常执行链：请求进入 A 后发生什么

图中上半部分描述正常执行，可以依次看六个动作：

1. 调用方向 A 发起执行请求。入口准备输入和上下文，编排层选择一个顶层 Runner。逻辑视图中的这些模块，在进程视图里都合并到了 A 的生命线上。
2. A 登记本次执行。进入已注册的流式执行链路时，代码取得当前 asyncio.Task，登记它与会话、执行归属之间的关系，为后续取消提供定位依据。
3. A 调用模型或工具。Runner 推进业务执行，按需发起模型调用、工具调用、知识检索等操作。
4. 外部端点返回 chunk。这是一次返回的数据片段，可能是模型输出的一部分，也可能是工具执行结果；它不一定对应一个 token，也不一定是最终对外的 SSE 格式。
5. A 包装事件并发送 SSE。流适配、事件包装和 EventHandler 在 worker 内处理执行信息，整理成调用方可消费的事件。
6. 执行结束后注销登记。正常执行结束会走流的收尾逻辑；无论正常退出还是被取消，代码都通过 finally 尝试注销本次执行。

请求处理 → Runner 执行 → 模型与工具交互
→ 事件转换 → 响应输出 → 清理

A 的一条生命线合并了这些职责，它们并不分别对应独立进程。实际流式运行时，模型或工具交互、事件转换和响应输出会随着执行推进持续发生。

源码：agent-runtime/agent_runtime/serve/apis/orchestration.py:339；agent-runtime/agent_runtime/event_handler/event_handler.py:151,187,194。

为什么同时需要本地注册表和 Redis

执行登记采用两层结构，两层保存的东西不同。

本地注册表：保存真正的 Task 对象

conversation_id → 当前进程中的执行 Task

Python Task 存在于当前进程内存中。worker B 无法直接读取 worker A 的这张表，也无法直接操作 A 内存里的对象。

Redis：保存跨进程可见的信息

suspend 保存的是归属信息，完整的工作流恢复状态由检查点机制管理。

Redis 让各进程知道“哪个会话被取消”；本地注册表让持有任务的进程找到“该取消哪个 Task”。每个 worker 在服务启动的 lifespan 中创建一个长期运行的取消订阅任务，收到广播后查询自己的本地表。

图中的 Redis 通道承担取消通知；模型输出沿着 A 到调用方的响应链返回。

源码：agent-runtime/agent_runtime/serve/execution_registry.py:77,132,194,216,226；agent-runtime/agent_runtime/serve/server.py:196。

跨 worker 取消：B 如何让 A 停止执行

假设用户已经在接收 A 返回的 SSE，此时点击“停止”。取消操作是另一个 HTTP 请求，它可能被负载均衡分发到 B，而原来的 SSE 请求仍由 A 处理。

图中 OPT 区域可以展开为八个动作：

1. 调用方向 B 发送取消请求。完整路由是 POST /v1/{project_id}/conversations/{conversation_id}/cancel，图中简写为 POST /cancel。
2. B 查询 Redis 中的执行登记。找到这个会话当前的执行归属。
3. B 校验归属。校验路径中的项目；如果调用方提供了 Agent 或 Workflow 标识，还会校验对应入口。校验不通过则返回错误，不写取消标记。
4. B 写入取消标记并发布通知。将 cancel:{conversation_id} 置为真，同时向 runtime:cancel 频道发布会话标识。
5. B 返回接受结果。响应表示取消信号已被接受。
6. 各 worker 的订阅任务收到广播。每个 worker 查询自己的本地注册表，没有对应 Task 的进程忽略通知。
7. 持有任务的 A 调用 task.cancel()。取消作用于承载执行的异步任务。
8. 执行链退出并进行清理。流式执行的 finally 注销本地与共享的执行登记。

B 返回 HTTP 响应与 A 实际收到广播之间，没有固定的先后保证。图里画的是一种可能的交错顺序。

源码：agent-runtime/agent_runtime/serve/apis/orchestration.py:491；agent-runtime/agent_runtime/serve/execution_registry.py:194,216,226。

“取消已接受”与“执行已停止”有什么区别

取消接口返回 cancel signal accepted 时，说明取消标记和信号已经提交。它没有等待所有执行工作及外部操作都停止后，再返回确认。

如果没有执行登记，也没有可用于校验的归属快照，接口可以返回 HTTP 200，同时给出 cancelled: false、running: false 和“没有找到会话、未执行取消”的说明。HTTP 状态码本身不足以判断实际取消结果。

Task 如何响应取消

task.cancel() 采用异步任务的协作式取消机制：任务在可响应取消的位置收到 CancelledError，随后执行异常传播与清理代码。

• 正在等待异步 I/O 的任务通常能响应取消。
• 同步阻塞或长时间占用事件循环的代码，会影响响应速度。
• 子任务需要正确传播取消。当前 Controller 控制链会显式取消正在执行的成员任务。
• 本地停止等待外部调用，并不自动撤销外部服务已经完成的操作；能否停止远端处理，取决于客户端与远端协议。

图对应的内部流封装在正常走到流末尾时输出唯一的终态 done；被取消打断时，不会走到这段正常收尾逻辑。客户端还需要结合错误、挂起事件和外层协议判断业务结果，不能把所有连接结束都当作成功完成。

源码：agent-runtime/agent_runtime/serve/apis/orchestration.py:339,491；agent-runtime/jiuwen/multi_agent/agent_group/hierarchical_group/control_agent.py:124。

运行、挂起和取消：为什么恢复时还要读 Redis

“工作流等待用户输入”和“用户点击停止”是两种不同情况。

工作流挂起后，原来的请求已经结束，通常没有一个旧 Task 一直留在 worker 内等待用户回答。用户回答时，需要发起新的请求。Runtime 根据会话检查持久化状态，再创建本次执行所需的对象，通过恢复输入继续工作流。

挂起期间可能没有可取消的运行 Task，但仍然需要保存“用户已经取消这次挂起执行”的意图。因此取消除了广播，还要保留持久化标记。

当前 Workflow 路径会检查这个状态：

• 存在有效中断检查点，且未取消：使用 InteractiveInput 恢复。
• 存在中断检查点，但已经取消：尝试清理旧检查点，清理成功后从入口重新执行；清理失败时保留取消标记，避免静默恢复旧状态。

广播用于尽快通知正在运行的任务，持久化标记用于让后续执行仍能识别取消意图。

源码：agent-runtime/agent_runtime/runner/workflow_runner.py:264,371,480；agent-runtime/agent_runtime/runner/fast_redis_checkpointer.py:168。

一个 Runtime 有多少个 worker，图中的 A、B 如何对应部署

图中画出 A、B，是为了说明多 worker 场景下的协作机制。按当前仓库默认配置，一个 Runtime 实例启动 1 个 Python worker，可以配置成多个。

如果“一个 Runtime”指一个 Pod 或容器实例，其 Python worker 数量由 GUNICORN_WORK_NUM 配置，默认是 1。如果指整个 Runtime 服务，则还需要计算实例副本数。

按这个 Kubernetes 模板启动时，整个 Runtime 服务有 1 个处理请求的 Python worker。执行请求和取消请求可以由同一进程内的不同异步任务处理，A、B 两种角色就落在同一进程中。以上是仓库配置，实际运行数量还要看部署时是否覆盖了环境变量。

实例数与 worker 数可以分别调整

Python worker 总数 = Runtime 实例数 × 每个实例的 worker 数

示例：3 个实例 × 每个实例 4 个 worker = 12 个 Python worker

这个公式适用于每个实例采用相同 worker 配置的情况；配置不同的实例需要分别求和。增加 worker 或实例后，两次请求可能进入不同进程，Redis 广播与本地 Task 注册表的配合就能发挥跨进程作用。

当前代码支持两种启动方式

• 关闭 Nginx 模式：由 Uvicorn 启动配置数量的 worker。
• 开启 Nginx 模式：启动脚本拉起多个独立 Python 服务，每个服务内部只运行一个 Uvicorn worker，再由 Nginx 分发请求。

因此，配置为 4 时，目标是 4 个 Python worker。Nginx 启动脚本先保存目标数量，再将每个子服务的 worker 数设置为 1，避免重复扩出多层工作进程。

这张图的适用范围

它展示已接入执行注册的流式执行链路。应用接口即使最终返回 JSON，也可能在内部走这条链路；直接阻塞执行和单组件调试是否具备同样的取消行为，需要分别看对应实现。

如果 A 进程退出，它内存中的 Task 也随之消失。Redis 中的登记和检查点不会把 Task 自动迁移到 B；后续恢复依赖新的请求和有效持久化状态。

源码：deploy/k8s/studio-runtime.yaml:7,149,201；agent-runtime/agent_runtime/common/config.py:29；agent-runtime/agent_runtime/EIStart_base.py:9,45；docker/studio-runtime/script/start_nginx_lb.sh:17,26。

一个 worker 可以承担多少并发，怎样得到可信的容量数字

一个 worker 可以通过异步任务同时处理多个请求，但目前没有经过容量压测确认的“单 worker 最大并发数”。它尤其适合模型调用、工具调用这类包含大量 I/O 等待的工作。

需要区分三个数字：实例数、每个实例的 worker 数、每个 worker 的请求并发数。前两个主要由部署配置确定，第三个与任务负载、资源和可接受的延迟、错误率有关。

同时接收请求与稳定服务请求，衡量的是不同能力

当前 uvicorn.run() 的启动代码没有显式设置 limit_concurrency。这说明启动入口没有配置一个固定的请求并发限制，不能据此认定容量无限。

两个配置数字不能直接当作业务并发数

• worker_connections 1024：是 Nginx 的连接限制，不代表一个 Python worker 能稳定运行 1024 个工作流。
• Redis 默认连接池大小 50：是 Redis 连接数量，不代表最多支持 50 个用户请求。

如何得到可靠的并发容量

1. 固定测试条件。确定 CPU、内存、worker 数、模型端点，以及有代表性的工作流或 Agent 任务。
2. 逐级增加并发。记录同时执行的请求数，并保持测试条件可比较。
3. 观察服务质量与瓶颈。检查首个输出延迟、总耗时、错误率、CPU、内存，以及下游限流情况。
4. 按服务目标确定容量。选择仍满足延迟和错误率要求的稳定并发水平。

最终应得到带条件的结论：“在指定 CPU、内存、模型和工作流配置下，单个 worker 在满足延迟与错误率要求时，能稳定承载 N 个并发请求。”

源码：agent-runtime/agent_runtime/EIStart_base.py:45；docker/studio-runtime/script/start_nginx_lb.sh:99；packages/common_utils/common_utils/common_config.py:62；packages/common_utils/common_utils/redis_manager.py:108。