Comparing prompts
In AEL, the Agent Engineering Language, a system prompt is business logic: changing it changes what your agent does. ael 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
ael prompt diff --baseline <release>
ael prompt diff --baseline <release> --json
| Option | Meaning |
|---|---|
--baseline <release> | The released version to compare with. |
--json | The differences 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.
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.
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
ael 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:
ael eval --suite support-regression
ael prompt diff --baseline <release>
ael deploy plan
Runs already under way stay pinned to the version they were admitted with, to the end. Deployment plans describes promotion and rollback.
Related
- System prompts: prompt sources and fallback.
- Evaluations and prompt releases: versions, suites, promotion and rollback.