MessagesTools

Wie Tool-Nutzung funktioniert

Copy page



Verstehe die Tool-Nutzungsschleife, wo Tools ausgeführt werden und wann du Tools anstelle von Fließtext verwenden solltest.

Diese Seite erklärt die Konzepte hinter „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 erstellen oder dem Leitfaden Tools definieren.

Der Tool-Nutzungsvertrag

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 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 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 behandeln, ein Ergebnis zurückgeben. Der Unterschied besteht darin, dass der Aufrufer auf der anderen Seite ein Sprachmodell ist, das anhand der Konversation auswählt, welche Funktion aufgerufen wird.

Wo Tools laufen

Die wichtigste Achse, entlang derer 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. Dies ist der häufigste Fall: Der überwiegende Teil des Tool-Nutzungsverkehrs besteht aus benutzerdefinierten 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, einen HTTP-Aufruf, einen Dateischreibvorgang, was auch immer das Tool tut) und sendet die Ausgabe in einem tool_result-Block in 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 Desktops oder Browsers) veröffentlicht Anthropic das Tool-Schema, und deine Anwendung übernimmt die Ausführung. Die Tools in dieser Kategorie sind memory, bash, text_editor, computer und browser.

Das Ausführungsmodell ist identisch mit dem benutzerdefinierter 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 das mit einem benutzerdefinierten Tool täte, 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 erledigt 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 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 Zug, der zusätzlich 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 erzeugt hat oder aus einem anderen Grund gestoppt hat, den deine Anwendung behandeln sollte.

Zur Mechanik des Erstellens von Anfragen, des Umgangs mit parallelen Tool-Aufrufen und des Formatierens 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 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 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 Ergebnisse des Client-Tools 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 leisten kann:

• Aktionen mit Seiteneffekten. 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 brauchst statt Fließtext, der die Informationen zufällig enthält, erzwingt ein Tool-Schema die Form.
• Aufrufe in bestehende Systeme. Datenbanken, interne APIs, Dateisysteme. Tool-Nutzung ist die Brücke zwischen Anfragen in natürlicher Sprache und den Systemen, die sie erfüllen.

Ein klares Zeichen dafür, dass du Tools verwenden solltest: Wenn du einen regulären Ausdruck 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 zurückzugewinnen, 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. Zusammenfassungen, Übersetzungen und Fragen zum Allgemeinwissen benötigen keinen Tool-Roundtrip.
• Die Interaktion ein einmaliges Frage-Antwort-Szenario ohne Seiteneffekte 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