Wie Tool-Nutzung funktioniert

Diese Seite erklärt die Konzepte hinter der Tool-Nutzung: wo Tools ausgeführt werden, wie die agentische Schleife funktioniert und wann Tool-Nutzung der richtige Ansatz ist. Für praktische Anleitungen beginne mit dem Tutorial oder dem Implementierungsleitfaden.



Der Tool-Nutzungs-Vertrag

Tool-Nutzung ist ein Vertrag zwischen deiner Anwendung und dem Modell. Du legst fest, welche Operationen verfügbar sind und welche Form ihre Eingaben und Ausgaben haben; Claude entscheidet, wann und wie es sie aufruft. Das Modell führt niemals selbst etwas aus. Es gibt eine strukturierte Anfrage aus, dein Code (oder die Server von Anthropic) führt die Operation aus, und das Ergebnis fließt zurück in die Konversation.

Dieser Vertrag lässt das Modell weniger wie einen Textgenerator und mehr wie eine Funktion wirken, die du aufrufst. Entwickler mit klassischer API-Erfahrung können Tool-Nutzung genauso integrieren wie jede andere typisierte Schnittstelle: das Schema definieren, den Callback verarbeiten, ein Ergebnis zurückgeben. Der Unterschied ist, dass der Aufrufer auf der anderen Seite ein Sprachmodell ist, das basierend auf der Konversation entscheidet, welche Funktion es aufruft.



Wo Tools ausgeführt werden

Die primäre Achse, entlang der sich Tools unterscheiden, ist der Ort, an dem der Code ausgeführt wird. Jedes Tool fällt in eine von drei Kategorien, und die Kategorie bestimmt, wofür deine Anwendung verantwortlich ist.



Benutzerdefinierte Tools (clientseitig ausgeführt)

Du schreibst das Schema, du führst den Code aus, du gibst die Ergebnisse zurück. Das ist der Hauptanwendungsfall: Der überwiegende Teil des Tool-Nutzungs-Traffics besteht aus benutzerdefinierten Tools, die anwendungsspezifische Logik aufrufen.

Wenn Claude entscheidet, eines deiner Tools zu verwenden, enthält die API-Antwort einen tool_use-Block mit dem Tool-Namen und einem JSON-Objekt mit Argumenten. Deine Anwendung extrahiert diese Argumente, führt die Operation aus (eine Datenbankabfrage, einen HTTP-Aufruf, einen Dateischreibvorgang – was auch immer das Tool tut) und sendet die Ausgabe in einem tool_result-Block mit der nächsten Anfrage zurück. Claude sieht niemals deine Implementierung; es sieht nur das Schema, das du bereitgestellt hast, und das Ergebnis, das du zurückgegeben hast.



Anthropic-Schema-Tools (clientseitig ausgeführt)

Für eine Handvoll gängiger Operationen (Verwaltung von Scratchpad-Speicher, Ausführen von Shell-Befehlen, Bearbeiten von Dateien, Steuern eines Browsers) veröffentlicht Anthropic das Tool-Schema, und deine Anwendung übernimmt die Ausführung. Die Tools in dieser Kategorie sind memory, bash, text_editor und computer.

Das Ausführungsmodell ist identisch mit benutzerdefinierten Tools: Die Antwort enthält einen tool_use-Block, dein Code führt die Operation aus, und du sendest ein tool_result zurück. Der Grund, ein Anthropic-Schema-Tool anstelle eines eigenen Äquivalents zu verwenden, ist, dass diese Schemas eintrainiert sind. Claude wurde auf Tausenden erfolgreicher Trajektorien optimiert, die genau diese Tool-Signaturen verwenden, sodass es sie zuverlässiger aufruft und sich eleganter von Fehlern erholt als bei einem benutzerdefinierten Tool, das dasselbe tut. Das Schema ist die Schnittstelle, die das Modell bereits erwartet.



Serverseitig ausgeführte Tools

Für web_search, web_fetch, code_execution und tool_search führt Anthropic den Code aus. Du aktivierst das Tool in deiner Anfrage, und der Server übernimmt alles Weitere. Du erstellst niemals einen tool_result-Block für diese Tools. Wenn ein Turn nur Server-Tools aufruft, führt die serverseitige Schleife die Operation aus und speist die Ausgabe zurück in das Modell, bevor die Antwort dich erreicht – es sei denn, die Schleife stoppt, bevor sie fertig ist, meistens weil sie pausiert.

Die Antwort, die du erhältst, enthält server_tool_use-Blöcke, die zeigen, was ausgeführt wurde und was zurückkam. Im Normalfall ist die Ausführung bereits abgeschlossen, wenn du sie siehst, und die Aufgabe deiner Anwendung besteht darin, das Tool zu aktivieren und die endgültige Antwort zu lesen, anstatt an der Ausführungsschleife teilzunehmen; die wichtigsten Ausnahmen sind eine pausierte Schleife (pause_turn) und ein Turn, der auch ein Client-Tool aufruft.



Die agentische Schleife (Client-Tools)

Clientseitig ausgeführte Tools (sowohl benutzerdefinierte als auch Anthropic-Schema-Tools) erfordern, dass deine Anwendung eine Schleife steuert. Das Modell kann deinen Code nicht ausführen, daher ist jeder Tool-Aufruf ein Round-Trip: Das Modell fragt an, du führst aus, du meldest zurück, das Modell fährt fort.

Die kanonische Form ist eine while-Schleife, die auf stop_reason basiert:

1. Sende eine Anfrage mit deinem tools-Array und der Benutzernachricht.
2. Claude antwortet mit stop_reason: "tool_use" und einem oder mehreren tool_use-Blöcken.
3. Führe jedes Tool aus. Formatiere die Ausgaben als tool_result-Blöcke.
4. Sende eine neue Anfrage, die die ursprünglichen Nachrichten, die Antwort des Assistenten und eine Benutzernachricht mit den tool_result-Blöcken enthält.
5. Wiederhole ab Schritt 2, solange stop_reason den Wert "tool_use" hat.

In der Praxis liest sich das so: Solange stop_reason == "tool_use", führe die Tools aus und setze die Konversation fort. Die Schleife endet bei jedem anderen Stop-Reason ("end_turn", "max_tokens", "stop_sequence" oder "refusal"), was bedeutet, dass Claude entweder eine endgültige Antwort produziert hat oder aus einem anderen Grund gestoppt hat, den deine Anwendung behandeln sollte.

Für die Mechanik des Erstellens von Anfragen, des Umgangs mit parallelen Tool-Aufrufen und des Formatierens von Ergebnissen siehe Tool-Aufrufe verarbeiten.



Die serverseitige Schleife

Serverseitig ausgeführte Tools durchlaufen ihre eigene Schleife innerhalb der Infrastruktur von Anthropic. Eine einzelne Anfrage von deiner Anwendung kann mehrere Websuchen oder Code-Ausführungen auslösen, bevor eine Antwort zurückkommt. Das Modell sucht, liest Ergebnisse, entscheidet sich für eine erneute Suche und iteriert, bis es hat, was es braucht – alles ohne Beteiligung deiner Anwendung.

Diese interne Schleife hat ein Iterationslimit. Wenn das Modell noch iteriert, wenn es das Limit erreicht, kommt die Antwort mit stop_reason: "pause_turn" statt "end_turn" zurück. Ein pausierter Turn bedeutet, dass die Arbeit nicht abgeschlossen ist; sende die Konversation erneut (einschließlich der pausierten Antwort), damit das Modell dort fortfahren kann, wo es aufgehört hat. Siehe Server-Tools für das Fortsetzungsmuster.

Die Schleife gibt die Kontrolle auch an dich zurück, bevor ein Server-Tool ausgeführt wird, wenn Claude dieses Server-Tool und ein Client-Tool in derselben Gruppe paralleler Tool-Aufrufe aufruft. Die Antwort kommt dann mit stop_reason: "tool_use" und einem server_tool_use-Block zurück, der noch keinen Ergebnisblock hat; die API führt ihn aus, nachdem du die Client-Tool-Ergebnisse zurückgegeben hast. Siehe Stop-Reasons und Fallback für den genauen Vertrag.



Wann du Tools verwenden solltest (und wann nicht)

Tool-Nutzung passt, wenn die Aufgabe etwas erfordert, das das Modell nicht allein aus Text leisten kann:

• Aktionen mit Nebeneffekten. Eine E-Mail senden, eine Datei schreiben, einen Datensatz aktualisieren. Das Modell kann diese Aktionen beschreiben, aber nur ein Tool kann sie ausführen.
• Aktuelle oder externe Daten. Aktuelle Preise, das heutige Wetter, der Inhalt einer Datenbank. Alles, was außerhalb der Trainingsdaten liegt oder spezifisch für dein System ist, benötigt ein Tool, um es abzurufen.
• Strukturierte Ausgaben mit garantierter Form. Wenn du ein JSON-Objekt mit bestimmten Feldern benötigst statt Prosa, die zufällig die Informationen enthält, erzwingt ein Tool-Schema die Form.
• Aufrufe in bestehende Systeme. Datenbanken, interne APIs, Dateisysteme. Tool-Nutzung ist die Brücke zwischen natürlichsprachlichen Anfragen und den Systemen, die sie erfüllen.

Das Anzeichen dafür, dass du Tools verwenden solltest: Wenn du einen Regex schreibst, um eine Entscheidung aus der Modellausgabe zu extrahieren, hätte diese Entscheidung ein Tool-Aufruf sein sollen. Das Parsen von Freitext, um strukturierte Absichten wiederherzustellen, ist ein Zeichen dafür, dass die Struktur ins Schema gehört.

Tool-Nutzung passt nicht, wenn:

• Das Modell allein aus dem Training antworten kann. Zusammenfassung, Übersetzung und Fragen zum Allgemeinwissen benötigen keinen Tool-Round-Trip.
• Die Interaktion ein einmaliges Frage-Antwort-Szenario ohne Nebeneffekte ist. Wenn es nichts auszuführen gibt, gibt es nichts, was ein Tool tun könnte.
• Die Latenz des Tool-Aufrufs eine triviale Antwort dominieren würde. Jeder Tool-Aufruf ist mindestens ein zusätzlicher Round-Trip; bei leichtgewichtigen Aufgaben kann der Overhead die eigentliche Arbeit übersteigen.



Wahl zwischen den Ansätzen



Nächste Schritte