Claude Platform Docs
MessagesOutils

Outils serveur

Travaillez avec les outils exécutés par Anthropic : blocs server_tool_use, poursuite après pause_turn, tours mêlant outils serveur et outils client, et filtrage de domaines.

Les outils exécutés côté serveur partagent ces mécanismes : le bloc server_tool_use, la continuation pause_turn, les tours qui mélangent outils serveur et outils client, l’éligibilité à la « Zero Data Retention » (conservation zéro des données), ou ZDR, et le filtrage de domaines. 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é côté serveur s’exécute. Son champ id utilise le préfixe srvtoolu_ pour le distinguer des appels d’outils client :

{
  "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 client, vous n’avez pas besoin de répondre avec un tool_result. Le bloc de résultat de l’outil (par exemple, web_search_tool_result pour la recherche web) suit le bloc server_tool_use dans le même tour de l’assistant, apparié par tool_use_id. Si Claude appelle en même temps l’un de vos outils client, le bloc server_tool_use apparaît sans son résultat, et la réponse se termine par stop_reason: "tool_use". L’API exécute l’outil lorsque vous renvoyez les blocs tool_result client dans votre requête suivante.

La boucle côté serveur et pause_turn

Lorsque vous utilisez des outils serveur tels que la recherche web, l’API exécute les appels d’outils dans une boucle agentique côté serveur. Lors d’un tour de longue durée, l’API peut mettre cette boucle en pause et renvoyer un motif d’arrêt pause_turn.

Voici comment gérer le motif d’arrêt pause_turn :

client = anthropic.Anthropic()

# Requête initiale avec recherche web.
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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}],
)

# Vérifier si la réponse a une raison d'arrêt pause_turn.
if response.stop_reason == "pause_turn":
    # Poursuivre la conversation avec le contenu mis en pause.
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Envoyer la requête de poursuite.
    continuation = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        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 :

  • Poursuivez la conversation : renvoyez la réponse mise en pause telle quelle dans une requête ultérieure pour permettre à Claude de poursuivre son tour.
  • Préservez l’état des outils : incluez les mêmes outils dans la requête de continuation. Un tour mis en pause peut se terminer par un bloc server_tool_use dont l’outil ne s’est pas encore exécuté, et l’API renvoie une erreur de validation si cet outil est absent de la continuation.
  • Conservez le conteneur : si la réponse inclut un container, comme c’est le cas avec l’outil d’exécution de code, renvoyez son ID dans la requête de continuation. Sans lui, la requête s’exécute dans un nouveau conteneur, et les fichiers créés plus tôt dans le tour sont perdus.
  • Répétez si nécessaire : un tour poursuivi peut être mis en pause à nouveau. Vérifiez stop_reason sur chaque réponse et poursuivez jusqu’à obtenir un motif d’arrêt différent, en plafonnant le nombre de continuations comme vous le feriez pour toute boucle de nouvelle tentative. Conservez chaque réponse mise en pause dans messages, dans l’ordre. Une continuation ne contient que le nouveau contenu, de sorte qu’une requête qui omet une réponse mise en pause antérieure perd ce travail et peut renvoyer une erreur 400.

Pour les autres valeurs de stop_reason et les modèles de gestion généraux, consultez Motifs d’arrêt et repli.

Mêler outils serveur et outils client dans un même tour

Claude peut appeler un outil serveur et un outil client dans le même groupe d’appels d’outils parallèles, par exemple web_fetch avec un outil défini par l’utilisateur. Un outil client est tout outil que votre code exécute et qui produit un bloc tool_use, qu’il soit défini par l’utilisateur ou qu’il s’agisse d’un outil client à schéma Anthropic tel que l’outil Bash. Dans ce cas, l’API n’exécute pas l’outil serveur. Elle renvoie immédiatement une réponse afin que vous puissiez d’abord exécuter l’outil client :

  • stop_reason vaut "tool_use", et non "pause_turn".
  • content contient le bloc server_tool_use et le bloc tool_use client, mais aucun bloc de résultat pour l’outil serveur : cet appel n’est pas terminé.
  • Il n’y a aucun autre marqueur. Détectez cet état en recherchant un bloc server_tool_use dont l’id n’a pas de bloc de résultat correspondant dans la réponse. Un bloc mcp_tool_use provenant du connecteur MCP se comporte de la même manière. Les appels d’outils serveur qui ont déjà leur bloc de résultat dans la même réponse sont terminés et ne nécessitent rien de votre part.
{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "text",
      "text": "I'll fetch the article and check your system at the same time."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_fetch",
      "input": { "url": "https://example.com/article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

Pour poursuivre le tour, exécutez les outils client et envoyez un message utilisateur dont le contenu se compose uniquement des blocs tool_result, un pour chaque bloc tool_use de cette réponse. Conservez le même tableau tools : une requête de reprise qui ne définit plus l’outil serveur en attente échoue avec une erreur 400 dont le message se termine par but no `web_fetch` tool was provided.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

L’API rattache vos résultats au tour de l’assistant encore ouvert, exécute l’outil serveur différé (ou, pour une exécution de code en pause, la reprend), puis laisse Claude continuer. Pour un outil serveur appelé directement par Claude, la réponse suivante commence par le bloc de résultat qui répond à l’id du server_tool_use de la réponse précédente, suivi du contenu nouvellement généré et d’une nouvelle stop_reason :

{
  "stop_reason": "end_turn",
  "content": [
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          }
        }
      }
    },
    {
      "type": "text",
      "text": "The article argues that... and your machine is running Linux..."
    }
  ]
}

Un bloc server_tool_use et son bloc de résultat s’apparient par tool_use_id, et non par position : dans ce flux, ils arrivent dans deux réponses différentes, et le bloc server_tool_use n’est pas répété dans la seconde. Lors des requêtes ultérieures, conservez l’intégralité de l’échange dans votre tableau messages, dans l’ordre : la première réponse en tant que message assistant, le message utilisateur tool_result, puis la réponse suivante en tant qu’autre message assistant, de la même manière que vous accumulez tout autre échange d’utilisation d’outils.

En quoi cela diffère de pause_turn : une réponse pause_turn peut également se terminer par un bloc server_tool_use qui ne s’est pas exécuté, mais elle ne laisse jamais un bloc tool_use client en attente de votre part ; vous la poursuivez donc en renvoyant le contenu de l’assistant tel quel. Une réponse qui laisse un bloc tool_use client en attente de votre part n’a jamais un stop_reason de pause_turn : lorsque Claude s’arrête pour appeler vos outils, stop_reason vaut tool_use, et vous la poursuivez en renvoyant la réponse avec un nouveau message utilisateur qui contient les blocs tool_result client. Dans les deux cas, l’API exécute l’outil serveur en attente au début de la requête suivante.

L’exemple suivant active la récupération web avec un outil run_command défini par l’utilisateur et gère la réponse mixte :

client = anthropic.Anthropic()

tools = [
    {"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
    {
        "name": "run_command",
        "description": "Run a shell command on this computer and return its output.",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"],
        },
    },
]
messages = [
    {
        "role": "user",
        "content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
    }
]

response = client.messages.create(
    model="claude-opus-5-5", max_tokens=4096, tools=tools, messages=messages
)

tool_results = [
    {
        "type": "tool_result",
        "tool_use_id": block.id,
        # Exécutez votre outil ici. Cet exemple renvoie une chaîne fixe.
        "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
    }
    for block in response.content
    if block.type == "tool_use"
]

if response.stop_reason == "tool_use" and tool_results:
    # Un bloc server_tool_use sans bloc de résultat dans cette réponse n'est pas terminé ; son résultat arrive dans une réponse ultérieure.
    # Renvoyez uniquement les blocs tool_result client, avec les mêmes outils.
    continuation = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        tools=tools,
        messages=[
            *messages,
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results},
        ],
    )
    # Si un web_fetch a été différé, il s'exécute lors de cette requête et son
    # web_fetch_tool_result est le premier bloc de continuation.content.
    print(continuation)
else:
    print(response)

Ce code est également correct lorsque Claude ne mélange pas les deux types d’appels. Un tour ne comportant que des blocs tool_use client emprunte le même chemin de poursuite. Un tour ne comportant que des appels d’outils serveur ne nécessite aucun bloc tool_result client de votre part, car ses blocs de résultat sont normalement déjà présents. Si ce tour revient suspendu, par exemple sous forme de réponse pause_turn, renvoyez-le plutôt tel quel.

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 à la ZDR (conservation zéro des données).

Les versions _20260209 et ultérieures avec filtrage dynamique ne sont pas éligibles au ZDR par défaut, car le filtrage dynamique repose en interne sur l’exécution de code.

Pour utiliser un outil serveur _20260209 ou ultérieur avec le 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 aux seuls appels directs, en contournant l’étape interne d’exécution de code.

allowed_callers contrôle la manière dont un outil peut être appelé : directement par Claude ("direct"), depuis un conteneur d’exécution de code (par exemple, "code_execution_20260120"), ou les deux. Les versions _20260209 des outils web utilisent par défaut uniquement l’appelant d’exécution de code ; les versions antérieures utilisent par défaut ["direct"]. Sur les modèles qui ne prennent pas en charge l’appel d’outils programmatique, ces versions nécessitent allowed_callers: ["direct"] ; sans cela, l’API renvoie une erreur de validation indiquant de le définir.

Filtrage de domaines

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. Tous deux sont des champs de l’objet outil :

{
  "type": "web_search_20250305",
  "name": "web_search",
  "allowed_domains": ["example.com", "docs.python.org"]
}

Lors de l’utilisation de filtres de domaines :

  • 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 restreignent les résultats à ce seul sous-domaine (docs.example.com ne renvoie que les résultats de ce sous-domaine, et non de example.com ou api.example.com).
  • Les sous-chemins sont pris en charge pour la recherche web et correspondent à tout ce qui suit le chemin (example.com/blog correspond à example.com/blog/post-1).
  • La récupération web ne fait correspondre que le domaine : une entrée qui inclut un chemin ne correspond jamais à une URL de récupération web.
  • Vous pouvez utiliser soit allowed_domains, soit blocked_domains, mais pas les deux dans la même requête.

Prise en charge des caractères génériques :

  • Les caractères génériques (*) ne sont pas autorisés dans le domaine lui-même, uniquement dans le chemin qui le suit.
  • Valide : example.com/*, example.com/*/articles
  • Invalide : *.example.com, ex*.com

Les formats de domaine invalides sont rejetés au moment de la requête avec une erreur 400 invalid_request_error.

Pour les listes de domaines et les paramètres de votre organisation dans les sessions Claude Managed Agents, consultez Restreindre les domaines de recherche web et de récupération web.

Filtrage dynamique avec exécution de code

Les versions _20260209 et ultérieures 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.

Streaming des événements d’outils serveur

Les événements d’outils serveur sont diffusés en « streaming » (flux continu) dans le cadre du flux normal de « server-sent events » (événements envoyés par le serveur), ou SSE. Un bloc server_tool_use que Claude appelle directement est diffusé comme un bloc tool_use client : un événement content_block_start suivi d’événements input_json_delta. Le bloc de résultat arrive complet dans un seul événement content_block_start, sans deltas.

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

Requêtes par lots

Tous les outils serveur prennent en charge le traitement par lots. Dans un lot, la boucle agentique s’exécute exactement comme pour les requêtes synchrones, avec une limite d’itérations par tour plus élevée. Si la boucle atteint cette limite, la réponse se termine avec stop_reason: "pause_turn" ; vous pouvez la poursuivre en soumettant une requête de suivi avec le contenu renvoyé. Consultez Outils serveur et boucle agentique pour plus de détails.

Les charges de travail par lots courantes incluent l’enrichissement d’un jeu de données avec des informations provenant du web, la vérification d’un grand ensemble de documents par rapport à des sources actuelles, et l’exécution de code d’analyse sur de nombreux fichiers.

Étapes suivantes

Corrigez les erreurs d’utilisation d’outils les plus courantes grâce à des tableaux de diagnostic symptôme-correction.

Recherchez sur le web et citez les résultats.

Récupérez et lisez le contenu d’URL spécifiques pour enrichir le contexte de Claude avec du contenu web en direct.

Exécutez du code Python et Bash dans un conteneur isolé pour analyser des données, générer des fichiers et itérer sur des solutions.

Découvrez et chargez des outils à la demande.

Cette page vous a-t-elle été utile ?