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:

# 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)

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.

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.

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.

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