运行时架构

KsADK 本地运行时的核心职责是：加载用户 Agent 项目，把所选框架适配到统一 Runner 接口，并为终端、浏览器和 API 客户端暴露可预测的本地协议。

分层模型

入口 → 启动 → HTTP/UI → 对话运行时 → Runner → Session 持久化 → 0.6.7 Run 能力层。关键边界是：HTTP server 和对话运行时不需要知道用户项目是 ADK、LangGraph、LangChain 还是 DeepAgents，它们调用 BaseRunner.invoke() 或 BaseRunner.stream()。

核心包

启动生命周期

agentengine run 和 agentengine web 大体路径一致：

启动边界

本地运行时有严格启动边界：

公开示例应保持项目配置明确：

name: support-agent
framework: langgraph
entry_point: agent.py
agent_variable: root_agent

框架检测

检测优先使用显式配置，再使用约定：

约定检测仍适合快速实验。它会检查：

• 根目录 agent.py、main.py 或 app.py。
• 包目录中的 agent.py、main.py、app.py 或 __init__.py。
• src/<package> 布局。
• langgraph.json graph target。

Runner 契约

每个 Runner 都实现同一组概念契约：

这个契约刻意保持窄。框架特定行为留在 adapter 中，而不是塞进 FastAPI endpoint。

请求生命周期

普通非流式 /v1/responses 请求路径：

Streaming 使用同样的准备路径，再把内部语义事件序列化为 server-sent events。文本 delta、reasoning、tool call、tool result、approval interrupt、final output 和 error 会先成为运行时事件，再成为协议特定 SSE payload。

Streaming 事件模型

框架 adapter 可能发出很不同的原生事件，但对话运行时期待一小组语义 chunk：

协议层随后把这些语义事件映射到 /v1/responses、/v1/chat/completions、 /run_sse 或本地 Web UI action 格式。

模型策略与 thinking 语义

thinking chunk 是否出现、以及 reasoning 内容如何注入，由运行时的统一模型策略和 thinking disable 注入语义共同决定（0.6.6 起统一，0.6.7 补全 disable 注入）：

• 统一模型策略：托管部署通过 AGENTENGINE_MODEL_POLICY_JSON 注入 primary / multimodal / fallback 默认值，Hermes、OpenClaw 和通用 Agent 共用同一套语义；显式 请求参数或显式环境变量仍优先于策略默认值。
• fallback 重试：conversation runtime 对超时、限流、5xx、模型不可用、权限/配额等 可恢复错误自动 fallback 重试一次；400 参数错误、业务错误和 tool 错误不会被吞掉。 fallback 触发时，下一轮 streaming 可能切换到 fallback backend，thinking chunk 是否出现以目标模型能力为准。
• thinking disable 注入：当 model_options.thinking 为 disabled （reasoning.effort=none、thinking.type=disabled 或 max_reasoning_tokens<=0） 时，runtime 自动向 extra_body 注入 enable_thinking=false 和 chat_template_kwargs.enable_thinking=false（DeepSeek 等模型兼容），并在流式输出 中过滤 reasoning 类 output item，因此 thinking chunk 不会出现在 SSE 流中。

具体的策略 JSON 结构、catalog 字段和注入细节见 环境变量参考。

Session 与上下文边界

每个 turn 在调用 Runner 前都会构造 PlatformInvocationContext。它包含框架 adapter 可能需要的稳定标识和运行时事实：

• agent_id、user_id、session_id 和 invocation metadata。
• 规范化输入内容和消息历史。
• 当前 turn 附件和最近有效附件。
• model、model metadata 和 model options。
• 启用时的知识库和记忆上下文。

Runner 会把这个 context 作为准备后输入的一部分收到。业务逻辑应优先读取公开文档中的 runner payload 字段和框架 hook，而不是读取私有 server globals。

Checkpoint、Resume 与协作式取消

Run 级 checkpoint、resume 和取消建立在 session store 与框架 checkpoint backend 之上， 是独立于 streaming chunk 的能力层。conversation runtime 在每个 turn 写入 run_status 事件，并以 checkpoint 为边界暴露恢复与取消入口：

CancelRun 是协作式取消：runtime 在下一个 runner 协作点（如下一个 streaming chunk、tool call 边界或 interrupt 检查点）观测到取消请求后停止 run，写入 run_status=cancelled，并尽可能保留已产出的 checkpoint 与事件供后续 resume。它不会 强杀进程或丢弃已持久化的 turn。

resume 能力受 GetAgentUiBootstrap 返回的 RuntimeCapabilities.ResumeRun.ResumeMode 与 RunLifecycle 双重门控（time_travel / forward_only / none）；前端入口必须 同时满足 RunLifecycle.Checkpoints 与 RunLifecycle.CheckpointResume 才能展示。

完整的 action 路径、ResumeMode 语义、SubscribeRunEvents 续订与 5 分钟服务端保护 超时见 会话与文件。

本地协议入口

公开文档边界