Outil d'utilisation de l'ordinateur

Claude peut interagir avec des environnements informatiques grâce à l'outil « computer use » (utilisation de l'ordinateur), 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, voir ensembles d'outils client : 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 par tour (une action groupée).

Pour les tâches qui restent à l'intérieur de pages web, l'outil d'utilisation du navigateur (« browser use tool ») est mieux adapté : ses outils membres lisent et agissent sur la page elle-même, et il ne nécessite pas un environnement de bureau complet.

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 de l'interaction avec Internet.

Dans certaines circonstances, Claude suivra des commandes trouvées dans le contenu même lorsqu'elles entrent en conflit avec vos instructions. Par exemple, des instructions présentes sur des pages web ou contenues dans des images peuvent supplanter 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 les outils d'utilisation de l'ordinateur, des classificateurs analyseront automatiquement ce que renvoient les outils, comme les captures d'écran, afin de signaler d'éventuelles injections de prompt. Lorsque ces classificateurs identifient une injection de prompt potentielle, ils orienteront automatiquement le modèle pour qu'il vérifie si l'instruction provient réellement de vous avant d'agir en conséquence.

Cette protection supplémentaire ne sera pas idéale pour tous les cas d'usage (par exemple, les cas d'usage sans humain dans la boucle) ; si vous souhaitez la désactiver, contactez le support. Les précautions ci-dessus 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 Messages 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'édition 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 membres, chacun nommant un outil membre et portant "toolset_name": "computer". Au cours de cette tâche, après que Claude a vu 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 par 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 demande de l'utilisateur.
   • Si c'est le cas, Claude répond avec un ou plusieurs blocs tool_use 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, signalant 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 en fonction du name du membre associé à 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 par bloc tool_use, associés par tool_use_id et reprenant chacun "toolset_name": "computer". Renvoyez une image pour screenshot et zoom ; un court texte 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 groupe 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 égal à tool_use et vous devez revenir à l'étape 3.
   • Sinon, il renvoie une réponse textuelle à l'utilisateur.

La répétition des étapes 3 et 4 sans intervention de l'utilisateur est appelée « agent loop » (boucle d'agent), c'est-à-dire que Claude répond par une demande d'utilisation d'outils et que 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 « batch action » (action groupée) ; elle utilise la même forme de réponse que l'utilisation d'outils en parallèle avec une différence : vous exécutez les blocs dans l'ordre plutôt que simultanément.

Une réponse contenant un groupe 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 d'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 groupe dépendent généralement des précédentes : le type de cet exemple saisit du texte dans l'élément que le clic précédent a sélectionné. Exécutez les blocs séquentiellement dans l'ordre où ils apparaissent dans content, et si l'un échoue, n'exécutez pas les suivants. Chaque bloc tool_use nécessite tout de même un tool_result, répondez donc au groupe comme suit :

• Pour chaque action qui a réussi, 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 groupe, 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 voit alors quelles actions ont réussi, laquelle a échoué et lesquelles ont été ignorées, puis replanifie à son tour suivant. Une requête qui laisse sans réponse un bloc tool_use du groupe est rejetée avec une invalid_request_error, de sorte qu'une boucle d'agent qui ne lit que le premier bloc échoue à son appel suivant. Si votre application demande à un humain de confirmer les actions à conséquences importantes, effectuez cette vérification avant l'exécution de chaque bloc, car un groupe peut accomplir une action en plusieurs étapes au sein d'un seul tour.

Claude termine généralement un groupe par screenshot afin de pouvoir observer le résultat avant de décider de la suite. Lorsqu'un groupe ne se termine pas ainsi, votre application peut joindre une capture d'écran sous forme de bloc image supplémentaire au dernier résultat du groupe afin que Claude voie 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 groupe par une capture d'écran (consultez Optimiser les performances du modèle grâce au 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 rend l'interface de bureau que Claude verra via des captures d'écran et contrôlera avec des actions de souris et de clavier.

2. Environnement de bureau : une interface légère avec gestionnaire de fenêtres (Mutter) et 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 (tels que 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 les 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, 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 déclare uniquement l'ensemble d'outils d'utilisation de l'ordinateur, et la fonction utilitaire de traitement des appels d'outils présentée sous Implémenter l'outil d'utilisation de l'ordinateur. Si vous déclarez également d'autres outils, comme les outils bash et d'édition 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 des membres de l'utilisation de l'ordinateur, et la boucle considère un tour sans appel traité comme 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. Ce garde-fou empêche les boucles infinies potentielles qui pourraient entraîner des coûts d'API inattendus.

Optimiser les performances du modèle grâce au prompting

1. Spécifiez des tâches simples et bien définies et fournissez des instructions explicites pour chaque étape.
2. Claude suppose parfois le résultat de ses actions sans vérifier explicitement leurs effets. 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. Explicitly show your thinking: "I have evaluated step X..." If not correct, 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 avec des 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 ou interactions d'interface répétables, incluez dans votre prompt des exemples de captures d'écran et d'appels d'outils ayant abouti à des résultats réussis.
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>. 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 des identifiants de connexion au modèle.
6. Lors de la construction du tableau content d'un tour utilisateur, placez le texte d'instruction avant l'image de 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 alors que 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 contient uniquement 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 les coordonnées de Claude à l'échelle 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 sur la paire (toolset_name, name). C'est toolset_name qui marque un bloc comme une action sur l'ordinateur : un outil personnalisé dans 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'elle partage avec l'ensemble d'outils d'utilisation du navigateur sont répertorié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 membre par tour (consultez Désactiver l'utilisation d'outils en parallèle).

L'entrée rejette les paramètres suivants issus des versions antérieures de l'outil, 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 : le 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, le placement de defer_loading, tool_choice, le streaming et les restrictions d'appelant, 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'édition 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, et les appels aux membres qui partagent un nom, comme screenshot ou key, sont distingués par toolset_name.

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

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. Cependant, vous pouvez créer votre propre environnement d'utilisation de l'ordinateur adapté à vos besoins. Vous aurez besoin :

• D'un environnement virtualisé ou conteneurisé adapté à l'utilisation de l'ordinateur avec Claude
• D'une implémentation des actions de l'outil d'utilisation de l'ordinateur
• D'une boucle d'agent qui interagit avec la Claude API et exécute les résultats tool_use à l'aide de vos implémentations d'outils
• D'une API ou d'une interface utilisateur permettant à l'utilisateur de lancer 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 interagira. Cela implique généralement de configurer Xvfb (X Virtual Framebuffer) ou 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

   

   # 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

   

   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

   Encapsulez 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 dans chaque langage.

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 groupe 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 les images pour vous, de sorte qu'une image tool_result trop grande est rejetée avec une erreur de validation. Comme Claude renvoie les coordonnées dans l'espace de pixels de l'image qu'il voit, conservez le facteur d'échelle que vous avez utilisé afin de pouvoir reconvertir ces coordonnées vers votre écran.

Si votre écran est plus grand que la limite, redimensionnez chaque capture d'écran avant de la renvoyer et remettez les coordonnées renvoyées par Claude à l'échelle de l'espace d'é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 sont tout ce dont vous avez besoin :

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 performances.
• 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 des 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 par côté plus stricte. Une boucle qui conserve son historique de captures d'écran atteint ce nombre en quelques dizaines de tours ; vous devez donc soit redimensionner chaque capture d'écran de sorte qu'aucun côté ne dépasse 2000 px, soit supprimer les captures d'écran plus anciennes pour en conserver 20 ou moins dans la requête.

Pour que le « 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. Utilisez-en donc un 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 2000 px sur l'un des côtés, choisissez un intervalle qui maintient chaque requête à 20 images ou moins.
• Sur Claude Fable 5.1 et Claude Opus 5.5, évitez la suppression côté client : retirer une capture d'écran antérieure invalide tous les blocs de réflexion ultérieurs dans chaque requête qui contient encore ces tours. Redimensionnez plutôt les captures d'écran à 2000 px ou moins par côté, et utilisez l'effacement des résultats d'outils côté serveur pour retirer les anciennes du contexte. Si vous devez effectuer une suppression, conservez prefix_mismatch_behavior: "drop_block" défini à partir de ce moment. Après chaque suppression, Claude continue sans la réflexion produite depuis la capture d'écran supprimée, sur cette requête et sur toutes les suivantes.

Diagnostiquer les problèmes de clic

Si les clics manquent leur cible, 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

La mise à niveau de computer_20251124 vers l'ensemble d'outils est facultative : les modèles répertoriés pour computer_20251124 dans Versions antérieures de l'outil continuent de l'accepter avec son en-tête bêta, de sorte qu'une intégration existante continue de fonctionner jusqu'à ce que vous la modifiiez. Les modèles Claude 5.5 et ultérieurs font exception sur la Claude API et Google Cloud : ils n'y acceptent que l'ensemble d'outils. Mettez à niveau une intégration avant de la faire passer à l'un d'entre eux. Sur Amazon Bedrock, Claude Opus 5.5 continue d'accepter computer_20251124. 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. Dans les SDK, supprimez le paramètre 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. Le toolset rejette chacun de ces champs.
3. Choisissez de garder ou non le zoom activé. Le zoom est activé par défaut sur le toolset, 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 (voir Actions disponibles).
4. Traitez chaque bloc d'un tour. Mettez à jour votre boucle d'agent pour itérer sur chaque bloc tool_use d'une réponse plutôt que de ne lire que le premier, et pour effectuer la répartition en fonction du name du bloc conjointement avec toolset_name au lieu de 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 par lot. 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 compteur repeat facultatif de 1 à 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. Le toolset 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 avant de renvoyer l'image 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 de toolset sont répertoriées sous Toolsets 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 antérieure, qui ne définit pas enable_zoom ; omettez entièrement configs pour accepter la valeur par défaut et laisser Claude zoomer :

{
  "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 gagne 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 d'utilisation de l'ordinateur restent disponibles en bêta pour les intégrations existantes, pour les modèles qui ne prennent pas en charge le toolset, et sur les plateformes où le toolset n'est pas actuellement disponible. Chacune nécessite son 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êta. Dans les SDK, transmettez l'en-tête via le paramètre betas et utilisez l'espace de noms bêta ; seul l'outil d'utilisation de l'ordinateur a besoin de l'en-tête, et non les outils bash ou éditeur de texte de la même requête.

Limitations

1. Latence : La « latency » (latence) actuelle de l'utilisation de l'ordinateur pour les interactions humain-IA peut être trop lente par rapport aux actions informatiques habituelles dirigées par un humain. Concentrez-vous sur les cas d'utilisation 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 les problèmes potentiels ; définissez display: "summarized" dans la configuration de la réflexion, car les modèles qui prennent en charge le toolset 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 entreprendre 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 médias 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 par le biais d'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 des lois 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 nécessitant une précision parfaite ou impliquant 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 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 au ZDR. Pour l'éligibilité au ZDR de toutes les fonctionnalités, consultez API et conservation des données.

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 du toolset : Déclarer computer_toolset_20260801 avec ses membres par défaut ajoute environ 4 500 tokens d'entrée à une requête (environ 4 520 sur Claude Fable 5, Claude Mythos 5, Claude Opus 5 et Claude Opus 4.8, et environ 4 590 sur Claude Sonnet 5), ce qui couvre les définitions des outils membres et le « system prompt » (invite système) de l'utilisation d'outils. Désactiver zoom avec configs supprime environ 410 de ces tokens. Le décompte 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

Compatibility