Tool-Nutzung mit Claude

„Tool use" (Tool-Nutzung) ermöglicht es Claude, Funktionen aufzurufen, die du definierst oder die Anthropic bereitstellt. Claude entscheidet anhand der Anfrage des Nutzers und der Beschreibung des Tools, wann ein Tool aufgerufen wird. Anschließend gibt es einen strukturierten Aufruf zurück, den deine Anwendung ausführt (Client-Tools) oder den Anthropic ausführt (Server-Tools).

Hier ist ein minimales Beispiel mit einem Server-Tool, dem Websuche-Tool, das Anthropic für dich ausführt:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude führt die Suche auf der Infrastruktur von Anthropic aus und gibt die zitierten Ergebnisse in derselben Antwort zurück. Damit Claude eine von dir definierte Funktion aufruft, übergib ein Tool mit einem input_schema und führe dann den Aufruf aus, wenn Claude einen tool_use-Block zurückgibt. Wie Tool-Nutzung funktioniert zeigt diesen Roundtrip von Anfang bis Ende. Erfahre mehr über das Definieren von Tools und das Verarbeiten von Tool-Aufrufen.



Wie Tool-Nutzung funktioniert

Tools unterscheiden sich hauptsächlich darin, wo der Code ausgeführt wird. Client-Tools (einschließlich benutzerdefinierter Tools und Tools mit von Anthropic definierten Schemas, wie bash und text_editor) laufen in deiner Anwendung. Claude antwortet mit stop_reason: "tool_use" und einem oder mehreren tool_use-Blöcken. Dein Code führt die Operation aus und sendet ein tool_result zurück. Server-Tools (wie web_search, web_fetch, code_execution und tool_search) laufen auf der Infrastruktur von Anthropic: Du siehst die Ergebnisse direkt, ohne die Ausführung zu übernehmen, es sei denn, Claude ruft das Tool in derselben Gruppe paralleler Tool-Aufrufe auf wie eines deiner Client-Tools (siehe Stop-Reasons und Fallback).

Hier ist dieser Roundtrip vollständig für ein Client-Tool. Die erste Anfrage definiert ein get_weather-Tool, und Claude beantwortet die Frage, indem es dieses aufruft: Die Antwort enthält einen tool_use-Block, dein Code führt die Abfrage aus, und eine zweite Anfrage sendet das Ergebnis in einem tool_result-Block zurück, damit Claude mit der Antwort reagieren kann.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude antwortet mit einem tool_use-Block, der das Tool und seine Argumente benennt.
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # Fordere höchstens einen Tool-Aufruf pro Zug an.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Führe das Tool aus und sende das Ergebnis dann in einem tool_result-Block zurück.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude nutzt das Ergebnis, um die ursprüngliche Frage zu beantworten.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

Tool-Aufrufe verarbeiten behandelt jeden Schritt im Detail, einschließlich der Formatierung von Ergebnissen und der Fehlersignalisierung; Parallele Tool-Nutzung behandelt Antworten, die mehrere Tools gleichzeitig aufrufen. Um diesen Roundtrip nicht selbst schreiben zu müssen, verwende den Tool Runner: Die SDKs führen deine Tools aus und senden die Ergebnisse automatisch zurück.

Das vollständige konzeptionelle Modell einschließlich der agentischen Schleife und wann welcher Ansatz zu wählen ist, findest du unter Wie Tool-Nutzung funktioniert.

Für die Verbindung zu Model Context Protocol (MCP)-Servern siehe den MCP-Connector. Um einen eigenen MCP-Client zu erstellen, siehe den Model Context Protocol-Leitfaden zum Erstellen eines MCP-Clients.



Wann Claude Tools verwendet

Mit dem Standardwert {"type": "auto"} für tool_choice entscheidet Claude bei jedem Zug, ob ein Tool aufgerufen oder direkt geantwortet wird. Es ruft ein Tool auf, wenn die Anfrage der beschriebenen Fähigkeit dieses Tools entspricht und die Antwort nicht bereits im Kontext vorhanden ist. Es antwortet direkt bei stabilem Wissen, kreativen Aufgaben und Gesprächszügen.

Diese Grenze lässt sich über deinen System-Prompt steuern. Wenn Claude keine Tools aufruft, obwohl du es erwartest, erhöht eine leichte Anweisung wie "Use the tools to investigate before responding." die Tool-Nutzung. Eine stärkere Form wie "Always call a tool first before responding." geht noch weiter. Umgekehrt hält "Use your judgment about whether to call a tool or respond directly." das Auslöseverhalten konservativ.

Um einen Tool-Aufruf zu erzwingen, anstatt dich auf Prompting zu verlassen, setze tool_choice.

Die Seite jedes Server-Tools beschreibt die jeweilige Auslösegrenze genauer.



Wähle ein Tool

Für type-Strings, Versionen und Beta-Header siehe die Tool-Referenz.



Deine eigenen Tools

Bei Tools, die du definierst, schreibst du das Schema und deine Anwendung führt jeden Aufruf aus.



Client-Tools mit Anthropic-Schema

Anthropic veröffentlicht das Schema und trainiert Claude darauf. Deine Anwendung führt weiterhin jeden Aufruf aus und gibt das tool_result zurück.



Server-Tools

Server-Tools laufen auf der Infrastruktur von Anthropic, ohne Handler-Code in deiner Anwendung. Siehe Server-Tools für die Mechanismen, die sie gemeinsam haben.



Preise

Anfragen mit Tool-Nutzung werden basierend auf folgenden Faktoren berechnet:

1. Die Gesamtzahl der an das Modell gesendeten Input-Token (einschließlich des tools-Parameters)
2. Die Anzahl der generierten Output-Token
3. Bei serverseitigen Tools zusätzliche nutzungsbasierte Kosten (zum Beispiel berechnet die Websuche Gebühren pro durchgeführter Suche)

Clientseitige Tools werden genauso berechnet wie jede andere Claude-API-Anfrage, während serverseitige Tools je nach ihrer spezifischen Nutzung zusätzliche Kosten verursachen können.

Die zusätzlichen Token durch Tool-Nutzung stammen aus:

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

Wenn du tools verwendest, fügt die API automatisch auch einen speziellen System-Prompt für das Modell hinzu, der die Tool-Nutzung ermöglicht. Die Anzahl der für jedes Modell erforderlichen Tool-Nutzungs-Token ist in der folgenden Tabelle aufgeführt (ohne die zuvor aufgeführten zusätzlichen Token). Beachte, dass die Tabelle davon ausgeht, dass mindestens 1 Tool bereitgestellt wird. Wenn keine tools bereitgestellt werden, verwendet eine Tool-Auswahl von none 0 zusätzliche System-Prompt-Token.

Diese Token-Anzahlen werden zu deinen normalen Input- und Output-Token addiert, um die Gesamtkosten einer Anfrage zu berechnen.

Siehe die Tabelle in der Modellübersicht für aktuelle Preise pro Modell.

Wenn du einen Tool-Nutzungs-Prompt sendest, enthält die Antwort wie bei jeder anderen API-Anfrage sowohl die Anzahl der Input- als auch der Output-Token in den gemeldeten usage-Metriken.

Einige Server-Tools erheben zusätzlich zu den Token nutzungsbasierte Gebühren: Siehe Websuche-Tool und Code-Execution-Tool für deren Tarife.



Nächste Schritte