Outil de contrôle d'ordinateur

Claude peut interagir avec des environnements informatiques grâce à l'outil de contrôle d'ordinateur, qui offre des capacités de capture d'écran et un contrôle de la souris/clavier pour l'interaction autonome du bureau.

Aperçu

Le contrôle d'ordinateur est une fonctionnalité bêta qui permet à Claude d'interagir avec des environnements de bureau. Cet outil fournit :

• Capture d'écran : Voir ce qui s'affiche actuellement à l'écran
• Contrôle de la souris : Cliquer, glisser et déplacer le curseur
• Entrée au clavier : Taper du texte et utiliser les raccourcis clavier
• Automatisation du bureau : Interagir avec n'importe quelle application ou interface

Bien que le contrôle d'ordinateur puisse être augmenté avec d'autres outils comme bash et l'éditeur de texte pour des flux de travail d'automatisation plus complets, le contrôle d'ordinateur fait spécifiquement référence à la capacité de l'outil de contrôle d'ordinateur à voir et contrôler les environnements de bureau.

Compatibilité des modèles

Le contrôle d'ordinateur est disponible pour les modèles Claude suivants :

Considérations de sécurité

Le contrôle d'ordinateur est une fonctionnalité bêta avec des risques uniques distincts des fonctionnalités API standard. Ces risques sont amplifiés lors de l'interaction avec Internet.

Dans certaines circonstances, Claude suivra les commandes trouvées dans le contenu même si cela entre en conflit avec les instructions de l'utilisateur. Par exemple, les instructions Claude sur les pages Web ou contenues dans les images peuvent remplacer les instructions ou amener Claude à faire des erreurs. Nous suggérons de prendre des précautions pour isoler Claude des données et actions sensibles afin d'éviter les risques liés à l'injection de prompt.

Nous avons entraîné le modèle à résister à ces injections de prompt et avons ajouté une couche de défense supplémentaire. Si vous utilisez nos outils de contrôle d'ordinateur, nous exécuterons automatiquement des classificateurs sur vos prompts pour signaler les instances potentielles d'injections de prompt. Lorsque ces classificateurs identifient des injections de prompt potentielles dans les captures d'écran, ils orienteront automatiquement le modèle à demander une confirmation de l'utilisateur avant de procéder à l'action suivante. Nous reconnaissons que cette protection supplémentaire ne sera pas idéale pour tous les cas d'utilisation (par exemple, les cas d'utilisation sans humain dans la boucle), donc si vous souhaitez vous désabonner et l'éteindre, veuillez nous contacter.

Nous suggérons toujours de prendre des précautions pour isoler Claude des données et actions sensibles afin d'éviter les risques liés à l'injection de prompt.

Enfin, veuillez informer les utilisateurs finaux des risques pertinents et obtenir leur consentement avant d'activer le contrôle d'ordinateur dans vos propres produits.

Démarrage rapide

Voici comment commencer avec le contrôle d'ordinateur :

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",  # ou un autre modèle compatible
    max_tokens=1024,
    tools=[
        {
          "type": "computer_20251124",
          "name": "computer",
          "display_width_px": 1024,
          "display_height_px": 768,
          "display_number": 1,
        },
        {
          "type": "text_editor_20250728",
          "name": "str_replace_based_edit_tool"
        },
        {
          "type": "bash_20250124",
          "name": "bash"
        }
    ],
    messages=[{"role": "user", "content": "Enregistrer une image d'un chat sur mon bureau."}],
    betas=["computer-use-2025-11-24"]
)
print(response)

Comment fonctionne le contrôle d'ordinateur

Nous nous référons à la répétition des étapes 3 et 4 sans entrée utilisateur comme la « boucle d'agent » - c'est-à-dire Claude répondant avec une demande d'utilisation d'outil et votre application répondant à Claude avec les résultats de l'évaluation de cette demande.

L'environnement informatique

Le contrôle d'ordinateur nécessite un environnement informatique en bac à sable où Claude peut interagir en toute sécurité avec les applications et le Web. Cet environnement inclut :

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/clavier.

2. Environnement de bureau : Une interface utilisateur légère avec gestionnaire de fenêtres (Mutter) et panneau (Tint2) fonctionnant sur Linux, qui fournit une interface graphique cohérente pour que Claude interagisse.

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

4. Implémentations d'outils : Code d'intégration qui traduit les demandes d'outils abstraits 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, envoyant les actions de Claude à l'environnement et retournant les résultats (captures d'écran, sorties de commande) à Claude.

Lorsque vous utilisez le contrôle d'ordinateur, Claude ne se connecte pas directement à cet environnement. Au lieu de cela, votre application :

1. Reçoit les demandes d'utilisation d'outil de Claude
2. Les traduit en actions dans votre environnement informatique
3. Capture les résultats (captures d'écran, sorties de commande, etc.)
4. Retourne ces résultats à Claude

Pour la sécurité et l'isolation, l'implémentation de référence exécute tout cela à l'intérieur d'un conteneur Docker avec les mappages de port appropriés pour visualiser et interagir avec l'environnement.

Comment implémenter le contrôle d'ordinateur

Commencer avec notre implémentation de référence

Nous avons construit une implémentation de référence qui inclut tout ce dont vous avez besoin pour commencer rapidement avec le contrôle d'ordinateur :

• Un environnement conteneurisé adapté au contrôle d'ordinateur avec Claude
• Des implémentations des outils de contrôle d'ordinateur
• Une boucle d'agent qui interagit avec l'API Claude et exécute les outils de contrôle d'ordinateur
• Une interface Web pour interagir avec le conteneur, la boucle d'agent, et les outils.

Comprendre la boucle multi-agent

Le cœur du contrôle d'ordinateur est la « boucle d'agent » - un cycle où Claude demande des actions d'outil, votre application les exécute, et retourne les résultats à Claude. Voici un exemple simplifié :

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Ajouter une limite d'itération pour prévenir les boucles infinies
):
    """
    Une boucle d'agent simple pour les interactions de contrôle d'ordinateur Claude.

    Cette fonction gère l'aller-retour entre :
    1. Envoyer des messages utilisateur à Claude
    2. Claude demandant d'utiliser des outils
    3. Votre application exécutant ces outils
    4. Envoyer les résultats de l'outil à Claude
    """
    # Configurer les outils et les paramètres API
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # Configurer les outils - vous devriez déjà les avoir initialisés ailleurs
    tools = [
        {"type": f"computer_{tool_version}", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"}
    ]

    # Boucle d'agent principale (avec limite d'itération pour prévenir les coûts API incontrôlés)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Configurer le paramètre de réflexion optionnel (pour Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Appeler l'API Claude
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking
        )

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

        # Vérifier si Claude a utilisé des outils
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # Dans une application réelle, vous exécuteriez l'outil ici
                # Par exemple : result = run_tool(block.name, block.input)
                result = {"result": "Outil exécuté avec succès"}

                # Formater le résultat pour Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Si aucun outil n'a été utilisé, Claude a terminé - retourner les messages finaux
        if not tool_results:
            return messages

        # Ajouter les résultats de l'outil aux messages pour la prochaine itération avec Claude
        messages.append({"role": "user", "content": tool_results})

La boucle continue jusqu'à ce que Claude réponde sans demander d'outils (fin de tâche) ou que la limite d'itération maximale soit atteinte. Cette protection empêche les boucles infinies potentielles qui pourraient entraîner des coûts API inattendus.

Nous recommandons d'essayer l'implémentation de référence avant de lire le reste de cette documentation.

Optimiser les performances du modèle avec les invites

Voici quelques conseils sur comment obtenir les meilleures sorties de qualité :

1. Spécifier des tâches simples et bien définies et fournir des instructions explicites pour chaque étape.
2. Claude suppose parfois les résultats de ses actions sans vérifier explicitement leurs résultats. Pour éviter cela, vous pouvez inviter Claude avec Après chaque étape, prenez une capture d'écran et évaluez soigneusement si vous avez atteint le bon résultat. Montrez explicitement votre réflexion : « J'ai évalué l'étape X... » Si ce n'est pas correct, réessayez. Ce n'est que lorsque vous confirmez qu'une étape a été exécutée correctement que vous devriez passer à la suivante.
3. Certains éléments d'interface utilisateur (comme les listes déroulantes et les barres de défilement) pourraient être délicats pour Claude à manipuler en utilisant les mouvements de souris. Si vous rencontrez cela, essayez d'inviter le modèle à utiliser les raccourcis clavier.
4. Pour les tâches répétables ou les interactions d'interface utilisateur, incluez des captures d'écran d'exemple et des appels d'outil de résultats réussis dans votre invite.
5. Si vous avez besoin que le modèle se connecte, fournissez-lui le nom d'utilisateur et le mot de passe dans votre invite à l'intérieur de balises xml comme <robot_credentials>. L'utilisation du contrôle d'ordinateur dans les applications qui nécessitent une connexion augmente le risque de mauvais résultats en raison de l'injection de prompt. Veuillez consulter notre guide sur l'atténuation des injections de prompt avant de fournir au modèle les identifiants de connexion.

Invites système

Lorsqu'un des outils définis par Anthropic est demandé via l'API Claude, une invite système spécifique au contrôle d'ordinateur est générée. Elle est similaire à l'invite système d'utilisation d'outil mais commence par :

Vous avez accès à un ensemble de fonctions que vous pouvez utiliser pour répondre à la question de l'utilisateur. Cela inclut l'accès à un environnement informatique en bac à sable. Vous n'avez actuellement pas la capacité d'inspecter les fichiers ou d'interagir avec les ressources externes, sauf en invoquant les fonctions ci-dessous.

Comme avec l'utilisation régulière d'outil, le champ system_prompt fourni par l'utilisateur est toujours respecté et utilisé dans la construction de l'invite système combinée.

Actions disponibles

L'outil de contrôle d'ordinateur supporte ces actions :

Actions de base (toutes les versions)

• screenshot - Capturer l'affichage actuel
• left_click - Cliquer aux coordonnées [x, y]
• type - Taper une chaîne de texte
• key - Appuyer sur une touche ou une combinaison de touches (par exemple, « ctrl+s »)
• mouse_move - Déplacer le curseur aux coordonnées

Actions améliorées (computer_20250124) Disponible dans les modèles Claude 4 et Claude Sonnet 3.7 :

• scroll - Faire défiler dans n'importe quelle direction avec contrôle de la quantité
• left_click_drag - Cliquer et glisser entre les coordonnées
• right_click, middle_click - Boutons de souris supplémentaires
• double_click, triple_click - Clics multiples
• left_mouse_down, left_mouse_up - Contrôle fin des clics
• hold_key - Maintenir une touche enfoncée pendant une durée spécifiée (en secondes)
• wait - Pause entre les actions

Actions améliorées (computer_20251124) Disponible dans Claude Opus 4.6 et Claude Opus 4.5 :

• Toutes les actions de computer_20250124
• zoom - Afficher une région spécifique de l'écran à pleine résolution. Nécessite enable_zoom: true dans la définition de l'outil. Prend un paramètre region avec les coordonnées [x1, y1, x2, y2] définissant les coins supérieur gauche et inférieur droit de la zone à inspecter.

Paramètres de l'outil

Activer la capacité de réflexion dans les modèles Claude 4 et Claude Sonnet 3.7

Claude Sonnet 3.7 a introduit une nouvelle capacité de « réflexion » qui vous permet de voir le processus de raisonnement du modèle au fur et à mesure qu'il travaille sur des tâches complexes. Cette fonctionnalité vous aide à comprendre comment Claude aborde un problème et peut être particulièrement précieuse pour le débogage ou à des fins éducatives.

Pour activer la réflexion, ajoutez un paramètre thinking à votre demande API :

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

Le paramètre budget_tokens spécifie combien de jetons Claude peut utiliser pour la réflexion. Ceci est soustrait de votre budget global max_tokens.

Lorsque la réflexion est activée, Claude retournera son processus de raisonnement dans le cadre de la réponse, ce qui peut vous aider à :

1. Comprendre le processus de prise de décision du modèle
2. Identifier les problèmes potentiels ou les idées fausses
3. Apprendre de l'approche de Claude à la résolution de problèmes
4. Obtenir plus de visibilité sur les opérations complexes multi-étapes

Voici un exemple de ce que la sortie de réflexion pourrait ressembler :

[Réflexion]
Je dois enregistrer une image d'un chat sur le bureau. Décomposons cela en étapes :

1. D'abord, je vais prendre une capture d'écran pour voir ce qui est sur le bureau
2. Ensuite, je vais chercher un navigateur Web pour rechercher des images de chat
3. Après avoir trouvé une image appropriée, je devrai l'enregistrer sur le bureau

Commençons par prendre une capture d'écran pour voir ce qui est disponible...

Augmenter le contrôle d'ordinateur avec d'autres outils

L'outil de contrôle d'ordinateur peut être combiné avec d'autres outils pour créer des flux de travail d'automatisation plus puissants. Ceci est particulièrement utile lorsque vous avez besoin de :

• Exécuter des commandes système (outil bash)
• Éditer des fichiers de configuration ou des scripts (outil d'éditeur de texte)
• Intégrer avec des API personnalisées ou des services (outils personnalisés)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-01-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      },
      {
        "name": "get_weather",
        "description": "Obtenir la météo actuelle dans un lieu donné",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "La ville et l'état, par exemple San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "L'unité de température, soit « celsius » soit « fahrenheit »"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Trouver des vols de San Francisco vers un endroit avec un temps plus chaud."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

Créer un environnement informatique personnalisé

L'implémentation de référence est conçue pour vous aider à démarrer avec l'utilisation informatique. Elle inclut tous les composants nécessaires pour que Claude utilise un ordinateur. Cependant, vous pouvez créer votre propre environnement pour l'utilisation informatique selon vos besoins. Vous aurez besoin de :

• Un environnement virtualisé ou conteneurisé adapté à l'utilisation informatique avec Claude
• Une implémentation d'au moins l'un des outils informatiques définis par Anthropic
• Une boucle d'agent qui interagit avec l'API Claude et exécute les résultats tool_use en utilisant vos implémentations d'outils
• Une API ou une interface utilisateur qui permet l'entrée utilisateur pour démarrer la boucle d'agent

Implémenter l'outil informatique

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

Gérer les erreurs

Lors de l'implémentation de l'outil informatique, diverses erreurs peuvent survenir. Voici comment les gérer :

Gérer la mise à l'échelle des coordonnées pour les résolutions plus élevées

L'API limite les images à un maximum de 1568 pixels sur le bord le plus long et environ 1,15 mégapixels au total (voir redimensionnement d'image pour plus de détails). Par exemple, un écran de 1512x982 est réduit à environ 1330x864. Claude analyse cette image plus petite et retourne les coordonnées dans cet espace, mais votre outil exécute les clics dans l'espace d'écran d'origine.

Cela peut faire que les coordonnées de clic de Claude manquent leurs cibles à moins que vous ne gériez la transformation des coordonnées.

Pour corriger cela, redimensionnez les captures d'écran vous-même et augmentez les coordonnées de Claude :

import math

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)

# When capturing screenshot
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Resize image to scaled dimensions before sending to Claude
screenshot = capture_and_resize(scaled_width, scaled_height)

# When handling Claude's coordinates, scale them back up
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Suivre les meilleures pratiques d'implémentation

Comprendre les limitations de l'utilisation informatique

La fonctionnalité d'utilisation informatique est en version bêta. Bien que les capacités de Claude soient à la pointe de la technologie, les développeurs doivent être conscients de ses limitations :

1. Latence : la latence actuelle de l'utilisation informatique pour les interactions humain-IA peut être trop lente par rapport aux actions informatiques régulières dirigées par l'homme. Nous recommandons de se concentrer sur les cas d'usage où la vitesse n'est pas critique (par exemple, la collecte d'informations de base, les tests de logiciels automatisés) dans des environnements de confiance.
2. Précision et fiabilité de la vision par ordinateur : Claude peut faire des erreurs ou halluciner lors de la sortie de coordonnées spécifiques lors de la génération d'actions. Claude Sonnet 3.7 introduit la capacité de réflexion qui peut vous aider à comprendre le raisonnement du modèle et à identifier les problèmes potentiels.
3. Précision et fiabilité de la sélection d'outils : Claude peut faire des erreurs ou halluciner lors de la sélection d'outils lors de la génération d'actions ou prendre des actions inattendues pour résoudre les problèmes. De plus, la fiabilité peut être inférieure lors de l'interaction avec des applications de niche ou plusieurs applications à la fois. Nous recommandons aux utilisateurs de bien inviter le modèle lors de la demande de tâches complexes.
4. Fiabilité du défilement : Claude Sonnet 3.7 a introduit des actions de défilement dédiées avec contrôle directionnel qui améliore la fiabilité. Le modèle peut maintenant faire défiler explicitement dans n'importe quelle direction (haut/bas/gauche/droite) d'une quantité spécifiée.
5. Interaction avec des feuilles de calcul : Les clics de souris pour l'interaction avec des feuilles de calcul se sont améliorés dans Claude Sonnet 3.7 avec l'ajout d'actions de contrôle de souris plus précises comme left_mouse_down, left_mouse_up, et le nouveau support des touches de modification. La sélection de cellules peut être plus fiable en utilisant ces contrôles granulaires et en combinant les touches de modification avec les clics.
6. Création de compte et génération de contenu sur les plateformes sociales et de communication : Bien que Claude visitera les sites Web, nous limitons sa capacité à créer des comptes ou à générer et partager du contenu ou à s'engager autrement dans l'usurpation d'identité sur les sites Web et plateformes de médias sociaux. Nous pouvons mettre à jour cette capacité à l'avenir.
7. Vulnérabilités : Les vulnérabilités telles que le jailbreaking ou l'injection de requête peuvent persister dans les systèmes d'IA de pointe, y compris l'API informatique bêta. Dans certaines circonstances, Claude suivra les commandes trouvées dans le contenu, parfois même en conflit avec les instructions de l'utilisateur. Par exemple, les instructions Claude sur les pages Web ou contenues dans les images peuvent remplacer les instructions ou faire que Claude fasse des erreurs. Nous recommandons : a. Limiter l'utilisation informatique aux environnements de confiance tels que les machines virtuelles ou les conteneurs avec des privilèges minimaux b. Éviter de donner l'accès à l'utilisation informatique à des comptes sensibles ou à des données sans surveillance stricte c. Informer les utilisateurs finaux des risques pertinents et obtenir leur consentement avant d'activer ou de demander les autorisations nécessaires pour les fonctionnalités d'utilisation informatique dans vos applications
8. Actions inappropriées ou illégales : Conformément aux conditions de service d'Anthropic, vous ne devez pas utiliser l'utilisation informatique pour violer les lois ou notre Politique d'utilisation acceptable.

Examinez et vérifiez toujours attentivement les actions et les journaux d'utilisation informatique de Claude. N'utilisez pas Claude pour les tâches nécessitant une précision parfaite ou des informations utilisateur sensibles sans surveillance humaine.

Tarification

Computer use follows the standard tool use pricing. When using the computer use tool:

System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt

Computer use tool token usage:

Additional token consumption:

• Screenshot images (see Vision pricing)
• Tool execution results returned to Claude

Prochaines étapes