The Runtime Abstraction Layer: Swap the Model, Keep the Mind

One manager, six runtimes, one contract

AdapterManager owns the lifecycle of every model runtime attached to Agentis: registration, task dispatch, cancellation, inbound event bridging, and per-runtime health. Six concrete adapters ship today — ClaudeCodeAdapter, CodexAdapter, CursorAdapter, HermesAgentAdapter, AntigravityAdapter, and a generic HttpAdapter for any HMAC-authenticated custom endpoint — and the orchestration engine never touches any of them directly. It calls one method, dispatchTask(task, agentId), and gets back a normalized stream of thoughts, tool calls, and results regardless of which runtime is actually behind that agent.

What actually stays put when you swap

An agent's row in the agents table, its memory episodes, and its skill atoms are keyed by the agent's own id — never by adapter type. Change the adapterType on an existing agent and every memory it ever formed, every skill it ever earned, and every habit reinforced through repeated success is still there on its very next turn. The new runtime doesn't get a fresh identity; it inherits the old one's mind.

Runtime switching is a controlled operation

agentis.agents.runtime.switch changes the execution runtime for an existing agent while preserving its identity, Brain, skills, workflow seats, and sessions. Agentis waits briefly for a detected runtime to become healthy, checks the requested model and capabilities, and can select a compatible healthy fallback when the requested runtime cannot be started. If no compatible runtime is available, the operation reports the blocker and leaves the agent unchanged.

Native parity is an explicit runtime profile

Running a model binary outside the Agentis process does not inherently make the model weaker. The loss happens when the surrounding harness changes invisibly: a different project root, missing user or project instructions, absent plugins or skills, disabled browser access, a new session policy, or a stricter permission boundary. RuntimeProfileV2 makes those inputs explicit. It selects native, hermetic, or containerized execution and pins the project root, permission profile, inherited configuration and instructions, plugins, skills, browser policy, and persistent-or-ephemeral session policy.

Every turn leaves an execution envelope

Each dispatch persists an AgentExecutionEnvelope: adapter and binary, CLI version, working directory, model, reasoning effort and service tier, browser and permission state, loaded user/project/Agentis sources, MCP server count, the resolved runtime profile, and capability warnings. The envelope is the receipt for what actually ran. When two turns behave differently, an operator can compare facts instead of guessing which invisible harness feature disappeared.

Parity is measured, not assumed

pnpm eval:runtime-parity runs the same black-box fixture corpus through a native harness and Agentis, then compares paired scores. The default gate requires every fixture to be paired and rejects an Agentis aggregate delta below -0.05. --allow-unpaired exists only for smoke testing; it is not parity evidence.

Guarding against a bad host

A global semaphore caps concurrent runtime process dispatches across every run and swarm at once (default 128, override with AGENTIS_MAX_CONCURRENT_PROCESSES), and each adapter type is wrapped in its own circuit breaker — so one flaky runtime backing off doesn't starve or crash the others. Runtime health is introspectable per adapter, not just platform-wide.

The mechanics of routing a task to the right runtime — capability matching, model-tier selection, session continuity — get their own full treatment in Agents & Cognition. This page is the ownership argument; that one is the engineering.

Continue