Manifests & Versioning

DecimalAI automatically tracks changes to your agent’s configuration across deployments. When a change is detected, a new manifest version is registered and a compatibility analysis shows how existing traces are affected.

What Is a Manifest?

A manifest is a snapshot of your agent’s contract — the tools, model, prompts, subagents, and output schema that define how your agent behaves:

Manifest v3
├── Tools: search, calculator, web_browser
├── Model: gpt-4o (temperature: 0.7)
├── Prompts: "You are a helpful research assistant..."
├── Subagents: fact-checker, summarizer
└── Skills: code-review, sql-optimizer

Every time your agent runs, the SDK extracts this contract, hashes it, and compares to the previous version. If something changed, a new version is registered automatically.

How Auto-Detection Works

Detection is framework-specific. Each integration extracts the maximum available information:

Framework	Init flag	Tools	Model	Prompts	Schema Depth
LangChain	`langchain=True`	✅ Auto + full schema	✅ Full config	✅ System/user	Full
OpenAI Agents (`install(agent=...)`)	`openai_agents=True` + explicit install	✅ Full JSON schema	✅ Name	✅ Instructions	Full
OpenAI Agents (auto)	`openai_agents=True`	Names only	✅ Full config	❌	Names
LlamaIndex	`llamaindex=True`	Names only (OTel)	✅ Full config	❌	Names
CrewAI	`crewai=True`	Names only (OTel)	✅ Full config	❌	Names
AutoGen / AG2	`autogen=True`	Names only (OTel)	✅ Full config	❌	Names
Generic OTel	`otel=True`	Names only	✅ Full config	❌	Names
Generic + `@tool` decorator	(no flag)	✅ From type hints	✅ Full	❌	Full
Explicit `register_manifest()`	(no flag)	✅ Whatever you pass	✅	✅	Full

This is the canonical capability matrix. The Quickstart shows code for each framework but doesn’t repeat the matrix — come back here if you want to know how deep auto-detection goes for your framework before committing to it.

Two calling forms — when to use which:

Flag form (decimalai.init(api_key=..., langchain=True)) auto-installs the integration. Use this by default — it’s what the Quickstart shows.
Explicit install(...) form is for when you need to pass advanced arguments — e.g., an Agent object for OpenAI Agents to capture full schemas, or prompts={...} to override dynamic prompts in LangChain. Call decimalai.init(api_key=...) first, then install(...).

Don’t pass the framework flag and call install() separately — pick one form per integration.

LangChain
OpenAI Agents
OTel / CrewAI
Generic

import decimalai

# Default — flag form auto-installs the integration
decimalai.init(api_key="your-api-key", langchain=True)

# Use LangChain as normal — everything is auto-detected

Tools are extracted from callbacks, model config from on_chat_model_start, and prompts from system messages.

Gotcha: Dynamic prompts (RAG chunks, today’s date) cause false drift. Drop into the explicit form to override:

decimalai.init(api_key="your-api-key")
from decimalai.langchain import install
install(prompts={"system": "Your static template"})

# Default — flag form picks up Agent objects on first run
import decimalai
decimalai.init(api_key="your-api-key", openai_agents=True)

# Run your agent as usual; the SDK introspects it at trace time.

For full JSON-schema capture, drop into the explicit form and pass the Agent object:

import decimalai
from agents import Agent
from decimalai.openai_agents import install

decimalai.init(api_key="your-api-key")
agent = Agent(name="research-agent", instructions="...", model="gpt-4o", tools=[...])
install(agent=agent)  # Full schema introspection

# Default — flag form
import decimalai
decimalai.init(api_key="your-api-key", otel=True)
# Or for CrewAI specifically: decimalai.init(api_key="...", crewai=True)

OTel spans expose model name, temperature, and tool names, but not full tool schemas.

# Option 1: Explicit registration (highest fidelity)
decimalai.register_manifest(
    agent_name="my-agent",
    tools=[
        {"name": "search", "schema": {"type": "object", "properties": {"query": {"type": "string"}}}},
    ],
    prompts={"system": "You are a helpful research assistant."},
    models={"default": {"provider": "openai", "model": "gpt-4o", "temperature": 0.7}},
)

# Option 2: Auto-deduce from trace calls (zero config)
@decimalai.trace(agent_name="my-agent")
def run_agent(query: str):
    decimalai.log_llm_call(model="gpt-4o", ...)
    decimalai.log_tool_call(name="search", ...)

Manifest Hashing

Manifest hashing is deterministic and noise-resistant:

Hashing implementation details

Rule	What it does	Effect on drift
Per-surface hashing	Tools, prompts, models, subagents, skills, and output schema each get their own hash; the overall hash is the hash of all surface hashes sorted alphabetically	Isolates where drift came from
Temperature quantization	Small changes (0.70 → 0.71) are quantized to the nearest 0.1	No drift for tweaks; 0.7 → 0.8 will trigger a new manifest
Runtime settings excluded	`max_retries`, `timeout`, and operational settings are stripped before hashing	These never cause drift
Tool order invariant	Tools are sorted by name before hashing	Reordering doesn’t create false drift
Hash dedup	If the same hash already exists, no new version is created	Deploying the same config to multiple pods won’t create duplicates

Compatibility Scoring

When a new manifest is detected, DecimalAI classifies every existing trace against the new config:

Verdict	Meaning	Example
Keep	Trace is fully compatible	Model temperature changed slightly
Repair	Trace can be adapted mechanically	Tool schema added an optional field
Replay	Trace should be re-run with the new agent	System prompt changed significantly
Drop	Trace is incompatible — exclude from training data	Tool was removed entirely

The classification considers 10 surfaces, each with its own severity:

Surface	Minor (keep)	Moderate (flag)	Major (drop)
`prompt_stack`	Whitespace change	Content changed	Complete rewrite
`model_runtime`	Temperature tweak	Model changed	Provider changed
`tool_registry`	Schema field added	Schema field changed	Tool removed
`skill_registry`	Skill added	Skill content changed	Skill removed
`workflow`	Parameter change	Handoff added	Step removed
`subagents`	Sub-agent added	Sub-agent reconfigured	Sub-agent removed
`output_contract`	Optional field added	Field type changed	Required field removed
`guardrails`	Threshold relaxed	Rule changed	Rule removed
`context_config`	Window grew	Retrieval source changed	Source removed
`environment`	Non-semantic var added	Value changed	Var removed

Repair: Fix Traces Mechanically

Traces classified as repair can be fixed with a deterministic data migration — no LLM calls, no re-running your agent. The platform rewrites tool call data inside the trace records so they conform to the new manifest.

What Repair Does

Rule Type	What It Fixes	Example
`tool_rename`	Rewrites tool name in trace records	`check_inventory(...)` → `lookup_stock(...)`
`param_rename`	Renames parameter in tool call args	`product_id` → `item_id`
`param_remove`	Strips deprecated parameter	Removes `legacy_flag` from args
`param_add_default`	Adds new optional parameter	Adds `region: null`

After repair, the trace’s manifest_id is updated to point to the new manifest — it’s now “compatible” with v2.

Repair Flow

Preview

See what rules would be applied, with before/after examples:

curl -X POST https://api.decimal.ai/api/v1/repair/preview \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"old_manifest_id": "...", "new_manifest_id": "...", "sample_size": 5}'

Response shows each rule with confidence level and sample trace diffs.

Approve

Review the rules. You can apply all rules or select specific ones:

Apply All — repairs every eligible trace with all generated rules
Selective — pick which rules to apply (e.g., approve the tool rename but skip the param removal)

Apply

# Apply all rules
curl -X POST https://api.decimal.ai/api/v1/repair/apply \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"old_manifest_id": "...", "new_manifest_id": "..."}'

# Or apply selectively
curl -X POST https://api.decimal.ai/api/v1/repair/apply-selective \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"old_manifest_id": "...", "new_manifest_id": "...", "approved_rule_indices": [0, 2]}'

Returns a batch ID with repaired/failed/skipped counts.

Dashboard Quickstart

In the dashboard, the Impact Report banner appears automatically when your agent has 2+ manifest versions. From the banner you can:

Click “Repair All” to preview repair rules (before/after examples for each affected trace)
Review the rules, then click “Apply Repairs” to execute
Or click “Repair & Build” for a combined flow: repair all eligible traces, then build a clean SFT dataset from keep + repaired traces — one click, end to end

REST API

import httpx

base = "https://api.decimal.ai/api/v1"
headers = {"Authorization": "Bearer dai_sk_..."}

# Preview repair rules — returns the proposed transforms with sample diffs
rules = httpx.post(
    f"{base}/repair/preview",
    headers=headers,
    json={"old_manifest_id": "...", "new_manifest_id": "...", "sample_size": 5},
).json()

# Apply all repairs
result = httpx.post(
    f"{base}/repair/apply",
    headers=headers,
    json={"old_manifest_id": "...", "new_manifest_id": "..."},
).json()

# Apply selectively (approve specific rule indices only)
result = httpx.post(
    f"{base}/repair/apply-selective",
    headers=headers,
    json={
        "old_manifest_id": "...",
        "new_manifest_id": "...",
        "approved_rule_indices": [0, 2],
    },
).json()

Repair vs Replay: Repair is instant (deterministic DB rewrite, zero LLM cost). Replay re-runs the full agent on original prompts (minutes/hours, full LLM cost). Use repair for schema changes; use replay when the agent’s behavior changed.

Compatibility Policies

How aggressively traces are classified when a manifest changes (strict / default / permissive presets, per-surface overrides, distillation mode, impact preview) is covered in its own guide:

Compatibility Policies

Preset reference, per-surface overrides, impact preview before applying, and the distillation override for fine-tuning workflows.

What Happens When a Manifest Changes

New version is registered

Auto-incremented (v1 → v2 → v3).

Compatibility report is generated

Each trace is classified as keep/repair/replay/drop.

Dashboard shows Impact Report

Visual breakdown with progress bars and action buttons.

Sidebar shows notification badge

Pulsing dot alerts you to drift.

Toast notification appears

Slide-in alert with “View Impact →” link.

If you roll back to a previous configuration, DecimalAI detects the matching hash and re-activates the old manifest instead of creating a duplicate. Your version history stays clean.

The Manifest Timeline

The agent dashboard shows a timeline of all manifest versions with:

Version label (v1, v2, v3, or custom labels)
Date registered
Diff view — which surfaces changed between versions
Trace count — how many traces were recorded under each version
Compatibility summary — keep/repair/replay/drop counts

Click any two versions to see a side-by-side diff highlighting exactly what changed: tools added/removed, prompt text differences, model configuration changes.

When Manifests Are Registered

Framework	Timing
LangChain	On first trace completion (lazy)
OpenAI Agents (with `Agent`)	Immediately at `install()` time
OpenAI Agents (without `Agent`)	On first trace completion
OTel	On first trace batch export
Generic (explicit)	When `register_manifest()` is called
Generic (auto-deduce)	On first trace completion

Best Practices

Use static prompts. Dynamic content (RAG chunks, dates) in system prompts causes false drift. Pass dynamic content as user messages instead.
Use @decimalai.tool for full schema tracking. The decorator generates JSON schemas from Python type hints — enabling schema-level drift detection, not just name-level.
Start with the default policy. The balanced preset works for most teams. Switch to strict when you need training data purity guarantees.
Label important versions. Use version_label="v2.1-prod" when deploying significant changes so you can find them in the timeline.

Next Steps

Regression Check

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

Manifests API

REST reference for register, list, get, diff.

Versioning & Compatibility

Conceptual model — manifest hash, component verdict, severity, repair.

Compatibility Policies

Tune how the engine maps severity to verdicts.

Troubleshooting

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

​What Is a Manifest?

​How Auto-Detection Works

​Manifest Hashing

​Compatibility Scoring

​Repair: Fix Traces Mechanically

​What Repair Does

​Repair Flow

​Dashboard Quickstart

​REST API

​Compatibility Policies

Compatibility Policies

​What Happens When a Manifest Changes

​The Manifest Timeline

​When Manifests Are Registered

​Best Practices

​Next Steps

Regression Check

Manifests API

Versioning & Compatibility

Compatibility Policies

Troubleshooting

What Is a Manifest?

How Auto-Detection Works

Manifest Hashing

Compatibility Scoring

Repair: Fix Traces Mechanically

What Repair Does

Repair Flow

Dashboard Quickstart

REST API

Compatibility Policies

What Happens When a Manifest Changes

The Manifest Timeline

When Manifests Are Registered

Best Practices

Next Steps