Skip to Content
Platform
Core ConceptsRuntimes

Runtimes

A runtime is the deployable version of your agent: a recipe bound to Introspection’s execution harness, plus the policy and resources it needs to run.

What a runtime is

A recipe defines your agent’s behavior, but it doesn’t run on its own. A runtime is what makes it deployable. It binds a recipe to Introspection’s execution harness (the managed environment where your agent actually runs) and resolves the policy and resources the agent needs at execution time.

A runtime serves one or more environment lanes (typically staging and production) so you can promote a version from test traffic to live traffic. Pointing an environment at a runtime activates it for that lane; the environment moves between sibling versions the way a git ref moves between commits.

Runtime groups: the lineage

Successive versions of one logical agent share a runtime group, a stable identity that ties every version of that agent together. Each new version is its own immutable runtime row; the group is the through-line across all of them.

The lineage is not just bookkeeping. It is what lets:

  • Experiments route between versions: an experiment compares arms within a single group’s lineage, on one environment.
  • Patterns accumulate across versions: behavior and failure modes observed on one version stay attached to the lineage, so you can see how a recurring issue trends as the agent evolves, not just within a single deploy.

A runtime is one immutable deployable version. A runtime group is the agent’s identity over time. You experiment and trend patterns across the group, then ship a single version into an environment lane.

Kind and LLM mode

Two properties shape how a runtime is delivered and how it talks to a model:

PropertyOptionsMeaning
Kindbring-your-own-recipe / bring-your-own-harnessWhether Introspection supplies the execution harness around your recipe, or you bring your own.
LLM modemanaged / bring-your-own-keyWhether the runtime uses Introspection-managed model access, or your own provider credentials.

Resolution and availability

When you start a task against a runtime by name, the platform resolves that name to a concrete version. There are two modes:

  • Sticky (production default): a run pins the version that was active when it started, so an in-flight task keeps using one version even if you promote a new one mid-run.
  • Latest (non-production default): every run resolves the currently-active version, so new work always picks up the newest promotion.

If a version turns out to be bad, an operator can deactivate it. A deactivated runtime stops resolving as available for new work while in-flight sticky runs keep their pinned version. Reactivation is explicit and reversible. Application SDKs intentionally do not expose lifecycle mutation; use introspection runtimes deactivate / reactivate or the dashboard.

Creating and running runtimes

Runtime registration is manifest-driven. Place a canonical .introspection/<runtime-slug>.yaml file in the repository, validate it locally, then bootstrap the first runtime from that manifest:

name: support-agent
description: Customer support agent
path: apps/support-agent
runtime:
  llm_mode: byok
  config:
    memory_mb: 2048
introspection recipes validate
introspection runtimes create --manifest .introspection/support-agent.yaml

The manifest filename is the stable runtime-group slug. create reads the manifest and Git checkout, records the immutable recipe pin through the active GitHub integration, and bootstraps the first runtime. Later commits produce new recipe-backed versions through the repository integration rather than imperative SDK mutation.

Operators inspect and route versions with the CLI:

introspection runtimes list --runtime support-agent
introspection runtimes versions <runtime-id>
introspection runtimes staging track <runtime-id> --git-ref main
introspection runtimes staging pin <runtime-id>
introspection runtimes deactivate <runtime-id> --reason "tool-call regression"
introspection runtimes reactivate <runtime-id>

The JavaScript, Python, and Rust SDKs expose runtime list/get, resolution, and .run() only. This keeps deployment state in the operator surface while application code focuses on execution.

A typical flow: register the manifest once, track a branch in staging while you iterate, pin staging when you need a stable candidate, and start sending it work. Each pushed version joins the same runtime group, ready to experiment against the current baseline before you promote it.

Last updated on