Server-Tools

Diese Seite behandelt die gemeinsamen Mechaniken von Server-ausgeführten Tools: den server_tool_use Block, pause_turn Fortsetzung, ZDR-Überlegungen und Domain-Filterung. Für einzelne Tools siehe die Tool-Referenz.

Der server_tool_use Block

Der server_tool_use Block erscheint in Claudes Antwort, wenn ein Server-ausgeführtes Tool läuft. Sein id Feld verwendet das srvtoolu_ Präfix, um es von Client-Tool-Aufrufen zu unterscheiden:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

Die API führt das Tool intern aus. Sie sehen den Aufruf und sein Ergebnis in der Antwort, aber Sie handhaben die Ausführung nicht. Im Gegensatz zu Client tool_use Blöcken müssen Sie nicht mit einem tool_result antworten. Der Ergebnis-Block erscheint unmittelbar nach dem server_tool_use Block in derselben Assistent-Wendung.

Die Server-seitige Schleife und pause_turn

Bei Verwendung von Server-Tools wie Web-Suche kann die API einen pause_turn Stop-Grund zurückgeben, der anzeigt, dass die API eine lange laufende Wendung pausiert hat.

So handhaben Sie den pause_turn Stop-Grund:

Bei der Handhabung von pause_turn:

Setzen Sie das Gespräch fort: Geben Sie die pausierte Antwort unverändert in einer nachfolgenden Anfrage zurück, um Claude seine Wendung fortsetzen zu lassen
Ändern Sie bei Bedarf: Sie können den Inhalt optional vor der Fortsetzung ändern, wenn Sie das Gespräch unterbrechen oder umleiten möchten
Bewahren Sie den Tool-Status: Fügen Sie die gleichen Tools in die Fortsetzungsanfrage ein, um die Funktionalität zu erhalten

ZDR und allowed_callers

Die grundlegenden Versionen der Web-Suche (web_search_20250305) und des Web-Abrufs (web_fetch_20250910) sind berechtigt für Zero Data Retention (ZDR).

Die _20260209 Versionen mit dynamischer Filterung sind nicht standardmäßig ZDR-berechtigt, da die dynamische Filterung intern auf Code-Ausführung angewiesen ist.

Um ein _20260209 Server-Tool mit ZDR zu verwenden, deaktivieren Sie die dynamische Filterung, indem Sie "allowed_callers": ["direct"] auf dem Tool setzen:

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

Dies beschränkt das Tool auf direkte Aufrufe nur und umgeht den internen Code-Ausführungsschritt.

Obwohl das Web-Abruf-Tool selbst ZDR-berechtigt ist, können Website-Verleger alle Parameter beibehalten, die an die URL übergeben werden, wenn Claude Inhalte von ihrer Website abruft.

Domain-Filterung

Server-Tools, die auf das Web zugreifen, akzeptieren allowed_domains und blocked_domains Parameter, um zu kontrollieren, welche Domains Claude erreichen kann.

Bei Verwendung von Domain-Filtern:

Domains sollten nicht das HTTP/HTTPS-Schema enthalten (verwenden Sie example.com statt https://example.com)
Subdomains sind automatisch enthalten (example.com deckt docs.example.com ab)
Spezifische Subdomains beschränken die Ergebnisse nur auf diese Subdomain (docs.example.com gibt nur Ergebnisse von dieser Subdomain zurück, nicht von example.com oder api.example.com)
Subpfade werden unterstützt und entsprechen allem nach dem Pfad (example.com/blog entspricht example.com/blog/post-1)
Sie können entweder allowed_domains oder blocked_domains verwenden, aber nicht beide in derselben Anfrage

Wildcard-Unterstützung:

Pro Domain-Eintrag ist nur ein Wildcard (*) zulässig, und es muss nach dem Domain-Teil (im Pfad) erscheinen
Gültig: example.com/*, example.com/*/articles
Ungültig: *.example.com, ex*.com, example.com/*/news/*

Ungültige Domain-Formate geben einen invalid_tool_input Tool-Fehler zurück.

Domain-Beschränkungen auf Anfrage-Ebene müssen mit Domain-Beschränkungen auf Organisations-Ebene kompatibel sein, die in der Console konfiguriert sind. Domain-Beschränkungen auf Anfrage-Ebene können Domains nur weiter einschränken, nicht außer Kraft setzen oder über die Organisations-Ebene-Liste hinaus erweitern. Wenn Ihre Anfrage Domains enthält, die mit Organisations-Einstellungen in Konflikt stehen, gibt die API einen Validierungsfehler zurück.

Beachten Sie, dass Unicode-Zeichen in Domain-Namen Sicherheitslücken durch Homograph-Angriffe schaffen können, bei denen visuell ähnliche Zeichen aus verschiedenen Skripten Domain-Filter umgehen können. Zum Beispiel kann аmazon.com (mit kyrillischem 'а') identisch mit amazon.com aussehen, stellt aber eine andere Domain dar.

Bei der Konfiguration von Domain-Allow/Block-Listen:

Verwenden Sie wenn möglich nur ASCII-Domain-Namen
Beachten Sie, dass URL-Parser Unicode-Normalisierung möglicherweise unterschiedlich handhaben
Testen Sie Ihre Domain-Filter mit potenziellen Homograph-Variationen
Überprüfen Sie regelmäßig Ihre Domain-Konfigurationen auf verdächtige Unicode-Zeichen

Dynamische Filterung mit Code-Ausführung

Die _20260209 Versionen der Web-Suche und des Web-Abrufs verwenden Code-Ausführung intern, um dynamische Filter gegen Suchergebnisse anzuwenden.

Das Einschließen eines eigenständigen code_execution Tools neben _20260209 Versionen von Web-Tools erstellt zwei Ausführungsumgebungen, was das Modell verwirren kann. Verwenden Sie das eine oder das andere, oder heften Sie beide an die gleiche Version.

Streaming von Server-Tool-Ereignissen

Server-Tool-Ereignisse streamen als Teil des normalen SSE-Flusses. Der server_tool_use Block und sein Ergebnis kommen als content_block_start und content_block_delta Ereignisse an, auf die gleiche Weise wie Text und Client-Tool-Aufrufe streamen.

Siehe Streaming für die vollständige Ereignisreferenz. Einzelne Tool-Seiten dokumentieren Tool-spezifische Ereignisnamen, wo sie sich unterscheiden.

Batch-Anfragen

Alle Server-Tools unterstützen Batch-Verarbeitung. Siehe Batch-Verarbeitung.

Nächste Schritte

Web-Suche

Durchsuchen Sie das Web und zitieren Sie Ergebnisse.

Web-Abruf

Rufen Sie Inhalte von bestimmten URLs ab.

Code-Ausführung

Führen Sie Python in einem isolierten Container aus.

Tool-Suche

# Initial request with web search
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)