Hier sind einige Code-Beispiele, die verschiedene Muster und Techniken der Tool-Nutzung demonstrieren. Der Kürze halber sind die Tools einfache Tools und die Tool-Beschreibungen kürzer als ideal, um die beste Leistung zu gewährleisten. Weitere Informationen finden Sie unter Tools spezifizieren.

Einzelnes Tool

Dieses Beispiel zeigt eine grundlegende Situation mit einem einzigen Tool unter Verwendung eines get_weather Tools.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "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"]
        }
    }],
    "messages": [{"role": "user", "content": "Wie ist das Wetter in San Francisco?"}]
}'

Claude wird eine Antwort ähnlich der folgenden zurückgeben:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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"}
    }
  ]
}

Sie müssten dann die Funktion get_weather mit der bereitgestellten Eingabe ausführen und das Ergebnis in einer neuen user-Nachricht zurückgeben:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "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"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Wie ist das Wetter in San Francisco?"
        },
        {
            "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"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 Grad"
                }
            ]
        }
    ]
}'

Dies wird Claudes endgültige Antwort ausgeben, die die Wetterdaten enthält:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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!"
    }
  ]
}

Fehlende Informationen

Wenn die Eingabeaufforderung des Benutzers nicht genügend Informationen enthält, um alle erforderlichen Parameter für ein Tool auszufüllen, erkennt Claude 3 Opus mit viel höherer Wahrscheinlichkeit, dass ein Parameter fehlt, und fragt danach. Claude 3 Sonnet kann fragen, insbesondere wenn es aufgefordert wird, vor der Ausgabe einer Tool-Anfrage nachzudenken. Es kann aber auch sein Bestes tun, um einen vernünftigen Wert abzuleiten.

Wenn Sie Claude beispielsweise mit dem obigen get_weather-Tool fragen: “Wie ist das Wetter?”, ohne einen Ort anzugeben, kann Claude, insbesondere Claude 3 Sonnet, eine Vermutung über die Tool-Eingaben anstellen:

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

Dieses Verhalten ist nicht garantiert, insbesondere bei mehrdeutigeren Eingabeaufforderungen und bei Modellen, die weniger intelligent sind als Claude 3 Opus. Wenn Claude 3 Opus nicht genügend Kontext hat, um die erforderlichen Parameter auszufüllen, ist es viel wahrscheinlicher, dass es stattdessen mit einer Klarstellungsfrage antwortet, anstatt einen Tool-Aufruf zu tätigen.


Mehrere Tools

Sie können Claude in einer einzigen Anfrage mehrere Tools zur Auswahl stellen. Hier ist ein Beispiel mit einem get_weather- und einem get_time-Tool sowie einer Benutzerabfrage, die nach beidem fragt.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [{
        "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"]
        }
    },
    {
        "name": "get_time",
        "description": "Ruft die aktuelle Uhrzeit für eine bestimmte Zeitzone ab",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "Der IANA-Zeitzonenname, z.B. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "Wie ist das Wetter gerade in New York? Und wie spät ist es dort?"
    }]
}'

In diesem Fall wird Claude höchstwahrscheinlich versuchen, zwei separate Tools zu verwenden, eines nach dem anderen - get_weather und dann get_time -, um die Frage des Benutzers vollständig zu beantworten. Gelegentlich wird es jedoch auch zwei tool_use-Blöcke auf einmal ausgeben, insbesondere wenn sie nicht voneinander abhängig sind. Sie müssten jedes Tool ausführen und deren Ergebnisse in separaten tool_result-Blöcken innerhalb einer einzigen user-Nachricht zurückgeben.


Sequentielle Tools

Manche Aufgaben erfordern möglicherweise den Aufruf mehrerer Tools in Folge, wobei die Ausgabe eines Tools als Eingabe für ein anderes verwendet wird. In einem solchen Fall ruft Claude ein Tool nach dem anderen auf. Wenn Claude aufgefordert wird, alle Tools auf einmal aufzurufen, wird es wahrscheinlich Parameter für weiter unten liegende Tools erraten, wenn diese von Tool-Ergebnissen für weiter oben liegende Tools abhängig sind.

Hier ist ein Beispiel für die Verwendung eines get_location-Tools, um den Standort des Benutzers zu ermitteln, und die anschließende Übergabe dieses Standorts an das get_weather-Tool:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Ruft den aktuellen Standort des Benutzers basierend auf seiner IP-Adresse ab. Dieses Tool hat keine Parameter oder Argumente.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "Wie ist das Wetter dort, wo ich bin?"
    }]
}'

In diesem Fall würde Claude zuerst das get_location-Tool aufrufen, um den Standort des Benutzers zu ermitteln. Nachdem Sie den Standort in einem tool_result zurückgegeben haben, würde Claude dann get_weather mit diesem Standort aufrufen, um die endgültige Antwort zu erhalten.

Die vollständige Konversation könnte folgendermaßen aussehen:

RolleInhalt
BenutzerWie ist das Wetter dort, wo ich bin?
Assistent<thinking>Um dies zu beantworten, muss ich zunächst den Standort des Benutzers mit dem get_location-Tool ermitteln. Dann kann ich diesen Standort an das get_weather-Tool übergeben, um das aktuelle Wetter dort herauszufinden.</thinking>[Tool-Verwendung für get_location]
Benutzer[Tool-Ergebnis für get_location mit übereinstimmender ID und Ergebnis von San Francisco, CA]
Assistent[Tool-Verwendung für get_weather mit der folgenden Eingabe]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Benutzer[Tool-Ergebnis für get_weather mit übereinstimmender ID und Ergebnis von “59°F (15°C), meist bewölkt”]
AssistentBasierend auf Ihrem aktuellen Standort in San Francisco, CA, beträgt das Wetter dort gerade 59°F (15°C) und ist meist bewölkt. Es ist ein ziemlich kühler und bedeckter Tag in der Stadt. Wenn Sie nach draußen gehen, sollten Sie vielleicht eine leichte Jacke mitnehmen.

Dieses Beispiel zeigt, wie Claude mehrere Tool-Aufrufe miteinander verketten kann, um eine Frage zu beantworten, die das Sammeln von Daten aus verschiedenen Quellen erfordert. Die wichtigsten Schritte sind:

  1. Claude erkennt zunächst, dass es den Standort des Benutzers benötigt, um die Wetterfrage zu beantworten, und ruft daher das get_location-Tool auf.
  2. Der Benutzer (d.h. der Client-Code) führt die eigentliche get_location-Funktion aus und gibt das Ergebnis “San Francisco, CA” in einem tool_result-Block zurück.
  3. Da der Standort nun bekannt ist, ruft Claude das get_weather-Tool auf und übergibt “San Francisco, CA” als location-Parameter (sowie einen vermuteten unit-Parameter, da unit kein erforderlicher Parameter ist).
  4. Der Benutzer führt erneut die eigentliche get_weather-Funktion mit den angegebenen Argumenten aus und gibt die Wetterdaten in einem weiteren tool_result-Block zurück.
  5. Schließlich integriert Claude die Wetterdaten in eine natürlichsprachige Antwort auf die ursprüngliche Frage.

Gedankenkette bei der Tool-Nutzung

Standardmäßig wird Claude 3 Opus aufgefordert, vor der Beantwortung einer Tool-Nutzungsabfrage nachzudenken, um am besten zu bestimmen, ob ein Tool notwendig ist, welches Tool verwendet werden soll und welche Parameter angemessen sind. Claude 3 Sonnet und Claude 3 Haiku werden aufgefordert, Tools so oft wie möglich zu verwenden, und neigen eher dazu, ein unnötiges Tool aufzurufen oder fehlende Parameter abzuleiten. Um Sonnet oder Haiku dazu zu bringen, die Benutzerabfrage besser zu bewerten, bevor sie Tool-Aufrufe tätigen, kann die folgende Aufforderung verwendet werden:

Aufforderung zur Gedankenkette

Beantworten Sie die Anfrage des Benutzers mit relevanten Tools (falls verfügbar). Bevor Sie ein Tool aufrufen, führen Sie eine Analyse innerhalb von \<thinking>\</thinking>-Tags durch. Überlegen Sie zunächst, welches der bereitgestellten Tools das relevante Tool ist, um die Anfrage des Benutzers zu beantworten. Gehen Sie dann jeden der erforderlichen Parameter des relevanten Tools durch und bestimmen Sie, ob der Benutzer direkt einen Wert angegeben hat oder genügend Informationen gegeben hat, um einen Wert abzuleiten. Wenn Sie entscheiden, ob der Parameter abgeleitet werden kann, berücksichtigen Sie sorgfältig den gesamten Kontext, um zu sehen, ob er einen bestimmten Wert unterstützt. Wenn alle erforderlichen Parameter vorhanden sind oder vernünftig abgeleitet werden können, schließen Sie den Thinking-Tag und fahren Sie mit dem Tool-Aufruf fort. ABER, wenn einer der Werte für einen erforderlichen Parameter fehlt, rufen Sie die Funktion NICHT auf (auch nicht mit Füllwerten für die fehlenden Parameter) und bitten Sie stattdessen den Benutzer, die fehlenden Parameter anzugeben. Fragen Sie NICHT nach weiteren Informationen zu optionalen Parametern, wenn diese nicht angegeben werden.


JSON-Modus

Sie können Tools verwenden, um Claude dazu zu bringen, JSON-Ausgaben zu erzeugen, die einem Schema folgen, auch wenn Sie nicht die Absicht haben, diese Ausgabe durch ein Tool oder eine Funktion laufen zu lassen.

Bei der Verwendung von Tools auf diese Weise:

  • Normalerweise möchten Sie ein einzelnes Tool bereitstellen
  • Sie sollten tool_choice setzen (siehe Erzwingen der Tool-Nutzung), um das Modell anzuweisen, dieses Tool explizit zu verwenden
  • Denken Sie daran, dass das Modell die input an das Tool weitergibt, daher sollten der Name des Tools und die Beschreibung aus der Sicht des Modells erfolgen.

Das Folgende verwendet ein record_summary-Tool, um ein Bild nach einem bestimmten Format zu beschreiben.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --data \
'{
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Zusammenfassung eines Bildes mit gut strukturiertem JSON aufzeichnen.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "Rotwert [0.0, 1.0]" },
"g": { "type": "number", "description": "Grünwert [0.0, 1.0]" },
"b": { "type": "number", "description": "Blauwert [0.0, 1.0]" },
"name": { "type": "string", "description": "Menschenlesbarer Farbname in snake_case, z.B. \"olive_green\" oder \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Schlüsselfarben im Bild. Auf weniger als vier begrenzen."
                },
                "description": {
                    "type": "string",
                    "description": "Bildbeschreibung. Maximal ein bis zwei Sätze."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Geschätztes Jahr, in dem das Bild aufgenommen wurde, wenn es sich um ein Foto handelt. Nur setzen, wenn das Bild nicht fiktional erscheint. Grobe Schätzungen sind in Ordnung!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Beschreibe dieses Bild."}
        ]}
    ]
}'