Herramienta de uso de computadora

Claude puede interactuar con entornos informáticos a través de la herramienta de uso de computadora, que proporciona capacidades de captura de pantalla y control de ratón/teclado para la interacción autónoma con el escritorio. En WebArena, un benchmark para la navegación web autónoma en sitios web reales, Claude logra resultados de vanguardia entre los sistemas de agente único, demostrando una gran 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

Si bien el uso de computadora puede complementarse con otras herramientas como bash y el 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 para ver y controlar entornos de escritorio.

Compatibilidad de modelos

El uso de computadora está disponible para los siguientes modelos de Claude:

Consideraciones de seguridad

El uso de computadora es una función beta con riesgos únicos distintos de las funciones estándar de la API. Estos riesgos se incrementan al interactuar con Internet.

En algunas circunstancias, Claude seguirá comandos encontrados en el 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 hacer que Claude cometa errores. Toma precauciones para aislar a Claude de datos y acciones confidenciales para evitar riesgos relacionados con la inyección de prompts.

El modelo ha sido entrenado para resistir estas inyecciones de prompts, y se ha añadido una capa adicional de defensa. Si utilizas las herramientas de uso de computadora, los clasificadores se ejecutarán automáticamente en tus prompts para señalar posibles instancias de inyecciones de prompts. Cuando estos clasificadores identifiquen posibles inyecciones de prompts en capturas de pantalla, dirigirán automáticamente al modelo para que solicite 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), por lo que si deseas optar por no participar y desactivarla, contacta con soporte.

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

Informa a los usuarios finales de los riesgos relevantes y obtén su consentimiento antes de habilitar el uso de computadora en tus propios productos.

Inicio rápido

Aquí te explicamos cómo comenzar con el uso de computadora:

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-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "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": "Save a picture of a cat to my desktop."
      }
    ]
  }'

Cómo funciona el uso de computadora

La repetición de los pasos 3 y 4 sin entrada del usuario se denomina "bucle de agente" (es decir, Claude responde con una solicitud de uso de herramienta y tu aplicación responde 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) que se ejecuta 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 abstractas de herramientas de Claude (como "mover el ratón" o "tomar una captura de pantalla") en operaciones reales en el entorno virtual.

5. Bucle de agente: Un programa que gestiona 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 usas el uso de computadora, Claude no se conecta directamente a este entorno. En cambio, tu aplicación:

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

Por seguridad y aislamiento, la implementación de referencia ejecuta todo esto dentro de un contenedor Docker con los mapeos de puertos apropiados para ver e interactuar con el entorno.

Cómo implementar el uso de computadora

Comienza con la implementación de referencia

Hay disponible una implementación de referencia que incluye todo lo que necesitas para comenzar rápidamente con el uso de computadora:

• Un entorno en contenedor 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, el bucle de agente y las herramientas.

Comprender el bucle multiagente

El núcleo del uso de computadora es el "bucle de agente": un ciclo donde Claude solicita acciones de herramientas, tu aplicación las ejecuta y devuelve los 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"
        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})

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

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

Optimiza el rendimiento del modelo con prompting

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

1. Especifica tareas simples y bien definidas y proporciona instrucciones explícitas para cada paso.
2. Claude a veces asume los resultados de sus acciones sin verificar explícitamente sus resultados. Para evitar esto, puedes indicarle 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 la interfaz de usuario (como menús desplegables y barras de desplazamiento) pueden ser difíciles de manipular para Claude usando movimientos del ratón. Si experimentas esto, intenta indicarle al modelo que use atajos de teclado.
4. Para tareas repetibles o interacciones de interfaz de usuario, incluye capturas de pantalla de ejemplo y llamadas a herramientas de resultados exitosos en tu prompt.
5. Si necesitas que el modelo inicie sesión, proporciónale el nombre de usuario y la contraseña en tu prompt dentro de etiquetas xml como <robot_credentials>. El uso de computadora dentro de aplicaciones que requieren inicio de sesión aumenta el riesgo de malos resultados como consecuencia de la inyección de prompts. Revisa la guía sobre cómo mitigar las inyecciones de prompts antes de proporcionar al modelo credenciales de inicio de sesión.

Prompts del sistema

Cuando se solicita una de las herramientas definidas por Anthropic a través de la API de Claude, se genera un prompt del sistema específico para el uso de computadora. Es similar al prompt 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.

Al igual que con el uso regular de herramientas, el campo system_prompt proporcionado por el usuario sigue siendo respetado y utilizado en la construcción del prompt del sistema combinado.

Acciones disponibles

La herramienta de uso de computadora admite estas acciones:

Acciones básicas (todas las versiones)

• screenshot - Captura la pantalla actual
• left_click - Hace clic en las coordenadas [x, y]
• type - Escribe una cadena de texto
• key - Presiona una tecla o combinación de teclas (por ejemplo, "ctrl+s")
• mouse_move - Mueve el cursor a las coordenadas

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

• scroll - Desplaza en cualquier dirección con control de cantidad
• left_click_drag - Hace clic y arrastra entre coordenadas
• right_click, middle_click - Botones adicionales del ratón
• double_click, triple_click - Múltiples clics
• left_mouse_down, left_mouse_up - Control de clic detallado
• hold_key - Mantiene presionada una tecla durante una duración especificada (en segundos)
• wait - Pausa entre acciones

Acciones mejoradas (computer_20251124) Disponibles en Claude Opus 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 la 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 la herramienta

Habilitar la capacidad de pensamiento en los modelos Claude 4 y Claude Sonnet 3.7

Claude Sonnet 3.7 introdujo una nueva capacidad de "pensamiento" que te permite ver el proceso de razonamiento del modelo mientras trabaja en tareas complejas. Esta función te ayuda a entender cómo Claude está abordando un problema y puede ser particularmente valiosa para la depuración o con fines educativos.

Para habilitar el pensamiento, agrega un parámetro thinking a tu solicitud de API:

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

El parámetro budget_tokens especifica cuántos tokens puede usar Claude para pensar. Esto se resta de tu presupuesto general de max_tokens.

Cuando el pensamiento está habilitado, Claude devolverá su proceso de razonamiento como parte de la respuesta, lo que puede ayudarte a:

1. Comprender el proceso de toma de decisiones del modelo
2. Identificar posibles problemas o conceptos erróneos
3. Aprender del enfoque de Claude para la resolución de problemas
4. Obtener más visibilidad sobre operaciones complejas de múltiples pasos

Aquí hay un ejemplo de cómo podría verse la salida del pensamiento:

[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...

Aumentar el uso del ordenador con otras herramientas

La herramienta de uso del ordenador se puede combinar con otras herramientas para crear flujos de trabajo de automatización más potentes. Esto es especialmente útil cuando necesitas:

• Ejecutar comandos del sistema (herramienta bash)
• Editar archivos de configuración o scripts (herramienta de editor de texto)
• Integrar con APIs o servicios personalizados (herramientas personalizadas)

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-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "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"
      },
      {
        "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
    }
  }'

Construir un entorno personalizado de uso del ordenador

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

• Un entorno virtualizado o en contenedor adecuado para el uso del ordenador con Claude
• Una implementación de al menos una de las herramientas de uso del ordenador definidas por 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 de agente

Implementar la herramienta de uso del ordenador

La herramienta de uso del ordenador se implementa como una herramienta sin esquema. Al usar 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 del ordenador, pueden ocurrir varios errores. Aquí se explica 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 (consulta redimensionamiento de imágenes 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 los clics en el espacio de pantalla original.

Esto puede hacer que las coordenadas de clic de Claude no alcancen 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 de vuelta:

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)

Seguir las mejores prácticas de implementación

Comprender las limitaciones del uso del ordenador

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

1. Latencia: la latencia actual del uso del ordenador para las interacciones humano-IA puede ser demasiado lenta en comparación con las acciones informáticas dirigidas por humanos regulares. Enfócate en casos de uso donde la velocidad no sea crítica (por ejemplo, recopilación de información en segundo plano, pruebas automatizadas de software) en entornos de confianza.
2. Precisión y fiabilidad de la visión por ordenador: 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 comprender el razonamiento del modelo e identificar posibles problemas.
3. Precisión y fiabilidad en 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 fiabilidad puede ser menor al interactuar con aplicaciones especializadas o múltiples aplicaciones a la vez. Indica al modelo con cuidado cuando solicites tareas complejas.
4. Fiabilidad del desplazamiento: Claude Sonnet 3.7 introdujo acciones de desplazamiento dedicadas con control de dirección que mejora la fiabilidad. El modelo ahora puede desplazarse explícitamente en cualquier dirección (arriba/abajo/izquierda/derecha) en 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 para teclas modificadoras. La selección de celdas puede ser más fiable usando estos controles detallados y combinando teclas modificadoras con clics.
6. Creación de cuentas y generación de contenido en plataformas sociales y de comunicación: Aunque Claude visitará sitios web, la capacidad de Claude para crear cuentas o generar y compartir contenido o de otro modo participar en la suplantación de personas en sitios web y plataformas de redes sociales es limitada. Esta capacidad puede actualizarse en el futuro.
7. Vulnerabilidades: Las vulnerabilidades como el jailbreaking o la inyección de prompts pueden persistir en los sistemas de IA de frontera, incluida la API de uso del ordenador en beta. En algunas circunstancias, Claude seguirá comandos encontrados en el contenido, a veces incluso 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 hacer que Claude cometa errores. Considera lo siguiente: a. Limitar el uso del ordenador a entornos de confianza como máquinas virtuales o contenedores con privilegios mínimos b. Evitar dar acceso al uso del ordenador a cuentas o datos sensibles sin una supervisión estricta c. Informar a los usuarios finales de los riesgos relevantes y obtener su consentimiento antes de habilitar o solicitar los permisos necesarios para las funciones de uso del ordenador en tus aplicaciones
8. Acciones inapropiadas o ilegales: Según los términos de servicio de Anthropic, no debes emplear el uso del ordenador para violar ninguna ley ni la Política de Uso Aceptable.

Revisa y verifica siempre cuidadosamente las acciones y registros de uso del ordenador de Claude. No uses Claude para tareas que requieran precisión perfecta o información sensible del usuario sin supervisión humana.

Retención de datos

El uso del ordenador 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 las 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.

Dado que tu aplicación controla dónde y cómo se almacenan los datos de uso del ordenador, el uso del ordenador es elegible para ZDR. Para la elegibilidad ZDR en todas las funciones, consulta 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