Ausfälle und Fehler eines KI-Agenten beheben und künftig vermeiden

Ausfälle und Fehler eines KI-Agenten beheben Sie am schnellsten in einer festen Reihenfolge. Zuerst prüfen Sie Verbindung und Konfiguration, dann Rechte und Zugangsdaten, dann die Feldtypen im Zielsystem und die Werkzeugdefinitionen. Das Modell prüfen Sie zuletzt. Die meisten Störungen im Betrieb entstehen an den Übergängen zu CRM, Helpdesk oder Buchhaltung, nicht im Sprachmodell selbst.

Diese Einschätzung stützt die Hilfeseite von Zendesk zur CRM-Verbindung ihrer AI Agents. Sie nennt als Prüfpunkte fast nur Einstellungen der Integration: Schalter, IDs, Auslöser, Geschäftszeiten und Feldtypen.

Der folgende Guide ordnet typische Symptome ihren Ursachen zu. Er geht ein Beispiel mit einem Service-Agenten vor Zoho Desk durch. Am Ende stehen ein Notfallplan und eine Überwachung, mit der Sie Fehler künftig früh bemerken. Sie brauchen dafür keine Programmierkenntnisse, wohl aber Zugriff auf die Einstellungen Ihrer Systeme oder eine Person, die ihn hat.

Ein KI-Agent ist ein Programm, das ein Sprachmodell wie Claude nutzt, um eine Aufgabe in mehreren Schritten zu erledigen. Dabei greift es über Werkzeuge auf andere Systeme zu. Ein Werkzeug (englisch tool) ist eine fest beschriebene Funktion wie „Ticket anlegen“ oder „Kontakt suchen“, die der Agent aufrufen darf. Laut der Modellübersicht von Anthropic unterstützen alle aktuellen Claude-Modelle tool use, also genau diesen Aufruf von Werkzeugen.

Die Integration ist die technische Verbindung zwischen Agent und Zielsystem. Bei Claude ist das ein connector, ein MCP server, ein plugin oder ein skill. Ein MCP server ist ein kleiner Dienst, der Claude die Funktionen eines Systems in einheitlicher Form anbietet. Wie ein Agent grundsätzlich aufgebaut ist, erklärt der Beitrag Was sind KI-Agenten: Aufbau, Grenzen und Kontrolle.

Für die Fehlersuche zählen fünf Stellen, an denen ein Agent ausfallen kann:

• die Verbindung zum Zielsystem, also Schalter, IDs und Auslöser,
• die Rechte und Zugangsdaten, mit denen der Agent sich anmeldet,
• die Daten und Felder, in die er schreibt,
• die Beschreibung der Werkzeuge, nach der er entscheidet,
• das Modell und seine Einstellungen.

Die Reihenfolge der Liste ist zugleich eine gute Prüfreihenfolge. Die ersten drei Punkte lassen sich in Minuten prüfen, die letzten beiden kosten mehr Zeit.

Typische Störungen eines KI-Agenten lassen sich meist schon am Symptom einer Ursache zuordnen. Die folgende Tabelle fasst zusammen, was die Hilfeseiten von Zendesk und Google Cloud, die Modelldokumentation von Anthropic und Berichte aus der Praxis beschreiben. Sie ersetzt keine Diagnose, aber sie sagt Ihnen, wo Sie zuerst nachsehen.

Symptom	Wahrscheinliche Ursache	Erste Prüfung
Agent nimmt an keinem Gespräch teil	Automatisierung ausgeschaltet, falsche Abteilungs-ID, kein Modell hinterlegt	Konfiguration der Integration
Übergabe an Mitarbeitende scheitert	Niemand online, Höchstzahl an Chats erreicht, außerhalb der Geschäftszeiten	Status, Kapazität, Geschäftszeiten
Schreiben in ein Feld schlägt fehl	Datentyp passt nicht, etwa ein Feld nur für Text	Feldtyp im Zielsystem
Fehler 401 bei Aufrufen	Token außerhalb seines Kontexts genutzt oder falscher Endpunkt	Weitergabe von Tokens, Endpunkt
Werkzeug scheitert, obwohl unterstützt	Einstellung der Organisation, etwa deaktivierte Websuche	Admin-Einstellungen
Alle Anfragen an das Modell schlagen fehl	Modell eingestellt	Lebenszyklus-Status des Modells
Antworten sind veraltet	Dokumentation hinkt dem Produkt hinterher	Wissensbasis und Anweisungen

Nur eine Zeile betrifft das Modell direkt. Die übrigen Ursachen liegen in Einstellungen, Rechten oder Daten, die Ihr Team selbst ändern kann.

Die Konfiguration der Verbindung ist die erste Prüfstelle, wenn ein KI-Agent gar nicht reagiert. Die Zendesk-Hilfe zu Fehlern bei der CRM-Verbindung mit AI Agents gibt dafür eine Checkliste vor. Sie gilt für Zendesk, die Fragen lassen sich aber auf jeden Agenten vor einem Helpdesk übertragen.

Wenn der Agent an keinem Gespräch teilnimmt

Zendesk nennt dafür vier Prüffragen:

• Ist die Automatisierungsengine eingeschaltet?
• Steht das Bot-Konto in seiner Abteilung oder Gruppe allein?
• Ist die Abteilungs-ID korrekt?
• Gibt es ein KI-Modell?

Außerdem müssen Konfigurationselemente wie Auslöser definiert sein und in der richtigen Reihenfolge stehen.

Wenn die Übergabe an Menschen scheitert

Eine Eskalation ist die Übergabe eines Gesprächs vom Agenten an einen Menschen. Laut Zendesk scheitert sie, wenn keine Mitarbeitenden online sind oder die Konfiguration die zulässige Zahl an Agenten oder Chats überschreitet. Zudem muss die Eskalation innerhalb der Geschäftszeiten erfolgen, die im CRM oder bei Zendesk hinterlegt sind.

Wenn Felder nicht geschrieben werden

Fehler beim Hinzufügen von Stichwörtern entstehen laut Zendesk, wenn der Stichworttyp nicht zu dem passt, was das CRM akzeptiert. Ein Feld lässt zum Beispiel nur Textwerte zu. Prüfen Sie also immer zuerst den Feldtyp im Zielsystem, bevor Sie die Anweisungen des Agenten ändern.

Zugangsdaten und Laufzeitumgebung sind die zweite Prüfstelle, wenn ein KI-Agent zwar startet, aber bei Aufrufen scheitert. Ein Token ist ein digitaler Berechtigungsnachweis, mit dem sich der Agent bei einem System anmeldet. Die Fehlerbehebung von Google Cloud für die Agentenlaufzeit beschreibt dazu zwei typische Ursachen für den Statuscode 401.

Erstens versucht der Agent, ein Token außerhalb des Kontexts zu nutzen, in dem es ausgestellt wurde. Ein Beispiel ist die Weitergabe eines Tokens zwischen zwei Agenten. Google bindet Tokens dort standardmäßig an Zertifikate, um Token-Diebstahl zu verhindern. Zweitens ruft der Agent einen Endpunkt auf, der nicht mit mTLS kompatibel ist, etwa telemetry.googleapis.com statt telemetry.mtls.googleapis.com. mTLS ist ein Verfahren, bei dem sich beide Seiten einer Verbindung per Zertifikat ausweisen.

Die Schutzrichtlinie lässt sich abschalten. Google rät jedoch dringend davon ab, weil der Agent dadurch anfällig für Anmeldediebstahl wird. Für Ihren Betrieb heißt das: Ein 401 ist ein Hinweis auf einen Konstruktionsfehler, nicht auf eine zu strenge Sicherheitseinstellung.

Eine dritte Ursache ist schlicht veraltete Software. Laut Google tritt ein Importfehler auf, wenn das Paket google-cloud-aiplatform älter als Version 1.82.0 ist. Der Befehl pip show google-cloud-aiplatform zeigt die installierte Version, pip install google-cloud-aiplatform --upgrade aktualisiert sie. In Notebooks wie Jupyter oder Colab müssen Sie danach unter Umständen die Laufzeit neu starten.

Ein Modellwechsel verursacht seltener Fehler als eine Integration, aber er verursacht sie plötzlich. Anthropic führt jedes Modell in einem von drei Zuständen. Active bedeutet verfügbar und nicht zur Einstellung vorgesehen. Deprecated bedeutet weiter nutzbar für bestehende Kunden, aber auf dem Weg zur Einstellung. Retired bedeutet, dass jede Anfrage mit diesem Modell fehlschlägt.

Ein Agent, der einen eingestellten Modellnamen fest im Code führt, fällt also vollständig aus. Die Modellübersicht nennt die frühesten Termine: Claude Fable 5.1 wird nicht vor dem 1. September 2027 eingestellt, Claude Haiku 5.5 nicht vor dem 7. Oktober 2027. Tragen Sie solche Termine für jedes eingesetzte Modell in den Betriebskalender ein.

Auch ohne Einstellung kann ein Wechsel Einstellungen ungültig machen. Die Models API von Anthropic liefert für jedes verfügbare Modell max_input_tokens, max_tokens und ein capabilities-Objekt mit den unterstützten Funktionen. Für Claude Sonnet 5.5 meldet sie zum Beispiel, dass sich das Nachdenken des Modells nicht abschalten lässt. Eine Konfiguration, die das voraussetzt, scheitert dort.

Beachten Sie eine Einschränkung: Die Liste der Modelle zeigt standardmäßig nur aktive und abgekündigte Modelle. Eingestellte Modelle erscheinen nur, wenn Sie sie ausdrücklich anfordern. Zudem kann eine Einstellung Ihrer Organisation ein unterstütztes Werkzeug blockieren, etwa wenn ein Administrator die Websuche deaktiviert hat.

Unklare Werkzeugdefinitionen führen dazu, dass ein KI-Agent das falsche Werkzeug wählt oder ein richtiges falsch befüllt. Jede Werkzeugbeschreibung sollte deshalb einen Zweck, die Pflichtfelder mit Datentyp und einen klaren Fall nennen, in dem das Werkzeug nicht passt. Zwei Werkzeuge mit ähnlichen Namen und überlappendem Zweck sind eine häufige Quelle von Fehlgriffen.

Testen Sie jede Werkzeugbeschreibung mit Anfragen, die knapp an der Grenze zwischen zwei Werkzeugen liegen. Wählt der Agent dabei das falsche, schärfen Sie die Beschreibung, nicht die allgemeinen Anweisungen. Halten Sie außerdem fest, in welches System der Agent seine Ergebnisse schreibt. Das führende System bleibt der Ort, an dem der Stand eines Vorgangs gilt.

Veraltetes Wissen ist die zweite Ursache für falsche Entscheidungen eines KI-Agenten. Ein Beitrag auf Reddit beschreibt den Fall: Hinkt die Dokumentation dem Produkt hinterher, muss der Agent mit veralteten Informationen arbeiten. Der Verfasser fragt Teams, die KI im Support einsetzen, wie viel Zeit die Wartung kostet und was die meiste Arbeit macht. Planen Sie deshalb feste Zuständigkeiten für die Pflege von Wissensbasis und Anweisungen ein.

Das folgende Beispiel zeigt die Prüfreihenfolge an einem typischen Fall. Ein Agent auf Claude Haiku 5.5 sortiert eingehende Anfragen vor Zoho Desk. Anthropic sieht dieses Modell für Aufgaben mit hohem Volumen wie Klassifizierung, Extraktion und Routing vor. Der Agent setzt eine Kategorie, trägt Stichwörter ein und übergibt schwierige Fälle an das Team.

Das Symptom: Seit einer Woche bleiben Anfragen, die nach 18 Uhr eingehen, ohne Bearbeiter. Zusätzlich fehlen bei manchen Tickets die Stichwörter.

1. Teilnahme prüfen. Der Agent antwortet weiterhin auf jede Anfrage. Schalter, Abteilungs-ID und Modell sind also in Ordnung.
2. Eskalation prüfen. Die Geschäftszeiten im System enden um 18 Uhr. Eine Übergabe danach ist nach der Konfiguration nicht zulässig, und niemand ist online.
3. Feldtyp prüfen. Das Stichwortfeld akzeptiert nur Text. Der Agent übergibt bei mehreren Stichwörtern eine Liste, die das System ablehnt.
4. Korrigieren. Außerhalb der Geschäftszeiten legt der Agent ein Ticket mit Vermerk für den Folgetag an und sagt dem Kunden, wann er Antwort erhält. Stichwörter übergibt das Werkzeug als einen Textwert.
5. Gegenprüfen. Das Team spielt die Testanfragen erneut durch, auch solche, die vorher funktionierten.

Keiner der beiden Fehler lag im Modell. Beide waren Einstellungen, die sich nach dem Start geändert hatten oder nie getestet wurden. Dasselbe Muster gilt, wenn der Agent statt in einen Helpdesk in Zoho CRM schreibt.

Ein Notfallplan legt vorab fest, wer was tut, wenn ein KI-Agent ausfällt oder falsche Ergebnisse liefert. Er gehört vor den Produktivstart, nicht in den Moment der Störung. Benennen Sie eine verantwortliche Person mit Vertretung, die den Agenten anhalten darf.

Diese sechs Schritte haben sich als Gerüst bewährt:

1. Schaden begrenzen. Den Agenten anhalten oder auf reines Lesen beschränken. Eingehende Anfragen gehen direkt an das Team.
2. Symptom festhalten. Zeitpunkt, betroffene Vorgänge, Fehlermeldung und letzte Änderung an Systemen oder Modell notieren.
3. In fester Reihenfolge prüfen. Verbindung, Zugangsdaten, Feldtypen, Werkzeugdefinitionen, Modell.
4. Eine Änderung je Versuch. Nur eine Stellschraube ändern und sofort testen, sonst bleibt die Ursache unklar.
5. Gegenprüfen. Sicherstellen, dass die Korrektur nichts anderes beschädigt hat.
6. Ursache dokumentieren. Den Fehlerfall als neuen Testfall in die Testsammlung aufnehmen.

Schritt fünf wird oft übersprungen. Ein Beitrag auf Reddit beschreibt genau diese Last: Nach einer schlechten Antwort muss jemand den Fehler finden, Anweisungen oder Wissensbasis anpassen und prüfen, ob die Korrektur etwas anderes kaputt gemacht hat. Ohne feste Testsammlung erledigt diese Prüfung niemand zuverlässig.

Eine Überwachung meldet Fehler eines KI-Agenten, bevor Kunden sie bemerken. Sie besteht aus drei Teilen: Protokollen, Warnmeldungen und wiederholbaren Tests. Ohne diese Teile fallen Störungen erst auf, wenn sich jemand beschwert.

Protokolle für jeden Werkzeugaufruf

Protokollieren Sie für jeden Aufruf das Werkzeug, die übergebenen Felder, die Antwort des Zielsystems und die Dauer. So sehen Sie bei einem Feldfehler sofort den abgelehnten Wert. Legen Sie fest, wie lange Protokolle aufbewahrt werden, damit sie nicht unkontrolliert wachsen.

Warnmeldungen bei Abweichungen

Eine Warnung sollte auslösen, wenn Fehlermeldungen eines Werkzeugs zunehmen, Eskalationen ausbleiben oder ein Code wie 401 auftritt. Ebenso wichtig ist ein Hinweis, wenn ein eingesetztes Modell den Status deprecated erhält.

Feste Testsammlung nach jeder Änderung

Halten Sie je Werkzeug einige typische und einige schwierige Testfälle bereit. Spielen Sie sie nach jeder Änderung an Feldern, Rechten, Anweisungen oder Modell erneut durch. Bei Svennis legen wir diese Testfälle für jede Verbindung vor dem Produktivstart fest und führen sie nach jeder Änderung im CRM oder am Modell erneut aus. Die Störung, die wir dabei am häufigsten finden, ist ein umbenanntes oder anders typisiertes Feld, nicht ein Fehler des Modells.

Für Unternehmen in Deutschland ergeben sich bei der Fehlersuche an einem KI-Agenten drei besondere Punkte. Sie betreffen Sprache, interne Richtlinien und die Zahl der verbundenen Systeme.

Erstens sind viele Hilfeseiten auf Deutsch maschinell übersetzt. Zendesk weist auf seiner Seite ausdrücklich darauf hin und erklärt die englische Fassung zur offiziellen Version. Wenn eine Einstellung im deutschen Text unklar benannt ist, prüfen Sie den englischen Originalnamen. Dasselbe gilt für Feldnamen: Die Oberfläche zeigt deutsche Bezeichnungen, die Schnittstelle arbeitet oft mit anderen internen Namen.

Zweitens schränken IT-Richtlinien in vielen Betrieben Funktionen zentral ein. Die Modellübersicht von Anthropic nennt genau diesen Fall: Eine Einstellung der Organisation kann einen Aufruf scheitern lassen, obwohl das Werkzeug unterstützt wird. Klären Sie daher vor dem Start mit der IT, welche Funktionen freigegeben sind.

Drittens hängen im Mittelstand an einem Agenten oft mehrere Systeme, etwa Helpdesk, CRM und Zoho Books. Jede zusätzliche Verbindung bringt eigene Rechte, Felder und Geschäftszeiten mit. Schreibende Zugriffe auf die Buchhaltung sollten deshalb eine menschliche Freigabe behalten. Wie sich solche Abläufe insgesamt ordnen lassen, beschreibt die Seite KI-Automatisierung für den Mittelstand.

Wenn Ihr KI-Agent bereits läuft, beginnen Sie mit einer Bestandsaufnahme. Listen Sie alle Werkzeuge mit ihrem Zielsystem, den genutzten Feldern und den eingesetzten Modellen auf. Prüfen Sie dann für jedes Modell den Lebenszyklus-Status und legen Sie für jede Verbindung eine kleine Testsammlung an. Schreiben Sie den Notfallplan auf eine Seite und benennen Sie die verantwortliche Person.

Wenn Sie erst prüfen wollen, ob Ihre Daten und Systeme für einen Agenten bereit sind, hilft der KI-Readiness-Check für Ihr Unternehmen. Er zeigt, wo Felder, Rechte oder Zuständigkeiten vor dem Start geklärt werden müssen.

Wenn Sie einen neuen Agenten planen, bauen Sie Überwachung und Tests von Anfang an ein. Bei Svennis verläuft das in vier Schritten: Workshop, dann Pilot Claude A, ein KI-Agent auf Claude für einen Prozess, oder Pilot Claude B mit Claude Team für das ganze Team, danach die Activation der Abteilung und schließlich der monatliche Betrieb. Für jede Verbindung bauen wir einen connector, einen MCP server, ein plugin oder einen skill. Wir zeigen die Optionen mit ihren Kosten, und Sie entscheiden.

Den Ablauf eines solchen Piloten beschreibt die Seite KI-Agent mit Claude: Pilot A in 30 Tagen.