Tool-Nutzung (Funktionsaufrufe)

Claude ist in der Lage, mit externen clientseitigen Tools und Funktionen zu interagieren, wodurch Sie Claude mit Ihren eigenen benutzerdefinierten Tools ausstatten können, um eine größere Vielfalt an Aufgaben auszuführen.

Hier ist ein Beispiel, wie man Tools für Claude über die Messages API bereitstellt:

​

Wie die Tool-Nutzung funktioniert

Integrieren Sie externe Tools mit Claude in diesen Schritten:

Hinweis: Schritte 3 und 4 sind optional. Für einige Arbeitsabläufe könnte Claudes Tool-Nutzungsanfrage (Schritt 2) alles sein, was Sie benötigen, ohne Ergebnisse an Claude zurückzusenden.

​

Wie man die Tool-Nutzung implementiert

​

Auswahl eines Modells

Verwenden Sie im Allgemeinen Claude 3.5 Sonnet oder Claude 3 Opus für komplexe Tools und mehrdeutige Anfragen; sie handhaben mehrere Tools besser und suchen bei Bedarf nach Klärung.

Verwenden Sie Claude 3.5 Haiku oder Claude 3 Haiku für einfache Tools, beachten Sie aber, dass sie fehlende Parameter ableiten können.

​

Spezifizierung von Tools

Tools werden im tools Top-Level-Parameter der API-Anfrage spezifiziert. Jede Tool-Definition enthält:

{
  "name": "get_weather",
  "description": "Ruft das aktuelle Wetter für einen bestimmten Ort ab",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Die Stadt und der Bundesstaat, z.B. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Die Temperatureinheit, entweder 'celsius' oder 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

Tool-Nutzungs-Systemprompt

Wenn Sie die Anthropic API mit dem tools Parameter aufrufen, erstellen wir einen speziellen Systemprompt aus den Tool-Definitionen, der Tool-Konfiguration und jedem benutzerspezifischen Systemprompt. Der erstellte Prompt ist darauf ausgelegt, das Modell anzuweisen, das/die angegebene(n) Tool(s) zu verwenden und den notwendigen Kontext für die ordnungsgemäße Funktionsweise des Tools bereitzustellen:

In dieser Umgebung haben Sie Zugriff auf eine Reihe von Tools, die Sie zur Beantwortung der Frage des Benutzers verwenden können.
{{ FORMATIERUNGSANWEISUNGEN }}
String- und Skalar-Parameter sollten wie angegeben spezifiziert werden, während Listen und Objekte das JSON-Format verwenden sollten. Beachten Sie, dass Leerzeichen für String-Werte nicht entfernt werden. Die Ausgabe muss kein gültiges XML sein und wird mit regulären Ausdrücken geparst.
Hier sind die verfügbaren Funktionen im JSONSchema-Format:
{{ TOOL-DEFINITIONEN IM JSON-SCHEMA }}
{{ BENUTZER-SYSTEMPROMPT }}
{{ TOOL-KONFIGURATION }}

​

Best Practices für Tool-Definitionen

Um die beste Leistung von Claude bei der Verwendung von Tools zu erhalten, befolgen Sie diese Richtlinien:

• Stellen Sie extrem detaillierte Beschreibungen bereit. Dies ist bei weitem der wichtigste Faktor für die Tool-Leistung. Ihre Beschreibungen sollten jedes Detail über das Tool erklären, einschließlich:
  • Was das Tool tut
  • Wann es verwendet werden sollte (und wann nicht)
  • Was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst
  • Alle wichtigen Vorbehalte oder Einschränkungen, wie z.B. welche Informationen das Tool nicht zurückgibt, wenn der Tool-Name unklar ist. Je mehr Kontext Sie Claude über Ihre Tools geben können, desto besser wird es bei der Entscheidung sein, wann und wie sie zu verwenden sind. Streben Sie mindestens 3-4 Sätze pro Tool-Beschreibung an, mehr wenn das Tool komplex ist.
• Priorisieren Sie Beschreibungen über Beispiele. Während Sie Beispiele für die Verwendung eines Tools in seiner Beschreibung oder im begleitenden Prompt einschließen können, ist dies weniger wichtig als eine klare und umfassende Erklärung des Zwecks und der Parameter des Tools. Fügen Sie erst dann Beispiele hinzu, wenn Sie die Beschreibung vollständig ausgearbeitet haben.

{
  "name": "get_stock_price",
  "description": "Ruft den aktuellen Aktienkurs für ein gegebenes Tickersymbol ab. Das Tickersymbol muss ein gültiges Symbol für ein börsennotiertes Unternehmen an einer großen US-Börse wie NYSE oder NASDAQ sein. Das Tool gibt den letzten Handelspreis in USD zurück. Es sollte verwendet werden, wenn der Benutzer nach dem aktuellen oder jüngsten Preis einer bestimmten Aktie fragt. Es wird keine anderen Informationen über die Aktie oder das Unternehmen liefern.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Das Aktien-Tickersymbol, z.B. AAPL für Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Holt den Aktienkurs für einen Ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

Die gute Beschreibung erklärt klar, was das Tool tut, wann es zu verwenden ist, welche Daten es zurückgibt und was der ticker Parameter bedeutet. Die schlechte Beschreibung ist zu kurz und lässt Claude mit vielen offenen Fragen über das Verhalten und die Verwendung des Tools.

​

Steuerung von Claudes Ausgabe

​

Erzwingen der Tool-Nutzung

In manchen Fällen möchten Sie vielleicht, dass Claude ein bestimmtes Tool verwendet, um die Frage des Benutzers zu beantworten, auch wenn Claude denkt, dass es eine Antwort ohne Verwendung eines Tools geben kann. Sie können dies tun, indem Sie das Tool im tool_choice Feld wie folgt angeben:

tool_choice = {"type": "tool", "name": "get_weather"}

Bei der Arbeit mit dem tool_choice Parameter haben wir drei mögliche Optionen:

• auto erlaubt Claude zu entscheiden, ob es bereitgestellte Tools aufrufen soll oder nicht. Dies ist der Standardwert.
• any sagt Claude, dass es eines der bereitgestellten Tools verwenden muss, erzwingt aber kein bestimmtes Tool.
• tool erlaubt uns, Claude zu zwingen, immer ein bestimmtes Tool zu verwenden.

Dieses Diagramm veranschaulicht, wie jede Option funktioniert:

Beachten Sie, dass wenn Sie tool_choice als any oder tool haben, wir die Assistenten-Nachricht vorausfüllen, um die Verwendung eines Tools zu erzwingen. Dies bedeutet, dass die Modelle keinen Chain-of-Thought text Inhaltsblock vor tool_use Inhaltsblöcken ausgeben werden, auch wenn sie explizit darum gebeten werden.

Unsere Tests haben gezeigt, dass dies die Leistung nicht reduzieren sollte. Wenn Sie Chain-of-Thought beibehalten möchten (besonders bei Opus), während Sie immer noch die Verwendung eines bestimmten Tools anfordern, können Sie {"type": "auto"} für tool_choice (der Standard) verwenden und explizite Anweisungen in einer user Nachricht hinzufügen. Zum Beispiel: Wie ist das Wetter in London? Verwende das get_weather Tool in deiner Antwort.

​

JSON-Ausgabe

Tools müssen nicht unbedingt clientseitige Funktionen sein — Sie können Tools jederzeit verwenden, wenn Sie möchten, dass das Modell JSON-Ausgabe zurückgibt, die einem bereitgestellten Schema folgt. Zum Beispiel könnten Sie ein record_summary Tool mit einem bestimmten Schema verwenden. Siehe Tool-Nutzungsbeispiele für ein vollständiges Arbeitsbeispiel.

​

Chain of Thought

Bei der Verwendung von Tools wird Claude oft seine “Gedankenkette” zeigen, d.h. die schrittweise Argumentation, die es verwendet, um das Problem zu zerlegen und zu entscheiden, welche Tools zu verwenden sind. Das Claude 3 Opus Modell wird dies tun, wenn tool_choice auf auto gesetzt ist (dies ist der Standardwert, siehe Erzwingen der Tool-Nutzung), und Sonnet und Haiku können dazu aufgefordert werden.

Zum Beispiel könnte Claude auf die Aufforderung “Wie ist das Wetter gerade in San Francisco und wie spät ist es dort?” wie folgt antworten:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Um diese Frage zu beantworten, werde ich: 1. Das get_weather Tool verwenden, um das aktuelle Wetter in San Francisco zu erhalten. 2. Das get_time Tool verwenden, um die aktuelle Zeit in der America/Los_Angeles Zeitzone zu erhalten, die San Francisco, CA abdeckt.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Diese Gedankenkette gibt Einblick in Claudes Denkprozess und kann helfen, unerwartetes Verhalten zu debuggen.

Mit dem Claude 3 Sonnet Modell ist die Gedankenkette standardmäßig weniger häufig, aber Sie können Claude auffordern, seine Argumentation zu zeigen, indem Sie etwas wie "Bevor du antwortest, erkläre deine Argumentation Schritt für Schritt in Tags." zur Benutzer-Nachricht oder zum System-Prompt hinzufügen.

Es ist wichtig zu beachten, dass während die <thinking> Tags eine häufige Konvention sind, die Claude verwendet, um seine Gedankenkette zu kennzeichnen, sich das genaue Format (wie dieser XML-Tag genannt wird) im Laufe der Zeit ändern kann. Ihr Code sollte die Gedankenkette wie jeden anderen vom Assistenten generierten Text behandeln und sich nicht auf das Vorhandensein oder die spezifische Formatierung der <thinking> Tags verlassen.

​

Deaktivieren der parallelen Tool-Nutzung

Standardmäßig kann Claude mehrere Tools verwenden, um eine Benutzeranfrage zu beantworten. Sie können dieses Verhalten deaktivieren, indem Sie disable_parallel_tool_use=true im tool_choice Feld setzen.

• Wenn der tool_choice Typ auto ist, stellt dies sicher, dass Claude höchstens ein Tool verwendet
• Wenn der tool_choice Typ any oder tool ist, stellt dies sicher, dass Claude genau ein Tool verwendet

​

Umgang mit Tool-Nutzungs- und Tool-Ergebnis-Inhaltsblöcken

Wenn Claude sich entscheidet, eines der von Ihnen bereitgestellten Tools zu verwenden, wird es eine Antwort mit einem stop_reason von tool_use und einem oder mehreren tool_use Inhaltsblöcken in der API-Antwort zurückgeben, die Folgendes enthalten:

• id: Eine eindeutige Kennung für diesen bestimmten Tool-Nutzungsblock. Diese wird später verwendet, um die Tool-Ergebnisse zuzuordnen.
• name: Der Name des verwendeten Tools.
• input: Ein Objekt, das die Eingabe enthält, die an das Tool übergeben wird, entsprechend dem input_schema des Tools.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Ich muss get_weather verwenden, und der Benutzer möchte SF, was wahrscheinlich San Francisco, CA ist.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Wenn Sie eine Tool-Nutzungsantwort erhalten, sollten Sie:

1. Extrahieren Sie name, id und input aus dem tool_use Block.
2. Führen Sie das tatsächliche Tool in Ihrem Codebase aus, das diesem Tool-Namen entspricht, und übergeben Sie die Tool-input.
3. Setzen Sie das Gespräch fort, indem Sie eine neue Nachricht mit der role von user senden und einen content Block, der den tool_result Typ und die folgenden Informationen enthält:
   • tool_use_id: Die id der Tool-Nutzungsanfrage, für die dies ein Ergebnis ist.
   • content: Das Ergebnis des Tools, als String (z.B. "content": "15 Grad") oder Liste von verschachtelten Inhaltsblöcken (z.B. "content": [{"type": "text", "text": "15 Grad"}]). Diese Inhaltsblöcke können die Typen text oder image verwenden.
   • is_error (optional): Auf true setzen, wenn die Tool-Ausführung zu einem Fehler führte.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 Grad"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 Grad"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

Nach Erhalt des Tool-Ergebnisses wird Claude diese Information verwenden, um eine Antwort auf die ursprüngliche Benutzeranfrage zu generieren.

​

Fehlerbehandlung

Es gibt verschiedene Arten von Fehlern, die bei der Verwendung von Tools mit Claude auftreten können:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: der Wetterdienst-API ist nicht verfügbar (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Fehler: Fehlender erforderlicher 'location' Parameter",
      "is_error": true
    }
  ]
}

​

Tool-Nutzungsbeispiele

Hier sind einige Codebeispiele, die verschiedene Tool-Nutzungsmuster und -Techniken demonstrieren. Der Kürze halber sind die Tools einfache Tools, und die Tool-Beschreibungen sind kürzer als ideal wäre, um die beste Leistung zu gewährleisten.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Ich muss die get_weather Funktion aufrufen, und der Benutzer möchte SF, was wahrscheinlich San Francisco, CA ist.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Das aktuelle Wetter in San Francisco beträgt 15 Grad Celsius (59 Grad Fahrenheit). Es ist ein kühler Tag in der Stadt an der Bucht!"
    }
  ]
}

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

​

Preisgestaltung

Tool-Nutzungsanfragen werden wie jede andere Claude API-Anfrage berechnet, basierend auf der Gesamtzahl der an das Modell gesendeten Eingabe-Token (einschließlich im tools Parameter) und der Anzahl der generierten Ausgabe-Token.”

Die zusätzlichen Token aus der Tool-Nutzung stammen von:

• Dem tools Parameter in API-Anfragen (Tool-Namen, Beschreibungen und Schemata)
• tool_use Inhaltsblöcken in API-Anfragen und -Antworten
• tool_result Inhaltsblöcken in API-Anfragen

Wenn Sie tools verwenden, fügen wir auch automatisch einen speziellen Systemprompt für das Modell hinzu, der die Tool-Nutzung ermöglicht. Die Anzahl der für jedes Modell erforderlichen Tool-Nutzungs-Token sind unten aufgeführt (ohne die oben aufgeführten zusätzlichen Token):

Diese Token-Anzahlen werden zu Ihren normalen Ein- und Ausgabe-Token hinzugefügt, um die Gesamtkosten einer Anfrage zu berechnen. Siehe unsere Modellübersichtstabelle für aktuelle Preise pro Modell.

Wenn Sie einen Tool-Nutzungsprompt senden, wird wie bei jeder anderen API-Anfrage die Antwort sowohl Ein- als auch Ausgabe-Token-Anzahlen als Teil der gemeldeten usage Metriken ausgeben.

​

Nächste Schritte

Erkunden Sie unser Repository mit sofort implementierbaren Tool-Nutzungs-Codebeispielen in unseren Kochbüchern: