Guardrails

Fünf Guardrails umgeben eine KI-Agenten-Sandbox. Zwei sind harte Grenzen, die der Agent physisch nicht überschreiten kann (LEASH, SCOPE), eine verwandelt Daten in ein Verdikt (POLICY), und zwei erzeugen Daten, die sie abwägen kann (LINT, BLAST). Keine setzt ein LLM in den Vertrauenspfad.

LEASH — Pro-Sandbox-Budgets

Blockiert: einen Agenten, der Amok läuft — Anweisungen, Compute oder Wanduhr ohne Grenze verbrennt.

Legen Sie ein Budget fest, wenn Sie die Sandbox erstellen oder ausführen:

keon sandbox create \
  --budget-statements 500 \
  --budget-compute-seconds 120 \
  --budget-wall-seconds 900
# or the same three flags on: keon sandbox run …

Bei Überschreitung beendet sich die Sandbox selbst: der Status wird discarded und budget_breached benennt, welche Grenze gesprengt wurde — statements, compute_seconds oder wall_clock. Die CLI beendet sich mit Fehlercode sandbox_budget_breached. Eine Warnung feuert bei 80 % eines beliebigen Budgets.

Auf der Leitung sind Budgets ein budgets-Objekt, ein Eintrag pro Budget:

"budgets": {
  "statements":      { "limit": 500, "used": 218, "warned": false },
  "compute_seconds": { "limit": 120, "used": 41,  "warned": false },
  "wall_clock":      { "used": 63 }
}

Ein fehlendes limit bedeutet unbegrenzt — es gibt keinen Sentinel-Wert zum Fehldeuten.

Standardwerte und Obergrenzen konfigurieren (Owner/Admin):

# Per-project defaults double as the create-time cap.
curl -X PATCH .../v1/projects/{id} \
  -d '{"sandbox_budget_defaults": {"statements": 500, "compute_seconds": 120}}'

Der Standard ist die Obergrenze: zur Erstellungszeit mehr als den Projekt- Standard anzufragen, gibt 422 sandbox_budget_exceeds_cap zurück. Pro-Projekt-Standards sind konfigurierbar — es gibt keine feste Zahl, die hier zu nennen wäre.

Zwei Invarianten:

• Bei Erstellung eingefroren. Budgets sind fixiert, wenn die Sandbox erstellt wird; das Ändern der Projekt-Standards später leint eine laufende Sandbox niemals neu.
• Agenten-Schlüssel verschärfen nur. Ein Schlüssel mit Agenten-Fähigkeit darf bei der Erstellung engere Budgets anfragen; er kann niemals die Projekt-Standards setzen.

POLICY — Promote-Policy-Stufen

Blockiert: ein Promote, dessen Änderungen riskanter sind, als das Projekt erlaubt — selbst eines, das ein Agent (oder ein Mensch) durchzuwinken versucht.

POLICY ist ein Pro-Projekt-Overlay, das eine Risikoklasse auf eine Aktion abbildet, über den Basis-promote_mode geschichtet.

Konfigurieren (CLI):

keon projects promote-policy <projectId>                 # show effective policy
keon projects promote-policy <projectId> \
  --set destructive=block \
  --set unbounded=require_human \
  --on-conflicts require_human                           # merge-write
keon projects promote-policy <projectId> --clear         # drop the overlay

--set <class=action> ist wiederholbar und mergt in das bestehende Overlay.

Konfigurieren (API): GET / PUT / DELETE /v1/projects/{projectId}/promote-policy:

{ "version": 1,
  "rules": { "destructive": "block", "unbounded": "require_human" },
  "on_conflicts": "require_human" }

ignore ist nur für on_conflicts zulässig, niemals als Klassen-Aktion.

Die Basishaltung kommt aus promote_mode, und das Overlay überschreibt pro Klasse:

Jede wirksame Regel meldet, woher sie stammt — source: overlay, promote_mode oder default.

Was der Agent bei einer Blockade sieht: ein blockiertes Promote gibt 409 promote_blocked_by_policy mit den angehängten Entscheidungsdetails zurück.

Schlüsselregel: ein menschliches Approve kann ein Policy-block niemals überschreiben. Die Policy wird zur Approve-Zeit neu bewertet, sodass block gegen den Klick hält. Die Policy- Validierung ist fail-closed / strikt — eine unparsbare Policy verweigert, sie degradiert niemals zu offen.

SCOPE — eingeschränkte Autorität (Bahnen)

Blockiert: jeden Lese- oder Schreibzugriff außerhalb der Schemas und Tabellen, die Sie deklariert haben — die Bahn des Agenten.

Konfigurieren (nur zur Erstellungszeit):

keon sandbox create \
  --schemas app,analytics \
  --tables  app.users,app.orders
# omit both flags → unscoped (full-branch authority)

--tables ohne --schemas wird clientseitig als invalid_lane abgelehnt.

Innerhalb des Forks kann der Agent physisch nicht außerhalb der Bahn schreiben — ein Schreibzugriff außerhalb der Bahn schlägt im Fork mit SQLSTATE 42501 (unzureichendes Privileg) oder 3F000 (ungültiger Schemaname) fehl. Lesezugriffe außerhalb der Bahn werden ebenfalls verweigert. Und Promote lehnt jede Änderung außerhalb der Bahn mit 409 sandbox_out_of_lane ab.

Auf der Leitung trägt die Sandbox ein scope-Objekt (fehlt = uneingeschränkt):

"scope": { "v": 1, "schemas": ["app", "analytics"], "tables": ["app.users", "app.orders"] }

keon sandbox diff erhält ein lane-Objekt, das etwaige violations[] auflistet, jede mit einem Grund — out_of_lane_schema, out_of_lane_relation oder unresolvable_targets.

Zwei Grenzen:

• Nach der Erstellung unveränderlich. Eine Bahn zu erweitern bedeutet Verwerfen + Neuerstellen — es gibt kein Erweitern-an-Ort-und-Stelle.
• Nur direkte Ziele. Eine Bahn regelt keine transitiven Nebenwirkungen, die über Trigger oder SECURITY DEFINER-Funktionen erreicht werden.

LINT — statische Risikoklassifizierung

Erzeugt: eine statische Risikoklasse für jede Anweisung im Replay-Satz — keine Ausführung, kein LLM, keine Zeilenzahlen. Rein textuell.

Es gibt keinen neuen Befehl. LINT taucht an drei Stellen auf, die Sie bereits lesen:

• innerhalb keon sandbox diff als risk_report,
• pro Aktion in keon sandbox log,
• als max_risk_class auf der Sandbox-Leitung.

Klassen, von niedrigster zu höchster Schwere:

additive  <  mutating  <  rewrite  <  unbounded  <  destructive

Ein leerer Replay-Satz klassifiziert als none.

Berichtsform:

{ "statements": [
    { "seq": 4, "risk_class": "unbounded",
      "reasons": ["where_trivially_true: DELETE guarded by WHERE 1=1 matches every row"] }
  ],
  "rollup": { "max_class": "unbounded", "counts": { "additive": 2, "unbounded": 1 } } }

Jeder Grund ist <snake_case_code>: <sentence>. Zum Beispiel klassifiziert WHERE true oder WHERE 1=1 die Anweisung als unbounded mit Grund where_trivially_true.

Zwei Dinge zu bedenken:

• LINT sind Daten, keine Entscheidung. Es klassifiziert; POLICY setzt durch. LINT blockiert niemals etwas von sich aus.
• Es fällt nach oben. Unter Unsicherheit weist LINT die schlimmste plausible Klasse zu. Weil die Erkennung textuell ist, sind tatsächliche Zeilenzahlen keine Eingabe — ein WHERE-loses DELETE liest sich als destructive, ob die Tabelle eine Zeile oder eine Milliarde hält.

BLAST — Explosionsradius-Trockenlauf

Erzeugt: gemessene Belege dafür, was ein Promote tatsächlich tun würde — echte Lock-Level, echte Lock-Halte-Dauern, echte Zeilenzahlen und jede Divergenz seit dem Fork.

keon sandbox dry-run <id>

Es spielt den exakten Anweisungssatz der Sandbox gegen zwei Wegwerf-Forks des Elternteils ab, misst die echten Kosten, erkennt Divergenz und zerstört dann beide. Es berührt niemals main, und der Agent erhält niemals eine Fork-Anmeldeinformation. BLAST ist beratend — es blockiert niemals ein Promote; Konflikte werden als Daten aufgezeigt.

Vollständige Feldreferenz, Konfliktsemantik und die Endpunktliste stehen auf Sandboxes & promote → Blast-radius dry-run.

Wie sie zusammenpassen

• LINT und BLAST erzeugen Daten — eines statisch, eines gemessen.
• POLICY verwandelt diese Daten in eine Entscheidung, fail-closed, durch einen menschlichen Klick nicht überschreibbar, wenn sie block sagt.
• LEASH und SCOPE sind harte Grenzen, die der Agent überhaupt nicht überschreiten kann — im Fork durchgesetzt, bei der Erstellung eingefroren.

Siehe Common pitfalls für die Arten, wie diese fünf routinemäßig fehlgedeutet werden.