Agent-Versioning für KI-Agenten: wie man Prompt, Tools und Policy sicher ausrollt

Idee in 30 Sekunden

Agent versioning ist eine Runtime-Kontrolle, die festlegt, welche Agent-Version ein Run exakt verwendet: Prompt, Tools, Policy und Modell.

Wann das nötig ist: wenn ein Agent regelmäßig aktualisiert wird und Production sichere Releases ohne Verlust der Reproduzierbarkeit braucht.

Problem

Ohne Versionierung werden neue Änderungen an Prompt, Tools und Policy zu einem einzigen "aktuellen Zustand" vermischt. Im Demo sieht man das kaum. In Production ist unklar, warum ein Run funktioniert hat und ein anderer nicht.

Typische Folgen:

• Incidents lassen sich nicht präzise reproduzieren
• es ist schwer zu erkennen, welche Änderung das Verhalten gebrochen hat
• rollback wird zu einer manuellen und riskanten Operation

Und jede Minute ohne klare Version erhöht die Incident-Untersuchungszeit.

Analogie: Das ist wie ein Deployment ohne Versionsnummer. Solange alles läuft, sieht man das Problem nicht. Wenn etwas bricht, ist unklar, wohin man zurückrollen soll.

Lösung

Die Lösung ist, den Agenten als versioniertes Paket (version manifest) zu speichern und Runs nur mit gepinntem version_id zu starten. Jeder Release durchläuft Contract-Kompatibilitätsprüfungen und ein Rollout-Gate, bevor Traffic freigeschaltet wird.

Version policy layer gibt eine technische Entscheidung zurück: allow oder stop mit explizitem Grund:

• contract_mismatch
• gate_failed
• rollback_required

Das ist eine eigene Systemschicht, nicht Teil von Prompt oder Modelllogik.

Agent versioning ≠ rollback

Das sind unterschiedliche Rollen im System:

• Versioning steuert Änderungen vor und während des Rollouts.
• Rollback bringt eine stabile Version zurück, wenn die neue bereits Regression erzeugt hat.

Eins ohne das andere reicht nicht:

• ohne versioning ist gezielter rollback schwer
• ohne rollback schützt selbst gutes versioning nicht vor Production-Incidents

Beispiel:

• versioning: support-agent@2.4.0 geht auf 5% Canary
• rollback: zurück auf support-agent@2.3.3, wenn die Error-Rate steigt

Komponenten der Versioning-Kontrolle

Diese Komponenten arbeiten bei jedem Run-Start zusammen.

Beispiel-Alert:

Slack: 🛑 Agent support@2.4.0 blocked: gate_failed on canary stage (error_rate > threshold).

Wie das in der Architektur aussieht

Version policy layer liegt zwischen Runtime und dem Start einer neuen Agent-Version und blockiert den Start vor Run-Beginn. Jede Entscheidung (allow oder stop) wird im Audit Log erfasst.

Jeder Run-Start geht vor der Ausführung durch diesen Flow: Runtime startet die neue Version nicht direkt, sondern fragt zuerst die Entscheidung des Policy Layers ab.

Flow kurz zusammengefasst:

• Runtime bereitet den Run-Start vor
• Policy prüft version_manifest, tool_contracts, rollout_stage, policy_version
• allow -> gepinnte agent_version startet
• stop -> Release wird blockiert, aktive stabile Version bleibt
• beide Entscheidungen werden ins Audit Log geschrieben

Beispiel

Team releast support-agent@2.4.0 mit neuem refund.create-Tool-Adapter. Beim Contract-Check wird eine Schema-Inkompatibilität gefunden.

Ergebnis:

• policy gibt stop (reason=contract_mismatch) zurück
• Canary startet nicht
• support-agent@2.3.3 läuft weiter

Versioning stoppt riskante Releases vor dem Incident, nicht erst danach.

Im Code sieht das so aus

Die vereinfachte Skizze oben zeigt den Haupt-Flow. Kritisch: Runtime darf Runs nur mit gepinntem version_id starten und nicht während der Ausführung "latest" laden.

Beispiel für Versioning-Konfiguration:

agent_release:
  stable_version: support-agent@2.3.3
  candidate_version: support-agent@2.4.0
  canary_percent: 5
  rollback_on:
    error_rate_p95: 0.05
    tool_failure_p95: 0.03

release_cfg = load_release_config("support-agent")
candidate = registry.get(release_cfg.candidate_version)
decision = versioning.check(candidate, runtime_context)

if decision.outcome == "stop":
    audit.log(
        run_id,
        decision=decision.outcome,
        reason=decision.reason,
        version_id=candidate.version_id,
        rollout_stage=decision.rollout_stage,
    )
    alerts.notify_if_needed(candidate.version_id, decision.reason)
    return stop(decision.reason)

selected = versioning.select(candidate, stable=release_cfg.stable_version)
run = runtime.start(
    version_id=selected.version_id,
    prompt_hash=selected.prompt_hash,
    policy_version=selected.policy_version,
)
# Decision.allow — bedingter Helper, um ein einheitliches outcome/reason-Modell zu behalten.
allow_decision = Decision.allow(reason=None)

audit.log(
    run.id,
    decision=allow_decision.outcome,
    reason=allow_decision.reason,
    version_id=selected.version_id,
    rollout_stage=selected.rollout_stage,
)

return run

Wie das während der Ausführung aussieht

Szenario 1: Blockierung wegen contract mismatch

1. Runtime bereitet den Start von support-agent@2.4.0 vor.
2. Policy prüft Tool-Contracts.
3. Entscheidung: stop (reason=contract_mismatch).
4. Neue Version startet nicht.
5. Event wird im Audit Log erfasst.

Szenario 2: Canary-Rollout

1. Policy erlaubt Candidate mit canary_percent=5.
2. Ein Teil der Runs geht auf 2.4.0, der Rest auf stable.
3. Metriken werden nach version_id verfolgt.
4. Wenn Schwellenwerte nicht verletzt werden, wird die Stage erhöht.
5. Version geht in breiteren Rollout.

Szenario 3: rollback required

1. Nach dem Rollout steigt tool_failure_rate.
2. Policy gibt stop (reason=rollback_required) zurück.
3. Traffic geht zurück auf stable version.
4. Runs mit neuer Version starten nicht mehr.
5. Team analysiert den Incident über version_id und Audit Trail.

Typische Fehler

• Runs aus "latest" starten statt aus gepinntem version_id
• nur Prompt versionieren und Tools/Policy-Contracts ignorieren
• Full Rollout ohne Canary-Gate
• version_id und rollout_stage nicht im Audit loggen
• rollback und neuen Release in einem Schritt mischen, ohne stable fallback
• keine expliziten Schwellenwerte definieren, die rollback auslösen

Ergebnis: Releases wirken kontrolliert, werden unter Last aber unvorhersehbar.

Selbstcheck

Schneller Agent-Versioning-Check vor dem Production-Start:

FAQ

Q: Warum nicht einfach die "aktuelle" Agent-Version aktualisieren?
A: Weil du ohne gepinntes version_id die Reproduzierbarkeit von Runs verlierst und Regressionen nicht präzise lokalisieren kannst.

Q: Was genau soll versioniert werden: nur Prompt?
A: Nein. Minimum: Prompt, Tool-Contracts, Policy/Config und Runtime-Kompatibilität. Sonst ist die Version unvollständig.

Q: Ist Canary für jede Änderung Pflicht?
A: Für High-Risk-Änderungen ja. Für Low-Risk kann man Stufen verkürzen, aber weiter mit expliziten Metriken und Stop-Schwellen.

Q: Wann sollte rollback starten?
A: Wenn vereinbarte Schwellen verletzt sind (error/tool failure/latency/cost). Das sollte eine Policy-Entscheidung sein, keine manuelle Improvisation.

Q: Ersetzt versioning rollback?
A: Nein. Versioning verhindert Release-Chaos, rollback bleibt der Notfall-Mechanismus für die Rückkehr auf stable.

Wo Agent Versioning im Gesamtsystem liegt

Agent versioning ist eine der Ebenen von Agent Governance. Zusammen mit RBAC, Limits, Budgets, Approval und Audit bildet es ein System kontrollierter Production-Änderungen.

Verwandte Seiten

Als Nächstes zum Thema:

• Agent Governance Überblick — Gesamtmodell der Agent-Kontrolle in Production.
• Rollback Strategien — wie man sicher zur stable version zurückkehrt.
• Access Control (RBAC) — wie man begrenzt, wer was ausführen kann.
• Budget Controls — wie Rollout-Kosten kontrolliert bleiben.
• Audit Logs für Agenten — wie man Entscheidungs-Ketten nach version_id rekonstruiert.