Herramienta de uso de computadora

​

Descripción general

• 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

​

Compatibilidad de modelos

​

Consideraciones de seguridad

​

Inicio rápido

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",  # o otro modelo compatible
    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."}],
    betas=["computer-use-2025-01-24"]
)
print(response)

​

Cómo funciona el uso de computadora

​

El entorno informático

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.

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

​

Cómo implementar el uso de computadora

​

Comience con nuestra implementación de referencia

• 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 múltiples agentes

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,  # Agregue límite de iteración para prevenir bucles infinitos
):
    """
    Un bucle de agente simple para interacciones de uso de computadora de Claude.

    Esta función maneja la ida y vuelta entre:
    1. Enviar mensajes del usuario a Claude
    2. Claude solicitando usar herramientas
    3. Su aplicación ejecutando esas herramientas
    4. Enviando resultados de herramientas de vuelta a Claude
    """
    # Configurar herramientas y parámetros de 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"

    # Configurar herramientas - ya debería tenerlas inicializadas en otro lugar
    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"}
    ]

    # Bucle de agente principal (con límite de iteración para prevenir costos de API desbocados)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Configurar parámetro de pensamiento opcional (para Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Llamar a la API de Claude
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking
        )

        # Agregar la respuesta de Claude al historial de conversación
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Verificar si Claude usó alguna herramienta
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # En una aplicación real, ejecutaría la herramienta aquí
                # Por ejemplo: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Formatear el resultado para Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Si no se usaron herramientas, Claude ha terminado - devuelva los mensajes finales
        if not tool_results:
            return messages

        # Agregar resultados de herramientas a mensajes para la siguiente iteración con Claude
        messages.append({"role": "user", "content": tool_results})

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2025-01-24"]

​

Optimizar el rendimiento del modelo con indicaciones

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 prevenir esto, puede indicar a Claude con Después de cada paso, tome una captura de pantalla y evalúe cuidadosamente si ha logrado el resultado correcto. Muestre explícitamente su pensamiento: "He evaluado el paso X..." Si no es correcto, intente de nuevo. Solo cuando confirme que un paso fue ejecutado correctamente debe pasar al siguiente.
3. Algunos elementos de interfaz de usuario (como menús desplegables y barras de desplazamiento) pueden 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. Por favor revise nuestra guía sobre mitigación de inyecciones de indicaciones antes de proporcionar al modelo credenciales de inicio de sesión.

​

Indicadores del sistema

Tiene acceso a un conjunto de funciones que puede usar para responder la pregunta del usuario. Esto incluye acceso a un entorno informático aislado. Actualmente NO tiene la capacidad de inspeccionar archivos o interactuar con recursos externos, excepto invocando las siguientes funciones.

​

Acciones disponibles

• screenshot - Capturar la pantalla actual
• left_click - Hacer clic en 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

• 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 una tecla mientras se realizan otras acciones
• wait - Pausar entre acciones

// Tomar una captura de pantalla
{
  "action": "screenshot"
}

// Hacer clic en posición
{
  "action": "left_click",
  "coordinate": [500, 300]
}

// Escribir texto
{
  "action": "type",
  "text": "Hello, world!"
}

// Desplazarse hacia abajo (Claude 4/3.7)
{
  "action": "scroll",
  "coordinate": [500, 400],
  "scroll_direction": "down",
  "scroll_amount": 3
}

​

Parámetros de herramienta

​

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

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

1. Entender 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 en operaciones complejas de múltiples pasos

[Pensamiento]
Necesito guardar una imagen de un gato en el escritorio. Déjame desglosar esto en pasos:

1. Primero, tomaré una captura de pantalla para ver qué hay en el escritorio
2. Luego buscaré un navegador web para buscar imágenes de gatos
3. Después de encontrar una imagen adecuada, necesitaré guardarla en el escritorio

Déjame comenzar tomando una captura de pantalla para ver qué está disponible...

​

Aumentar el uso de computadora con otras herramientas

• Ejecutar comandos del sistema (herramienta bash)
• Editar archivos de configuración o scripts (herramienta editor de texto)
• Integrar con APIs personalizadas o servicios (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-01-24" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 2000,
    "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
    }
  }'

​

Construir un entorno de uso de computadora personalizado

• 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 definidas por Anthropic
• Un bucle de agente que interactúe con la API de Claude y ejecute los resultados de tool_use usando sus implementaciones de herramientas
• Una API o interfaz de usuario que permita entrada del usuario para iniciar el bucle de agente

​

Implementar la herramienta de uso de computadora

def handle_computer_action(action_type, params):
    if action_type == "screenshot":
        return capture_screenshot()
    elif action_type == "left_click":
        x, y = params["coordinate"]
        return click_at(x, y)
    elif action_type == "type":
        return type_text(params["text"])
    # ... manejar otras acciones

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)
        
        # Devolver resultado a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

while True:
    response = client.beta.messages.create(...)
    
    # Verificar si Claude usó alguna herramienta
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # Sin más uso de herramienta, tarea completada
        break
        
    # Continuar conversación con resultados de herramientas
    messages.append({"role": "user", "content": tool_results})

​

Manejar errores

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Coordinates (1200, 900) are outside display bounds (1024x768).",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to perform click action. The application may be unresponsive.",
      "is_error": true
    }
  ]
}

​

Seguir mejores prácticas de implementación

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Permitir que la interfaz de usuario se actualice

def validate_action(action_type, params):
    if action_type == "left_click":
        x, y = params.get("coordinate", (0, 0))
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging

def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

​

Entender las limitaciones del uso de computadora

1. Latencia: la latencia actual del uso de computadora para interacciones humano-IA puede ser demasiado lenta en comparación con acciones de computadora dirigidas por humanos regulares. Recomendamos enfocarse 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 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 ayudarle a entender el razonamiento del modelo e identificar posibles problemas.
3. Precisión y confiabilidad de 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 cuando se interactúa con aplicaciones de nicho o múltiples aplicaciones a la vez. Recomendamos que los usuarios indiquen al modelo cuidadosamente cuando soliciten tareas complejas.
4. Confiabilidad de 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 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.
6. Creación de cuentas y generación de contenido en plataformas sociales y de comunicaciones: Aunque Claude visitará sitios web, estamos limitando su capacidad para crear cuentas o generar y compartir contenido u otro compromiso en suplantación de identidad humana en sitios web y plataformas de redes sociales. Podemos actualizar esta capacidad en el futuro.
7. Vulnerabilidades: Las vulnerabilidades como jailbreaking o inyección de indicaciones pueden persistir en sistemas de IA fronteriza, incluyendo la API beta de uso de computadora. En algunas circunstancias, Claude seguirá comandos encontrados en 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 causar que Claude cometa errores. Recomendamos: a. Limitar el uso de computadora a entornos confiables como máquinas virtuales o contenedores con privilegios mínimos b. Evitar dar acceso de uso de computadora a cuentas sensibles o datos sin supervisión estricta c. Informar a los usuarios finales de los riesgos relevantes y obtener su consentimiento antes de habilitar o solicitar permisos necesarios para características de uso de computadora en sus aplicaciones
8. Acciones inapropiadas o ilegales: Según los términos de servicio de Anthropic, no debe usar el uso de computadora para violar ninguna ley o nuestra Política de Uso Aceptable.

​

Precios

• Screenshot images (see Vision pricing)
• Tool execution results returned to Claude

​

Próximos pasos