Im November letzten Jahres übergab ich einem Kunden einen Claude-gestützten Agenten, der eingehende Support-Tickets triagieren, sie zur richtigen Abteilung weiterleiten und erste Entwürfe für Antworten schreiben sollte. Es dauerte drei Wochen, das zu bauen. Sah im Staging brillant aus. Am ersten Tag in der Produktion halluzinierte es eine Rückgaberichtlinie, die es gar nicht gibt, leitete siebzehn Tickets in die falsche Warteschlange weiter und versicherte einem Kunden selbstsicher, dass seine Bestellung „bis Donnerstag" ankommt – ohne jeglichen Zugriff auf Versanddaten.
Also. Ich habe einiges gelernt.
Dieser Beitrag behandelt das, was ich jetzt weiß, nachdem ich diesen Agenten ordnungsgemäß umgebaut und mehrere weitere seit damals versendet habe. Keine Theorie. Echte Entscheidungen, die ich getroffen habe, Tools, zu denen ich gegriffen habe, und Fehler, die ich nicht wiederhole. Falls du Agenturbesitzer oder Freelancer bist und mit dem Claude Agent SDK über die Demo-Phase hinausgehen möchtest, ist das für dich geschrieben.
---
Was das Claude Agent SDK wirklich ist (und nicht)
Allererstes: Das SDK ist keine Magie. Es ist eine strukturierte Methode, um Claude Zugang zu Tools zu geben, Gesprächskontexte über mehrere Durchläufe hinweg zu verwalten und zu orchestrieren, was auf eine Entscheidungsschleife hinausläuft. Claude denkt über eine Aufgabe nach, entscheidet, ob er ein Tool aufrufen soll, erhält ein Ergebnis zurück, denkt erneut nach und ruft entweder ein weiteres Tool auf oder produziert eine endgültige Antwort.
Diese Schleife klingt einfach. Sie ist einfach. Die Komplexität lebt vollständig in dem, was du drumherum legst.
Das SDK gibt dir die Rohrleitungen. Du bist immer noch dafür verantwortlich, den Wasserdruck, den Rohrdurchmesser und ob du daran gedacht hast, den Haupthahn zu schließen, bevor du anfängst zu bohren. Ich habe Agenturbesitzer gesehen, die das SDK einem Junior-Developer geben, ein fertiges Produkt in einem Sprint erwarten und etwas zurückbekommen, das technisch läuft, aber bei jeder Eingabe auseinanderfällt, die nicht im Happy Path liegt.
Wie die Schleife in der Praxis aussieht
Du definierst Tools als JSON-Schemas. Claude liest diese Schemas, entscheidet, wann er sie verwendet, übergibt strukturierte Argumente, und dein Code führt die eigentliche Logik aus. Claude führt niemals Code direkt aus. Er fragt. Dein System leistet die Arbeit. Dann erhält Claude das Ergebnis und fährt fort.
Diese Trennung ist wichtiger, als die meisten Leute denken. Sie bedeutet, dass Claude immer ein Orchestrator ist, keine Ausführungsinstanz. Und dieses Verständnis sollte jede architektonische Entscheidung prägen, die du triffst.
---
Tools entwerfen, die Claude tatsächlich nutzen kann
Hier scheitern die meisten Builds. Ich habe im vergangenen Jahr wahrscheinlich fünfzehn Agent-Codebasen von anderen Entwicklern überprüft, und das häufigste Problem ist nicht Prompt Engineering oder Modellwahl. Es ist schlecht designte Tools.
Hier siehst du, was „schlecht designt" in der Praxis bedeutet:
- Ein Tool namens
process_data, das je nach übergebenen Parametern fünf unzusammenhängende Dinge tut - Tool-Beschreibungen, die wie interne Code-Kommentare klingen („ruft den v2-Endpoint mit Auth-Headern auf")
- Parameter mit Namen wie
typeodermode, die beliebige Strings statt Enums akzeptieren - Keine Fehlerinformationen im Rückgabewert, daher hat Claude keine Ahnung, ob der Aufruf erfolgreich war
Anfang 2023 hatte Seahawk ein Content-Pipeline-Projekt, bei dem wir ein manage_content-Tool erstellt hatten, das einen action-Parameter akzeptierte: create, update, delete, publish, unpublish, archive. Claude wählte ständig die falsche Aktion, weil die Unterschiede allein aus dem Schema nicht klar waren. Wir teilten es in sechs separate Tools auf. Die Genauigkeit bei dieser spezifischen Entscheidung stieg von etwa 60% auf 94% in unseren internen Tests. Eine einzige Änderung.
Die Regeln, die ich jetzt befolge
- Ein Tool, eine Aufgabe. Wenn du den Zweck des Tools nicht in einem einzigen Satz ohne „und" beschreiben kannst, teile es auf.
- Verwende Enums, wo immer möglich. Lass Claude nicht Strings erraten.
- Schreibe die Beschreibung für Claude, nicht für einen menschlichen Entwickler. Claude kennt deine Codebasis nicht. Es kennt nur das, was du ihm erzählst.
- Gib immer strukturierte Daten mit einem expliziten Erfolgs-/Fehlerstatus zurück. Lass Claude nie aus Schweigen ableiten.
- Halte Toolnamen verb-zuerst. search_orders, create_draft, fetch_customer_record. Nicht orders, draft,
customer.
Die Tool-Use-Dokumentation von Anthropic geht tiefer auf die Schemastruktur ein und verdient es, sorgfältig gelesen zu werden, nicht nur überflogen.
---
Kontextverwaltung ist die versteckte Kosten
Das spricht niemand genug an. Token sind nicht kostenlos, und Agenten sind gefräßig.
Jede Schleife beinhaltet die vollständige Konversationshistorie, alle Tool-Schemas, Systemprompt und Tool-Ergebnisse. Ein mäßig komplexer Agent mit zehn Tools und einem detaillierten Systemprompt könnte jede Benutzersitzung bei 3.000–4.000 Token beginnen, bevor der Benutzer ein einziges Zeichen eingegeben hat. Addiere fünf oder sechs Tool-Aufrufe mit Ergebnissen, und du schaust auf 15.000–20.000 Token pro gelöster Aufgabe. Bei Claudes aktuellem API-Pricing addiert sich das schnell bei größeren Volumina.
Ich verfolge das jetzt obsessiv. Für jeden Agent, den ich ausliefere, führe ich während der QA eine Kosten-pro-Auflösung-Rechnung durch. Wenn sie über einem Schwellenwert liegt, den ich mit dem Client vorher vereinbart habe, gehe ich zurück und straffe den Systemprompt, reduziere Tool-Schemas oder überprüfe, ob ich statische Kontexte mit Prompt Caching cachen kann, das Anthropic hinzugefügt hat und das ich wirklich in jedem Projekt nutze. Cache-fähige Token kosten bei einem Cache-Hit etwa 10% des Standard-Eingabesatzes. Bei einem ausgelasteten Agent, der jeden Tag Tausende Male denselben Systemprompt erneut ausführt, ist das kein Rundungsfehler.
Kürzen ohne Dinge zu beschädigen
Die Versuchung ist groß, einen umfangreichen, detaillierten Systemprompt zu schreiben, der alle Grenzfälle abdeckt. Widerstehe. Jede Zeile, die du hinzufügst, kostet Token bei jeder Schleife. Schreibe für den häufigen Fall. Behandle Grenzfälle in Tool-Rückgabewerten oder in kürzeren In-Context-Anweisungen, die zum richtigen Moment injiziert werden.
Ich streiche auch skrupellos Tool-Beschreibungen, sobald ein Agent funktioniert. Wenn eine Beschreibung sagt „Dieses Tool durchsucht die Auftragsdatenbank und gibt eine Liste der Aufträge zurück, die der Abfrage entsprechen, einschließlich Auftrags-ID, Kundenname, Positionen, Versandstatus und Zeitstempel" kürze ich es auf „Aufträge nach Abfrage durchsuchen. Gibt entsprechende Auftragszeilen zurück." Claude ist intelligent genug. Es braucht die Feldliste nicht in der Tool-Beschreibung, wenn das Rückgabe-Schema diese Felder richtig dokumentiert.
---
Multi-Agent-Orchestrierung: Wenn ein Agent nicht ausreicht
Single-Agent-Systeme scheitern bei einer bestimmten Komplexitätsgrenze. Ich bin auf ein solches Projekt für ein Immobilienverwaltungsunternehmen letztes Frühjahr gestoßen. Der Agent musste Wartungsanfragen bearbeiten, mit Auftragnehmern kommunizieren, eine Notion-Datenbank aktualisieren, Templates-E-Mails via SendGrid versenden und Verfügbarkeitsdaten aus einer Custom-API abrufen. Sieben Tools, mehrere davon mit Sub-Workflows.
Ein Agent, der das alles koordinieren versuchte, wurde unzuverlässig. Der Kontext wurde chaotisch. Claude verlor gelegentlich den Überblick, an welcher Teilaufgabe er gerade arbeitete.
Die Lösung war rückblickend offensichtlich: Orchestrator plus Spezialisten. Ein Top-Level-Claude-Agent behandelt Intent-Klassifizierung und Routing. Spezialist-Sub-Agenten bearbeiten spezifische Domänen (Kommunikation, Planung, Datenaktualisierungen) und berichten strukturierte Ergebnisse zurück. Der Orchestrator sieht nie die Internals dessen, was jeder Spezialist tat. Er sieht nur die Ausgabe.
Dieses Muster wird in Anthropics eigener Multi-Agent-Anleitung beschrieben und kartografiert eng, wie du ein menschliches Team gestalten würdest. Ein Projektmanager schreibt nicht persönlich jede E-Mail und aktualisiert nicht jede Tabellenkalkulation. Er delegiert, wartet auf Bestätigung und geht weiter.
Praktische Anmerkungen zum Design von Sub-Agenten
- Gib jedem Sub-Agenten einen engen, spezifischen System Prompt. Keine bereichsübergreifenden Anweisungen.
- Sub-Agenten sollten niemals mehr Tools haben, als sie für ihren Bereich brauchen. Tool-Überfluss ist genauso gefährlich bei Sub-Agenten wie beim Haupt-Orchestrator.
- Gib Kontext explizit weiter. Nimm nicht an, dass ein Sub-Agent "weiß", was upstream passiert ist. Schick ihm genau das, was er braucht, nicht mehr.
---
Fehler elegant behandeln (weil sie passieren werden)
Production Agents schlagen fehl. Sie laufen in Timeouts. Externe APIs returnen 500s. Nutzer schicken Inputs, die du nie erwartet hast. Claude liest gelegentlich ein Tool-Schema falsch und übergibt ein malgeformtes Argument.
Die Frage ist nicht, ob dein Agent fehlschlagen wird. Die Frage ist, ob er sicher fehlschlägt.
Ich baue drei Dinge in jeden Agent jetzt ohne Ausnahme ein:
- Retry-Logik mit Backoff bei allen externen Tool-Aufrufen. Nicht nur bei Rate-Limit-Fehlern. Bei allem, das nicht 200 ist.
- Einen Fallback-Pfad, wenn der Agent mehr als N Tool-Aufrufe gemacht hat, ohne die Aufgabe zu lösen. N variiert, aber ich lasse es selten über acht gehen. Ab dem Punkt stimmt etwas nicht und ein Mensch sollte eingebunden werden.
- Explizite Unsicherheitsbehandlung im System Prompt. Ich sage Claude: Wenn du nicht genug Informationen hast, um zuversichtlich zu handeln, stell eine Klärungsfrage, anstatt auf Annahmen fortzufahren.
Das dritte hat den Ticket-Triage-Agenten gerettet, den ich am Anfang erwähnt habe. Die überarbeitete Version stellt jetzt eine Klärungsfrage, wenn sie sich bei der Weiterleitung unsicher ist. Nutzer stören sich nicht daran. Sie beantworten lieber eine Frage, als dass ihr Ticket in der falschen Queue landet.
---
Evals: Du kannst nicht ohne sie ausliefern
Ich habe bei der ersten Version des Support-Ticket-Agenten keine ordentlichen Evals durchgeführt. Das war wirklich der Fehler. Alles andere war ein Symptom davon.
Evals müssen nicht fancy sein. Was ich jetzt mache, ist einen Satz von 40-60 repräsentativen Inputs zusammenstellen, bevor ich anfange zu bauen, Normalfälle, Edge Cases und adversarische Inputs abdeckend. Ich führe den Agent nach jeder signifikanten Änderung gegen alle durch. Ich verfolge drei Zahlen: Task-Completion-Rate, Tool-Call-Genauigkeit (hat er das richtige Tool mit den richtigen Argumenten aufgerufen), und Halluzinations-Rate (behauptete er etwas, das nicht in Tool-Ergebnissen verankert ist).
Für einen Production Agent werde ich nichts unter 88% Task Completion ausliefern und null Toleranz für Halluzination bei High-Stakes-Outputs wie kundenorientierten Nachrichten mit spezifischen Aussagen (Daten, Preise, Richtlinien).
Das HELM Benchmarking Framework von Stanford ist es wert, sich für Inspiration beim Eval-Design anzuschauen, auch wenn du nicht in akademischem Maßstab laufen lässt. Die Kategorien, die sie testen, mappen gut auf echte Production-Anforderungen.
---
Der System Prompt ist tragend
Ich habe meine Meinung dazu im letzten Jahr geändert. Ich habe den System Prompt mal als Setup-Text behandelt, etwas, das man einmal schreibt und vergisst. Jetzt behandle ich ihn als die wichtigste Datei im Projekt.
Ein gut geschriebener System Prompt macht vier Dinge:
- Definiert die Identität und den Umfang des Agenten klar (was er tut und, kritisch, was er explizit nicht tut)
- Setzt Ton und Output-Format-Erwartungen
- Behandelt die häufigsten Fehler proaktiv ("Wenn du eine Bestellung nicht findest, sag es explizit, anstatt zu raten")
- Etabliert Eskalationskriterien
Die Umfang-Definition ist die, die die meisten Entwickler überspringen. Ohne sie wird Claude versuchen, auf Arten hilfreiche zu sein, die du nicht beabsichtigt hast. Beim Property-Management-Agent schloss der erste System Prompt Finanzberatung nicht explizit aus. Ein Mieter fragte den Agent, ob er eine Gebühr anfechten sollte. Claude half hilfreicherweise mit. Das ist nicht das, wofür der Kunde bezahlt hat, und es ist nicht das, wozu der Agent gebaut wurde.
Ein Satz hat es gelöst: „Sie sind nicht berechtigt, Ratschläge zu Finanzstreitigkeiten, rechtlichen Angelegenheiten oder Mietvertragsauslegung zu geben. Leiten Sie Nutzer für diese Themen direkt an das Büro weiter."
Schreiben Sie diesen Satz für jede Domain, die außerhalb des Geltungsbereichs liegt. Gehen Sie nicht davon aus, dass Claude die Grenzen von selbst erfasst.
---
FAQ
Worin unterscheidet sich das Claude Agent SDK von der direkten Nutzung der Claude API?
Die API gibt dir eine einzelne Anfrage-Antwort. Das Agent SDK (und die Agent-Patterns, die Anthropic dazu dokumentiert) gibt dir eine strukturierte Schleife, bei der Claude mehrere Entscheidungen treffen, Tools aufrufen, Ergebnisse empfangen und über Turns hinweg weiter reasoning kann. Es geht weniger um ein eigenständiges Softwarepaket und mehr um ein Pattern: Tool-Definitionen, Multi-Turn Context Management und Orchestrierungslogik. Du baust die Strukturen um die API herum, um diese Schleife zu ermöglichen.
Was ist ein realistischer Zeitrahmen für den Versand eines produktionsreifigen Agenten?
Ehrlich gesagt, vier bis sechs Wochen für alles Nichttriviale. Zwei Wochen davon sind Bau und Verkabelung von Tools. Eine Woche ist Prompt Engineering und Iteration. Eine bis zwei Wochen sind Evals, Edge-Case-Handling und QA. Wer dir einen produktiven Agenten in einer Woche verspricht, hat noch nie einen gebaut oder verkauft dir eine Demo als Produkt.
Sollte ich Claude für alle Sub-Agenten in einem Multi-Agent-System verwenden oder Modelle mixen?
Ich nutze Claude für alles, das nuanciertes Reasoning erfordert oder wo Output-Qualität für den Endnutzer zählt. Für einfache Klassifizierungsaufgaben oder hochvolumige Low-Stakes-Routing kann ein kleineres und günstigeres Modell funktionieren. Aber Modelle zu mixen erzeugt Integrations-Overhead und macht Debugging schwieriger. Starten Sie mit Claude für alles, dann optimieren Sie, sobald Sie echte Produktionsdaten haben, die zeigen, wo ein leichteres Modell ausreicht.
Wie vermeide ich, dass ein Agent vom Drehbuch abweicht?
Drei Dinge arbeiten zusammen: ein straffes System Prompt mit expliziten Out-of-Scope-Aussagen, Tool-Design, das bestimmte Aktionen physisch verhindert (gib dem Agenten kein Tool, das er nicht verwenden sollte), und Output-Validierung für alles, das kundenseitig sichtbar ist. Du kannst dich nicht nur auf das System Prompt verlassen. Verteidigungstiefe.
Was ist der größte Fehler, den Entwickler bei Agent Memory machen?
Das Context Window als unendlich zu behandeln. Es ist es nicht. Die meisten Fehler, die ich in schlecht gebauten Agenten sehe, kommen von einem Kontext, der mit irrelevanter History aufgebläht ist und Claude zwingt, durch Rauschen zu reasonen. Prunen Sie aggressiv. Fassen Sie zusammen, wo Sie können. Tragen Sie nur weiter, was der Agent wirklich braucht, um die aktuelle Aufgabe zu erfüllen.
---
Die ehrliche Zusammenfassung ist: Das SDK ist nicht der schwierige Teil. Der schwierige Teil ist das Gleiche wie immer in der Software – klar über Scope nachdenken, für Fehler designen und vor dem Versand testen. Claude ist eine bemerkenswert fähige Reasoning-Schicht, aber es kompensiert kein schlecht designtes System darum herum. Machen Sie zuerst die Rohrleitungen richtig.