Wie Tool-Nutzung funktioniert

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

Der Tool-Nutzungsvertrag

Tool-Nutzung ist ein Vertrag zwischen Ihrer Anwendung und dem Modell. Sie geben an, welche Operationen verfügbar sind und welche Form ihre Ein- und Ausgaben haben; Claude entscheidet, wann und wie diese aufgerufen werden. Das Modell führt niemals etwas von selbst aus. Es gibt eine strukturierte Anfrage ab, Ihr Code (oder Anthropic's Server) führt die Operation aus, und das Ergebnis fließt zurück in das Gespräch.

Dieser Vertrag lässt das Modell weniger wie einen Textgenerator und mehr wie eine Funktion wirken, die Sie aufrufen. Ingenieure mit klassischer API-Erfahrung können Tool-Nutzung auf die gleiche Weise integrieren wie jede andere typisierte Schnittstelle: Schema definieren, Callback verarbeiten, Ergebnis zurückgeben. Der Unterschied besteht darin, dass der Aufrufer auf der anderen Seite ein Sprachmodell ist, das basierend auf dem Gespräch auswählt, welche Funktion aufgerufen werden soll.

Wo Tools ausgeführt werden

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

Benutzerdefinierte Tools (Client-ausgeführt)

Sie schreiben das Schema, Sie führen den Code aus, Sie geben die Ergebnisse zurück. Dies ist das Hauptereignis: Die überwiegende Mehrheit des Tool-Nutzungs-Datenverkehrs sind benutzerdefinierte Tools, die in anwendungsspezifische Logik aufrufen.

Wenn Claude sich entscheidet, eines Ihrer Tools zu verwenden, enthält die API-Antwort einen tool_use-Block mit dem Tool-Namen und einem JSON-Objekt von Argumenten. Ihre Anwendung extrahiert diese Argumente, führt die Operation aus (eine Datenbankabfrage, ein HTTP-Aufruf, ein Dateischreiben, was auch immer das Tool tut), und sendet die Ausgabe in einem tool_result-Block in der nächsten Anfrage zurück. Claude sieht Ihre Implementierung nie; es sieht nur das Schema, das Sie bereitgestellt haben, und das Ergebnis, das Sie zurückgegeben haben.

Anthropic-Schema-Tools (Client-ausgeführt)

Für eine Handvoll häufiger Operationen (Ausführung von Shell-Befehlen, Bearbeitung von Dateien, Steuerung eines Browsers, Verwaltung von Scratchpad-Speicher) veröffentlicht Anthropic das Tool-Schema und Ihre Anwendung verwaltet die Ausführung. Die Tools in dieser Kategorie sind bash, text_editor, computer und memory.

Das Ausführungsmodell ist identisch mit benutzerdefinierten Tools: Die Antwort enthält einen tool_use-Block, Ihr Code führt die Operation aus, und Sie senden ein tool_result zurück. Der Grund, ein Anthropic-Schema-Tool statt eines eigenen äquivalenten Tools zu verwenden, besteht darin, dass diese Schemas trainiert sind. Claude wurde auf Tausenden erfolgreicher Trajektorien optimiert, die diese exakten Tool-Signaturen verwenden, daher ruft es sie zuverlässiger auf und erholt sich von Fehlern eleganter als mit einem benutzerdefinierten Tool, das das gleiche tut. Das Schema ist die Schnittstelle, die das Modell bereits erwartet.

Server-ausgeführte Tools

Für web_search, web_fetch, code_execution und tool_search führt Anthropic den Code aus. Sie aktivieren das Tool in Ihrer Anfrage und der Server verwaltet alles andere. Sie konstruieren niemals einen tool_result-Block für diese Tools, da die serverseitige Schleife die Operation ausführt und die Ausgabe an das Modell zurückfüttert, bevor die Antwort Sie erreicht.

Die Antwort, die Sie erhalten, enthält server_tool_use-Blöcke, die zeigen, was ausgeführt wurde und was zurückkam, aber zu dem Zeitpunkt, an dem Sie sie sehen, ist die Ausführung bereits abgeschlossen. Die Aufgabe Ihrer Anwendung besteht darin, das Tool zu aktivieren und die endgültige Antwort zu lesen, nicht an der Ausführungsschleife teilzunehmen.

Die agentengesteuerte Schleife (Client-Tools)

Client-ausgeführte Tools (sowohl benutzerdefinierte als auch Anthropic-Schema) erfordern, dass Ihre Anwendung eine Schleife steuert. Das Modell kann Ihren Code nicht ausführen, daher ist jeder Tool-Aufruf eine Hin- und Rückfahrt: Das Modell fragt, Sie führen aus, Sie berichten zurück, das Modell setzt fort.

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

1. Senden Sie eine Anfrage mit Ihrem tools-Array und der Benutzernachricht.
2. Claude antwortet mit stop_reason: "tool_use" und einem oder mehreren tool_use-Blöcken.
3. Führen Sie jedes Tool aus. Formatieren Sie die Ausgaben als tool_result-Blöcke.
4. Senden Sie eine neue Anfrage, die die ursprünglichen Nachrichten, die Antwort des Assistenten und eine Benutzernachricht mit den tool_result-Blöcken enthält.
5. Wiederholen Sie ab Schritt 2, während stop_reason "tool_use" ist.

In der Praxis liest sich dies als: Während stop_reason == "tool_use", führen Sie die Tools aus und setzen Sie das Gespräch 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 Ihre Anwendung verarbeiten sollte.

Für die Mechanik des Erstellens von Anfragen, der Verarbeitung paralleler Tool-Aufrufe und der Formatierung von Ergebnissen siehe Tool-Aufrufe verarbeiten.

Die serverseitige Schleife

Server-ausgeführte Tools führen ihre eigene Schleife in der Anthropic-Infrastruktur aus. Eine einzelne Anfrage von Ihrer Anwendung könnte mehrere Websuchen oder Code-Ausführungen auslösen, bevor eine Antwort zurückkommt. Das Modell sucht, liest Ergebnisse, entscheidet sich zu suchen, und iteriert, bis es hat, was es braucht, alles ohne dass Ihre Anwendung teilnimmt.

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; senden Sie das Gespräch erneut (einschließlich der pausierten Antwort), um das Modell dort fortsetzen zu lassen, wo es aufgehört hat. Siehe Server-Tools für das Fortsetzungsmuster.

Wann Tools verwendet werden (und wann nicht)

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

• Aktionen mit Nebenwirkungen. Senden einer E-Mail, Schreiben einer Datei, Aktualisieren eines Datensatzes. Das Modell kann diese Aktionen beschreiben, aber nur ein Tool kann sie ausführen.
• Frische oder externe Daten. Aktuelle Preise, heutiges Wetter, der Inhalt einer Datenbank. Alles außerhalb der Trainingsdaten oder spezifisch für Ihr System benötigt ein Tool, um es abzurufen.
• Strukturierte, garantierte Ausgabeformen. Wenn Sie ein JSON-Objekt mit spezifischen Feldern benötigen, anstatt 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ürlichsprachigen Anfragen und den Systemen, die sie erfüllen.

Das Zeichen, dass Sie Tools verwenden sollten: Wenn Sie einen Regex schreiben, um eine Entscheidung aus der Modellausgabe zu extrahieren, sollte diese Entscheidung ein Tool-Aufruf gewesen sein. Das Parsen von freier Form Text, um strukturierte Absicht wiederherzustellen, ist ein Zeichen, dass die Struktur im Schema gehört.

Tool-Nutzung passt nicht, wenn:

• Das Modell allein aus dem Training antworten kann. Zusammenfassung, Übersetzung und allgemeine Wissensfragen benötigen keine Tool-Hin- und Rückfahrt.
• Die Interaktion ist einmalige Frage-und-Antwort ohne Nebenwirkungen. Wenn es nichts auszuführen gibt, gibt es nichts für ein Tool zu tun.
• Tool-Aufruf-Latenz würde eine triviale Antwort dominieren. Jeder Tool-Aufruf ist mindestens eine zusätzliche Hin- und Rückfahrt; für leichte Aufgaben kann der Overhead die Arbeit übersteigen.

Wahl zwischen Ansätzen

Nächste Schritte