Utilisation d'ordinateur (bêta)

Claude 4 Opus et Sonnet, ainsi que Claude Sonnet 3.7 et Claude Sonnet 3.5 (nouveau), sont capables d’interagir avec des outils qui peuvent manipuler un environnement de bureau informatique. Les modèles Claude 4 utilisent des versions d’outils mises à jour et optimisées pour la nouvelle architecture. Claude Sonnet 3.7 introduit des outils supplémentaires et vous permet d’activer la réflexion, vous donnant plus d’informations sur le processus de raisonnement du modèle.

Voici un exemple de la façon de fournir des outils d’utilisation d’ordinateur à Claude en utilisant l’API Messages :

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-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

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-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

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-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

Comment fonctionne l’utilisation d’ordinateur

Nous appelons la répétition des étapes 3 et 4 sans entrée utilisateur 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

L’utilisation d’ordinateur nécessite un environnement informatique isolé 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 à travers 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 sous Linux, qui fournit une interface graphique cohérente pour que Claude puisse interagir.

3. Applications : Applications Linux préinstallées comme Firefox, LibreOffice, éditeurs de texte et 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 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 renvoyant les résultats (captures d’écran, sorties de commandes) à Claude.

Lorsque vous utilisez l’utilisation d’ordinateur, Claude ne se connecte pas directement à cet environnement. Au lieu de cela, 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 (captures d’écran, sorties de commandes, etc.)
4. Renvoie 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 des mappages de ports appropriés pour visualiser et interagir avec l’environnement.

​

Comment implémenter l’utilisation d’ordinateur

​

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

Nous avons construit une implémentation de référence qui comprend tout ce dont vous avez besoin pour démarrer rapidement avec l’utilisation d’ordinateur :

• Un environnement conteneurisé adapté à l’utilisation d’ordinateur avec Claude
• Des implémentations des outils d’utilisation d’ordinateur
• Une boucle d’agent qui interagit avec l’API Anthropic et exécute les outils d’utilisation 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 de l’utilisation d’ordinateur est la “boucle d’agent” - un cycle où Claude demande des actions d’outils, votre application les exécute et renvoie 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érations pour éviter les boucles infinies
):
    """
    Une boucle d'agent simple pour les interactions d'utilisation d'ordinateur de Claude.

    Cette fonction gère les allers-retours entre :
    1. Envoyer des messages utilisateur à Claude
    2. Claude demandant à utiliser des outils
    3. Votre application exécutant ces outils
    4. Envoyer les résultats des outils à 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érations pour éviter des 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 vraie application, vous exécuteriez l'outil ici
                # Par exemple : result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # 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é - renvoyer les messages finaux
        if not tool_results:
            return messages

        # Ajouter les résultats des outils 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 (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.

Nous vous 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 le prompting

Voici quelques conseils pour obtenir les meilleures sorties de 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 inciter Claude avec Après chaque étape, prends une capture d'écran et évalue soigneusement si tu as obtenu le bon résultat. Montre explicitement ton raisonnement : "J'ai évalué l'étape X..." Si ce n'est pas correct, essaie à nouveau. Ce n'est que lorsque tu confirmes qu'une étape a été correctement exécutée que tu dois passer à la suivante.
3. Certains éléments d’interface utilisateur (comme les menus déroulants et les barres de défilement) peuvent être difficiles à manipuler pour Claude en utilisant des mouvements de souris. Si vous rencontrez ce problème, essayez d’inciter le modèle à utiliser des 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’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 à l’intérieur de balises xml comme <robot_credentials>. L’utilisation d’ordinateur dans des applications nécessitant une connexion augmente le risque de mauvais résultats suite à une injection de prompt. Veuillez consulter notre guide sur l’atténuation des injections de prompts avant de fournir au modèle des informations d’identification.

​

Prompts système

Lorsqu’un des outils définis par Anthropic est demandé via l’API Anthropic, un prompt système spécifique à l’utilisation d’ordinateur est généré. Il est similaire au prompt 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 isolé. Vous n’avez PAS actuellement la capacité d’inspecter des fichiers ou d’interagir avec des ressources externes, sauf en invoquant les fonctions ci-dessous.

Comme avec l’utilisation régulière d’outils, le champ system_prompt fourni par l’utilisateur est toujours respecté et utilisé dans la construction du prompt système combiné.

​

Comprendre les outils définis par Anthropic

Nous avons fourni un ensemble d’outils qui permettent à Claude d’utiliser efficacement des ordinateurs. Lors de la spécification d’un outil défini par Anthropic, les champs description et tool_schema ne sont pas nécessaires ou autorisés.

Nous fournissons un ensemble d’outils définis par Anthropic, chaque outil ayant des versions optimisées pour Claude 4, Claude Sonnet 3.7 et Claude Sonnet 3.5 :

Le champ type identifie l’outil et ses paramètres à des fins de validation, le champ name est le nom de l’outil exposé au modèle.

Si vous souhaitez inciter le modèle à utiliser l’un de ces outils, vous pouvez explicitement faire référence à l’outil par le champ name. Le champ name doit être unique dans la liste d’outils ; vous ne pouvez pas définir un outil avec le même nom qu’un outil défini par Anthropic dans le même appel API.

​

Activer la capacité de réflexion dans 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 à des fins de débogage ou d’éducation.

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 renverra 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 les idées fausses potentiels
3. Apprendre de l’approche de Claude pour résoudre les problèmes
4. Obtenir plus de visibilité sur les opérations complexes en plusieurs étapes

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

[Thinking]
Je dois enregistrer une image de chat sur le bureau. Décomposons cela en étapes :

1. D'abord, je vais prendre une capture d'écran pour voir ce qui se trouve sur le bureau
2. Ensuite, je vais chercher un navigateur web pour rechercher des images de chats
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...

​

Combiner l’utilisation d’ordinateur avec d’autres outils

Vous pouvez combiner l’utilisation régulière d’outils avec les outils définis par Anthropic pour l’utilisation d’ordinateur.

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-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

Construire un environnement d’utilisation d’ordinateur personnalisé

L’implémentation de référence est destinée à vous aider à démarrer avec l’utilisation d’ordinateur. Elle comprend tous les composants nécessaires pour que Claude utilise un ordinateur. Cependant, vous pouvez construire votre propre environnement pour l’utilisation d’ordinateur selon vos besoins. Vous aurez besoin de :

• Un environnement virtualisé ou conteneurisé adapté à l’utilisation d’ordinateur avec Claude
• Une implémentation d’au moins un des outils d’utilisation d’ordinateur définis par Anthropic
• Une boucle d’agent qui interagit avec l’API Anthropic 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

​

Comprendre les limitations de l’utilisation d’ordinateur

La fonctionnalité d’utilisation d’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 d’utilisation d’ordinateur pour les interactions humain-IA peut être trop lente par rapport aux actions informatiques régulières dirigées par l’humain. Nous recommandons de se concentrer sur les cas d’utilisation où la vitesse n’est pas critique (par exemple, la collecte d’informations en arrière-plan, les tests automatisés de logiciels) 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 pendant la génération d’actions ou prendre des actions inattendues pour résoudre des 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 d’inciter soigneusement le modèle lors de la demande de tâches complexes.
4. Fiabilité du défilement : Alors que Claude Sonnet 3.5 (nouveau) avait des limitations avec le défilement, Claude Sonnet 3.7 introduit des actions de défilement dédiées avec contrôle de direction qui améliore la fiabilité. Le modèle peut maintenant explicitement faire défiler 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 ont été 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 de touches modificatrices. La sélection de cellules peut être plus fiable en utilisant ces contrôles précis et en combinant des touches modificatrices avec des clics.
6. Création de compte et génération de contenu sur les plateformes sociales et de communication : Bien que Claude visitera des 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é humaine sur les sites web et plateformes de médias sociaux. Nous pourrons mettre à jour cette capacité à l’avenir.
7. Vulnérabilités : Des vulnérabilités comme le jailbreaking ou l’injection de prompts peuvent persister à travers les systèmes d’IA de pointe, y compris l’API bêta d’utilisation d’ordinateur. 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, des instructions pour Claude sur des pages web ou contenues dans des images peuvent remplacer les instructions ou amener Claude à faire des erreurs. Nous recommandons : a. Limiter l’utilisation d’ordinateur à des environnements de confiance tels que des machines virtuelles ou des conteneurs avec des privilèges minimaux b. Éviter de donner accès à l’utilisation d’ordinateur à des comptes ou des données sensibles sans surveillance stricte c. Informer les utilisateurs finaux des risques pertinents et obtenir leur consentement avant d’activer ou de demander les permissions nécessaires pour les fonctionnalités d’utilisation d’ordinateur dans vos applications
8. Actions inappropriées ou illégales : Selon les conditions d’utilisation d’Anthropic, vous ne devez pas employer l’utilisation d’ordinateur pour violer des lois ou notre Politique d’utilisation acceptable.

Vérifiez toujours soigneusement les actions et les journaux d’utilisation d’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.

​

Tarification

En tant que sous-ensemble des requêtes d’utilisation d’outils, les requêtes d’utilisation d’ordinateur sont tarifées de la même manière que toute autre requête API Claude.

Nous incluons également automatiquement un prompt système spécial pour le modèle, qui permet l’utilisation d’ordinateur.

En plus des tokens de base, les tokens d’entrée supplémentaires suivants sont nécessaires pour les outils définis par Anthropic :

Si vous activez la réflexion avec Claude 4 ou Claude Sonnet 3.7, les tokens utilisés pour la réflexion seront comptabilisés dans votre budget max_tokens en fonction des budget_tokens que vous spécifiez dans le paramètre de réflexion.