Skip to Content
Platform
PlatformRuntimes

Runtimes

A runtime is the deployable version of your agent: Pi running a pinned recipe with the policy and resources it needs.

This page is the concept: what a runtime is, how versions form a lineage, and how environment lanes select which version serves traffic. Two sibling pages carry the rest:

  • Runtime manifest — the .introspection/<slug>.yaml reference: slug rules, manifest keys, resources, and the runtime.github grant.
  • Operating runtimes — the procedures: bootstrapping the first version, controlling what staging serves, yanking a bad version, and what happens when a managed task starts.

What a runtime is

A recipe defines your agent’s behavior, but it doesn’t run on its own. Pi runs the agent loop from that recipe. An Introspection runtime makes that combination deployable: it pins the exact recipe version Pi loads, provides an isolated sandbox, and resolves the identity, policy, bindings, and resources needed for each task.

Runtimes list showing customer support, returns and refunds, and escalation agents with conversation volume, active runs, failure rate, and recent activity
The Runtimes view summarizes each agent lineage and its current activity before you open a specific runtime.

Environments and deployment

An environment is a lane shared across the platform: development, staging, or production. Environment-scoped API keys, bindings, experiments, and memory keep test work separate from live traffic.

A runtime serves one or more environment lanes (typically staging and production) so you can move a version from test traffic to live traffic. A lane points to one version in a runtime group, much like a Git ref points to a commit. Staging and production are deployed lanes whose selected runtime versions can change independently; development is the local introspection dev lane and has no deployed version assignment.

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.

This lineage enables:

  • Experiments to route between versions: an experiment compares arms within a single group’s lineage, on one environment.
  • Patterns that 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.

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.

Customer support runtime detail showing recent health metrics, missing staging bindings, and Git-backed versions assigned to staging and production
A runtime detail keeps operational health, required bindings, Git versions, and their active environment lanes together.

Three senses of “pinned”

The word “pin” is used for three different, independent facts. Keeping them apart avoids most runtime confusion:

SenseWhat is pinnedWhen it changes
Recipe pinEach runtime version records the exact recipe path and Git commit it was built from.Never. A runtime version is immutable; a new commit produces a new version.
Lane assignmentAn environment lane points at one version in the group, and staging can additionally be pinned to one exact commit instead of following a branch.When you move or pin the lane.
Task resolutionA task resolves its runtime name to the lane’s active version once, at creation, and keeps it.Never within the task. Start a new task to pick up a lane’s newer version.

The last sense — resolution is sticky for the task — means every run in a task keeps the same version even if the lane moves while the task is working.

Withdrawing a version

If a version turns out to be bad, you can yank it: a yanked runtime stops accepting new tasks while existing tasks keep their pinned version, and the decision is reversible. See Operating runtimes for the procedure.

Model credential mode

llm_mode (managed or byok) is set in the runtime manifest; see LLM providers for both paths and how a task’s model calls are routed.

Last updated on