Werkzeugnutzung (Funktionsaufrufe)

Claude ist in der Lage, mit externen clientseitigen Werkzeugen und Funktionen zu interagieren, sodass Sie Claude mit Ihren eigenen benutzerdefinierten Werkzeugen ausstatten können, um eine breitere Palette von Aufgaben zu erledigen.

Hier ist ein Beispiel, wie man Claude über die Messages API Werkzeuge zur Verfügung stellt:

​

Wie die Werkzeugnutzung funktioniert

Integrieren Sie externe Werkzeuge mit Claude in diesen Schritten:

Hinweis: Die Schritte 3 und 4 sind optional. Für einige Arbeitsabläufe reicht möglicherweise Claudes Werkzeugnutzungsanfrage (Schritt 2) aus, ohne dass die Ergebnisse an Claude zurückgesendet werden müssen.

​

Wie man die Werkzeugnutzung implementiert

​

Auswahl eines Modells

Verwenden Sie im Allgemeinen Claude 3 Opus für komplexe Werkzeuge und mehrdeutige Anfragen; es handhabt mehrere Werkzeuge besser und sucht bei Bedarf nach Klarstellung.

Verwenden Sie Haiku für unkomplizierte Werkzeuge, aber beachten Sie, dass es fehlende Parameter ableiten kann.

​

Angabe von Werkzeugen

Werkzeuge werden im Parameter tools auf oberster Ebene der API-Anfrage angegeben. Jede Werkzeugdefinition enthält:

{
  "name": "get_weather",
  "description": "Hole das aktuelle Wetter für einen bestimmten Ort",
  "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"]
  }
}

​

Bewährte Methoden für Werkzeugdefinitionen

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

• Stellen Sie extrem detaillierte Beschreibungen bereit. Dies ist mit Abstand der wichtigste Faktor für die Leistung des Werkzeugs. Ihre Beschreibungen sollten jedes Detail über das Werkzeug erklären, einschließlich:
  • Was das Werkzeug tut
  • Wann es verwendet werden sollte (und wann nicht)
  • Was jeder Parameter bedeutet und wie er das Verhalten des Werkzeugs beeinflusst
  • Alle wichtigen Vorbehalte oder Einschränkungen, z.B. welche Informationen das Werkzeug nicht zurückgibt, wenn der Werkzeugname unklar ist. Je mehr Kontext Sie Claude über Ihre Werkzeuge geben können, desto besser kann es entscheiden, wann und wie es sie verwendet. Streben Sie mindestens 3-4 Sätze pro Werkzeugbeschreibung an, mehr, wenn das Werkzeug komplex ist.
• Priorisieren Sie Beschreibungen gegenüber Beispielen. Während Sie Beispiele für die Verwendung eines Werkzeugs in seiner Beschreibung oder in der begleitenden Aufforderung aufnehmen können, ist dies weniger wichtig als eine klare und umfassende Erklärung des Zwecks und der Parameter des Werkzeugs. Fügen Sie Beispiele erst hinzu, nachdem Sie die Beschreibung vollständig ausgearbeitet haben.

{
  "name": "get_stock_price",
  "description": "Ruft den aktuellen Aktienkurs für ein bestimmtes 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 Werkzeug 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 liefert keine weiteren Informationen über die Aktie oder das Unternehmen.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Das Aktientickersymbol, z.B. AAPL für Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

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

Die gute Beschreibung erklärt deutlich, was das Werkzeug tut, wann es verwendet werden soll, welche Daten es zurückgibt und was der Parameter ticker bedeutet. Die schlechte Beschreibung ist zu kurz und lässt Claude mit vielen offenen Fragen zum Verhalten und zur Verwendung des Werkzeugs zurück.

​

Steuerung der Ausgabe von Claude

​

Erzwingen der Werkzeugnutzung

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

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

Bei der Arbeit mit dem Parameter tool_choice haben wir drei Möglichkeiten:

• auto erlaubt Claude zu entscheiden, ob bereitgestellte Werkzeuge aufgerufen werden sollen oder nicht. Dies ist der Standardwert.
• any weist Claude an, dass es eines der bereitgestellten Werkzeuge verwenden muss, erzwingt aber kein bestimmtes Werkzeug.
• tool ermöglicht es uns, Claude zu zwingen, immer ein bestimmtes Werkzeug zu verwenden.

Dieses Diagramm veranschaulicht, wie jede Option funktioniert:

Beachten Sie, dass wir bei tool_choice als any oder tool die Assistentennachricht vorfüllen, um die Verwendung eines Werkzeugs zu erzwingen. Das bedeutet, dass die Modelle keine Gedankenketten-text-Inhaltsblöcke vor tool_use-Inhaltsblöcken ausgeben, auch wenn dies explizit gefordert wird.

Unsere Tests haben gezeigt, dass dies die Leistung nicht beeinträchtigen sollte. Wenn Sie die Gedankenkette (insbesondere mit Opus) beibehalten möchten und gleichzeitig die Verwendung eines bestimmten Werkzeugs anfordern, können Sie {"type": "auto"} für tool_choice (Standard) verwenden und explizite Anweisungen in einer user-Nachricht hinzufügen. Zum Beispiel: Wie ist das Wetter in London? Verwenden Sie in Ihrer Antwort das Werkzeug get_weather.

​

JSON-Ausgabe

Werkzeuge müssen nicht unbedingt clientseitige Funktionen sein - Sie können Werkzeuge jederzeit verwenden, wenn Sie möchten, dass das Modell JSON-Ausgaben zurückgibt, die einem bereitgestellten Schema entsprechen. Beispielsweise könnten Sie ein record_summary-Werkzeug mit einem bestimmten Schema verwenden. Ein vollständiges funktionierendes Beispiel finden Sie unter Beispiele für die Werkzeugnutzung.

​

Gedankenkette

Bei der Verwendung von Werkzeugen zeigt Claude oft seine “Gedankenkette”, d.h. die schrittweise Argumentation, die es verwendet, um das Problem zu zerlegen und zu entscheiden, welche Werkzeuge verwendet werden sollen. Das Modell Claude 3 Opus tut dies, wenn tool_choice auf auto gesetzt ist (dies ist der Standardwert, siehe Erzwingen der Werkzeugnutzung), und Sonnet und Haiku können dazu aufgefordert werden.

Beispielsweise könnte Claude bei der 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 Werkzeug get_weather verwenden, um das aktuelle Wetter in San Francisco zu erhalten. 2. Das Werkzeug get_time verwenden, um die aktuelle Uhrzeit in der Zeitzone America/Los_Angeles 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 Argumentationsprozess und kann Ihnen helfen, unerwartetes Verhalten zu debuggen.

Beim Modell Claude 3 Sonnet ist die Gedankenkette standardmäßig weniger häufig, aber Sie können Claude auffordern, seine Argumentation zu zeigen, indem Sie etwas wie "Erklären Sie vor der Beantwortung Ihre Argumentation Schritt für Schritt in Tags." zur Benutzernachricht oder Systemaufforderung hinzufügen.

Es ist wichtig zu beachten, dass die <thinking>-Tags zwar eine gängige Konvention sind, die Claude verwendet, um seine Gedankenkette zu kennzeichnen, sich das genaue Format (z.B. wie dieser XML-Tag benannt ist) jedoch 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 das spezifische Format der <thinking>-Tags verlassen.

​

Umgang mit Inhaltsblöcken für Werkzeugnutzung und Werkzeugergebnisse

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

• id: Eine eindeutige Kennung für diesen speziellen Werkzeugnutzungsblock. Diese wird später verwendet, um die Werkzeugergebnisse zuzuordnen.
• name: Der Name des verwendeten Werkzeugs.
• input: Ein Objekt, das die an das Werkzeug übergebene Eingabe enthält und dem input_schema des Werkzeugs entspricht.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "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 Werkzeugnutzungsantwort erhalten, sollten Sie:

1. Extrahieren Sie name, id und input aus dem tool_use-Block.
2. Führen Sie das tatsächliche Werkzeug in Ihrem Codebase aus, das diesem Werkzeugnamen entspricht, und übergeben Sie die Werkzeugeingabe input.
3. [optional] Setzen Sie die Konversation fort, indem Sie eine neue Nachricht mit der role user und einem content-Block senden, der den Typ tool_result und die folgenden Informationen enthält:
   • tool_use_id: Die id der Werkzeugnutzungsanfrage, für die dies ein Ergebnis ist.
   • content: Das Ergebnis des Werkzeugs 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 Werkzeugausführung zu einem Fehler geführt hat.

{
  "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 Werkzeugergebnisses verwendet Claude diese Informationen, um weiterhin eine Antwort auf die ursprüngliche Benutzeranfrage zu generieren.

​

Fehlerbehebung

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

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

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

​

Beispiele für die Werkzeugnutzung

Hier sind einige Codebeispiele, die verschiedene Muster und Techniken der Werkzeugnutzung demonstrieren. Der Kürze halber sind die Werkzeuge einfache Werkzeuge und die Werkzeugbeschreibungen kürzer, als es für eine optimale Leistung ideal wäre.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Ich muss die Funktion get_weather 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-20240620",
  "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

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

Die zusätzlichen Token durch die Werkzeugnutzung stammen aus:

• Dem Parameter tools in API-Anfragen (Werkzeugnamen, Beschreibungen und Schemas)
• tool_use-Inhaltsblöcken in API-Anfragen und -Antworten
• tool_result-Inhaltsblöcken in API-Anfragen

Wenn Sie tools verwenden, fügen wir dem Modell auch automatisch eine spezielle Systemaufforderung hinzu, die die Werkzeugnutzung ermöglicht. Die Anzahl der für jedes Modell erforderlichen Werkzeugnutzungs-Token ist unten aufgeführt (ohne die oben aufgeführten zusätzlichen Token):

Diese Token-Anzahlen werden zu Ihren normalen Eingabe- und Ausgabe-Token addiert, um die Gesamtkosten einer Anfrage zu berechnen. Eine Übersicht über die aktuellen Preise pro Modell finden Sie in unserer Modellübersichtstabelle.

Wenn Sie eine Werkzeugnutzungsaufforderung senden, gibt die Antwort wie bei jeder anderen API-Anfrage sowohl die Anzahl der Eingabe- als auch der Ausgabe-Token als Teil der gemeldeten usage-Metriken aus.

​

Nächste Schritte

Erkunden Sie unser Repository mit einsatzbereiten Codebeispielen für die Werkzeugnutzung in unseren Kochbüchern: