Skip to main content
DecimalAI records the configuration your agent runs with. When that configuration changes, it registers a new manifest version and checks past traces against it, so you can see which ones still hold.
This page is about code versions: what DecimalAI detects from your agent’s code. What DecimalAI serves an agent, its prompt and skill list, has its own numbered versions (“Setup v14”), which you change on the dashboard and can roll back. See Prompt & skills, versions and roll back.

What Is a Manifest?

A manifest is a snapshot of what defines your agent at a point in time:
Each line is a component, with a type, a name and a content hash. Components group into ten surfaces, such as tool_registry or model_runtime, and each surface gets its own rules when a version changes. Versions are labeled v1, v2, v3. These count up and aren’t semantic versions. Pass version_label when you register one to name it yourself. A label already in use gets a suffix such as .1.

Manifest-aware versus eval-driven

An eval-driven check runs a test suite you wrote against the new version and compares pass rates. A manifest-aware check starts from what changed: it knows which past traces used the changed tool or prompt, so it can show what a change touches without running your agent. A structural match doesn’t prove response quality, so use both when you can. Regression Check has the side-by-side comparison.

How Auto-Detection Works

You don’t have to declare a manifest. Each integration builds one from what it can see, so the detail depends on the integration: Each framework page shows its setup code. Use agent_config(name) by default: it gives the agent its prompt and skills and traces it. The flags trace only. Use instrument() when you need its arguments, such as agent= or prompts=. Call decimalai.init() first, and pick one form per integration: don’t pass a flag and also call instrument().
agent_config() records the saved prompt as written. A system message of your own that changes on each run (retrieved text, today’s date) makes prompt diffs noisy. To record a template instead, call instrument() first, because a later call logs a warning and changes nothing:

When Manifests Are Registered


Manifest Hashing

Each version has a SHA-256 fingerprint, and the same fingerprint for the same agent means the same version. That is what decides whether a run creates a new one: Some changes don’t count: A version’s status is active (the current reference) or superseded. The dashboard shows these as Current reference and Earlier reference.

Compatibility Scoring

When a new version registers, DecimalAI checks past traces against it, one trace at a time. A trace is checked only against the components it used, so a change to a tool it never called doesn’t touch it. A trace with no recorded component use stays Keep. Registration covers the ten most recent older versions, up to 5,000 traces each. Other traces are worked out when someone opens them. Two steps produce a verdict. First, DecimalAI grades each change as minor, moderate or major: The grade for a trace can be sharper than the grade for the surface, because it looks at the component the trace used:
  • Tools: a renamed or removed parameter, a new optional one or a new description is moderate. A new required parameter or a changed type is major. A renamed tool normally reads as removed, which is major.
  • Skills: a removed skill that the trace used is major.
Second, the agent’s compatibility policy turns the grade into an action. The same major tool change replays under the default preset and drops under strict. If a trace used several changed components, the most severe action wins.
The manifest, the diff and the compatibility format are defined by agentversion, the open spec the platform is built on. You can produce the same manifests and verdicts outside DecimalAI with the agentversion package on PyPI.

Repair: Fix Traces Mechanically

Traces marked repair can be fixed with a data migration: no LLM calls, and your agent doesn’t run. The platform keeps the original recorded tool-call payload and stores a repaired copy with a before/after record.

What Repair Does

After a repair, the trace’s manifest_id points to the target version, and execution_manifest_id still names the version that really ran. Dataset builds for the target version use the repaired copy.

Repair Flow

1

Preview

See the rules and before/after examples:
The response has rules, previews, scanned_count, matching_count and a preview_token tied to this version pair, these rules and the recorded traces.
2

Approve

Apply every rule, or pick some: send approved_rule_indices in another preview and review that selection.A field-level repair needs stored parameter schemas. A schema hash can show that something changed, but not how to transform it safely, so the preview can come back with no rules or examples.
3

Apply

For some rules only, call POST /api/v1/repair/apply-selective with the same body plus approved_rule_indices, using the token from a preview of those indices.The response is a batch with repaired, failed and skipped counts. Read it again at GET /api/v1/repair/{batch_id}. If the reviewed set changed, apply returns 409 REPAIR_PREVIEW_STALE, so review a fresh preview. Retrying with the same idempotency key returns the existing batch.
The same flow is in the CLI: decimalai repair preview and decimalai repair apply. See Runs and data.

Dashboard Quickstart

Select your agent, then open More → Code changes:
  1. Pick a version under History. The comparison uses its recorded parent.
  2. Under Comparison evidence, choose Current comparison or Stored report. Each has its own trace coverage.
  3. Choose Preview matching repairs. Check the rules, matching count and examples, then choose Apply matching repairs or Cancel.
  4. Read the saved result. It’s still there after a refresh.
  5. Choose Review dataset settings, then Build dataset from the version. The compatibility filter is Keep, which means structurally compatible, not good. Open the dataset to download JSONL.
Evaluation performance is a separate panel on the same page, because structural compatibility doesn’t prove response quality.
Repair vs Replay: Repair rewrites stored data and costs no LLM calls. Replay re-runs your agent at full LLM cost. Use repair for schema changes, and replay when the agent’s behavior changed.

Compatibility Policies

How strictly traces are classified is up to you. See Compatibility Policies for the presets, per-surface rules and impact preview.

What Happens When a Manifest Changes

1

A new version is registered

The label goes up by one (v1 to v2) and it becomes the current reference.
2

Past traces are checked

Each gets a verdict for this version pair, and a report is stored for the parent and the new version.
3

A regression check is recorded

More → Regression checks gains an Impact Report for the change, drawn from the last 30 days of traces.
4

You're told

The dashboard shows a toast, “agent updated to v2”, with repair and replay counts and a link to Code changes. A manifest.changed event also goes to your organization’s webhook, if it has one.
A rollback (POST /api/v1/manifests/{manifest_id}/rollback) changes the recorded current reference. It doesn’t deploy or restore your running code. To verify, restore the configuration and run the agent: a matching hash reuses the recorded version.

The Manifest Timeline

More → Code changes lists every version under History, with its label, its associated trace count and the date it was registered. Load older versions pages back, and the export icon downloads the history as CSV. Selecting a version shows its recorded parent, the changed surfaces with their grades, and Keep, Repair, Replay and Drop counts. This changes the review, not your running agent.

Best Practices

  1. Keep changing text out of system prompts. It won’t create new versions, but it makes prompt diffs compare two renderings instead of two edits. Pass dynamic content as user messages.
  2. Declare schemas for tool-level detail. Most integrations only see tool names, so a parameter change goes unnoticed. Use @decimalai.tool with the generic tracer, or register_manifest().

REST API

The SDK calls POST /api/v1/manifests for you, so you’ll rarely need it. These routes read what it recorded: From the command line: decimalai manifests list and decimalai compat-check --agent-name my-agent. See Runs and data.

Next Steps

Regression Check

Get manifest impact analysis as a PR comment on every change.

Register a manifest

register_manifest() and flush_manifest_for_ci().

Compatibility Policies

Choose what each kind of change does to past traces.

Troubleshooting

False drift, or the action says “no manifest”? Common fixes.