Tools definieren

Auswahl eines Modells

Verwenden Sie das neueste Claude Opus (4.7) Modell für komplexe Tools und mehrdeutige Anfragen; es verarbeitet mehrere Tools besser und sucht bei Bedarf nach Klarstellung.

Verwenden Sie Claude Haiku Modelle für unkomplizierte Tools, aber beachten Sie, dass sie möglicherweise fehlende Parameter ableiten.

Angeben von Client-Tools

Client-Tools (sowohl Anthropic-Schema als auch benutzerdefinierte) werden im tools Top-Level-Parameter der API-Anfrage angegeben. Jede Tool-Definition umfasst:

Für den vollständigen Satz optionaler Eigenschaften, die auf jeder Tool-Definition verfügbar sind, einschließlich cache_control, strict, defer_loading und allowed_callers, siehe die Tool-Referenz.

Tool-Nutzungs-Systemprompt

Wenn Sie die Claude API mit dem tools Parameter aufrufen, konstruiert die API einen speziellen Systemprompt aus den Tool-Definitionen, der Tool-Konfiguration und jedem benutzerdefinierten Systemprompt. Der konstruierte Prompt ist darauf ausgelegt, das Modell anzuweisen, die angegebenen Tools zu verwenden und den notwendigen Kontext für den ordnungsgemäßen Betrieb des Tools bereitzustellen:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Best Practices für Tool-Definitionen

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

• Geben Sie äußerst detaillierte Beschreibungen an. 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, 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, wann und wie sie verwendet werden. Streben Sie mindestens 3-4 Sätze pro Tool-Beschreibung an, mehr wenn das Tool komplex ist.
• Priorisieren Sie Beschreibungen, erwägen Sie aber die Verwendung von input_examples für komplexe Tools. Klare Beschreibungen sind am wichtigsten, aber für Tools mit komplexen Eingaben, verschachtelten Objekten oder formatempfindlichen Parametern können Sie das Feld input_examples verwenden, um schemavalidierte Beispiele bereitzustellen. Siehe Bereitstellung von Tool-Nutzungsbeispielen für Details.
• Konsolidieren Sie verwandte Operationen in weniger Tools. Anstatt für jede Aktion ein separates Tool zu erstellen (create_pr, review_pr, merge_pr), gruppieren Sie sie in einem einzelnen Tool mit einem action Parameter. Weniger, aber leistungsfähigere Tools reduzieren Auswahlmehrdeutigkeit und machen Ihre Tool-Oberfläche für Claude leichter zu navigieren.
• Verwenden Sie aussagekräftige Namensräume in Tool-Namen. Wenn sich Ihre Tools über mehrere Services oder Ressourcen erstrecken, präfixieren Sie Namen mit dem Service (z. B. github_list_prs, slack_send_message). Dies macht die Tool-Auswahl eindeutig, wenn Ihre Bibliothek wächst, und ist besonders wichtig bei der Verwendung von Tool-Suche.
• Gestalten Sie Tool-Antworten so, dass sie nur hochwertige Informationen zurückgeben. Geben Sie semantische, stabile Identifikatoren (z. B. Slugs oder UUIDs) anstelle von undurchsichtigen internen Referenzen zurück, und fügen Sie nur die Felder ein, die Claude benötigt, um seinen nächsten Schritt zu überdenken. Überladene Antworten verschwenden Kontext und machen es für Claude schwieriger, das Wichtige zu extrahieren.

Die gute Beschreibung erklärt klar, was das Tool tut, wann es verwendet werden sollte, 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 zum Verhalten und zur Verwendung des Tools.

Bereitstellung von Tool-Nutzungsbeispielen

Sie können konkrete Beispiele gültiger Tool-Eingaben bereitstellen, um Claude zu helfen, Ihre Tools effektiver zu verstehen. Dies ist besonders nützlich für komplexe Tools mit verschachtelten Objekten, optionalen Parametern oder formatempfindlichen Eingaben.

Grundlegende Verwendung

Fügen Sie ein optionales input_examples Feld zu Ihrer Tool-Definition mit einem Array von Beispiel-Eingabeobjekten hinzu. Jedes Beispiel muss gemäß dem input_schema des Tools gültig sein:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Beispiele sind im Prompt neben Ihrem Tool-Schema enthalten und zeigen Claude konkrete Muster für gut geformte Tool-Aufrufe. Dies hilft Claude zu verstehen, wann optionale Parameter einzubeziehen sind, welche Formate zu verwenden sind und wie komplexe Eingaben strukturiert werden.

Anforderungen und Einschränkungen

• Schema-Validierung - Jedes Beispiel muss gemäß dem input_schema des Tools gültig sein. Ungültige Beispiele geben einen 400-Fehler zurück
• Nicht unterstützt für serverseitige Tools - Eingabebeispiele funktionieren bei benutzerdefinierten und Anthropic-Schema-Client-Tools, aber nicht bei Server-Tools wie Web-Suche oder Code-Ausführung
• Token-Kosten - Beispiele addieren sich zu Prompt-Tokens: ~20-50 Tokens für einfache Beispiele, ~100-200 Tokens für komplexe verschachtelte Objekte

Kontrolle der Claude-Ausgabe

Erzwungene Tool-Nutzung

In einigen Fällen möchten Sie möglicherweise, dass Claude ein bestimmtes Tool verwendet, um die Frage des Benutzers zu beantworten, auch wenn Claude sonst direkt antworten würde, ohne ein Tool aufzurufen. 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 gibt es vier mögliche Optionen:

• auto ermöglicht Claude zu entscheiden, ob bereitgestellte Tools aufgerufen werden sollen oder nicht. Dies ist der Standardwert, wenn tools bereitgestellt werden.
• any teilt Claude mit, dass es eines der bereitgestellten Tools verwenden muss, erzwingt aber kein bestimmtes Tool.
• tool erzwingt, dass Claude immer ein bestimmtes Tool verwendet.
• none verhindert, dass Claude Tools verwendet. Dies ist der Standardwert, wenn keine tools bereitgestellt werden.

Dieses Diagramm zeigt, wie jede Option funktioniert:

Beachten Sie, dass wenn Sie tool_choice als any oder tool haben, die API die Assistenten-Nachricht vorausfüllt, um zu erzwingen, dass ein Tool verwendet wird. Dies bedeutet, dass die Modelle keine natürlichsprachige Antwort oder Erklärung vor tool_use Inhaltsblöcken ausgeben, auch wenn sie explizit dazu aufgefordert werden.

Tests haben gezeigt, dass dies die Leistung nicht reduzieren sollte. Wenn Sie möchten, dass das Modell natürlichsprachigen Kontext oder Erklärungen bereitstellt, während es immer noch anfordert, dass das Modell ein bestimmtes Tool verwendet, können Sie {"type": "auto"} für tool_choice (Standard) verwenden und explizite Anweisungen in einer user Nachricht hinzufügen. Zum Beispiel: What's the weather like in London? Use the get_weather tool in your response.

Modell-Antworten mit Tools

Bei der Verwendung von Tools wird Claude oft kommentieren, was es tut, oder natürlich auf den Benutzer reagieren, bevor es Tools aufruft.

Zum Beispiel, gegeben den Prompt "What's the weather like in San Francisco right now, and what time is it there?", könnte Claude antworten mit:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Dieser natürliche Antwortstil hilft Benutzern zu verstehen, was Claude tut, und schafft eine konversativere Interaktion. Sie können den Stil und Inhalt dieser Antworten durch Ihre Systemprompts und durch Bereitstellung von <examples> in Ihren Prompts lenken.

Es ist wichtig zu beachten, dass Claude verschiedene Formulierungen und Ansätze verwenden kann, wenn es seine Aktionen erklärt. Ihr Code sollte diese Antworten wie jeden anderen vom Assistenten generierten Text behandeln und sich nicht auf spezifische Formatierungskonventionen verlassen.

Nächste Schritte