Agent Runtime Architecture
The agent runtime is the execution machinery that runs an agent loop: build context, call a model, dispatch tools, persist state, enforce guards, stream events, and resume or halt safely.
Boundary
The runtime is the layer under the Agent Harness. A harness is the usable agent product. A runtime is the engine that makes a run advance from one state to the next.
| Layer | Primary question |
|---|---|
| Agent Harness | What working environment and rules does the agent operate inside? |
| Agent runtime | How does one agent run execute correctly and resumably? |
| Agent Control Plane Architecture | How are many agents provisioned, routed, observed, scheduled, and governed? |
This distinction prevents architecture soup. Cursor, Claude Code, Codex, Hermes, and OpenClaw are harnesses. LangGraph, OpenAI Agents SDK runners, graph executors, sandbox runners, and workflow engines are runtime shapes.
Core components
| Component | Contract |
|---|---|
| Run/session store | Owns run identity, step state, checkpoints, messages, artifacts, and resumability. |
| Context builder | Selects instructions, memory, files, retrieval results, tool schemas, and current state. |
| Model router | Chooses model/provider and normalizes streaming, tool-call, and structured-output semantics. |
| Tool dispatcher | Validates arguments, checks permission, invokes the tool, and returns bounded observations. |
| Sandbox adapter | Executes untrusted or stateful work in an isolated environment. |
| Guardrail engine | Blocks or redirects unsafe input, output, or actions before side effects happen. |
| Handoff router | Delegates to another agent, subgraph, human, or remote service. |
| Trace emitter | Emits spans/events for model calls, tools, handoffs, guardrails, approvals, and custom steps. |
| Verifier | Runs tests, evals, doctors, screenshots, or task-specific success checks. |
Runtime invariants
- Every run has a stable ID and durable event log.
- Tool calls are validated before execution.
- Side-effecting steps are idempotent or explicitly non-retryable.
- Human approvals survive process lifetime.
- Context assembly is reproducible enough to debug.
- Observations are token-bounded and structured.
- Completion requires evidence, not agent confidence.
These are the same invariants behind Durable Agent Execution Architecture, Tool Execution Runtime Architecture, and Agent Guardrails Architecture.
IRL comparison
| Runtime | What it proves | Notes |
|---|---|---|
| LangGraph | Explicit graph/state runtime for long-running stateful agents | Official docs describe durable execution, streaming, human-in-the-loop, persistence, and deployment as first-class runtime features. Source: LangGraph docs, https://docs.langchain.com/oss/python/langgraph/overview, 2026-06-18 |
| OpenAI Agents SDK | Code-first runner with agents, handoffs, guardrails, sessions, and tracing | Tracing records model generations, tool calls, handoffs, guardrails, and custom spans by default. Source: OpenAI Agents SDK tracing docs, https://openai.github.io/openai-agents-python/tracing/, 2026-06-18 |
| Vercel AI SDK / AI SDK HarnessAgent | App-facing abstraction over complete harness runtimes | Useful when a product embeds a coding agent without reimplementing each harness API. |
| Agent Machines | Persistent worker runtime on isolated machines | Treats runtime plus substrate plus skills plus schedules as a deployable worker. |
The 2026 trend is not one universal runtime. It is runtime specialization with adapter layers: graph runtimes for explicit workflow control, SDK runners for app integration, sandbox runtimes for code execution, and product harnesses for day-to-day operator UX.
Failure modes
| Failure | Typical cause | Fix |
|---|---|---|
| Run cannot resume | State lives in process memory only | Persist run log, checkpoints, and artifacts |
| Tool result poisons context | Dispatcher returns raw dumps | Marshal summaries, pagination, and structured observations |
| Agent repeats failed action | No idempotency key or failure memory | Persist step result and retry policy |
| Human approval is lost | Approval tied to a live socket | Store pending approval as durable state |
| Debugging is impossible | No trace spans or artifacts | Emit trajectory traces and keep artifact URLs |
| Completion is fake | Runtime trusts final answer | Run verifier/evaluator before marking done |
Kevin-stack implication
For Kevin's projects, runtime architecture should be explicit in any agent product spec:
- If the work lasts longer than one request, use durable run state.
- If tools mutate the world, define permission and idempotency.
- If quality matters, emit traces and feed them into Agent Trajectory Evaluation.
- If runtime choices overlap, route through Capability Routing Map rather than picking the fashionable SDK.
Architecture Position
| Axis | Value |
|---|---|
| Family | Agent runtime and control plane |
| Boundary owned | One agent run: context, model call, tool dispatch, state, trace, verifier, resume/halt. |
| Read with | Agent Harness Architecture, Agent Control Plane Architecture, Durable Agent Execution Architecture |
| Use this page when | designing the engine that advances one agent run |
Timeline
-
2026-07-01 | Architecture category refresh added this page to the Agent runtime and control plane family, linked it to Architecture System Map, and kept it standalone because it owns this boundary: One agent run: context, model call, tool dispatch, state, trace, verifier, resume/halt. Source: User request, 2026-07-01
-
2026-06-18 | Created as the missing architecture layer between concrete harness pages and tool-execution runtime pages. Source: whole-wiki graph audit, 2026-06-18