Outils serveur

Cette page couvre les mécanismes partagés des outils exécutés par le serveur : le bloc server_tool_use, la continuation pause_turn, les considérations ZDR et le filtrage de domaine. Pour les outils individuels, consultez la référence des outils.

Le bloc server_tool_use

Le bloc server_tool_use apparaît dans la réponse de Claude lorsqu'un outil exécuté par le serveur s'exécute. Son champ id utilise le préfixe srvtoolu_ pour le distinguer des appels d'outils clients :

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

L'API exécute l'outil en interne. Vous voyez l'appel et son résultat dans la réponse, mais vous ne gérez pas l'exécution. Contrairement aux blocs tool_use clients, vous n'avez pas besoin de répondre avec un tool_result. Le bloc de résultat apparaît immédiatement après le bloc server_tool_use dans le même tour d'assistant.

La boucle côté serveur et pause_turn

Lors de l'utilisation d'outils serveur comme la recherche web, l'API peut retourner une raison d'arrêt pause_turn, indiquant que l'API a mis en pause un tour de longue durée.

Voici comment gérer la raison d'arrêt pause_turn :

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

Lors de la gestion de pause_turn :

• Continuez la conversation : Transmettez la réponse mise en pause telle quelle dans une demande ultérieure pour permettre à Claude de continuer son tour
• Modifiez si nécessaire : Vous pouvez éventuellement modifier le contenu avant de continuer si vous souhaitez interrompre ou rediriger la conversation
• Préservez l'état des outils : Incluez les mêmes outils dans la demande de continuation pour maintenir la fonctionnalité

ZDR et allowed_callers

Les versions de base de la recherche web (web_search_20250305) et de la récupération web (web_fetch_20250910) sont éligibles pour la rétention zéro données (ZDR).

Les versions _20260209 avec filtrage dynamique ne sont pas éligibles à ZDR par défaut car le filtrage dynamique repose sur l'exécution de code en interne.

Pour utiliser un outil serveur _20260209 avec ZDR, désactivez le filtrage dynamique en définissant "allowed_callers": ["direct"] sur l'outil :

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

Cela restreint l'outil à l'invocation directe uniquement, en contournant l'étape d'exécution de code interne.

Filtrage de domaine

Les outils serveur qui accèdent au web acceptent les paramètres allowed_domains et blocked_domains pour contrôler les domaines que Claude peut atteindre.

Lors de l'utilisation de filtres de domaine :

• Les domaines ne doivent pas inclure le schéma HTTP/HTTPS (utilisez example.com au lieu de https://example.com)
• Les sous-domaines sont automatiquement inclus (example.com couvre docs.example.com)
• Les sous-domaines spécifiques limitent les résultats à ce sous-domaine uniquement (docs.example.com retourne uniquement les résultats de ce sous-domaine, pas de example.com ou api.example.com)
• Les sous-chemins sont pris en charge et correspondent à tout ce qui suit le chemin (example.com/blog correspond à example.com/blog/post-1)
• Vous pouvez utiliser soit allowed_domains soit blocked_domains, mais pas les deux dans la même demande

Support des caractères génériques :

• Un seul caractère générique (*) est autorisé par entrée de domaine, et il doit apparaître après la partie domaine (dans le chemin)
• Valide : example.com/*, example.com/*/articles
• Invalide : *.example.com, ex*.com, example.com/*/news/*

Les formats de domaine invalides retournent une erreur d'outil invalid_tool_input.

Filtrage dynamique avec exécution de code

Les versions _20260209 de la recherche web et de la récupération web utilisent l'exécution de code en interne pour appliquer des filtres dynamiques aux résultats de recherche.

Événements serveur-outil en streaming

Les événements des outils serveur sont diffusés en continu dans le flux SSE normal. Le bloc server_tool_use et son résultat arrivent sous forme d'événements content_block_start et content_block_delta, de la même manière que le texte et les appels d'outils clients sont diffusés en continu.

Consultez Streaming pour la référence complète des événements. Les pages d'outils individuels documentent les noms d'événements spécifiques aux outils où ils diffèrent.

Demandes par lot

Tous les outils serveur prennent en charge le traitement par lot. Consultez Traitement par lot.

Prochaines étapes