Runtime Architecture

KsADK local runtime has one central job: load a user agent project, adapt the selected framework to a common runner interface, and expose predictable local protocols for terminal, browser, and API clients.

Layer Model

Entry → Boot → HTTP/UI → Conversations Runtime → Runner → Session persistence → 0.6.7 Run capability layer. The important boundary is that the HTTP server and conversation runtime do not need to know whether the user project is ADK, LangGraph, LangChain, or DeepAgents. They call BaseRunner.invoke() or BaseRunner.stream().

Core Packages

Startup Lifecycle

agentengine run and agentengine web follow the same broad path:

Startup Boundaries

The local runtime has a strict startup boundary:

For public examples, keep project setup explicit:

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

Explicit configuration reduces ambiguity in CI and makes the same project work the same way under agentengine run, agentengine web, local API tests, and packaging checks.

Framework Detection

Detection uses explicit configuration first, then convention:

The convention-based fallback is still useful for quick experiments. It checks common project layouts such as:

• a root agent.py, main.py, or app.py.
• a package directory with agent.py, main.py, app.py, or __init__.py.
• a src/<package> layout.
• langgraph.json graph targets.

Runner Contract

Every runner implements the same conceptual contract:

This contract is intentionally narrow. Framework-specific behavior belongs in the adapter, not in the FastAPI endpoint.

The narrow contract also defines where custom behavior should live:

Request Lifecycle

A normal non-streaming /v1/responses request follows this path:

Streaming uses the same preparation path, then serializes internal semantic events into server-sent events. Text deltas, reasoning, tool calls, tool results, approval interrupts, final output, and errors are represented as runtime events before they become protocol-specific SSE payloads.

Streaming Event Model

Streaming output is normalized before it is serialized. Framework adapters may emit very different native events, but the conversation runtime expects a small set of semantic chunk types:

The protocol layer then maps those semantic events to /v1/responses, /v1/chat/completions, /run_sse, or the local Web UI action format. This is why application code should not depend on a specific SSE event name unless it is writing a client for that exact public protocol.

Model Policy And Thinking Semantics

Whether a thinking chunk appears, and how reasoning content is injected, is decided by the runtime's unified model policy and thinking-disable injection semantics (unified from 0.6.6, disable injection completed in 0.6.7):

• Unified model policy: hosted deployments inject primary / multimodal / fallback defaults through AGENTENGINE_MODEL_POLICY_JSON, shared by Hermes, OpenClaw, and generic agents. Explicit request parameters or explicit environment variables still take precedence over policy defaults.
• Fallback retry: the conversation runtime automatically retries once with the fallback model on recoverable errors such as timeouts, rate limiting, 5xx, model unavailability, or permission/quota errors. 400 parameter errors, business errors, and tool errors are not swallowed. When fallback triggers, the next streaming turn may switch to the fallback backend, and whether a thinking chunk appears depends on the target model's capability.
• Thinking-disable injection: when model_options.thinking is disabled (reasoning.effort=none, thinking.type=disabled, or max_reasoning_tokens<=0), the runtime automatically injects enable_thinking=false and chat_template_kwargs.enable_thinking=false into extra_body (compatible with DeepSeek-style models) and filters reasoning output items from the stream, so no thinking chunk is emitted over SSE.

For the policy JSON structure, catalog fields, and injection details see Environment Variables.

Session And Context Boundary

Every turn builds a PlatformInvocationContext before calling the runner. It contains the stable identifiers and runtime facts a framework adapter may need:

• agent_id, user_id, session_id, and invocation metadata.
• normalized input content and message history.
• effective attachments and current-turn attachments.
• model, model metadata, and model options.
• knowledge and memory context when those integrations are enabled.

The runner receives this context as part of the prepared input. Business logic should prefer the documented runner payload fields and framework hooks over reading private server globals. That keeps local terminal runs, Web UI runs, and OpenAI-compatible API calls aligned.

Checkpoint, Resume, And Cooperative Cancel

Run-level checkpoint, resume, and cancel sit on top of the session store and framework checkpoint backend, as a capability layer independent of streaming chunks. The conversation runtime writes a run_status event on every turn and exposes recovery and cancel entry points at checkpoint boundaries:

CancelRun is a cooperative cancel: the runtime observes the cancel request at the next runner cooperation point (for example the next streaming chunk, a tool call boundary, or an interrupt checkpoint), stops the run, writes run_status=cancelled, and preserves already-produced checkpoints and events for later resume where possible. It does not hard-kill the process or discard already-persisted turns.

Resume capability is gated by both RuntimeCapabilities.ResumeRun.ResumeMode and RunLifecycle returned from GetAgentUiBootstrap (time_travel / forward_only / none); the frontend entry point must satisfy both RunLifecycle.Checkpoints and RunLifecycle.CheckpointResume before being shown.

For the full action paths, ResumeMode semantics, SubscribeRunEvents replay, and the 5-minute server protection timeout see Sessions And Files.

Local Protocol Entrypoints

Public Documentation Boundary