Fehlermodi von Agenten klassifizieren
Erstellen Sie eine Taxonomie für Agentenfehler: Tool-Fehler, fehlerhafte Ausgaben, Reasoning-Schleifen, erschöpfter Kontext und nicht verfügbare externe Dienste. Entwickeln Sie für jeden Fehler geeignete Wiederherstellungsstrategien.
Fehlermodi von Agenten klassifizieren ist eine kostenlose AI Engineering Academy-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des AI Engineering Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der AI Engineering Academy-Kurs umfasst insgesamt 4 Lektionen.
Warum Agents auf besondere Weise scheitern
Agents scheitern anders als einfache LLM-Aufrufe. Ein Aufruf mit einem einzelnen Turn liefert entweder eine Antwort oder löst einen Fehler aus. Ein Agent, der eine Aufgabe in mehreren Schritten ausführt, kann an jeder Stelle scheitern – und der Fehler ist möglicherweise in der finalen Ausgabe nicht offensichtlich. Das Verständnis der Taxonomie von Agent-Fehlermustern ist der erste Schritt, um Agents zu entwickeln, die ihre eigenen Fehler erkennen, diagnostizieren und beheben.
Fehlermuster 1: Tool-Fehler
Tool-Fehler treten auf, wenn der Agent ein Tool mit ungültigen Argumenten aufruft, das Tool eine Exception auslöst oder ein leeres bzw. fehlerhaft formatiertes Ergebnis zurückgibt. Beispiele sind der Aufruf einer Such-API mit einer fehlerhaft formatierten Abfrage, eine Datenbankabfrage mit ungültigem SQL oder der Aufruf eines Code-Executors, der wegen eines Timeouts abbricht. Tool-Fehler sind am einfachsten zu erkennen, da sie explizite Exception-Signale erzeugen, die abgefangen und behandelt werden können.
class ToolError(Exception):
def __init__(self, tool_name: str, args: dict, error: Exception):
self.tool_name = tool_name
self.args = args
self.original_error = error
super().__init__(f'Tool {tool_name} failed: {error}')
def safe_tool_call(tool_func, args: dict) -> str:
try:
result = tool_func(**args)
if not result:
return 'Tool returned empty result. Try a different approach.'
return str(result)
except Exception as e:
raise ToolError(tool_func.__name__, args, e)Fehlermuster 2: Fehlerhaft formatierte Ausgaben
Fehlerhaft formatierte Ausgaben entstehen, wenn der Agent Text erzeugt, der nicht dem erwarteten Format entspricht – beispielsweise wenn er natürliche Sprache zurückgibt, obwohl der nächste Schritt JSON erwartet, oder ein Tool mit Argumenten in der falschen Struktur aufruft. Dies geschieht häufig, wenn der Agent seinen aktuellen Schritt mit einem vorherigen verwechselt. Validieren Sie das Format jeder Agent-Ausgabe, bevor Sie sie verwenden, und senden Sie bei einem falschen Format einen neuen Prompt.
import json
def validate_agent_output(raw_output: str, expected_format: str) -> dict:
if expected_format == 'json':
try:
return json.loads(raw_output)
except json.JSONDecodeError as e:
return {
'valid': False,
'error': f'Expected JSON but got invalid JSON: {e}',
'raw': raw_output[:200]
}
return {'valid': True, 'data': raw_output}Fehlermuster 3: Reasoning-Schleifen
Reasoning-Schleifen treten auf, wenn ein Agent ohne Fortschritt dieselbe Aktion oder denselben Gedankengang unbegrenzt wiederholt. Der Agent ruft möglicherweise zehnmal hintereinander dieselbe Suchabfrage auf, erhält jedes Mal dasselbe leere Ergebnis und weiß nicht, was er als Nächstes versuchen soll. Erkennen Sie Schleifen, indem Sie die letzten Aktionen verfolgen und auf Wiederholungen prüfen. Wenn eine Schleife erkannt wird, fügen Sie einen Meta-Prompt ein, der den Agent anweist, einen anderen Ansatz zu versuchen.
from collections import Counter
class LoopDetector:
def __init__(self, window: int = 5, threshold: int = 3):
self.recent_actions = []
self.window = window
self.threshold = threshold
def record(self, action: str) -> bool:
self.recent_actions.append(action)
if len(self.recent_actions) > self.window:
self.recent_actions.pop(0)
counts = Counter(self.recent_actions)
most_common_count = counts.most_common(1)[0][1] if counts else 0
return most_common_count >= self.threshold # True = loop detectedFehlermuster 4: Erschöpfung des Kontexts
Kontext-Erschöpfung tritt auf, wenn der angesammelte Verlauf des Agents (Tool-Aufrufe, Beobachtungen, Gedankengänge) das Kontextfenster des Modells überschreitet. Das Modell kürzt den Verlauf entweder unbemerkt (wodurch wichtige Informationen verloren gehen) oder löst einen Fehler wegen des Token-Limits aus. Verhindern Sie dies, indem Sie die Token-Nutzung über die einzelnen Schritte hinweg verfolgen und den Verlauf (durch Zusammenfassen älterer Schritte) komprimieren, bevor das Limit erreicht wird.
import tiktoken
CONTEXT_LIMIT = 100_000 # tokens
COMPRESS_AT = 80_000 # trigger compression with headroom
enc = tiktoken.encoding_for_model('gpt-4o')
def total_tokens(messages: list) -> int:
return sum(len(enc.encode(str(m))) for m in messages)
def check_context(messages: list) -> str:
tokens = total_tokens(messages)
if tokens > COMPRESS_AT:
return 'compress'
if tokens > CONTEXT_LIMIT:
return 'critical'
return 'ok'Fehlermuster 5: Nichtverfügbarkeit externer Dienste
Fehler externer Dienste treten auf, wenn der zugrunde liegende Dienst eines Tools nicht verfügbar ist, ein Rate-Limit erreicht oder unerwartete Fehler zurückgibt. Ein Agent, der die benötigte Datenbank nicht erreichen kann, steckt fest. Im Gegensatz zu Reasoning-Schleifen (die vom Agent verursacht werden) sind externe Fehler Umgebungsfehler. Behandeln Sie sie mit Wiederholungsversuchen und exponentiellem Backoff und stellen Sie Fallback-Tools bereit, die das Ergebnis mithilfe anderer Datenquellen annähern können.
import asyncio
async def resilient_tool_call(tool_func, args: dict, max_retries: int = 3) -> str:
for attempt in range(max_retries):
try:
return await tool_func(**args)
except (ConnectionError, TimeoutError) as e:
if attempt == max_retries - 1:
return f'Service unavailable after {max_retries} attempts. Error: {e}'
wait = 2 ** attempt # 1s, 2s, 4s
await asyncio.sleep(wait)
return 'Unexpected error in resilient_tool_call'Fehlermuster 6: Missverständnis des Ziels
Ein Missverständnis des Ziels liegt vor, wenn der Agent die Aufgabe falsch interpretiert und ein leicht abweichendes Ziel verfolgt. Dies ist der am schwersten zu erkennende Fehler, da der Agent die Aufgabe möglicherweise erfolgreich abschließt – nur nicht die vom Benutzer beabsichtigte. Bitten Sie den Agenten zu Beginn, das Ziel in eigenen Worten wiederzugeben, und implementieren Sie einen abschließenden Verifizierungsschritt, der prüft, ob das Ergebnis tatsächlich die ursprüngliche Frage beantwortet.
async def confirm_goal_understanding(original_task: str) -> str:
resp = await client.chat.completions.create(
model='gpt-4o',
messages=[
{'role': 'system', 'content': 'Restate the task in your own words. Be specific about what the final deliverable should be.'},
{'role': 'user', 'content': f'Task: {original_task}'}
]
)
return resp.choices[0].message.content
# Use the restatement as the first step of the agent
# to catch misunderstandings before any tools are calledAufbauen eines Systems zur Fehlerklassifizierung
Erstellen Sie einen strukturierten Fehlerklassifizierer, der jede Agent-Exception mit ihrem Typ versieht. Dadurch kann automatisch die passende Strategie zur Fehlerbehebung ausgewählt werden. Speichern Sie Fehlerprotokolle mit Typkennzeichnungen, damit Sie analysieren können, welche Fehlermuster am häufigsten auftreten, und priorisieren können, welche zuerst behoben werden sollen. Tool-Fehler und Schleifen treten typischerweise am häufigsten auf und lassen sich am einfachsten beheben.
from enum import Enum
from dataclasses import dataclass
class FailureType(Enum):
TOOL_ERROR = 'tool_error'
MALFORMED_OUTPUT = 'malformed_output'
REASONING_LOOP = 'reasoning_loop'
CONTEXT_EXHAUSTION = 'context_exhaustion'
EXTERNAL_SERVICE = 'external_service'
GOAL_MISUNDERSTANDING = 'goal_misunderstanding'
MAX_ITERATIONS = 'max_iterations'
UNKNOWN = 'unknown'
@dataclass
class AgentFailure:
failure_type: FailureType
step: int
tool_name: str | None
error_message: str
recoverable: boolZuordnen von Fehlern zu Maßnahmen zur Fehlerbehebung
Für jeden Fehlertyp gibt es eine passende Maßnahme zur Fehlerbehebung. Bei Tool-Fehlern ist ein erneuter Versuch mit angepassten Argumenten sinnvoll. Bei Schleifen sollte ein Diversity-Prompt den Agenten anweisen, etwas Neues zu versuchen. Bei Kontext-Erschöpfung ist eine Komprimierung erforderlich. Bei Fehlern externer Dienste sollten Fallback-Tools verwendet werden. Bei einem Missverständnis des Ziels sollte eine Rückfrage gestellt werden. Bilden Sie diese Zuordnungen explizit in einem Recovery-Router ab, den die Agent-Runtime bei auftretenden Fehlern aufruft.
RECOVERY_ACTIONS = {
FailureType.TOOL_ERROR: 'retry_with_corrected_args',
FailureType.MALFORMED_OUTPUT: 'reformat_output',
FailureType.REASONING_LOOP: 'inject_diversity_prompt',
FailureType.CONTEXT_EXHAUSTION: 'compress_history',
FailureType.EXTERNAL_SERVICE: 'use_fallback_tool',
FailureType.GOAL_MISUNDERSTANDING:'request_clarification',
FailureType.MAX_ITERATIONS: 'escalate_to_human',
FailureType.UNKNOWN: 'escalate_to_human'
}Festlegen von maximalen Iterationslimits
Jeder Agent muss ein maximales Iterationslimit als feste Sicherheitsgrenze haben. Ohne diese Grenze läuft ein Agent mit einer Schleife unbegrenzt weiter und verbraucht Tokens und Geld. Legen Sie das Limit anhand der erwarteten Aufgabenkomplexität fest: Ein einfacher Agent für Fragen und Antworten könnte auf 5 Schritte begrenzt werden, während ein komplexer Research-Agent möglicherweise 20 Schritte ausführen darf. Wenn das Limit erreicht ist, protokollieren Sie den Fehler, speichern Sie die Teilergebnisse und eskalieren Sie an einen Menschen oder geben Sie eine Teilantwort zurück.
MAX_ITERATIONS = 15
async def run_agent(task: str) -> str:
messages = [{'role': 'user', 'content': task}]
loop_detector = LoopDetector()
for iteration in range(MAX_ITERATIONS):
response = await get_agent_action(messages)
if response.is_final:
return response.answer
action_key = f'{response.tool}:{response.args}'
if loop_detector.record(action_key):
messages.append({'role': 'system', 'content': 'You are repeating yourself. Try a completely different approach.'})
continue
result = await execute_tool(response.tool, response.args)
messages.append({'role': 'tool', 'content': result})
return 'Task exceeded maximum iterations. Partial results: ' + get_partial_result(messages)Protokollieren von Fehlern für die Post-Mortem-Analyse
Protokollieren Sie jeden Agent-Fehler mit genügend Kontext, um ihn nachträglich diagnostizieren zu können: die vollständige Aufgabenbeschreibung, den kompletten Aktionsverlauf bis zum Fehlerzeitpunkt, den Fehlertyp und die Fehlermeldung, die Anzahl der Iterationen sowie die Token-Nutzung. Speichern Sie diese Informationen in einer Tabelle für Fehler mit einem Index auf failure_type und task_id. Überprüfen Sie die Fehlerprotokolle regelmäßig, um festzustellen, welche Aufgabentypen besonders anfällig für bestimmte Fehlermuster sind, und priorisieren Sie die entsprechenden Korrekturen.
import json
from dataclasses import asdict
async def log_agent_failure(task_id: str, failure: AgentFailure, history: list, pool):
async with pool.acquire() as conn:
await conn.execute('''
INSERT INTO agent_failures
(task_id, failure_type, step, tool_name, error_message,
recoverable, action_history, failed_at)
VALUES ($1, $2, $3, $4, $5, $6, $7, NOW())
''',
task_id,
failure.failure_type.value,
failure.step,
failure.tool_name,
failure.error_message,
failure.recoverable,
json.dumps(history)
)Kurzer Test
Testen Sie Ihr Verständnis der Klassifizierung von Agent-Fehlermustern.
Zusammenfassung der Lektion
In dieser Lektion haben Sie gelernt: Zu den sechs wichtigsten Fehlermodi von Agents gehören Toolfehler, fehlerhafte Ausgaben, Denkschleifen, erschöpfte Kontexte, Ausfälle externer Dienste und ein Missverständnis des Ziels. Die Schleifenerkennung anhand des Aktionsverlaufs erkennt sich wiederholende Muster, bevor sie das Iterationsbudget aufbrauchen, und die Zuordnung von Fehlertypen zu Wiederherstellungsaktionen ermöglicht eine automatisierte Selbstheilung. Als Nächstes implementieren wir Selbstkorrektur und reflektierendes Prompting.
Lerne Python mit einem KI-Tutor — kostenlos
Schreibe und führe echten Code in deinem Browser aus, bekomme sofortige Hilfe von einem 24/7 KI-Tutor und setze dein Lernen im Web oder in der App fort.
- Kurse
- 30
- Lektionen
- 120
Häufig gestellte Fragen
Ist die Lektion „Fehlermodi von Agenten klassifizieren“ kostenlos?
Ja — der vollständige Text von „Fehlermodi von Agenten klassifizieren“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des AI Engineering Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der AI Engineering Academy-Kurs umfasst insgesamt 4 Lektionen.
Was lerne ich in „Fehlermodi von Agenten klassifizieren“?
Erstellen Sie eine Taxonomie für Agentenfehler: Tool-Fehler, fehlerhafte Ausgaben, Reasoning-Schleifen, erschöpfter Kontext und nicht verfügbare externe Dienste. Entwickeln Sie für jeden Fehler geeig… Du übst AI Engineering Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.
Brauche ich Erfahrung, um AI Engineering Academy zu starten?
Keine Vorkenntnisse erforderlich. AI Engineering Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.
Wie lange dauert die Lektion „Fehlermodi von Agenten klassifizieren“?
Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.
Kann ich in dieser AI Engineering Academy-Lektion Code schreiben und ausführen?
Ja. Jede AI Engineering Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.
Alle Lektionen in diesem Kurs
- Fehlermodi von Agenten klassifizieren
- Selbstkorrektur und reflektierendes Prompting
- Checkpoints und Fortsetzen von Aufgaben
- Eskalation mit Human-in-the-Loop