Wie Tool-Nutzung funktioniert

Diese Seite erklärt die Konzepte hinter der „tool use" (Tool-Nutzung): wo Tools laufen, wie die agentische Schleife funktioniert und wann Tool-Nutzung der richtige Ansatz ist. Für praktische Anleitungen beginne mit dem Tutorial Einen Tool-nutzenden Agenten bauen oder dem Leitfaden Tools definieren.



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 Ein- und Ausgaben haben; Claude bestimmt, wann und wie sie aufgerufen werden. 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 verhalten, die du aufrufst. Entwickler mit klassischer API-Erfahrung können Tool-Nutzung genauso integrieren wie jede andere typisierte Schnittstelle: das Schema definieren, den Callback behandeln, ein Ergebnis zurückgeben. Der Unterschied ist, dass der Aufrufer auf der anderen Seite ein Sprachmodell ist, das basierend auf der Konversation auswählt, welche Funktion aufgerufen wird.



Wo Tools laufen

Die primäre Achse, entlang derer sich Tools unterscheiden, ist, wo 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. Dies ist der häufigste Fall: Die überwiegende Mehrheit des Tool-Nutzungs-Traffics sind benutzerdefinierte Tools, die anwendungsspezifische Logik aufrufen.

Wenn Claude eines deiner Tools aufruft, 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, ein HTTP-Aufruf, ein Schreibvorgang in eine Datei, 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.



Tools mit Anthropic-Schema (clientseitig ausgeführt)

Für eine Handvoll gängiger Operationen (Verwalten 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 Tool mit Anthropic-Schema zu verwenden, anstatt ein eigenes Äquivalent zu definieren, ist, dass diese Schemas antrainiert 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 es mit einem benutzerdefinierten Tool der Fall wäre, 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 kümmert sich um alles andere. Du konstruierst für diese Tools niemals einen tool_result-Block. Wenn ein Zug nur Server-Tools aufruft, führt die serverseitige Schleife die Operation aus und gibt die Ausgabe an das Modell zurück, 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 Hauptausnahmen sind eine pausierte Schleife (pause_turn) und ein Zug, der auch ein Client-Tool aufruft.



Die agentische Schleife (Client-Tools)

Clientseitig ausgeführte Tools (sowohl benutzerdefinierte als auch solche mit Anthropic-Schema) erfordern, dass deine Anwendung eine Schleife steuert. Das Modell kann deinen Code nicht ausführen, daher ist jeder Tool-Aufruf ein Roundtrip: Das Modell fragt, 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 gleich "tool_use" ist.

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-Grund ("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, der Behandlung paralleler Tool-Aufrufe und der Formatierung von Ergebnissen siehe Tool-Aufrufe behandeln.



Die serverseitige Schleife

Serverseitig ausgeführte Tools führen ihre eigene Schleife innerhalb der Infrastruktur von Anthropic aus. Eine einzelne Anfrage deiner Anwendung kann mehrere Websuchen oder Code-Ausführungen auslösen, bevor eine Antwort zurückkommt. Das Modell sucht, liest Ergebnisse, entscheidet, ob es erneut suchen soll, 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 die Obergrenze erreicht, kommt die Antwort mit stop_reason: "pause_turn" statt "end_turn" zurück. Ein pausierter Zug bedeutet, dass die Arbeit nicht abgeschlossen ist; sende die Konversation (einschließlich der pausierten Antwort) erneut, damit das Modell dort weitermachen 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 läuft, 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-Gründe 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 heraus tun kann:

• Aktionen mit Nebenwirkungen. 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 außerhalb der Trainingsdaten oder spezifisch für dein System 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.

Ein klares Zeichen 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 heraus antworten kann. Zusammenfassung, Übersetzung und Fragen zu Allgemeinwissen benötigen keinen Tool-Roundtrip.
• Die Interaktion ein einmaliges Q&A ohne Nebenwirkungen ist. Wenn es nichts auszuführen gibt, gibt es für ein Tool nichts zu tun.
• Die Latenz des Tool-Aufrufs eine triviale Antwort dominieren würde. Jeder Tool-Aufruf ist mindestens ein zusätzlicher Roundtrip; bei leichtgewichtigen Aufgaben kann der Overhead die eigentliche Arbeit übersteigen.



Zwischen Ansätzen wählen



Nächste Schritte