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. Sur WebArena, un benchmark pour la navigation web autonome sur des sites réels, Claude obtient des résultats de pointe parmi les systèmes monoagent, démontrant une forte capacité à compléter les tâches du navigateur multi-étapes de bout en bout.

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, faire 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.

Pour le support des modèles, consultez la Référence des outils.

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. Prenez des précautions pour isoler Claude des données et actions sensibles afin d'éviter les risques liés à l'injection de prompt.

Le modèle a été entraîné pour résister à ces injections de prompt, et une couche de défense supplémentaire a été ajoutée. Si vous utilisez les outils de contrôle d'ordinateur, des classificateurs s'exécuteront automatiquement 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 la confirmation de l'utilisateur avant de procéder à l'action suivante. 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), donc si vous souhaitez refuser et la désactiver, veuillez contacter le support.

Ces précautions restent importantes même avec la couche de défense du classificateur en place.

Informez les utilisateurs finaux des risques pertinents et obtenez 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 :

Comment fonctionne le contrôle d'ordinateur

La répétition des étapes 3 et 4 sans entrée utilisateur est appelée 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) s'exécutant sur Linux, qui fournit une interface graphique cohérente pour que Claude interagisse.

3. Applications : Applications Linux pré-installées comme Firefox, LibreOffice, éditeurs de texte et gestionnaires de fichiers que Claude peut utiliser pour compléter les 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 ports appropriés pour visualiser et interagir avec l'environnement.

Comment implémenter le contrôle d'ordinateur

Commencer par l'implémentation de référence

Une implémentation de référence est disponible 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
• 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 d'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,  # Add iteration limit to prevent infinite loops
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {
            "type": f"computer_{tool_version}",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        },
        {"type": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # Add Claude's response to the conversation history
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": result}
                )

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

La boucle continue jusqu'à ce que Claude réponde sans demander d'outils (achèvement de la tâche) ou jusqu'à ce 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.

Essayez l'implémentation de référence avant de lire le reste de cette documentation.

Optimiser les performances du modèle avec des 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 résultat souhaité. 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 la 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. Consultez le 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 du schéma 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 pour l'utilisation régulière d'outils, 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 prend en charge 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 faire 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, Claude Sonnet 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

Combinaison avec la réflexion étendue

Pour combiner le contrôle d'ordinateur avec la réflexion étendue, consultez Réflexion étendue.

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

Pour ajouter d'autres outils aux côtés du contrôle d'ordinateur, incluez-les dans le même tableau tools. Le démarrage rapide ci-dessus montre ce modèle avec l'outil bash et l'outil éditeur de texte. Vous pouvez ajouter vos propres définitions d'outils personnalisés de la même manière.

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 du schéma 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 de l'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 de 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 de coordonnées.

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

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'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 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. Invitez le modèle avec soin 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, et un 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.

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.

Conservation des données

L'utilisation informatique est un outil côté client. Toutes les captures d'écran, les actions de souris, les entrées au clavier et tous les fichiers impliqués dans une session sont capturés et stockés dans votre environnement, pas par Anthropic. Anthropic traite les images de capture d'écran et les demandes d'action en temps réel dans le cadre de l'appel API mais ne les conserve pas après le retour de la réponse.

Parce que votre application contrôle où et comment les données d'utilisation informatique sont stockées, l'utilisation informatique est admissible à ZDR. Pour l'admissibilité à ZDR dans toutes les fonctionnalités, voir API et conservation des données.

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