Herramienta de uso de computadora

Claude puede interactuar con entornos de computadora a través de la herramienta de uso de computadora, que proporciona capacidades de captura de pantalla y control de ratón/teclado para interacción autónoma de escritorio. En WebArena, un punto de referencia para navegación web autónoma en sitios web reales, Claude logra resultados de última generación entre sistemas de agente único, demostrando una fuerte capacidad para completar tareas de navegador de múltiples pasos de principio a fin.

Descripción general

El uso de computadora es una función beta que permite a Claude interactuar con entornos de escritorio. Esta herramienta proporciona:

• Captura de pantalla: Ver lo que se muestra actualmente en la pantalla
• Control del ratón: Hacer clic, arrastrar y mover el cursor
• Entrada de teclado: Escribir texto y usar atajos de teclado
• Automatización de escritorio: Interactuar con cualquier aplicación o interfaz

Aunque el uso de computadora puede aumentarse con otras herramientas como bash y editor de texto para flujos de trabajo de automatización más completos, el uso de computadora se refiere específicamente a la capacidad de la herramienta de uso de computadora de ver y controlar entornos de escritorio.

Para compatibilidad de modelos, consulte la referencia de herramientas.

Consideraciones de seguridad

El uso de computadora es una función beta con riesgos únicos distintos de las características estándar de API. Estos riesgos se acentúan cuando se interactúa con Internet.

En algunas circunstancias, Claude seguirá comandos encontrados en contenido incluso si entra en conflicto con las instrucciones del usuario. Por ejemplo, las instrucciones de Claude en páginas web o contenidas en imágenes pueden anular instrucciones o causar que Claude cometa errores. Tome precauciones para aislar a Claude de datos y acciones sensibles para evitar riesgos relacionados con inyección de indicaciones.

El modelo ha sido entrenado para resistir estas inyecciones de indicaciones, y se ha añadido una capa adicional de defensa. Si utiliza las herramientas de uso de computadora, los clasificadores se ejecutarán automáticamente en sus indicaciones para marcar posibles instancias de inyección de indicaciones. Cuando estos clasificadores identifiquen posibles inyecciones de indicaciones en capturas de pantalla, automáticamente dirigirán el modelo a pedir confirmación del usuario antes de proceder con la siguiente acción. Esta protección adicional no será ideal para todos los casos de uso (por ejemplo, casos de uso sin un humano en el bucle), así que si desea optar por no participar y desactivarla, por favor contacte con soporte.

Estas precauciones siguen siendo importantes incluso con la capa de defensa del clasificador en su lugar.

Informe a los usuarios finales de los riesgos relevantes y obtenga su consentimiento antes de habilitar el uso de computadora en sus propios productos.

Inicio rápido

Aquí se explica cómo comenzar con el uso de computadora:

Cómo funciona el uso de computadora

La repetición de los pasos 3 y 4 sin entrada del usuario se conoce como el "bucle de agente" (es decir, Claude respondiendo con una solicitud de uso de herramienta y su aplicación respondiendo a Claude con los resultados de evaluar esa solicitud).

El entorno informático

El uso de computadora requiere un entorno informático aislado donde Claude pueda interactuar de forma segura con aplicaciones y la web. Este entorno incluye:

1. Pantalla virtual: Un servidor de pantalla X11 virtual (usando Xvfb) que renderiza la interfaz de escritorio que Claude verá a través de capturas de pantalla y controlará con acciones de ratón/teclado.

2. Entorno de escritorio: Una interfaz de usuario ligera con gestor de ventanas (Mutter) y panel (Tint2) ejecutándose en Linux, que proporciona una interfaz gráfica consistente para que Claude interactúe.

3. Aplicaciones: Aplicaciones Linux preinstaladas como Firefox, LibreOffice, editores de texto y gestores de archivos que Claude puede usar para completar tareas.

4. Implementaciones de herramientas: Código de integración que traduce las solicitudes de herramientas abstractas de Claude (como "mover ratón" o "tomar captura de pantalla") en operaciones reales en el entorno virtual.

5. Bucle de agente: Un programa que maneja la comunicación entre Claude y el entorno, enviando las acciones de Claude al entorno y devolviendo los resultados (capturas de pantalla, salidas de comandos) a Claude.

Cuando utiliza el uso de computadora, Claude no se conecta directamente a este entorno. En su lugar, su aplicación:

1. Recibe las solicitudes de uso de herramienta de Claude
2. Las traduce en acciones en su entorno informático
3. Captura los resultados (capturas de pantalla, salidas de comandos, etc.)
4. Devuelve estos resultados a Claude

Para seguridad y aislamiento, la implementación de referencia ejecuta todo esto dentro de un contenedor Docker con asignaciones de puerto apropiadas para ver e interactuar con el entorno.

Cómo implementar el uso de computadora

Comience con la implementación de referencia

Una implementación de referencia está disponible que incluye todo lo que necesita para comenzar rápidamente con el uso de computadora:

• Un entorno containerizado adecuado para el uso de computadora con Claude
• Implementaciones de las herramientas de uso de computadora
• Un bucle de agente que interactúa con la API de Claude y ejecuta las herramientas de uso de computadora
• Una interfaz web para interactuar con el contenedor, bucle de agente y herramientas.

Entender el bucle de agente

El núcleo del uso de computadora es el "bucle de agente" - un ciclo donde Claude solicita acciones de herramientas, su aplicación las ejecuta y devuelve resultados a Claude. Aquí hay un ejemplo simplificado:

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})

El bucle continúa hasta que Claude responda sin solicitar ninguna herramienta (finalización de tarea) o se alcance el límite máximo de iteraciones. Esta salvaguarda previene posibles bucles infinitos que podrían resultar en costos de API inesperados.

Pruebe la implementación de referencia antes de leer el resto de esta documentación.

Optimizar el rendimiento del modelo con indicaciones

Aquí hay algunos consejos sobre cómo obtener los mejores resultados de calidad:

1. Especifique tareas simples y bien definidas y proporcione instrucciones explícitas para cada paso.
2. Claude a veces asume resultados de sus acciones sin verificar explícitamente sus resultados. Para evitar esto, puede indicar a Claude con 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. Algunos elementos de interfaz de usuario (como menús desplegables y barras de desplazamiento) podrían ser complicados para que Claude los manipule usando movimientos del ratón. Si experimenta esto, intente indicar al modelo que use atajos de teclado.
4. Para tareas repetibles o interacciones de interfaz de usuario, incluya capturas de pantalla de ejemplo y llamadas de herramientas de resultados exitosos en su indicación.
5. Si necesita que el modelo inicie sesión, proporciónele el nombre de usuario y contraseña en su indicación dentro de etiquetas xml como <robot_credentials>. Usar el uso de computadora dentro de aplicaciones que requieren inicio de sesión aumenta el riesgo de malos resultados como resultado de inyección de indicaciones. Revise la guía sobre mitigación de inyecciones de indicaciones antes de proporcionar al modelo credenciales de inicio de sesión.

Indicaciones del sistema

Cuando se solicita una de las herramientas del esquema de Anthropic a través de la API de Claude, se genera una indicación del sistema específica del uso de computadora. Es similar a la indicación del sistema de uso de herramientas pero comienza con:

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.

Como con el uso regular de herramientas, el campo system_prompt proporcionado por el usuario sigue siendo respetado y utilizado en la construcción de la indicación del sistema combinada.

Acciones disponibles

La herramienta de uso de computadora admite estas acciones:

Acciones básicas (todas las versiones)

• screenshot - Capturar la pantalla actual
• left_click - Hacer clic en las coordenadas [x, y]
• type - Escribir cadena de texto
• key - Presionar tecla o combinación de teclas (por ejemplo, "ctrl+s")
• mouse_move - Mover cursor a coordenadas

Acciones mejoradas (computer_20250124) Disponible en modelos Claude 4 y Claude Sonnet 3.7:

• scroll - Desplazarse en cualquier dirección con control de cantidad
• left_click_drag - Hacer clic y arrastrar entre coordenadas
• right_click, middle_click - Botones de ratón adicionales
• double_click, triple_click - Múltiples clics
• left_mouse_down, left_mouse_up - Control de clic de grano fino
• hold_key - Mantener presionada una tecla durante una duración especificada (en segundos)
• wait - Pausar entre acciones

Acciones mejoradas (computer_20251124) Disponible en Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 y Claude Opus 4.5:

• Todas las acciones de computer_20250124
• zoom - Ver una región específica de la pantalla a resolución completa. Requiere enable_zoom: true en la definición de herramienta. Toma un parámetro region con coordenadas [x1, y1, x2, y2] que definen las esquinas superior izquierda e inferior derecha del área a inspeccionar.

Parámetros de herramienta

Combinación con pensamiento extendido

Para combinar el uso de computadora con pensamiento extendido, consulte Pensamiento extendido.

Aumentar el uso de computadora con otras herramientas

Para agregar otras herramientas junto con el uso de computadora, inclúyalas en el mismo array tools. El inicio rápido anterior muestra este patrón con la herramienta bash y la herramienta editor de texto. Puede agregar sus propias definiciones de herramientas personalizadas de la misma manera.

Construir un entorno personalizado de uso de computadora

La implementación de referencia está diseñada para ayudarte a comenzar con el uso de computadora. Incluye todos los componentes necesarios para que Claude use una computadora. Sin embargo, puedes construir tu propio entorno para el uso de computadora según tus necesidades. Necesitarás:

• Un entorno virtualizado o containerizado adecuado para el uso de computadora con Claude
• Una implementación de al menos una de las herramientas de uso de computadora del esquema de Anthropic
• Un bucle de agente que interactúe con la API de Claude y ejecute los resultados de tool_use usando tus implementaciones de herramientas
• Una API o interfaz de usuario que permita la entrada del usuario para iniciar el bucle del agente

Implementar la herramienta de uso de computadora

La herramienta de uso de computadora se implementa como una herramienta sin esquema. Cuando uses esta herramienta, no necesitas proporcionar un esquema de entrada como con otras herramientas; el esquema está integrado en el modelo de Claude y no se puede modificar.

Manejar errores

Al implementar la herramienta de uso de computadora, pueden ocurrir varios errores. Así es cómo manejarlos:

Manejar el escalado de coordenadas para resoluciones más altas

La API limita las imágenes a un máximo de 1568 píxeles en el borde más largo y aproximadamente 1.15 megapíxeles en total (ver redimensionamiento de imagen para más detalles). Por ejemplo, una pantalla de 1512x982 se reduce a aproximadamente 1330x864. Claude analiza esta imagen más pequeña y devuelve coordenadas en ese espacio, pero tu herramienta ejecuta clics en el espacio de pantalla original.

Esto puede causar que las coordenadas de clic de Claude pierdan sus objetivos a menos que manejes la transformación de coordenadas.

Para solucionar esto, redimensiona las capturas de pantalla tú mismo y escala las coordenadas de Claude hacia arriba:

Seguir las mejores prácticas de implementación

Entender las limitaciones del uso de computadora

La funcionalidad de uso de computadora está en beta. Aunque las capacidades de Claude son de vanguardia, los desarrolladores deben ser conscientes de sus limitaciones:

1. Latencia: la latencia actual del uso de computadora para interacciones humano-IA puede ser demasiado lenta en comparación con las acciones de computadora dirigidas regularmente por humanos. Enfócate en casos de uso donde la velocidad no es crítica (por ejemplo, recopilación de información de fondo, pruebas automatizadas de software) en entornos confiables.
2. Precisión y confiabilidad de la visión por computadora: Claude puede cometer errores o alucinar al generar coordenadas específicas mientras genera acciones. Claude Sonnet 3.7 introduce la capacidad de pensamiento que puede ayudarte a entender el razonamiento del modelo e identificar posibles problemas.
3. Precisión y confiabilidad de la selección de herramientas: Claude puede cometer errores o alucinar al seleccionar herramientas mientras genera acciones o tomar acciones inesperadas para resolver problemas. Además, la confiabilidad puede ser menor al interactuar con aplicaciones de nicho o múltiples aplicaciones a la vez. Solicita al modelo cuidadosamente cuando solicites tareas complejas.
4. Confiabilidad del desplazamiento: Claude Sonnet 3.7 introdujo acciones de desplazamiento dedicadas con control de dirección que mejora la confiabilidad. El modelo ahora puede desplazarse explícitamente en cualquier dirección (arriba/abajo/izquierda/derecha) por una cantidad especificada.
5. Interacción con hojas de cálculo: Los clics del ratón para la interacción con hojas de cálculo han mejorado en Claude Sonnet 3.7 con la adición de acciones de control del ratón más precisas como left_mouse_down, left_mouse_up, y nuevo soporte de teclas modificadoras. La selección de celdas puede ser más confiable usando estos controles de grano fino y combinando teclas modificadoras con clics.

Siempre revisa y verifica cuidadosamente las acciones y registros de uso de computadora de Claude. No uses Claude para tareas que requieran precisión perfecta o información de usuario sensible sin supervisión humana.

Retención de datos

El uso de computadora es una herramienta del lado del cliente. Todas las capturas de pantalla, acciones del ratón, entradas de teclado y cualquier archivo involucrado en una sesión se capturan y almacenan en tu entorno, no por Anthropic. Anthropic procesa las imágenes de captura de pantalla y solicitudes de acción en tiempo real como parte de la llamada a la API pero no las retiene después de que se devuelve la respuesta.

Debido a que tu aplicación controla dónde y cómo se almacenan los datos de uso de computadora, el uso de computadora es elegible para ZDR. Para elegibilidad de ZDR en todas las características, ver API y retención de datos.

Precios

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

Próximos pasos