Outil d'utilisation de l'ordinateur

Claude peut interagir avec des environnements informatiques grâce à l'outil d'utilisation de l'ordinateur, qui offre des capacités de capture d'écran et un contrôle de la souris/du clavier pour une interaction autonome avec le bureau. Sur WebArena, un benchmark pour la navigation web autonome sur de vrais sites web, Claude obtient des résultats à l'état de l'art parmi les systèmes à agent unique, démontrant une forte capacité à accomplir des tâches de navigation multi-étapes de bout en bout.

Vue d'ensemble

L'utilisation de l'ordinateur est une fonctionnalité bêta qui permet à Claude d'interagir avec des environnements de bureau. Cet outil offre :

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

Bien que l'utilisation de l'ordinateur puisse être complétée par d'autres outils comme bash et l'éditeur de texte pour des flux de travail d'automatisation plus complets, l'utilisation de l'ordinateur désigne spécifiquement la capacité de l'outil d'utilisation de l'ordinateur à voir et contrôler les environnements de bureau.

Compatibilité des modèles

L'utilisation de l'ordinateur est disponible pour les modèles Claude suivants :

Considérations de sécurité

L'utilisation de l'ordinateur est une fonctionnalité bêta présentant des risques uniques distincts des fonctionnalités API standard. Ces risques sont accrus lors d'interactions avec Internet.

Dans certaines circonstances, Claude suivra des commandes trouvées dans le contenu même si cela entre en conflit avec les instructions de l'utilisateur. Par exemple, les instructions de Claude sur des pages web ou contenues dans des 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 prompts.

Le modèle a été entraîné pour résister à ces injections de prompts, et une couche de défense supplémentaire a été ajoutée. Si vous utilisez les outils d'utilisation de l'ordinateur, des classificateurs s'exécuteront automatiquement sur vos prompts pour signaler les instances potentielles d'injections de prompts. Lorsque ces classificateurs identifient des injections de prompts potentielles dans les captures d'écran, ils orienteront automatiquement le modèle pour qu'il demande une 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'utilisation (par exemple, les cas d'utilisation sans humain dans la boucle), donc si vous souhaitez vous désinscrire et la désactiver, veuillez contacter le support.

Ces précautions restent importantes même avec la couche de défense par classificateur 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

Voici comment démarrer avec l'utilisation de l'ordinateur :

Comment fonctionne l'utilisation de l'ordinateur

La répétition des étapes 3 et 4 sans entrée utilisateur est appelée la "boucle d'agent" (c'est-à-dire que Claude répond avec une requête d'utilisation d'outil et votre application répond à Claude avec les résultats de l'évaluation de cette requête).

L'environnement informatique

L'utilisation de l'ordinateur nécessite un environnement informatique en bac à sable où 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/clavier.

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

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 : Du code d'intégration qui traduit les requêtes 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, envoyant les actions de Claude à l'environnement et retournant 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. Au lieu de cela, votre application :

1. Reçoit les requêtes d'utilisation d'outils de Claude
2. Les traduit en actions dans votre environnement informatique
3. Capture les résultats (captures d'écran, sorties de commandes, 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 dans un conteneur Docker avec des mappages de ports appropriés pour visualiser et interagir avec l'environnement.

Comment implémenter l'utilisation de l'ordinateur

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

Une implémentation de référence est disponible et comprend tout ce dont vous avez besoin pour démarrer rapidement avec l'utilisation de l'ordinateur :

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

Comprendre la boucle multi-agent

Le cœur de l'utilisation de l'ordinateur est la "boucle d'agent" - un cycle où Claude demande des actions d'outils, 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"
        if "20250124" in tool_version
        else "computer-use-2024-10-22"
    )

    # 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": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "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 (tâche terminée) ou que la limite maximale d'itérations 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 le prompting

Voici quelques conseils pour obtenir des sorties de la meilleure qualité :

1. Spécifiez des tâches simples et bien définies et fournissez 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 demander à Claude avec 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 utilisateur (comme les menus déroulants 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 répétables ou les interactions avec l'interface utilisateur, incluez des captures d'écran d'exemple et des appels d'outils de résultats réussis dans votre prompt.
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 dans des balises xml comme <robot_credentials>. L'utilisation de l'ordinateur dans des applications nécessitant une connexion augmente le risque de mauvais résultats en raison d'injections de prompts. Consultez le guide sur l'atténuation des injections de prompts avant de fournir des identifiants de connexion au modèle.

Prompts système

Lorsqu'un des outils définis par Anthropic est demandé via l'API Claude, un prompt système spécifique à l'utilisation de l'ordinateur est généré. Il est similaire au prompt 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 ordinaire, le champ system_prompt fourni par l'utilisateur est toujours respecté et utilisé dans la construction du prompt système combiné.

Actions disponibles

L'outil d'utilisation de l'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 vers des coordonnées

Actions améliorées (computer_20250124) Disponibles 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 des 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) Disponibles 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 en pleine résolution. Nécessite enable_zoom: true dans la définition de l'outil. Prend un paramètre region avec des 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 lorsqu'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 requête API :

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

Le paramètre budget_tokens spécifie combien de tokens Claude peut utiliser pour la réflexion. Cela 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 ou idées fausses potentiels
3. Apprendre de l'approche de Claude pour la résolution de problèmes
4. Obtenir plus de visibilité sur les opérations complexes à plusieurs étapes

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

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

Augmenter l'utilisation de l'ordinateur avec d'autres outils

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

• Exécuter des commandes système (outil bash)
• Modifier des fichiers de configuration ou des scripts (outil éditeur de texte)
• Intégrer des API ou services personnalisés (outils personnalisés)

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 selon vos besoins. Vous aurez besoin de :

• Un environnement virtualisé ou conteneurisé adapté à l'utilisation de l'ordinateur avec Claude
• Une implémentation d'au moins un des outils d'utilisation de l'ordinateur 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 permettant à l'utilisateur de 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. 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é dans le modèle de Claude et ne peut pas être modifié.

Gérer les erreurs

Lors de l'implémentation de l'outil d'utilisation de l'ordinateur, 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 sous-échantillonné à environ 1330x864. Claude analyse cette image plus petite et renvoie des coordonnées dans cet espace, mais votre outil exécute les clics dans l'espace d'écran d'origine.

Cela peut faire manquer les cibles aux coordonnées de clic de Claude, sauf si vous gérez la transformation des coordonnées.

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

Suivre les meilleures pratiques d'implémentation

Comprendre les limitations de l'utilisation de l'ordinateur

La fonctionnalité d'utilisation de l'ordinateur 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 de l'ordinateur pour les interactions humain-IA peut être trop lente par rapport aux actions informatiques habituellement dirigées par des humains. Concentrez-vous sur des 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 faire des erreurs ou halluciner lors de la génération 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 des outils : Claude peut faire des erreurs ou halluciner lors de la sélection des outils lors de la génération d'actions ou prendre 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 plusieurs applications simultanément. Formulez soigneusement les instructions au 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 de direction qui améliore la fiabilité. Le modèle peut désormais faire défiler explicitement dans n'importe quelle direction (haut/bas/gauche/droite) d'une quantité spécifiée.
5. Interaction avec les feuilles de calcul : Les clics de souris pour l'interaction avec les 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 de touches modificatrices. La sélection de cellules peut être plus fiable en utilisant ces contrôles fins et en combinant les touches modificatrices avec les clics.

Examinez et vérifiez toujours soigneusement les actions et journaux d'utilisation de l'ordinateur de Claude. N'utilisez pas Claude pour des tâches nécessitant une précision parfaite ou des informations utilisateur sensibles sans surveillance 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 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.

É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. Pour l'éligibilité ZDR sur 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