Browse the documentation

Early preview

Comparing prompts

In the Open Engineering Language, a system prompt is business logic: changing it changes what your agent does. oel prompt-diff shows how the prompts of your working version differ from a released one, so a prompt change can be reviewed like a change to code.

Usage

oel prompt-diff --old RELEASED_PROJECT --new WORKING_PROJECT --entry NAME.node.oel
OptionMeaning
--old PROJECTThe project folder of the released version.
--new PROJECTThe project folder of your working version.
--entry NAME.node.oelThe node whose prompts are compared.

The differences are printed in machine-readable form.

What it shows

For each agent and node whose prompts changed, it shows:

  • the prompt text before and after, with the changed passages marked;
  • where each prompt comes from: written inline, read from a file, from the environment or from configuration.
  • the kinds of change between the two versions (prompt, contract and dependencies), whether the contract still agrees, and the files that were added, removed or changed;
  • the locked packages of each side and the pins that moved: the package, and its version and archive digest on each side.

A prompt written inline or kept in a file is compared as the exact text the agent uses, so a change of one word shows. A prompt taken from the environment, or from configuration resolved when a run starts, is shown by where it comes from rather than by its text.

Locked packages

A version also depends on the packages its pack.lock pins. When the lock of the two projects differs, the report lists dependencies among the changes and names every pin that moved, was added or was dropped. A project whose lock is missing, stale or unreadable is reported with the reason instead of its pins. Releasing a prompt change shows how the release commands record and check these pins.

A prompt change is a new version

An agent's version is identified by the exact text of every prompt it resolves, together with its input builders, its input and output types, its tools and permissions, its model bindings and its configuration. A prompt-only change gives the agent a new version, even when no code changes.

A change that goes beyond prompt text, such as a changed type, a new tool or a wider permission, needs more than a prompt release: the deployment plan shows it and requires it to be authorized. A prompt update alone can never widen a tool's permissions.

What it never does

oel prompt-diff calls no model and runs no agent. It changes nothing, and never shows secret values: a prompt that refers to a secret shows the reference, not its value.

In a release

Run an evaluation, compare the prompts, then plan the deployment:

oel eval --suite support-regression
oel prompt-diff --old ./released --new ./working --entry advisor.node.oel
oel deploy plan

Runs already under way stay pinned to the version they were admitted with, to the end. Deployment plans describes promotion and rollback.