Claude Agent SDK: Funktionen und Evaluierung

Claude Agent SDK ist eine Entwickleroberfläche zum Erstellen von Anwendungen, mit denen Claude begrenzte, toolbasierte Workflows ausführen kann. Das SDK kann Sitzungen verwalten, Tools aufrufen und die Arbeit koordinieren. Es ersetzt jedoch nicht die Anwendungsberechtigungen, die Versionskontrolle, die Evaluierung oder die Genehmigung durch einen Benutzer. Betrachten Sie es als eine Agenten-Laufzeitkomponente, nicht als ein vollständiges Produktionssystem.

Für Teams, die quellcodebasierte Arbeit abschließen müssen, ohne eine Agentenlaufzeitumgebung zu besitzen, bietet Ottermind den verwalteten Arbeitsbereich: Dateien, Forschungskontext, Entscheidungen und Ergebnisse bleiben verknüpft, während eine Person die Ergebnisse überprüft. Das SDK und ein verwalteter Arbeitsbereich lösen unterschiedliche Betriebsprobleme.

Forschung und Offenlegung: Dieser Leitfaden basiert auf Claude Agent SDK-Repository., Anthropic – Dokumentation zur Werkzeugverwendung und AWS AgentCore Claude Agent SDK Dokumentation und wurde am 3. September 2026 geprüft. APIs und Beschränkungen entwickeln sich weiter; überprüfen Sie die aktuelle Version vor der Implementierung.

Die Kernbausteine

Baustein	Verantwortlichkeit	Anwendungssteuerung
Sitzung	Verwaltet einen Lauf und dessen Konversationsstatus.	Ablauf, Isolation und Prüfprotokoll
Modell	Interpretiert den Kontext und schlägt Schritte vor	Modellversion, Budget und Ausgabevertrag
Tool	Führt eine begrenzte Operation aus	Schema, Timeout, Berechtigungen und Idempotenz
Subagent	Verwaltet eine eigenständige Rolle	Bereich, Budget und Eskalationsregeln
Berechtigungsmodus	Steuert, worauf der Agent zugreifen oder was er ändern darf.	Zulassungsliste und menschliche Bestätigung
Ergebnis	Gibt Text, strukturierte Daten oder Artefakte zurück.	Validierung und Übergabe an den Prüfer

Beginnen Sie mit einer reversiblen Aufgabe.

Prototypisieren Sie einen leseintensiven Workflow, z. B. die Umwandlung genehmigter Repository-Dateien in ein Änderungsdokument. Erfassen Sie die Eingabedaten, die Eingabeaufforderung, die Modellversion, die Tool-Aufrufe, die Ausgabe, die Korrekturen des Prüfers und die endgültige Entscheidung. Fügen Sie Schreibzugriff erst hinzu, wenn der Ablauf verständlich und Fehler behebbar sind.

Minimaler Aufgabenvertrag

Prompt

Ziel: Erstellung eines quellcodebasierten Implementierungsbriefings.
Zulässige Quellen: Nur die beigefügten Repository-Dateien.
Zulässige Werkzeuge: Dateien auflisten und lesen; keine Schreibvorgänge oder Netzwerkaufrufe.
Ausgabe: Ergebnisse, Änderungsvorschläge, Nachweise, Risiken und offene Fragen.
Abbruch, wenn: eine erforderliche Quelle fehlt oder Berechtigungen unklar sind.

Sitzungen und Subagenten

Verwenden Sie eine Sitzung, wenn der Workflow über mehrere Schritte hinweg Kontinuität erfordert. Verwenden Sie einen Subagenten nur, wenn sich Rolle, Werkzeuge oder Bewertungskriterien tatsächlich unterscheiden. Zusätzliche Agenten erhöhen Koordinationsaufwand, Latenz und Fehlerquellen. Übergeben Sie den kleinstmöglichen Kontext, den jede Rolle benötigt, und geben Sie strukturierte Ergebnisse mit Status und Nachweisen zurück.

Eine praktische Architektur

Halten Sie das SDK hinter einer Anwendungsgrenze mit fünf Verantwortlichkeiten:

Anfragebearbeiter: Authentifiziert den Benutzer, wählt das zulässige Projekt aus und legt ein Budget fest.
Kontextlader: Ruft nur zulässige Dateien ab und speichert deren Kennungen und Datumsangaben.
Agent-Runner: Startet die Sitzung, stellt Tools bereit und speichert jede Tool-Anfrage und deren Ergebnis.
Richtlinienschicht: Validiert Argumente, blockiert unzulässige Aktionen und fordert eine Bestätigung an.
Ergebnisadapter: Validiert die zurückgegebene Struktur und übergibt einen Entwurf an den Prüfer oder das nächste System.

Diese Trennung ist wichtig, da das SDK das Modell zwar bei der Anforderung eines Tools unterstützen kann, Ihre Anwendung jedoch entscheidet, ob diese Anforderung zulässig ist. Platzieren Sie keine Autorisierungslogik in einer Eingabeaufforderung und gehen Sie nicht davon aus, dass ein Modell die Mandantengrenzen automatisch wahrt.

Sitzungen, Wiederaufnahme und Fehler

Geben Sie jedem Lauf eine eindeutige Kennung und einen Endstatus wie completed, needs_review, blocked oder failed. Speichern Sie die Modell- und SDK-Version, die Eingabeaufforderungsrevision, die Eingabequellen, die Tool-Aufrufe und die Prüferentscheidung. Wenn nach einem Schreibvorgang ein Netzwerkfehler auftritt, verwenden Sie einen Idempotenzschlüssel und fragen Sie das System ab, bevor Sie es erneut versuchen. Wird eine Sitzung nach einer manuellen Bearbeitung fortgesetzt, sollten das bearbeitete Artefakt und der Grund für die Änderung anstelle einer undurchsichtigen Konversation angezeigt werden.

Beispiele für Werkzeugdesign

Eine Funktion wie create_draft_task(title, owner, due_date) ist einem universellen Shell-Tool vorzuziehen. Die spezialisierte Funktion kann Datumsformate, zulässige Besitzer, Projektumfang und den Status „Nur Entwurf“ festlegen. Ein Dateisuchtool sollte Dateikennungen und Auszüge zurückgeben und nicht stillschweigend ein gesamtes Laufwerk preisgeben. Ein Browsertool sollte eine Zulassungsliste verwenden und vor Authentifizierung oder Zahlung stoppen.

Kosten und Latenz

Festlegen Sie Budgets vor dem Start des Laufs: maximale Modellumdrehungen, Toolaufrufe, Tokens, verstrichene Zeit und Anzahl der Subagenten. Leiten Sie die Extraktion an ein kleineres Modell weiter, wenn die Qualität dies zulässt, und reservieren Sie komplexe Begründungen für mehrdeutige Schritte. Protokollieren Sie die tatsächliche Nutzung zusammen mit dem Ergebnis, damit eine erfolgreiche Demo keinen unwirtschaftlichen Workflow verschleiert. Lange Aufgaben sollten asynchron, abbrechbar und für den Benutzer sichtbar sein.

SDK versus verwalteter Arbeitsbereich

Entwickeln Sie mit dem SDK, wenn Ihr Team anwendungsspezifische Tools, Bereitstellungskontrolle oder eine benutzerdefinierte Laufzeitumgebung benötigt und die Verantwortung für Sicherheit, Überwachung und Wartung übernehmen kann. Ein verwalteter Arbeitsbereich ist ein besserer Ausgangspunkt, wenn die Hauptanforderung darin besteht, Dateien, Recherchen, Entscheidungen und Ergebnisse zur manuellen Überprüfung zu verknüpfen. Die Wahl hängt von der operativen Verantwortung ab, nicht davon, welche Bezeichnung autonomer klingt.

Beispiel: ein Agent für die Recherche-zu-Briefing-Erstellung

Stellen Sie sich ein Team vor, das wöchentlich eine Wettbewerbsanalyse benötigt. Der Anfragebearbeiter prüft die Identität des Analysten und wählt das genehmigte Projekt aus. Der Kontextlader ruft die Quellenliste ab und speichert das Abrufdatum. Die Agentensitzung kann nur search_approved_sources und draft_brief aufrufen. Die Richtlinienschicht lehnt Anfragen für beliebige URLs, externe Beiträge oder Dateien außerhalb des Projekts ab. Der Ergebnisadapter benötigt Abschnitte für Ergebnisse, Zitate, Unsicherheiten und offene Fragen, bevor der Entwurf einem Prüfer vorgelegt wird.

Das nützliche Artefakt ist nicht nur der fertige Text. Es ist der Ablauf: Welche Quellen waren verfügbar, welche Tools wurden aufgerufen, was wurde blockiert, was hat der Prüfer geändert und wurde die Analyse akzeptiert? Dieser Ablauf unterstützt das Debugging, die Kostenanalyse und einen reproduzierbaren Evaluierungssatz, wenn sich das Modell oder das SDK ändert.

Versionsverwaltung und Upgrades

Legen Sie die SDK- und Modellversionen in jeder Umgebung fest. Lesen Sie die Versionshinweise zu Änderungen an Berechtigungsmodi, Tool-Schemas, Sitzungsverhalten und unterstützten Modellen. Führen Sie vor dem Upgrade Regressionstests durch, einschließlich eines Tests, der bestätigt, dass verbotene Tools weiterhin verboten bleiben. Halten Sie eine Rollback-Version bereit und vermeiden Sie Upgrades mitten in einem laufenden Workflow ohne Migrationsplan.

Checkliste für die Produktionsbereitschaft

Authentifizierung und Mandantenprüfungen erfolgen vor dem Kontextabruf.
Jedes Tool verfügt über ein eng begrenztes Schema, ein Timeout und eine Autorisierungsprüfung.
Sitzungen haben Budgets, Stornierungs-, Ablauf- und Endzustände.
Ausgaben werden validiert, bevor sie in einem Datenspeicher abgelegt werden.
Sensible Aktionen erfordern eine explizite Genehmigung durch einen Benutzer.
Protokolle enthalten ausreichend Informationen, um einen Fehler ohne Speicherung von Geheimnissen nachzustellen.
Evaluierungsfälle umfassen Qualität, Sicherheit, Kosten und Latenz.

Berechtigungs- und Sicherheitsgrenzen

Tool-Argumente im Anwendungscode validieren. Anmeldeinformationen sollten außerhalb von Eingabeaufforderungen gespeichert, der Dateisystem- und Netzwerkzugriff eingeschränkt, Timeouts festgelegt und eine Bestätigung für das Senden, Löschen, Kaufen oder Ändern von Zugriffsrechten angefordert werden. Jeder relevante Tool-Aufruf sollte mit der jeweiligen Identität und der Genehmigungsentscheidung protokolliert werden.

Evaluieren Sie den Workflow, nicht die Demo.

Erstellen Sie einen Testdatensatz mit normalen, unvollständigen, widersprüchlichen, angreifbaren und berechtigungsabhängigen Fällen. Messen Sie die korrekte Ausführung, die sichere Eskalation, Tool-Fehler, Latenz, Kosten und Korrekturen durch Prüfer. Legen Sie die Modell- und SDK-Versionen für jeden Evaluierungslauf fest.

FAQ

Ist Claude Agent SDK identisch mit der Verwendung des Claude-API-Tools?

Nein. Die Verwendung von Tools ist ein Modellinteraktionsmuster. Das SDK bietet weitere Bausteine auf Anwendungsebene für Agentensitzungen und Workflows, während Ihre Anwendung weiterhin für Richtlinien, Speicher, Berechtigungen und Auswertung zuständig ist.

Benötige ich mehrere Agenten?

Normalerweise nicht zu Beginn. Ein Agent mit wenigen Tools und expliziten Prüfpunkten ist einfacher zu testen und zu betreiben.

Kann das SDK Dateien sicher bearbeiten oder Befehle ausführen?

Es kann mit solchen Tools verbunden werden, die Sicherheit wird jedoch durch Ihre Sandbox, Zulassungslisten, Validierung, Überprüfung und Rollback-Architektur gewährleistet. Behandeln Sie einen generierten Befehl niemals als vorab genehmigt.

Für die breitere Systemgrenze siehe KI-Agent-Architektur und KI-Agentensicherheit.