Kurz gesagt
Sie beenden das Babysitting von KI-Agenten, indem Sie drei Dinge aufbauen: Leitplanken (Einschränkungen, die katastrophale Fehler verhindern), Observability (Protokolle und Metriken, die Ihnen sagen, was passiert ist) und Checkpoints (automatische Pausen, in denen Menschen Entscheidungen überprüfen). Richten Sie diese einmal ein, und Ihre Agenten können stundenlang autonom laufen, anstatt nur Minuten. Tools wie Apidog helfen, indem sie es Ihnen ermöglichen, API-Verträge zu definieren, die Agenten nicht verletzen können, wodurch Ihre API-Schicht zu einem Sicherheitsnetz wird.
Einleitung
Letzte Woche habe ich beobachtet, wie ein Entwickler 4 Stunden damit verbracht hat, einen KI-Agenten zu überwachen, der ihm eigentlich Zeit sparen sollte. Alle paar Minuten unterbrach er ihn, korrigierte einen Fehler und startete neu. Am Ende hatte er mehr manuelle Arbeit geleistet, als wenn er den Code einfach selbst geschrieben hätte.
Das ist das Babysitting-Problem, und es ist der Hauptgrund, warum KI-Agenten ihr Versprechen nicht erfüllen. Die Tools funktionieren. Die Modelle sind leistungsfähig. Aber die meisten Teams kommen nie über die Phase der ständigen Überwachung hinaus.
Folgendes geschieht: Die meisten KI-Agenten-Setups behandeln das LLM wie einen Junior-Entwickler, der bei jeder Aufgabe an die Hand genommen werden muss. Aber LLMs sind keine Junioren. Sie sind eher wie extrem schnelle, gelegentlich halluzinierende Praktikanten, die selbstbewusst das Falsche tun werden, wenn Sie keine Grenzen setzen.
💡
Wenn Sie APIs entwickeln oder mit KI-Agenten arbeiten, die APIs aufrufen, hilft Ihnen Apidog, diese Grenzen zu definieren. Indem Sie exakte Request/Response-Schemas angeben, erstellen Sie Verträge, die Agenten nicht versehentlich verletzen können. Es ist, als würden Sie Ihrem Agenten eine Karte geben, anstatt ihn herumirren zu lassen.
Definieren Sie API-Verträge, denen Ihre KI-Agenten folgen können
Am Ende dieses Leitfadens werden Sie Folgendes haben:
- Ein mentales Modell, um über Agentenautonomie nachzudenken
- Konkrete Muster für Leitplanken, Observability und Checkpoints
- Codebeispiele, die Sie heute in Ihre Projekte kopieren können
- Eine Checkliste zur Beurteilung, ob ein Agent bereit ist, unbeaufsichtigt zu laufen
Warum Agenten ständige Überwachung benötigen
KI-Agenten versagen auf vorhersehbare Weise. Das Verständnis dieser Fehlermodi ist der erste Schritt zu ihrer Behebung.
Fehlermodus 1: Ausweitung des Umfangs (Scope Creep)
Sie bitten einen Agenten, „Authentifizierung zum API-Endpunkt hinzuzufügen“. Er fügt Authentifizierung hinzu. Dann fügt er Ratenbegrenzung hinzu. Dann refaktorisiert er das Datenbankschema. Dann löscht er, was er für „ungenutzte“ Dateien hält, die sich als wichtig erweisen.
Der Agent machte weiter, weil ihm niemand sagte, er solle aufhören. LLMs haben kein angeborenes Gefühl für „fertig“. Sie werden weiterhin Änderungen vornehmen, bis sie ein Token-Limit erreichen oder Sie sie unterbrechen.
Fehlermodus 2: Falsche Abstraktionen
Ein Agent, der mit der Aufgabe „Fehlerbehandlung verbessern“ betraut ist, könnte überall try-catch-Blöcke hinzufügen. Technisch korrekt. Praktisch schrecklich. Der Code wird unlesbar, die Protokollierung ist inkonsistent, und die eigentlichen Fehlerfälle werden nicht behandelt.
Der Agent verstand die Anfrage wörtlich, verpasste aber die Absicht. Ohne Beispiele für eine gute Fehlerbehandlung griff er auf die offensichtlichste (und schlechteste) Interpretation zurück.
Fehlermodus 3: Kaskadierende Fehler
Ein Agent macht in Schritt 1 einen kleinen Fehler. Bis Schritt 10 hat sich dieser Fehler durch jede nachfolgende Entscheidung ausgebreitet. Was als Tippfehler in einem Funktionsnamen begann, wird zu einer kaputten API, kaputten Tests und einem verwirrten Entwickler, der versucht herauszufinden, was schiefgelaufen ist.
Dies ist der gefährlichste Fehlermodus, da der Agent nicht weiß, dass er versagt hat. Jeder Schritt erscheint isoliert betrachtet vernünftig. Nur das Endergebnis offenbart das Problem.
Fehlermodus 4: Ressourcenerschöpfung
Unbeaufsichtigt lassen sich einige Agenten ewig schleifen. Sie werden fehlgeschlagene API-Aufrufe auf unbestimmte Zeit wiederholen, ohne Limit neue Sub-Agenten erzeugen oder weiterhin Code generieren, bis sie Ihr Abrechnungslimit erreichen.
Ohne Ressourcenbeschränkungen wissen Agenten nicht, wann sie aufhören sollen.
Das Autonomie-Framework: Leitplanken, Observability, Checkpoints
Sie lösen diese Probleme mit drei Schichten. Stellen Sie sie sich als Pyramide vor: Leitplanken unten (Fehler verhindern), Observability in der Mitte (Fehler erkennen) und Checkpoints oben (Fehler beheben).
Schicht 1: Leitplanken (Prävention)
Leitplanken sind Einschränkungen, die katastrophale Fehler verhindern. Es sind Regeln, die Ihr Agent nicht brechen kann, durch Code erzwungen, nicht durch Prompts.
Harte Einschränkungen durch Code:
# Don't: Trust the agent to follow instructions
agent.run("Only modify files in the src/ directory")
# Do: Enforce constraints in code
import os
from pathlib import Path
ALLOWED_DIRECTORIES = {"src", "tests", "docs"}
def validate_file_path(path: str) -> bool:
"""Agent cannot write outside allowed directories."""
abs_path = Path(path).resolve()
return any(
str(abs_path).startswith(str(Path(d).resolve()))
for d in ALLOWED_DIRECTORIES
)
# Use in your agent's file operations
def agent_write_file(path: str, content: str):
if not validate_file_path(path):
raise ValueError(f"Cannot write to {path}: outside allowed directories")
with open(path, 'w') as f:
f.write(content)
API-Schema-Einschränkungen:
Wenn Ihr Agent APIs aufruft, verwenden Sie Schemas, um fehlerhafte Anfragen zu verhindern. Hier glänzt Apidog. Definieren Sie Ihren API-Vertrag einmal, und Ihr Agent kann keine falschen Datenstrukturen senden.
// apidog-schema.ts
export const CreateUserSchema = {
type: 'object',
required: ['email', 'name'],
properties: {
email: { type: 'string', format: 'email' },
name: { type: 'string', minLength: 1, maxLength: 100 },
role: { type: 'string', enum: ['user', 'admin', 'guest'] }
},
additionalProperties: false
}
// Agent must validate before calling API
function validateRequest(schema: object, data: unknown): void {
const valid = ajv.validate(schema, data)
if (!valid) {
throw new Error(`Invalid request: ${JSON.stringify(ajv.errors)}`)
}
}
Budgetbeschränkungen:
import time
from dataclasses import dataclass
@dataclass
class AgentBudget:
max_steps: int = 50
max_tokens: int = 100000
max_time_seconds: int = 600 # 10 minutes
max_api_calls: int = 100
class BudgetEnforcer:
def __init__(self, budget: AgentBudget):
self.budget = budget
self.start_time = time.time()
self.steps = 0
self.tokens_used = 0
self.api_calls = 0
def check(self) -> bool:
"""Returns False if budget exceeded."""
elapsed = time.time() - self.start_time
if self.steps >= self.budget.max_steps:
raise RuntimeError(f"Step limit reached: {self.steps}")
if self.tokens_used >= self.budget.max_tokens:
raise RuntimeError(f"Token limit reached: {self.tokens_used}")
if elapsed >= self.budget.max_time_seconds:
raise RuntimeError(f"Time limit reached: {elapsed:.0f}s")
if self.api_calls >= self.budget.max_api_calls:
raise RuntimeError(f"API call limit reached: {self.api_calls}")
return True
def record_step(self, tokens: int, api_calls: int = 0):
self.steps += 1
self.tokens_used += tokens
self.api_calls += api_calls
self.check()
Schicht 2: Observability (Erkennung)
Wenn Agenten stundenlang laufen, müssen Sie wissen, was sie tun, ohne jeden Schritt zu überwachen. Observability bietet Ihnen eine Zeitleiste von Entscheidungen.
Strukturierte Protokollierung:
import json
from datetime import datetime
from typing import Any
class AgentLogger:
def __init__(self, log_file: str = "agent_trace.jsonl"):
self.log_file = log_file
self.entries = []
def log(self, event: str, data: dict[str, Any] | None = None):
entry = {
"timestamp": datetime.utcnow().isoformat(),
"event": event,
"data": data or {}
}
self.entries.append(entry)
# Append to file immediately (don't lose logs on crash)
with open(self.log_file, 'a') as f:
f.write(json.dumps(entry) + '\n')
def log_decision(self, decision: str, reasoning: str, confidence: float):
"""Log when agent makes a significant decision."""
self.log("decision", {
"decision": decision,
"reasoning": reasoning,
"confidence": confidence
})
def log_action(self, action: str, params: dict, result: str):
"""Log agent actions and their outcomes."""
self.log("action", {
"action": action,
"params": params,
"result": result[:200] # Truncate long results
})
def log_error(self, error: str, context: dict):
"""Log errors with full context."""
self.log("error", {
"error": error,
"context": context
})
# Usage in agent
logger = AgentLogger()
logger.log_decision(
decision="Add rate limiting to API",
reasoning="Current endpoint has no protection against abuse",
confidence=0.85
)
logger.log_action(
action="write_file",
params={"path": "src/middleware/rate-limit.ts"},
result="Successfully wrote 45 lines"
)
Metriken-Dashboard:
Für länger laufende Agenten möchten Sie aggregierte Metriken, nicht nur einzelne Protokolle.
from collections import Counter
from dataclasses import dataclass, field
@dataclass
class AgentMetrics:
actions_taken: Counter = field(default_factory=Counter)
files_modified: list[str] = field(default_factory=list)
api_calls: dict[str, int] = field(default_factory=dict)
errors: list[str] = field(default_factory=list)
decisions_by_confidence: dict[str, int] = field(default_factory=lambda: {
"high (>0.9)": 0,
"medium (0.7-0.9)": 0,
"low (<0.7)": 0
})
def record_action(self, action: str):
self.actions_taken[action] += 1
def record_file_modification(self, path: str):
if path not in self.files_modified:
self.files_modified.append(path)
def record_api_call(self, endpoint: str):
self.api_calls[endpoint] = self.api_calls.get(endpoint, 0) + 1
def record_error(self, error: str):
self.errors.append(error)
def record_decision(self, confidence: float):
if confidence > 0.9:
self.decisions_by_confidence["high (>0.9)"] += 1
elif confidence >= 0.7:
self.decisions_by_confidence["medium (0.7-0.9)"] += 1
else:
self.decisions_by_confidence["low (<0.7)"] += 1
def summary(self) -> str:
return f"""
Agent Metrics Summary
=====================
Actions: {dict(self.actions_taken)}
Files modified: {len(self.files_modified)}
API calls: {self.api_calls}
Errors: {len(self.errors)}
Decisions by confidence: {self.decisions_by_confidence}
"""
Schicht 3: Checkpoints (Wiederherstellung)
Checkpoints sind automatische Pausen, in denen der Agent auf menschliche Überprüfung wartet. Sie ermöglichen es Ihnen, Probleme frühzeitig zu erkennen, ohne ständige Überwachung.
Automatische Checkpoints:
from enum import Enum
from typing import Callable
class CheckpointTrigger(Enum):
BEFORE_FILE_WRITE = "before_file_write"
BEFORE_API_CALL = "before_api_call"
BEFORE_GIT_COMMIT = "before_git_commit"
BEFORE_DELETE = "before_delete"
AFTER_N_STEPS = "after_n_steps"
@dataclass
class Checkpoint:
trigger: CheckpointTrigger
description: str
data: dict
requires_approval: bool = True
class CheckpointManager:
def __init__(self, auto_approve: set[CheckpointTrigger] | None = None):
self.auto_approve = auto_approve or set()
self.pending: list[Checkpoint] = []
def create_checkpoint(
self,
trigger: CheckpointTrigger,
description: str,
data: dict
) -> bool:
"""Returns True if approved, False if rejected."""
# Auto-approve certain triggers
if trigger in self.auto_approve:
return True
checkpoint = Checkpoint(
trigger=trigger,
description=description,
data=data
)
self.pending.append(checkpoint)
# In a real system, this would notify the human and wait
# For now, we return False to pause execution
return False
def approve(self, checkpoint_id: int) -> None:
"""Human approves a pending checkpoint."""
if 0 <= checkpoint_id < len(self.pending):
self.pending.pop(checkpoint_id)
def reject(self, checkpoint_id: int) -> None:
"""Human rejects a pending checkpoint."""
raise RuntimeError(f"Checkpoint rejected: {self.pending[checkpoint_id]}")
# Usage in agent
checkpoints = CheckpointManager(
auto_approve={CheckpointTrigger.BEFORE_FILE_WRITE} # Trust file writes
)
# Before destructive action
if not checkpoints.create_checkpoint(
trigger=CheckpointTrigger.BEFORE_DELETE,
description="About to delete src/legacy/ directory",
data={"path": "src/legacy/", "files": ["old_handler.ts", "deprecated.ts"]}
):
# Wait for human approval
agent.pause("Waiting for approval to delete files")
Autonome Agenten mit Apidog entwickeln
Wenn Ihr KI-Agent mit APIs interagiert, besteht das größte Risiko in fehlerhaften Anfragen, die nachgelagerte Fehler verursachen. Apidog hilft Ihnen, exakte API-Schemas zu definieren, denen Ihr Agent folgen muss.
Einrichtung von API-Verträgen:
- Importieren oder definieren Sie Ihre OpenAPI-Spezifikation in Apidog
- Generieren Sie Client-Code mit integrierter Validierung
- Geben Sie Ihrem Agenten den validierten Client anstelle von rohem HTTP
// Instead of letting agent call APIs directly
const response = await fetch('/api/users', {
method: 'POST',
body: JSON.stringify(data) // No validation
})
// Give agent a validated client
import { UsersApi } from './generated/apidog-client'
const usersApi = new UsersApi()
// Agent can only send valid requests - schema enforced
const response = await usersApi.createUser({
email: 'user@example.com',
name: 'Test User',
role: 'user' // Must be valid enum value
})
Dies verwandelt Ihre API-Schicht in eine Leitplanke. Der Agent kann buchstäblich keine ungültigen Daten senden, da der Client sie ablehnt, bevor die Anfrage gesendet wird.
Generieren Sie validierte API-Clients für Ihre KI-Agenten
Bewährte Muster und häufige Fehler
Muster 1: Das Genehmigungs-Sandwich
Für riskante Operationen ist eine Genehmigung vor UND nach der Ausführung erforderlich.
def risky_operation(agent, operation):
# Pre-approval
if not agent.checkpoint(f"About to: {operation.description}"):
return "Cancelled by user"
# Do the operation
result = operation.execute()
# Post-approval (verify the result)
if not agent.checkpoint(f"Verify result of: {operation.description}"):
operation.rollback()
return "Rolled back by user"
return result
Muster 2: Vertrauensschwellenwerte
Lassen Sie Agenten nicht auf Entscheidungen mit geringem Vertrauen handeln.
MIN_CONFIDENCE = 0.75
def agent_decide(options: list[dict]) -> dict:
best = max(options, key=lambda x: x.get('confidence', 0))
if best['confidence'] < MIN_CONFIDENCE:
# Escalate to human
return {
'action': 'escalate',
'reason': f"Best option has confidence {best['confidence']:.2f} < {MIN_CONFIDENCE}",
'options': options
}
return best
Muster 3: Idempotente Operationen
Gestalten Sie die Aktionen Ihres Agenten so, dass sie ohne Nebenwirkungen wiederholbar sind.
import hashlib
def idempotent_write(path: str, content: str) -> bool:
"""Only write if content changed."""
content_hash = hashlib.sha256(content.encode()).hexdigest()
existing_hash = None
if os.path.exists(path):
with open(path, 'r') as f:
existing_hash = hashlib.sha256(f.read().encode()).hexdigest()
if content_hash == existing_hash:
logger.log_action("write_file", {"path": path}, "Skipped - no changes")
return False
with open(path, 'w') as f:
f.write(content)
logger.log_action("write_file", {"path": path}, f"Wrote {len(content)} bytes")
return True
Häufige Fehler, die es zu vermeiden gilt
- Prompts als Einschränkungen vertrauen. „Lösche keine Dateien“ in einem Prompt ist keine Einschränkung. Dateiberechtigungen sind Einschränkungen.
- Kein Rollback-Plan. Wenn ein Agent einen Fehler macht, müssen Sie ihn rückgängig machen. Wenn Sie git oder Backups nicht verwenden, vertrauen Sie dem Agenten mit unwiederbringlichen Aktionen.
- Ignorieren von Vertrauenswerten. Die meisten LLMs geben einen Vertrauenswert aus oder können dazu aufgefordert werden. Geringes Vertrauen = Pause und den Menschen fragen.
- Übermäßige Überwachung. Wenn Sie jeden Schritt überwachen, haben Sie kein autonomes System gebaut. Sie haben ein langsames manuelles System gebaut.
- Ungenügende Spezifikation des Erfolgs. Der Agent muss wissen, wann er fertig ist. „Den Fehler beheben“ hat keine Endbedingung. „Den Fehler beheben UND alle Tests bestehen“ hat eine.
Alternativen und Vergleiche
| Ansatz | Autonomie | Risiko | Am besten geeignet für |
|---|---|---|---|
| Manuelle Codierung | Keine | Gering | Komplexe, kritische Arbeit |
| Pair Programming mit KI | Gering | Gering | Lernen, Erkunden |
| Überwachte Agenten | Mittel | Mittel | Routineaufgaben |
| Autonome Agenten mit Leitplanken | Hoch | Kontrolliert | Massenoperationen, Migrationen |
| Vollständig autonome Agenten | Sehr hoch | Hoch | Vertrauenswürdige, gut getestete Workflows |
Die meisten Teams sollten „autonom mit Leitplanken“ anstreben. Das ist der optimale Bereich, in dem Sie 80 % der Zeitersparnis mit 10 % des Risikos erzielen.
Anwendungsfälle aus der Praxis
Codebase-Migration. Ein Team verwendete einen autonomen Agenten, um 200 API-Endpunkte von REST nach GraphQL zu migrieren. Leitplanken verhinderten Schemaänderungen. Checkpoints erforderten eine Genehmigung vor dem Löschen alter Endpunkte. Die Migration dauerte 3 Tage statt 3 Wochen, ohne Produktionszwischenfälle.
Dokumentationsgenerierung. Ein Agent generiert automatisch API-Dokumente aus Code. Leitplanken stellen sicher, dass er nur aus bestimmten Verzeichnissen liest. Checkpoints pausieren vor der Veröffentlichung. Das Team überprüft einmal pro Woche, anstatt Dokumente manuell zu schreiben.
Testabdeckung. Ein Agent analysiert Code und schreibt fehlende Tests. Budgetbeschränkungen verhindern eine unkontrollierte Testgenerierung. Vertrauensschwellenwerte markieren unsichere Tests zur menschlichen Überprüfung. Die Abdeckung verbesserte sich in einem Monat von 60 % auf 85 %.
Zusammenfassung
Hier ist, was Sie gelernt haben:
- KI-Agenten versagen auf vorhersehbare Weise: Ausweitung des Umfangs, falsche Abstraktionen, kaskadierende Fehler, Ressourcenerschöpfung
- Drei Schichten lösen die meisten Probleme: Leitplanken (Prävention), Observability (Erkennung), Checkpoints (Wiederherstellung)
- Leitplanken sind Code, nicht Prompts. Erzwingen Sie Einschränkungen programmatisch.
- Observability bedeutet strukturierte Protokolle und Metriken, nicht jeden Schritt zu überwachen
- Checkpoints ermöglichen es Menschen, Entscheidungen ohne ständige Überwachung zu überprüfen
- API-Schemas von Apidog verwandeln Ihre API-Schicht in eine Leitplanke
Ihre nächsten Schritte:
- Identifizieren Sie Ihre sich am häufigsten wiederholende KI-unterstützte Aufgabe
- Definieren Sie Leitplanken: Was darf der Agent niemals tun?
- Fügen Sie strukturierte Protokollierung hinzu, um zu sehen, was passiert
- Erstellen Sie Checkpoints für risikoreiche Operationen
- Lassen Sie es 30 Minuten laufen und überprüfen Sie die Protokolle
Das Ziel ist nicht, Menschen aus der Schleife zu entfernen. Es geht darum, Menschen an die richtige Stelle in der Schleife zu setzen: hochrangige Entscheidungen zu treffen, anstatt Fehler auf niedriger Ebene zu korrigieren.
Erstellen Sie API-Leitplanken für Ihre KI-Agenten – kostenlos
FAQ
Was ist der Unterschied zwischen einem KI-Agenten und einem KI-Assistenten?
Ein Assistent reagiert auf Ihre Anfragen und wartet auf Ihre nächste Anweisung. Ein Agent verfolgt ein Ziel und plant und führt autonom Schritte aus, um es zu erreichen. Assistenten benötigen Sie in jeder Schleife. Agenten laufen, bis sie einen Checkpoint erreichen oder fertig sind.
Woher weiß ich, ob mein Agent bereit ist, autonom zu laufen?
Führen Sie ihn im überwachten Modus für 10 Sitzungen aus. Verfolgen Sie jedes Mal, wenn Sie eingreifen mussten. Wenn die Interventionen unter 2 pro Sitzung fallen und alle geringfügig waren (Klarstellungen, keine Korrekturen), ist er bereit. Wenn Interventionen häufig sind oder das Rückgängigmachen von Arbeit erfordern, fügen Sie weitere Leitplanken hinzu.
Was ist das größte Risiko bei autonomen Agenten?
Kaskadierende Fehler, die der Agent nicht erkennt. Ein kleiner Fehler am Anfang wird später zu einem großen Problem, und der Agent macht weiter, weil jeder Schritt isoliert betrachtet vernünftig erscheint. Checkpoints unterbrechen diese Kaskaden, indem sie eine Überprüfung erzwingen.
Kann ich diese Muster mit jedem LLM verwenden?
Ja. Die Muster (Leitplanken, Observability, Checkpoints) sind modellunabhängig. Sie funktionieren mit Claude, GPT-4, Gemini oder jedem anderen Modell. Die spezifischen Implementierungsdetails können variieren, aber die Konzepte sind übertragbar.
Wie stark verlangsamt Observability den Agenten?
Vernachlässigbar. Das Schreiben in eine Protokolldatei dauert Mikrosekunden. Die Verlangsamung kommt von Checkpoints, die auf menschliche Eingabe warten. Für wirklich autonome Läufe setzen Sie Checkpoints nur in risikoreichen Momenten, nicht bei jedem Schritt.
Was, wenn der Agent eine Entscheidung trifft, mit der ich nicht einverstanden bin?
Dafür sind Checkpoints da. Wenn Sie eine Entscheidung sehen, mit der Sie nicht einverstanden sind, lehnen Sie den Checkpoint ab. Der Agent macht einen Rollback oder versucht einen anderen Ansatz. Besser: Fügen Sie Ihre Präferenzen in die Anweisungen des Agenten ein, damit er Ihren Stil mit der Zeit lernt.
Sollte ich mit überwachten oder autonomen Agenten beginnen?
Beginnen Sie immer überwacht. Führen Sie den Agenten mit Checkpoints bei jeder wichtigen Aktion aus, bis Sie ihm vertrauen. Entfernen Sie Checkpoints für risikoarme Aktionen schrittweise. Dies baut schrittweise Vertrauen auf, anstatt bei Ihrem ersten autonomen Lauf einen katastrophalen Fehler zu riskieren.
Wie hilft Apidog speziell bei KI-Agenten?
Apidog generiert validierte API-Clients aus Ihren Schemas. Wenn ein Agent diese Clients verwendet, werden fehlerhafte Anfragen abgelehnt, bevor sie Ihr Backend erreichen. Dies verhindert eine ganze Klasse von Fehlern, bei denen der Agent eine falsche Datenstruktur oder ungültige Werte sendet.
Top comments (0)