Outil d’utilisation de l’ordinateur

Claude peut interagir avec des environnements informatiques grâce à l’outil d’utilisation de l’ordinateur (« computer use »), qui fournit des capacités de capture d’écran et le contrôle de la souris et du clavier pour une interaction autonome avec le bureau.

L’outil d’utilisation de l’ordinateur est un « client toolset » (ensemble d’outils client) défini par Anthropic : une seule entrée {"type": "computer_toolset_20260801"} dans tools donne à Claude 17 outils membres tels que screenshot, left_click, type et zoom, et votre application exécute chaque appel dans un environnement que vous contrôlez. Il n’est actuellement pas disponible dans Claude Managed Agents. Les appels de Claude sont des blocs tool_use dont le name est le membre et qui portent "toolset_name": "computer", souvent plusieurs en un seul tour (une « batch action » (action groupée)).

Pour les tâches qui restent à l’intérieur de pages web, l’outil d’utilisation du navigateur est plus adapté : ses outils membres lisent la page elle-même et agissent sur elle, et il ne nécessite pas d’environnement de bureau complet.

Consultez Prise en charge de l’API pour connaître les modèles et les plateformes qui prennent en charge l’ensemble d’outils. Versions antérieures de l’outil répertorie l’en-tête bêta de chaque version antérieure ainsi que les modèles avec lesquels l’utiliser.

Considérations de sécurité

L’utilisation de l’ordinateur présente des risques uniques, distincts de ceux des fonctionnalités standard de l’API. Ces risques sont accrus lors d’interactions avec Internet.

Dans certaines circonstances, Claude suit des commandes trouvées dans le contenu même lorsqu’elles entrent en conflit avec vos instructions. Par exemple, des instructions figurant sur des pages web ou contenues dans des images peuvent prendre le pas sur vos instructions ou amener Claude à commettre des erreurs. Prenez des précautions pour isoler Claude des données et actions sensibles afin d’éviter les risques liés à la « prompt injection » (injection de prompt).

Anthropic a entraîné le modèle à résister à ces injections de prompt et a ajouté une couche de défense supplémentaire. Si vous utilisez l’outil d’utilisation de l’ordinateur, des classificateurs analysent automatiquement ce que renvoie l’outil, comme les captures d’écran, afin de signaler d’éventuelles injections de prompt. Lorsque ces classificateurs identifient une injection de prompt potentielle, ils orientent le modèle pour qu’il vérifie si l’instruction provient réellement de vous avant d’y donner suite.

Cette protection supplémentaire n’est pas idéale pour tous les cas d’utilisation (par exemple, les cas d’utilisation sans humain dans la boucle) ; si vous souhaitez donc la refuser et la désactiver, contactez le support. Les précautions énumérées précédemment restent importantes même avec ces classificateurs en place.

Informez les utilisateurs finaux des risques pertinents et obtenez leur consentement avant d’activer l’utilisation de l’ordinateur dans vos propres produits.

Démarrage rapide

Ajoutez l’ensemble d’outils d’utilisation de l’ordinateur au tableau tools d’une requête de l’API MessagesAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. sous la forme {"type": "computer_toolset_20260801"}. La requête ne nécessite aucun en-tête bêta. Cet exemple déclare également l’outil d’éditeur de texte et l’outil bash, que Claude utilise généralement en complément de l’utilisation de l’ordinateur :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
)
print(response)

Lorsque Claude agit sur le bureau, la réponse a un stop_reason égal à tool_use et contient un ou plusieurs blocs tool_use de membres, chacun nommant un outil membre et portant "toolset_name": "computer". Au milieu de cette tâche, après que Claude a reçu une capture d’écran du bureau, une réponse pourrait ressembler à ceci :

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Votre application exécute chaque appel dans l’ordre dans votre propre environnement, renvoie un bloc tool_result pour chaque bloc tool_use, puis appelle à nouveau l’API ; Fonctionnement de l’utilisation de l’ordinateur décrit cette boucle, et le reste de cette page montre comment l’implémenter.

Fonctionnement de l’utilisation de l’ordinateur

1. 1

   Fournir à Claude l’outil d’utilisation de l’ordinateur et un prompt utilisateur

   • Ajoutez l’ensemble d’outils d’utilisation de l’ordinateur (et éventuellement d’autres outils) au tableau tools de votre requête API.
   • Incluez un prompt utilisateur qui nécessite une interaction avec le bureau, par exemple : « Enregistre une image de chat sur mon bureau. »
2. 2

   Claude répond avec des appels d’outils membres

   • Claude évalue si agir sur le bureau peut aider à répondre à la requête de l’utilisateur.
   • Si c’est le cas, Claude répond avec un ou plusieurs blocs tool_use de membres, tels que screenshot, left_click ou type, chacun portant "toolset_name": "computer". Une réponse contenant plusieurs de ces blocs est une action groupée.
   • La réponse de l’API a un stop_reason égal à tool_use, ce qui signale une demande d’utilisation d’outils.
3. 3

   Exécuter les appels dans l’ordre et renvoyer les résultats

   • Parcourez chaque bloc tool_use de la réponse, dans l’ordre. Pour chacun, effectuez la répartition selon le name du membre conjointement avec toolset_name, et réalisez cette action avec l’input du bloc sur votre conteneur ou votre machine virtuelle.
   • Poursuivez la conversation avec un nouveau message user contenant un bloc tool_result pour chaque bloc tool_use, associé par tool_use_id et reprenant chacun "toolset_name": "computer". Renvoyez une image pour screenshot et zoom ; un texte court tel que OK suffit pour les autres actions.
   • Si une action échoue, renvoyez is_error: true pour ce bloc et répondez au reste du lot comme décrit dans Actions groupées.
4. 4

   Claude continue jusqu’à ce que la tâche soit terminée

   • Claude analyse les résultats des outils pour déterminer si d’autres actions sont nécessaires ou si la tâche est terminée.
   • Si Claude détermine que d’autres actions sont nécessaires, il répond avec un autre stop_reason tool_use ; revenez à l’étape 3.
   • Sinon, il renvoie une réponse textuelle à l’utilisateur.

Les étapes 3 et 4, répétées sans intervention de l’utilisateur, forment l’« agent loop » (boucle d’agent) : Claude répond avec une demande d’utilisation d’outils, et votre application répond à Claude avec les résultats de l’évaluation de cette demande.

Actions groupées

Claude peut planifier une courte séquence d’actions, par exemple cliquer, saisir du texte, puis prendre une capture d’écran, et les renvoyer ensemble dans une seule réponse. C’est ce qu’on appelle une action groupée ; elle utilise la même forme de réponse que l’utilisation d’outils en parallèle, à une différence près : vous exécutez les blocs dans l’ordre plutôt que simultanément.

Une réponse avec un lot de trois actions ressemble à ceci :

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

Renvoyez un bloc tool_result pour chaque bloc tool_use, associé par tool_use_id, tous dans le message user suivant. Chaque résultat pour un outil membre doit porter "toolset_name": "computer" ; un résultat qui l’omet, ou qui nomme un ensemble d’outils différent de celui de son bloc tool_use, est rejeté. Seuls les résultats de screenshot et zoom nécessitent une image ; pour les autres membres, un court accusé de réception textuel tel que OK suffit (cursor_position renvoie les coordonnées sous forme de texte) :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

Exécutez les blocs dans l’ordre et arrêtez-vous au premier échec. Les actions ultérieures d’un lot dépendent généralement des précédentes : dans cet exemple, le type saisit du texte dans l’élément auquel le clic précédent a donné le focus. Exécutez les blocs séquentiellement dans l’ordre où ils apparaissent dans content, et si l’un d’eux échoue, n’exécutez pas les suivants. Chaque bloc tool_use a tout de même besoin d’un tool_result ; répondez donc au lot comme suit :

• Pour chaque action réussie, renvoyez son résultat normal.
• Pour l’action qui a échoué, renvoyez is_error: true avec une description textuelle de ce qui s’est mal passé.
• Pour chaque action ultérieure du lot, renvoyez is_error: true avec exactement ce texte (l’outil d’utilisation du navigateur utilise son propre texte d’arrêt) :

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

Claude lit alors quelles actions ont réussi, laquelle a échoué et lesquelles ont été ignorées, puis replanifie lors de son tour suivant. Une requête qui laisse un bloc tool_use du lot sans réponse est rejetée avec une invalid_request_error ; une boucle d’agent qui ne lit que le premier bloc échoue donc lors de son appel suivant. Si votre application demande à un humain de confirmer les actions lourdes de conséquences, effectuez cette vérification avant l’exécution de chaque bloc, car un lot peut accomplir une action en plusieurs étapes en un seul tour.

Claude termine généralement un lot par screenshot afin d’observer le résultat avant de déterminer la suite. Lorsqu’un lot ne se termine pas par une capture d’écran, votre application peut joindre une capture d’écran sous forme de bloc image supplémentaire au dernier résultat du lot, afin que Claude reçoive toujours l’état actuel de l’écran, ce qui économise un aller-retour par rapport à l’attente d’une demande de Claude. Vous pouvez également demander à Claude, via le prompt, de terminer chaque lot par une capture d’écran (consultez Optimiser les performances du modèle avec le prompting).

L’environnement informatique

L’utilisation de l’ordinateur nécessite un environnement informatique isolé (« sandbox ») dans lequel Claude peut interagir en toute sécurité avec des applications et le web. Cet environnement comprend :

1. Affichage virtuel : un serveur d’affichage X11 virtuel (utilisant Xvfb) qui effectue le rendu de l’interface de bureau que Claude reçoit sous forme de captures d’écran et contrôle par des actions de souris et de clavier.

2. Environnement de bureau : une interface légère avec un gestionnaire de fenêtres (Mutter) et un panneau (Tint2) fonctionnant sous Linux, qui fournit une interface graphique cohérente avec laquelle Claude peut interagir.

3. Applications : des applications Linux préinstallées telles que Firefox, LibreOffice, des éditeurs de texte et des gestionnaires de fichiers que Claude peut utiliser pour accomplir des tâches.

4. Implémentations des outils : du code d’intégration qui traduit les demandes d’outils abstraites de Claude (comme « déplacer la souris » ou « prendre une capture d’écran ») en opérations réelles dans l’environnement virtuel.

5. Boucle d’agent : un programme qui gère la communication entre Claude et l’environnement, en envoyant les actions de Claude à l’environnement et en renvoyant les résultats (captures d’écran, sorties de commandes) à Claude.

Lorsque vous utilisez l’utilisation de l’ordinateur, Claude ne se connecte pas directement à cet environnement. À la place, votre application :

1. Reçoit les demandes d’utilisation d’outils de Claude.
2. Les traduit en actions dans votre environnement informatique.
3. Capture les résultats (comme les captures d’écran et les sorties de commandes).
4. Renvoie ces résultats à Claude.

Pour des raisons de sécurité et d’isolation, l’implémentation de référence exécute tout cela à l’intérieur d’un conteneur Docker avec des mappages de ports appropriés pour visualiser l’environnement et interagir avec lui.

Comment implémenter l’utilisation de l’ordinateur

Vous mettez à niveau une intégration computer_20251124 existante ? Commencez par Migrer depuis computer_20251124 ; le reste de cette section s’applique aussi bien aux nouvelles intégrations qu’aux intégrations migrées.

Comprendre la boucle d’agent

Le cœur de l’utilisation de l’ordinateur est la « boucle d’agent » : un cycle dans lequel Claude demande des actions d’outils, et votre application les exécute et renvoie les résultats à Claude. La boucle utilise le client que vous avez créé dans le Démarrage rapide, un tableau tools qui ne déclare que l’ensemble d’outils d’utilisation de l’ordinateur, et la fonction utilitaire de traitement des appels d’outils décrite sous Implémenter l’outil d’utilisation de l’ordinateur. Si vous déclarez également d’autres outils, comme les outils bash et d’éditeur de texte du Démarrage rapide, répartissez leurs blocs tool_use dans la même passe ; la fonction utilitaire ne répond qu’aux appels de membres de l’utilisation de l’ordinateur, et la boucle considère qu’un tour sans aucun appel traité est terminé. Voici un exemple simplifié :

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # Ajouter la réponse de Claude à l'historique de la conversation.
        messages.append({"role": "assistant", "content": response.content})

        # Exécuter les actions demandées par Claude, dans l'ordre, et collecter les résultats.
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Renvoyer tous les résultats à Claude dans un seul message utilisateur.
        messages.append({"role": "user", "content": tool_results})

    return messages

La boucle se poursuit jusqu’à ce que Claude réponde sans demander d’outils (tâche terminée) ou que la limite maximale d’itérations soit atteinte. Cette protection évite d’éventuelles boucles infinies susceptibles d’entraîner des coûts d’API inattendus.

Optimiser les performances du modèle avec le prompting

1. Spécifiez des tâches simples et bien définies, et fournissez des instructions explicites pour chaque étape.
2. Claude agit parfois comme si ses actions avaient réussi sans en vérifier explicitement les résultats. Pour éviter cela, vous pouvez donner à Claude le prompt suivant : After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, try again. Only when you confirm a step was executed correctly should you move on to the next one.
3. Certains éléments d’interface (comme les listes déroulantes et les barres de défilement) peuvent être difficiles à manipuler pour Claude à l’aide de mouvements de souris. Si vous rencontrez ce problème, essayez de demander au modèle d’utiliser des raccourcis clavier.
4. Pour les tâches répétables ou les interactions avec l’interface, incluez dans votre prompt des exemples de captures d’écran et d’appels d’outils ayant abouti.
5. Si vous avez besoin que le modèle se connecte, fournissez-lui le nom d’utilisateur et le mot de passe dans votre prompt, à l’intérieur de balises XML telles que <robot_credentials>. Utiliser l’utilisation de l’ordinateur dans des applications nécessitant une connexion augmente le risque de mauvais résultats dus à l’injection de prompt. Consultez Atténuer les jailbreaks et les injections de prompt avant de fournir au modèle des identifiants de connexion.
6. Lors de la construction du tableau content d’un tour utilisateur, placez le texte de l’instruction avant l’image de la capture d’écran. Fournir la description de la cible avant le traitement de l’image améliore la précision des clics.
7. Claude utilise l’action zoom pour inspecter une région en pleine résolution lorsqu’on l’interroge sur du petit texte ou des éléments d’interface spécifiques qui ne sont pas lisibles à la résolution par défaut de la capture d’écran, comme les noms de fichiers dans une barre latérale, les titres d’onglets, le texte de la barre d’état, les numéros de ligne ou les libellés de boutons. Si Claude ne zoome pas lorsque vous vous y attendez, posez une question sur une région ou un élément spécifique plutôt que sur l’écran dans son ensemble.
8. Si vous souhaitez que chaque action groupée se termine par une capture d’écran, indiquez-le dans l’invite système, par exemple : End each group of actions with a screenshot so you can verify the result before continuing.

Invites système

Lorsque vous incluez l’outil d’utilisation de l’ordinateur dans une requête, l’API génère une invite système spécifique à l’utilisation de l’ordinateur. Elle est similaire à l’invite système d’utilisation d’outils, mais commence par :

You have access to a set of functions you can use to answer the user’s question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

Comme pour l’utilisation d’outils classique, le paramètre system fourni par l’utilisateur est toujours respecté et utilisé dans la construction de l’invite système combinée.

Actions disponibles

Chaque action est un outil membre de l’ensemble d’outils d’utilisation de l’ordinateur : Claude nomme le membre dans un bloc tool_use qui porte "toolset_name": "computer", et l’input du bloc ne contient que les paramètres de ce membre, sans champ action. L’ensemble d’outils comporte 17 outils membres :

Gardez les points suivants à l’esprit lors de l’implémentation des membres :

• Les coordonnées sont exprimées en pixels de capture d’écran. Chaque valeur coordinate, start_coordinate et region, ainsi que la position indiquée par cursor_position, se situe dans l’espace de pixels des captures d’écran de l’affichage complet que vous renvoyez, avec l’origine en haut à gauche. Les images de zoom ne changent rien à cela : après un zoom, Claude exprime toujours les coordonnées dans l’espace de la capture d’écran complète, jamais par rapport à l’image zoomée. Si vous réduisez les captures d’écran avant de les renvoyer, remettez à l’échelle les coordonnées de Claude avant de les appliquer à l’affichage réel (consultez Dimensionner les captures d’écran pour respecter les limites d’image).
• Tous les membres sont activés par défaut, y compris zoom. Si votre environnement ne peut pas produire d’images de zoom, retirez le membre avec configs (consultez Paramètres de l’outil) plutôt que de le laisser activé et de renvoyer des erreurs. Si Claude appelle un membre que vous avez retiré ou que vous n’implémentez pas, renvoyez un tool_result avec is_error: true pour ce bloc.
• Effectuez la répartition selon la paire (toolset_name, name). C’est toolset_name qui identifie un bloc comme une action sur l’ordinateur : un outil personnalisé de la même requête peut partager le nom d’un membre, et une version ultérieure de l’ensemble d’outils peut ajouter des membres (consultez Ensembles d’outils client).

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

Paramètres de l’outil

L’entrée de l’ensemble d’outils dans le tableau tools accepte quatre paramètres ; les règles qu’ils partagent avec l’ensemble d’outils d’utilisation du navigateur sont énumérées sous Ensembles d’outils client.

Par exemple, cette entrée retire zoom pour un environnement qui ne l’implémente pas et définit un point d’arrêt de cache au niveau de la définition de l’ensemble d’outils :

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

Si votre boucle d’agent ne peut exécuter qu’une seule action par aller-retour, définissez disable_parallel_tool_use sur true dans tool_choice ; Claude renvoie alors au plus un bloc tool_use de membre par tour (consultez Désactiver l’utilisation d’outils en parallèle).

L’entrée rejette ces paramètres issus des versions d’outil antérieures, et une requête qui inclut l’un d’eux renvoie une invalid_request_error :

• name : les noms des membres sont fixés par la version de l’ensemble d’outils.
• display_width_px, display_height_px et display_number : les coordonnées sont toujours exprimées dans l’espace de pixels des captures d’écran que vous renvoyez.
• enable_zoom : zoom est un outil membre que vous contrôlez via configs.

L’entrée ne peut pas non plus être déclarée dans la même requête qu’une entrée computer_20251124 ou qu’un autre outil nommé computer. Pour strict, input_examples, l’emplacement de defer_loading, tool_choice, le streaming et les restrictions d’appelants, consultez Ensembles d’outils client.

Combinaison avec la réflexion

Pour combiner l’utilisation de l’ordinateur avec la réflexion, consultez Réflexion.

Enrichir l’utilisation de l’ordinateur avec d’autres outils

Pour ajouter d’autres outils en complément de l’utilisation de l’ordinateur, incluez-les dans le même tableau tools. La section Démarrage rapide illustre ce modèle avec l’outil bash et l’outil d’éditeur de texte. Vous pouvez ajouter vos propres définitions d’outils personnalisés de la même manière.

Pour les tâches qui restent à l’intérieur de pages web, vous pouvez également déclarer l’outil d’utilisation du navigateur dans la même requête. Les deux ensembles d’outils fonctionnent indépendamment, chacun dans son propre repère de coordonnées. La valeur toolset_name permet de distinguer les appels à des membres qui partagent un nom, comme screenshot ou key.

Créer un environnement personnalisé d’utilisation de l’ordinateur

L’implémentation de référence est destinée à vous aider à démarrer avec l’utilisation de l’ordinateur. Elle inclut tous les composants nécessaires pour que Claude utilise un ordinateur. Toutefois, vous pouvez créer votre propre environnement d’utilisation de l’ordinateur adapté à vos besoins. Vous avez besoin de :

• Un environnement virtualisé ou conteneurisé adapté à l’utilisation de l’ordinateur avec Claude
• Une implémentation des actions de l’outil d’utilisation de l’ordinateur
• Une boucle d’agent qui interagit avec l’API Claude et exécute les résultats tool_use à l’aide de vos implémentations d’outils
• Une API ou une interface utilisateur qui permet une saisie de l’utilisateur pour démarrer la boucle d’agent

Implémenter l’outil d’utilisation de l’ordinateur

L’outil d’utilisation de l’ordinateur est implémenté comme un outil sans schéma. Lorsque vous utilisez cet outil, vous n’avez pas besoin de fournir un schéma d’entrée comme pour les autres outils ; le schéma est intégré au modèle de Claude et ne peut pas être modifié.

1. 1

   Configurer votre environnement informatique

   Créez un affichage virtuel ou connectez-vous à un affichage existant avec lequel Claude interagit. Cela implique généralement la configuration de Xvfb (X Virtual Framebuffer) ou d’une technologie similaire.

2. 2

   Implémenter les gestionnaires d’actions

   Créez des fonctions pour gérer chaque type d’action que Claude pourrait demander :

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # Données d'image factices ; un exécuteur réel capture l'écran et renvoie les octets PNG.
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot répond avec un bloc image plutôt que du texte : renvoyer la liste de contenu du résultat.
       return [
           {
               "type": "image",
               "source": {
                   "type": "base64",
                   "media_type": "image/png",
                   "data": PLACEHOLDER_PNG,
               },
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate est facultatif ; sans lui, cliquer là où se trouve déjà le curseur.
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # Gérer les autres actions selon les besoins.
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Traiter les appels d’outils de Claude

   Extrayez et exécutez les appels d’outils à partir des réponses de Claude :

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # Seul le jeu d'outils computer est déclaré ; routez ici les autres outils si vous en ajoutez.
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # Une chaîne, ou une liste de blocs de contenu tels que l'image de capture d'écran.
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   Implémenter la boucle d’agent

   Enveloppez les deux étapes précédentes dans une boucle qui renvoie les résultats et se répète jusqu’à ce que Claude ne renvoie plus d’appels d’outils membres ; Comprendre la boucle d’agent présente cette boucle.

Gérer les erreurs

Signalez une action échouée à Claude sous la forme d’un tool_result avec is_error: true et une courte description, et incluez "toolset_name": "computer" comme pour tout autre résultat de membre. Si l’action échouée faisait partie d’une action groupée, répondez aux blocs restants du lot avec le texte d’arrêt indiqué dans cette section au lieu de les exécuter.

Par exemple, lorsque la capture d’écran échoue :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

Utilisez la même forme pour les coordonnées situées en dehors des limites de l’affichage et pour les actions qui ne parviennent pas à s’exécuter, avec un message indiquant ce qui s’est mal passé.

Dimensionner les captures d’écran pour respecter les limites d’image

Les captures d’écran et les images de zoom que vous renvoyez à l’ensemble d’outils d’utilisation de l’ordinateur doivent déjà respecter les limites de taille d’image de votre modèle : l’ensemble d’outils ne prend aucune dimension d’affichage et l’API ne réduit pas la taille à votre place, de sorte qu’une image tool_result surdimensionnée est rejetée avec une erreur de validation. Comme Claude renvoie des coordonnées dans l’espace de pixels de l’image qu’il reçoit, conservez le facteur d’échelle que vous avez utilisé afin de pouvoir reconvertir ces coordonnées vers votre écran.

Si votre écran dépasse la limite, redimensionnez chaque capture d’écran avant de la renvoyer et remettez à l’échelle les coordonnées renvoyées par Claude vers l’espace de l’écran d’origine. Comme l’ensemble d’outils ne prend aucune dimension d’affichage, le redimensionnement et la mise à l’échelle des coordonnées dans le code de votre application suffisent :

import math

screen_width, screen_height = 1512, 982


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# Lors de la capture d'écran
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Redimensionner l'image aux dimensions mises à l'échelle avant de l'envoyer à Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# Lors du traitement des coordonnées de Claude, les remettre à l'échelle d'origine
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Lorsque vous choisissez une résolution d’affichage et renvoyez des captures d’écran :

• Pour les tâches de bureau générales, utilisez 1024x768 ou 1280x720 ; pour les applications web, utilisez 1280x800 ou 1366x768.
• Évitez les résolutions supérieures à 1920x1080 pour prévenir les problèmes de performance.
• Encodez les captures d’écran en PNG ou JPEG base64, et envisagez de compresser les captures d’écran volumineuses pour améliorer les performances.
• Incluez les métadonnées pertinentes telles que l’horodatage ou l’état de l’affichage.
• Si vous utilisez des résolutions plus élevées, assurez-vous que les coordonnées sont mises à l’échelle avec précision.

Gérer l’historique des captures d’écran

Les longues boucles d’agent accumulent rapidement les captures d’écran (environ 1 000 à 1 800 tokens d’entrée chacune). Les limites de requête de l’API s’appliquent également. Dès qu’une seule requête contient plus de 20 images, chaque image qu’elle contient est soumise à une limite plus stricte par côté. Une boucle qui conserve son historique de captures d’écran atteint ce nombre en quelques dizaines de tours ; redimensionnez donc chaque capture d’écran pour rester sous cette limite, ou supprimez les captures d’écran plus anciennes pour en conserver 20 ou moins dans la requête.

Pour que la « prompt caching » (mise en cache des prompts) reste efficace tout en limitant le contexte :

• Placez un point d’arrêt cache_control après l’invite système et les définitions d’outils, et jusqu’à trois autres sur le dernier bloc tool_result de chacun des tours les plus récents, en les faisant avancer à chaque tour. Au sein d’une action groupée, les marqueurs placés sur plusieurs blocs agissent comme un seul point d’arrêt, mais chacun compte tout de même dans la limite de quatre ; n’en utilisez donc qu’un seul au maximum par tour.
• Supprimez les anciennes captures d’écran par lots, et non une à chaque tour. Supprimer une capture d’écran à chaque tour modifie le préfixe à chaque tour et invalide le cache. Une valeur par défaut raisonnable consiste à conserver les trois dernières captures d’écran et à effectuer la suppression tous les 25 tours, afin que le préfixe reste identique octet par octet entre deux suppressions ; si vos captures d’écran dépassent la limite plus stricte, choisissez un intervalle qui maintient chaque requête à 20 images ou moins.
• Sur Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5, évitez d’élaguer côté client : retirer une capture d’écran antérieure d’une requête invalide tous les blocs de réflexion ultérieurs dans cette requête et dans toutes les requêtes suivantes. Redimensionnez plutôt les captures d’écran pour rester sous la limite plus stricte et utilisez l’effacement des résultats d’outils côté serveur pour retirer les anciennes du contexte. Si vous devez élaguer, conservez prefix_mismatch_behavior: "drop_block" défini à partir de ce moment ; après chaque élagage, Claude continue sans la réflexion produite depuis la capture d’écran élaguée, sur cette requête et sur toutes les suivantes. Sur Claude Sonnet 5.5 et Claude Haiku 5.5, block_binding fonctionne uniquement avec thinking: {"type": "adaptive"}. Avec tout autre paramètre de réflexion sur ces modèles, conservez un historique en ajout seul ou supprimez tous les blocs thinking et redacted_thinking situés après la capture d’écran élaguée.

Diagnostiquer les problèmes de clic

Si les clics manquent leurs cibles, la cause est généralement l’une des suivantes :

Suivre les bonnes pratiques d’implémentation

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging


def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

Migrer depuis computer_20251124

Une intégration computer_20251124 fonctionne sans modification sur les modèles répertoriés pour cette version dans Versions antérieures de l’outil. Mettez à niveau l’intégration avant de la migrer vers un modèle qui n’accepte pas computer_20251124, comme un modèle Claude 5.5 sur l’API Claude.

Pour effectuer la mise à niveau, apportez les modifications suivantes ensemble :

1. Supprimez l’en-tête bêta. Retirez anthropic-beta: computer-use-2025-11-24 de vos requêtes. Avec le SDK, supprimez betas et appelez l’API Messages via le client standard plutôt que via l’espace de noms bêta.
2. Modifiez l’entrée tools. Définissez type sur computer_toolset_20260801 et supprimez name, display_width_px, display_height_px, display_number et enable_zoom. L’ensemble d’outils rejette chacun de ces champs.
3. Choisissez de conserver ou non le zoom activé. Le zoom est activé par défaut sur l’ensemble d’outils, alors que enable_zoom vaut false par défaut. Si votre environnement n’implémente pas le zoom, ajoutez "configs": {"zoom": {"enabled": false}} pour conserver le comportement précédent ; sinon, implémentez-le (consultez Actions disponibles).
4. Traitez chaque bloc d’un tour. Mettez à jour votre boucle d’agent afin qu’elle parcoure chaque bloc tool_use d’une réponse plutôt que de lire uniquement le premier, et qu’elle répartisse le traitement selon le name du bloc combiné à toolset_name plutôt que selon input.action. Les entrées des membres ne contiennent plus de champ action ; les autres champs sont inchangés.
5. Exécutez les blocs dans l’ordre et utilisez le texte d’arrêt. Exécutez les blocs séquentiellement, arrêtez-vous au premier échec, et répondez aux blocs restants avec Not executed: an earlier computer action in this turn failed. comme décrit dans Actions groupées. Si votre boucle ne peut pas encore exécuter de lots, Paramètres de l’outil explique comment limiter Claude à une action par tour.
6. Renvoyez toolset_name dans les résultats. Ajoutez "toolset_name": "computer" à chaque tool_result qui répond à un appel de membre. Les résultats ne peuvent contenir que du contenu text et image.
7. Prenez en charge repeat sur key. Le membre key accepte un nombre repeat facultatif compris entre 1 et 100. Un gestionnaire qui ignore les champs non reconnus n’appuierait sur la touche qu’une seule fois ; faites donc en sorte que votre gestionnaire key respecte repeat.
8. Redimensionnez vous-même les captures d’écran. L’ensemble d’outils rejette une capture d’écran ou une image de zoom qui dépasse les limites d’image du modèle au lieu de la réduire. Redimensionnez l’image avant de la renvoyer et continuez à mettre à l’échelle les coordonnées comme décrit dans Dimensionner les captures d’écran pour respecter les limites d’image.
9. Supprimez les options non prises en charge. Déplacez tout defer_loading de l’entrée vers configs, avec la même valeur sur chaque membre activé. Les autres options non prises en charge sur les entrées d’ensemble d’outils sont répertoriées dans Ensembles d’outils client.

Voici l’entrée tools avant la modification, envoyée avec l’en-tête anthropic-beta: computer-use-2025-11-24 :

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

Voici l’entrée tools après la modification, envoyée sans en-tête bêta. L’objet configs maintient le zoom désactivé pour correspondre à l’entrée précédente, qui ne définit pas enable_zoom ; omettez entièrement configs pour accepter la valeur par défaut et laisser Claude utiliser le zoom :

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

La paire suivante montre un bloc tool_use avant et après la modification. Le nom de l’action passe de input.action à name, et le bloc reçoit toolset_name :

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

Versions antérieures de l’outil

Deux versions antérieures de l’outil « computer use » (utilisation de l’ordinateur) sont disponibles en bêta. Chacune nécessite son « beta header » (en-tête bêta) sur chaque requête, et leurs paramètres sont documentés dans la référence de l’API Messages bêtaAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir.. Avec le SDK, transmettez l’en-tête via betas et utilisez l’espace de noms bêta ; seul l’outil d’utilisation de l’ordinateur a besoin de l’en-tête, pas les outils bash ou éditeur de texte dans la même requête.

Sur Amazon Bedrock, Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5 acceptent également l’outil computer_20251124 avec l’en-tête bêta computer-use-2025-11-24.

Limitations

1. Latence : La latence de l’utilisation de l’ordinateur pour les interactions humain-IA peut être trop lente par rapport aux actions informatiques classiques dirigées par un humain. Concentrez-vous sur les cas d’usage où la vitesse n’est pas critique (par exemple, la collecte d’informations en arrière-plan, les tests logiciels automatisés) dans des environnements de confiance.
2. Précision et fiabilité de la vision par ordinateur : Claude peut commettre des erreurs ou halluciner lorsqu’il produit des coordonnées spécifiques en générant des actions. La sortie de réflexion résumée de Claude peut vous aider à comprendre le raisonnement du modèle et à identifier d’éventuels problèmes ; définissez display: "summarized" dans la configuration de réflexion, car les modèles qui prennent en charge l’ensemble d’outils omettent le texte de réflexion par défaut.
3. Précision et fiabilité de la sélection d’outils : Claude peut commettre des erreurs ou halluciner lors de la sélection d’outils en générant des actions, ou effectuer des actions inattendues pour résoudre des problèmes. De plus, la fiabilité peut être moindre lors de l’interaction avec des applications de niche ou avec plusieurs applications à la fois. Rédigez soigneusement vos prompts lorsque vous demandez des tâches complexes.
4. Fiabilité du défilement : L’action de défilement prend en charge le contrôle de la direction (haut, bas, gauche, droite) et une quantité spécifiée. Dans les applications où le défilement ne prend pas effet, des alternatives au clavier telles que Page Down peuvent aider.
5. Interaction avec les feuilles de calcul : Utilisez les actions de contrôle fin de la souris (left_mouse_down, left_mouse_up) et les combinaisons de touches de modification pour sélectionner des cellules individuelles. Les opérations complexes sur les feuilles de calcul peuvent encore nécessiter plusieurs tentatives.
6. Création de comptes et génération de contenu sur les plateformes sociales et de communication : Bien que Claude visite des sites web, sa capacité à créer des comptes, à générer et partager du contenu, ou à se livrer de toute autre manière à l’usurpation d’identité humaine sur les sites et plateformes de réseaux sociaux est limitée.
7. Vulnérabilités : Les jailbreaks et l’injection de prompts peuvent affecter l’utilisation de l’ordinateur comme ils peuvent affecter tout système d’IA de pointe, y compris via des instructions intégrées dans des pages web ou des images ; appliquez les précautions décrites dans Considérations de sécurité.
8. Actions inappropriées ou illégales : Conformément aux Conditions d’utilisation d’Anthropic, vous ne devez pas employer l’utilisation de l’ordinateur pour enfreindre une quelconque loi ou la Politique d’utilisation acceptable.

Examinez et vérifiez toujours attentivement les actions et les journaux d’utilisation de l’ordinateur de Claude. N’utilisez pas Claude pour des tâches exigeant une précision parfaite ou des informations utilisateur sensibles sans supervision humaine.

Conservation des données

L’utilisation de l’ordinateur est un outil côté client. Toutes les captures d’écran, actions de la souris, saisies au clavier et tous les fichiers impliqués dans une session sont capturés et stockés dans votre environnement, et non par Anthropic. Anthropic traite les images de captures d’écran et les demandes d’action en temps réel dans le cadre de l’appel API. La conservation de ces requêtes API est régie par API et conservation des données.

Étant donné que votre application contrôle où et comment les données d’utilisation de l’ordinateur sont stockées, l’utilisation de l’ordinateur est éligible à la ZDR.

Tarification

L’utilisation de l’ordinateur suit la tarification standard de l’utilisation d’outils. Lors de l’utilisation de l’outil d’utilisation de l’ordinateur :

Surcharge liée à la définition de l’ensemble d’outils : Déclarer computer_toolset_20260801 avec ses membres par défaut ajoute environ 4 500 tokens d’entrée à une requête (environ 4 590 sur Claude Sonnet 5 et environ 4 520 sur les autres modèles pris en charge), ce qui couvre les définitions des outils membres et l’invite système d’utilisation d’outils. Désactiver zoom avec configs supprime environ 410 de ces tokens. Le nombre exact pour une requête est indiqué dans le champ usage de la réponse, et vous pouvez l’estimer à l’avance avec le point de terminaison de comptage des tokens.

Versions antérieures de l’outil : Les chiffres suivants s’appliquent aux versions d’outil computer_20251124 et computer_20250124, et non à computer_toolset_20260801 :

• Surcharge de l’invite système : 466 à 499 tokens ajoutés à l’invite système
• Définition de l’outil : environ 735 tokens d’entrée par définition d’outil (mesuré avec computer_20250124)

Consommation de tokens supplémentaire :

• Captures d’écran et images de zoom renvoyées dans les résultats d’outils, facturées comme entrée d’image (voir la tarification de la vision)
• Résultats d’exécution des outils renvoyés à Claude

Étapes suivantes

Disponibilité