Dokumentation

Agent Harness

Rollenbasierte Zugriffskontrolle, Budgets und Governance für KI-Agenten mit lean-ctx.

Der Agent Harness regelt, was KI-Agenten tun dürfen, wie viel sie ausgeben können und welche Tools sie verwenden dürfen. Er setzt rollenbasierte Zugriffskontrolle mit Echtzeit-Budget-Tracking durch.

Was ist der Agent Harness?

Der Agent Harness ist die Governance-Schicht von lean-ctx. Er weist Agenten Rollen zu, setzt Tool-Richtlinien durch und verfolgt Budgets (Tokens, Shell-Aufrufe, Kosten). Bei Annäherung an Limits werden Warnungen ausgegeben. LeanCTX blockiert standardmäßig nie - es hilft deiner AI immer, auch bei überschrittenem Budget. Blocking kann für strikte Governance-Szenarien explizit aktiviert werden.

Eingebaute Rollen

lean-ctx wird mit 5 eingebauten Rollen ausgeliefert. Jede Rolle definiert Tool-Zugriff, Shell-Richtlinie und Ressourcenlimits. Die Standardrolle ist coder.

coder

Voller Tool-Zugriff für Code-Implementierung. 200K Token-Budget, 100 Shell-Aufrufe, $5 Kostenlimit.

reviewer

Nur-Lese-Zugriff für Code-Review. Kein Shell, kein Editieren. 150K Tokens, $3 Kostenlimit.

debugger

Debug-fokussiert mit erweitertem Shell-Zugriff. 150K Tokens, 200 Shell-Aufrufe, $5 Kostenlimit.

ops

Infrastruktur und CI/CD-Operationen. Shell-intensiv, kein Editieren. 100K Tokens, 300 Shell-Aufrufe, $3 Kostenlimit.

admin

Uneingeschränkter Zugriff mit hohen Limits. 500K Tokens, 500 Shell-Aufrufe, $50 Kostenlimit.

Budget-Durchsetzung

Jeder Tool-Aufruf wird gegen das Budget der aktiven Rolle verfolgt. Das Budget hat drei Dimensionen:

Budget[coder]: tokens 50000/200000 (25%) | shell 5/100 (5%) | cost $0.50/$5.00 (10%) → OK

Budget-Dimensionen

  • Kontext-Tokens - Gesamtzahl der durch Tool-Ausgaben verbrauchten Tokens
  • Shell-Aufrufe - Anzahl der ctx_shell / ctx_execute Aufrufe
  • Geschätzte Kosten - ungefähre USD-Kosten der Sitzung

Budget-Signale

Der Harness gibt Signale basierend auf dem Budgetverbrauch aus:

  • OK - Verbrauch unter Warnschwelle (Standard: 80%)
  • WARNING - Verbrauch zwischen Warn- (80%) und Block-Schwelle (100%). Eine Warnung wird an Tool-Antworten angehängt.
  • EXHAUSTED - Verbrauch bei oder über Schwelle. Standardmäßig arbeitet LeanCTX mit Warnungen weiter (blockiert nie). Für strikte Governance block_at_percent: 100 in der Rollen-Konfig setzen um Blocking zu aktivieren.

Tool-Richtlinien

Jede Rolle definiert, welche Tools erlaubt und verboten sind. Verbotene Tools überschreiben immer erlaubte Tools. Verwende * als Platzhalter.

[tools]
allowed = ["ctx_read", "ctx_search", "ctx_tree", "ctx_session"]
denied = ["ctx_edit", "ctx_shell"]

Shell-Richtlinie

  • track - Shell erlaubt, Befehle werden protokolliert (Standard)
  • compress - Shell erlaubt, Ausgabe wird komprimiert
  • deny - Shell-Zugriff komplett blockiert

Harness-Events

Der Agent Harness gibt strukturierte Events an den Event-Bus und das JSONL-Log aus:

  • BudgetWarning - eine Budget-Dimension hat die Warnschwelle überschritten
  • BudgetExhausted - eine Budget-Dimension ist vollständig verbraucht
  • PolicyViolation - ein Agent hat versucht, ein blockiertes Tool zu verwenden
  • RoleChanged - die aktive Rolle wurde zur Laufzeit gewechselt

Eigene Rollen

Erstelle TOML-Dateien in .lean-ctx/roles/ (projektlokal) oder ~/.lean-ctx/roles/ (global). Rollen unterstützen Vererbung über das inherits-Feld.

[role]
name = "security-auditor"
inherits = "reviewer"
description = "Security-focused code review"
shell_policy = "deny"

[tools]
allowed = ["ctx_read", "ctx_search", "ctx_tree", "ctx_review", "ctx_session"]
denied = ["ctx_edit", "ctx_shell", "ctx_execute"]

[limits]
max_context_tokens = 100000
max_shell_invocations = 0
max_cost_usd = 2.0

Aktuelle Rolle prüfen mit ctx_session action=role. Rollen wechseln mit ctx_session action=role value=<name>.

Rolle aktivieren

Setze die LEAN_CTX_ROLE Umgebungsvariable:

export LEAN_CTX_ROLE=reviewer

Oder zur Laufzeit per MCP wechseln:

ctx_session action=role value=debugger

Budget-Status prüfen:

ctx_session action=budget