Architecture
KsADK's public architecture is an Agent Runtime Platform layer. You keep building business agents with your chosen framework, while KsADK unifies runtime, debugging, protocols, tools, sandboxing, deployment, and observability.
Overview
The diagram above shows KsADK's three-layer architecture: business Agent frameworks (user-provided) → KsADK Runtime data plane (core) → hosted control plane. KsADK layers runtime, debugging, protocols, tools, sandbox, deployment, and observability on top of your chosen Agent framework, while business logic stays in your framework code.
Key boundary
KsADK owns "how the agent runs", not "what it does". Agent logic, prompts, and domain tools stay in your framework code; runtime, sessions, tool protocols, deployment, and observability are handled by KsADK.
Main Boundaries
| Layer | Responsibility |
|---|---|
| Agent frameworks | business orchestration, state, tool calls, and model interaction |
| KsADK CLI | project creation, config loading, local runs, Web UI startup, packaging |
| Runner | adapt ADK, LangGraph, LangChain, and DeepAgents to one invocation contract |
| Local server | expose /v1/responses, /v1/chat/completions, and local Web UI APIs |
| Toolsets | provide Skill, Workspace, Platform, and Sandbox tool entrypoints |
| AgentEngine / Hermes / OpenClaw | remote runtime, deployment, and fuller backend execution |
| OpenTelemetry | standard tracing output for external observability systems |
Local Runtime Path
The flow when you run agentengine run or agentengine web:
- The CLI resolves the project directory,
.env, andagentengine.yaml. - Framework detection identifies ADK, LangGraph, LangChain, or DeepAgents.
- The runner factory creates the matching runner.
- The runner loads the user agent.
- The terminal, Web UI, or OpenAI-Compatible API invokes the runner.
- Sessions, attachments, workspace files, tool calls, and tracing use the KsADK runtime path.
Sessions, attachments, workspace, and tracing all flow through the same KsADK runtime path — local and remote behavior match, so you can debug locally and migrate to the hosted runtime seamlessly.
Why This Architecture Matters
The boundary lets teams keep their preferred agent frameworks while sharing:
- one local command surface.
- one browser debugging experience.
- one OpenAI-Compatible API surface.
- one Skill / Workspace / Sandbox tool model.
- one deployment and observability path.
For lower-level implementation details, see Runtime Architecture.