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 mouse/teclado para la interacción autónoma con el escritorio.

La herramienta de uso de computadora es un conjunto de herramientas de cliente definido por Anthropic: una entrada {"type": "computer_toolset_20260801"} en tools le da a Claude 17 herramientas miembro como screenshot, left_click, type y zoom, y tu aplicación ejecuta cada llamada en un entorno que tú controlas. Actualmente no está disponible en Claude Managed Agents. Las llamadas de Claude son bloques tool_use cuyo name es el miembro y que llevan "toolset_name": "computer", a menudo varios en un mismo turno (una acción por lotes).

Para tareas que se mantienen dentro de páginas web, la herramienta de uso del navegador es la opción más adecuada: sus herramientas miembro leen y actúan sobre la propia página, y no necesita un entorno de escritorio completo.

Consulta Compatibilidad con la API para ver los modelos y plataformas que admiten el “toolset” (conjunto de herramientas). Versiones anteriores de la herramienta enumera el “beta header” (encabezado beta) de cada versión anterior y los modelos con los que usarla.

Consideraciones de seguridad

El uso de computadora tiene riesgos únicos, distintos de las funciones estándar de la API. Estos riesgos aumentan al interactuar con internet.

En algunas circunstancias, Claude sigue comandos encontrados en el contenido incluso cuando entran en conflicto con tus instrucciones. Por ejemplo, las instrucciones en páginas web o contenidas en imágenes podrían anular tus instrucciones o hacer que Claude cometa errores. Toma precauciones para aislar a Claude de datos y acciones sensibles a fin de evitar riesgos relacionados con la “prompt injection” (inyección de prompts).

Anthropic ha entrenado al modelo para resistir estas inyecciones de prompts y ha añadido una capa adicional de defensa. Si usas la herramienta de uso de computadora, unos clasificadores analizan automáticamente lo que devuelve la herramienta, como las capturas de pantalla, para señalar posibles inyecciones de prompts. Cuando estos clasificadores identifican una posible inyección de prompts, orientan al modelo para que verifique si la instrucción realmente provino de ti antes de actuar en consecuencia.

Esta protección adicional no es ideal para todos los casos de uso (por ejemplo, casos de uso sin una persona en el ciclo), así que si quieres excluirte y desactivarla, contacta con soporte. Las precauciones indicadas anteriormente siguen siendo importantes incluso con estos clasificadores activos.

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

Inicio rápido

Agrega el conjunto de herramientas de uso de computadora al arreglo tools de una solicitud a la Messages APIVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. como {"type": "computer_toolset_20260801"}. La solicitud no necesita ningún encabezado beta. Este ejemplo también declara la herramienta de edición de texto y la herramienta bash, que Claude suele usar junto con el uso de computadora:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"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."}],
)
print(response)

Cuando Claude actúa sobre el escritorio, la respuesta tiene un stop_reason de tool_use y contiene uno o más bloques tool_use de miembros, cada uno nombrando una herramienta miembro y llevando "toolset_name": "computer". A mitad de esta tarea, después de que Claude haya recibido una captura de pantalla del escritorio, una respuesta podría verse así:

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Tu aplicación ejecuta cada llamada en orden en tu propio entorno, devuelve un bloque tool_result por cada bloque tool_use y vuelve a llamar a la API; Cómo funciona el uso de computadora describe ese bucle, y el resto de esta página muestra cómo implementarlo.

Cómo funciona el uso de computadora

1. 1

   Proporciona a Claude la herramienta de uso de computadora y un prompt de usuario

   • Agrega el conjunto de herramientas de uso de computadora (y opcionalmente otras herramientas) al arreglo tools de tu solicitud a la API.
   • Incluye un prompt de usuario que requiera interacción con el escritorio, por ejemplo, “Guarda una imagen de un gato en mi escritorio.”
2. 2

   Claude responde con llamadas a herramientas miembro

   • Claude evalúa si actuar sobre el escritorio puede ayudar con la consulta del usuario.
   • Si es así, Claude responde con uno o más bloques tool_use de miembros, como screenshot, left_click o type, cada uno con "toolset_name": "computer". Una respuesta con varios de estos bloques es una acción por lotes.
   • La respuesta de la API tiene un stop_reason de tool_use, lo que indica una solicitud de uso de herramientas.
3. 3

   Ejecuta las llamadas en orden y devuelve los resultados

   • Recorre cada bloque tool_use de la respuesta, en orden. Para cada uno, despacha según el name del miembro junto con toolset_name, y realiza esa acción con el input del bloque en tu contenedor o máquina virtual.
   • Continúa la conversación con un nuevo mensaje user que contenga un bloque tool_result por cada bloque tool_use, emparejados por tool_use_id y cada uno repitiendo "toolset_name": "computer". Devuelve una imagen para screenshot y zoom; un texto breve como OK es suficiente para las demás acciones.
   • Si una acción falla, devuelve is_error: true para ese bloque y responde al resto del lote como se describe en Acciones por lotes.
4. 4

   Claude continúa hasta completar la tarea

   • Claude analiza los resultados de las herramientas para determinar si se necesitan más acciones o si la tarea se ha completado.
   • Si Claude determina que se necesitan más acciones, responde con otro stop_reason de tool_use; vuelve al paso 3.
   • De lo contrario, devuelve una respuesta de texto al usuario.

La repetición de los pasos 3 y 4 sin intervención del usuario forma el “agent loop” (bucle del agente): Claude responde con una solicitud de uso de herramientas y tu aplicación responde a Claude con los resultados de evaluar esa solicitud.

Acciones por lotes

Claude puede planificar una secuencia corta de acciones, como hacer clic, escribir y luego tomar una captura de pantalla, y devolverlas juntas en una sola respuesta. Esto se llama “batch action” (acción por lotes); usa la misma forma de respuesta que el uso de herramientas en paralelo con una diferencia: ejecutas los bloques en orden en lugar de hacerlo de forma concurrente.

Una respuesta con un lote de tres acciones se ve así:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

Devuelve un bloque tool_result por cada bloque tool_use, emparejados por tool_use_id, todos en el siguiente mensaje user. Cada resultado de una herramienta miembro debe llevar "toolset_name": "computer"; un resultado que lo omita, o que nombre un conjunto de herramientas distinto al de su bloque tool_use, se rechaza. Solo los resultados de screenshot y zoom necesitan una imagen; para los demás miembros, basta con un breve reconocimiento de texto como OK (cursor_position devuelve las coordenadas como texto):

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

Ejecuta los bloques en orden y detente en el primer fallo. Las acciones posteriores de un lote suelen depender de las anteriores: el type de este ejemplo introduce texto en lo que sea que haya enfocado el clic anterior. Ejecuta los bloques secuencialmente en el orden en que aparecen en content y, si uno falla, no ejecutes el resto. Cada bloque tool_use sigue necesitando un tool_result, así que responde al lote de la siguiente manera:

• Para cada acción que tuvo éxito, devuelve su resultado normal.
• Para la acción que falló, devuelve is_error: true con una descripción de texto de lo que salió mal.
• Para cada acción posterior del lote, devuelve is_error: true con exactamente este texto (la herramienta de uso del navegador usa su propio texto de detención):

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

Claude lee entonces qué acciones tuvieron éxito, cuál falló y cuáles se omitieron, y replanifica en su siguiente turno. Una solicitud que deja sin responder algún bloque tool_use del lote se rechaza con un invalid_request_error, por lo que un bucle del agente que lee solo el primer bloque falla en su siguiente llamada. Si tu aplicación le pide a una persona que confirme acciones con consecuencias, haz esa comprobación antes de ejecutar cada bloque, porque un lote puede completar una acción de varios pasos dentro de un solo turno.

Claude suele terminar un lote con screenshot para poder observar el resultado antes de decidir qué hacer a continuación. Cuando un lote no termina con una, tu aplicación puede adjuntar una captura de pantalla como un bloque image adicional en el último resultado del lote para que Claude siempre reciba el estado actual de la pantalla, lo que ahorra un viaje de ida y vuelta en comparación con esperar a que Claude la pida. También puedes pedirle a Claude en el prompt que termine cada lote con una captura de pantalla (consulta Optimizar el rendimiento del modelo con prompts).

El entorno de computación

El uso de computadora requiere un entorno de computación aislado (sandbox) 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 recibe como capturas de pantalla y controla con acciones de mouse/teclado.

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

3. Aplicaciones: Aplicaciones de 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 mouse” o “tomar captura de pantalla”) en operaciones reales en el entorno virtual.

5. Bucle del 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 de computación.
3. Captura los resultados (como capturas de pantalla y salidas de comandos).
4. Devuelve estos resultados a Claude.

Por seguridad y aislamiento, la implementación de referencia ejecuta todo esto dentro de un contenedor Docker con las asignaciones de puertos apropiadas para ver el entorno e interactuar con él.

Cómo implementar el uso de computadora

¿Actualizas una integración existente de computer_20251124? Comienza con Migra desde computer_20251124; el resto de esta sección se aplica tanto a integraciones nuevas como migradas.

Comprender el bucle del agente

El núcleo del uso de computadora es el “bucle del agente”: un ciclo en el que Claude solicita acciones de herramientas y tu aplicación las ejecuta y devuelve los resultados a Claude. El bucle usa el cliente que creaste en el Inicio rápido, un arreglo tools que declara solo el conjunto de herramientas de uso de computadora, y la función auxiliar de procesamiento de llamadas a herramientas de Implementar la herramienta de uso de computadora. Si también declaras otras herramientas, como las herramientas bash y de edición de texto del Inicio rápido, despacha sus bloques tool_use en la misma pasada; la función auxiliar solo responde a las llamadas de miembros del uso de computadora, y el bucle trata un turno sin llamadas respondidas como completado. Aquí tienes un ejemplo simplificado:

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # Add Claude's response to the conversation history
        messages.append({"role": "assistant", "content": response.content})

        # Run the actions Claude requested, in order, and collect the results
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Send every result back to Claude in a single user message
        messages.append({"role": "user", "content": tool_results})

    return messages

El bucle continúa hasta que Claude responde sin solicitar ninguna herramienta (tarea completada) o se alcanza el límite máximo de iteraciones. Esta salvaguarda evita posibles bucles infinitos que podrían generar costos inesperados de API.

Optimizar el rendimiento del modelo con prompts

1. Especifica tareas bien definidas y proporciona instrucciones explícitas para cada paso.
2. A veces Claude actúa como si sus acciones hubieran tenido éxito sin comprobar explícitamente sus resultados. Para evitarlo, puedes indicarle a Claude en el prompt After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, 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 (como los menús desplegables y las barras de desplazamiento) pueden ser difíciles de manipular para Claude usando movimientos del mouse. Si te ocurre esto, intenta pedirle al modelo que use atajos de teclado.
4. Para tareas repetibles o interacciones con la interfaz, incluye en tu prompt capturas de pantalla de ejemplo y llamadas a herramientas de resultados exitosos.
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>. Usar 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 Mitigar jailbreaks e inyecciones de prompts antes de proporcionarle al modelo credenciales de inicio de sesión.
6. Al construir el arreglo content de un turno de usuario, coloca el texto de la instrucción antes de la imagen de la captura de pantalla. Proporcionar la descripción del objetivo antes de que se procese la imagen mejora la precisión de los clics.
7. Claude usa la acción zoom para inspeccionar una región a resolución completa cuando se le pregunta por texto pequeño o elementos específicos de la interfaz que no son legibles con la resolución predeterminada de la captura de pantalla, como nombres de archivos en una barra lateral, títulos de pestañas, texto de la barra de estado, números de línea o etiquetas de botones. Si Claude no hace zoom cuando lo esperas, pregunta por una región o elemento específico en lugar de por la pantalla en su conjunto.
8. Si quieres que cada acción por lotes termine con una captura de pantalla, indícalo en la indicación del sistema, por ejemplo, End each group of actions with a screenshot so you can verify the result before continuing.

Si te encuentras repetidamente con un conjunto claro de problemas, o conoces de antemano las tareas que Claude tiene que completar, dale a Claude consejos o instrucciones explícitas para ellas en la indicación del sistema.

Para agentes que abarcan varias sesiones, ejecuta una verificación de extremo a extremo al inicio de cada sesión, no solo después de la implementación. Las comprobaciones basadas en el navegador detectan regresiones de sesiones anteriores que la revisión a nivel de código por sí sola pasa por alto. Consulta Effective harnesses for long-running agents para más detalles.

Indicaciones del sistema

Cuando incluyes la herramienta de uso de computadora en una solicitud, la API genera una “system prompt” (indicación del sistema) específica para el 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.

Al igual que con el uso de herramientas habitual, el parámetro system proporcionado por el usuario se sigue respetando y se usa en la construcción de la indicación del sistema combinada.

Acciones disponibles

Cada acción es una herramienta miembro del conjunto de herramientas de uso de computadora: Claude nombra al miembro en un bloque tool_use que lleva "toolset_name": "computer", y el input del bloque contiene solo los parámetros de ese miembro, sin campo action. El conjunto de herramientas tiene 17 herramientas miembro:

Ten en cuenta lo siguiente al implementar los miembros:

• Las coordenadas están en píxeles de la captura de pantalla. Cada valor de coordinate, start_coordinate y region, y la posición que informa cursor_position, está en el espacio de píxeles de las capturas de pantalla completas que devuelves, con el origen en la esquina superior izquierda. Las imágenes de zoom no cambian esto: después de un zoom, Claude sigue expresando las coordenadas en el espacio de la captura de pantalla completa, nunca en relación con la imagen ampliada. Si reduces la escala de las capturas de pantalla antes de devolverlas, vuelve a escalar las coordenadas de Claude antes de aplicarlas a la pantalla real (consulta Ajusta el tamaño de las capturas de pantalla a los límites de imagen).
• Todos los miembros están habilitados por defecto, incluido zoom. Si tu entorno no puede producir imágenes de zoom, excluye el miembro con configs (consulta Parámetros de la herramienta) en lugar de dejarlo habilitado y devolver errores. Si Claude llama a un miembro que has excluido o que no implementas, devuelve un tool_result con is_error: true para ese bloque.
• Despacha según el par (toolset_name, name). toolset_name es lo que marca un bloque como una acción de computadora: una herramienta personalizada en la misma solicitud puede compartir el nombre de un miembro, y una versión posterior del conjunto de herramientas puede añadir miembros (consulta Conjuntos de herramientas de cliente).

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

Parámetros de la herramienta

La entrada del conjunto de herramientas en el arreglo tools acepta cuatro parámetros; las reglas que comparten con el conjunto de herramientas de uso del navegador se enumeran en Conjuntos de herramientas de cliente.

Por ejemplo, esta entrada excluye zoom para un entorno que no lo implementa y establece un punto de interrupción de caché en la definición del conjunto de herramientas:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

Si tu bucle del agente solo puede ejecutar una acción por cada viaje de ida y vuelta, establece disable_parallel_tool_use en true en tool_choice; entonces Claude devuelve como máximo un bloque tool_use de miembro por turno (consulta Deshabilitar el uso de herramientas en paralelo).

La entrada rechaza estos parámetros de versiones anteriores de la herramienta, y una solicitud que incluya cualquiera de ellos devuelve un invalid_request_error:

• name: los nombres de los miembros están fijados por la versión del conjunto de herramientas.
• display_width_px, display_height_px y display_number: las coordenadas siempre están en el espacio de píxeles de las capturas de pantalla que devuelves.
• enable_zoom: zoom es una herramienta miembro que controlas mediante configs.

Además, la entrada no puede declararse en la misma solicitud que una entrada computer_20251124 u otra herramienta llamada computer. Para strict, input_examples, la ubicación de defer_loading, tool_choice, streaming y las restricciones de llamadores, consulta Conjuntos de herramientas de cliente.

Combinar con el pensamiento

Para combinar el uso de computadora con el pensamiento, consulta Pensamiento.

Ampliar el uso de computadora con otras herramientas

Para añadir otras herramientas junto con el uso de computadora, inclúyelas en el mismo arreglo tools. La sección Inicio rápido muestra este patrón con la herramienta bash y la herramienta de edición de texto. Puedes añadir tus propias definiciones de herramientas personalizadas de la misma manera.

Para tareas que se mantienen dentro de páginas web, también puedes declarar la herramienta de uso del navegador en la misma solicitud. Los dos conjuntos de herramientas funcionan de forma independiente, cada uno en su propio marco de coordenadas. El valor de toolset_name distingue las llamadas a miembros que comparten nombre, como screenshot o key.

Crear un entorno personalizado de uso de computadora

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

• Un entorno virtualizado o en contenedor adecuado para el uso de computadora con Claude
• Una implementación de las acciones de la herramienta de uso de computadora
• Un bucle del agente que interactúe con la Claude API y ejecute los resultados tool_use usando tus implementaciones de herramientas
• Una API o interfaz 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. 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.

1. 1

   Configura tu entorno de computación

   Crea una pantalla virtual o conéctate a una pantalla existente con la que Claude interactúa. Esto normalmente implica configurar Xvfb (X Virtual Framebuffer) o una tecnología similar.

2. 2

   Implementa los manejadores de acciones

   Crea funciones para manejar cada tipo de acción que Claude pueda solicitar:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # Placeholder image data; a real executor captures the screen and returns the PNG bytes
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot answers with an image block rather than text: return the result content list
       return [
           {
               "type": "image",
               "source": {
                   "type": "base64",
                   "media_type": "image/png",
                   "data": PLACEHOLDER_PNG,
               },
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate is optional; without it, click where the cursor already is
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # Handle other actions as needed
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Procesa las llamadas a herramientas de Claude

   Extrae y ejecuta las llamadas a herramientas de las respuestas de Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # Only the computer toolset is declared; route other tools here if you add them
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # A string, or a list of content blocks such as the screenshot image
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   Implementa el bucle del agente

   Envuelve los dos pasos anteriores en un bucle que devuelva los resultados y se repita hasta que Claude no devuelva llamadas a herramientas miembro; Comprender el bucle del agente muestra este bucle.

Manejar errores

Informa a Claude de una acción fallida como un tool_result con is_error: true y una breve descripción, e incluye "toolset_name": "computer" como en cualquier otro resultado de miembro. Si la acción fallida formaba parte de una acción por lotes, responde a los bloques restantes del lote con el texto de detención que se muestra allí en lugar de ejecutarlos.

Por ejemplo, cuando falla la captura de pantalla:

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

Usa la misma forma para coordenadas fuera de los límites de la pantalla y para acciones que no se pueden ejecutar, con un mensaje que indique qué salió mal.

Ajusta el tamaño de las capturas de pantalla a los límites de imagen

Las capturas de pantalla y las imágenes de zoom que devuelves al conjunto de herramientas de uso de computadora ya deben ajustarse a los límites de tamaño de imagen de tu modelo: el conjunto de herramientas no acepta dimensiones de pantalla y la API no reduce la escala por ti, por lo que una imagen tool_result de tamaño excesivo se rechaza con un error de validación. Como Claude devuelve coordenadas en el espacio de píxeles de la imagen que recibe, conserva el factor de escala que usaste para poder asignar esas coordenadas de vuelta a tu pantalla.

Si tu pantalla es más grande que el límite, redimensiona cada captura de pantalla antes de devolverla y escala las coordenadas que devuelve Claude de vuelta al espacio original de la pantalla. Como el conjunto de herramientas no acepta dimensiones de pantalla, el redimensionamiento y el escalado de coordenadas en el código de tu aplicación es todo lo que necesitas:

import math

screen_width, screen_height = 1512, 982


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)


# Al capturar una captura de pantalla
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Redimensiona la imagen a las dimensiones escaladas antes de enviarla a Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# Al manejar las coordenadas de Claude, vuelve a escalarlas al tamaño original
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Cuando elijas una resolución de pantalla y devuelvas capturas de pantalla:

• Para tareas generales de escritorio, usa 1024x768 o 1280x720; para aplicaciones web, usa 1280x800 o 1366x768.
• Evita resoluciones superiores a 1920x1080 para prevenir problemas de rendimiento.
• Codifica las capturas de pantalla como PNG o JPEG en base64, y considera comprimir las capturas grandes para mejorar el rendimiento.
• Incluye metadatos relevantes, como la marca de tiempo o el estado de la pantalla.
• Si usas resoluciones más altas, asegúrate de que las coordenadas se escalen con precisión.

Administra el historial de capturas de pantalla

Los bucles de agente largos acumulan capturas de pantalla rápidamente (aproximadamente entre 1,000 y 1,800 tokens de entrada cada una). También se aplican los límites de solicitud de la API.

Una vez que una sola solicitud contiene más de 20 imágenes, cada imagen en ella queda sujeta a un límite por lado más estricto. Un bucle que conserva su historial de capturas de pantalla puede alcanzar esa cantidad. Redimensiona cada captura para mantenerte por debajo de ese límite, o elimina las capturas más antiguas para mantener 20 o menos en la solicitud.

Para mantener eficaz el almacenamiento en caché de prompts mientras limitas el contexto:

• Coloca un punto de interrupción cache_control después de la indicación del sistema y las definiciones de herramientas, y hasta tres más en el último bloque tool_result de cada uno de los turnos más recientes, avanzándolos en cada turno. Dentro de una acción por lotes, los marcadores en varios bloques actúan como un único punto de interrupción, pero cada uno sigue contando para el límite de cuatro, así que usa como máximo uno por turno.
• Elimina las capturas de pantalla antiguas en lotes, no una en cada turno. Omitir una captura en cada turno cambia el prefijo en cada turno e invalida la caché. Un valor predeterminado razonable es conservar las últimas tres capturas y eliminar cada 25 turnos, para que el prefijo se mantenga idéntico byte a byte entre eventos de eliminación; si tus capturas superan el límite más estricto, elige un intervalo que mantenga cada solicitud con 20 imágenes o menos.
• Evita eliminar en el cliente en Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 y Claude Mythos 5.1. Lo mismo aplica para Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5. En estos modelos, quitar una captura de pantalla anterior de una solicitud invalida todos los bloques de pensamiento posteriores que ya están en el historial de esa solicitud y de todas las solicitudes posteriores.
  • En su lugar: Redimensiona las capturas de pantalla para mantenerte por debajo del límite más estricto. La eliminación de resultados de herramientas ahorra tokens, pero las capturas de pantalla eliminadas siguen contando para los límites de solicitud, así que usa la compactación bajo demanda antes de que un bucle los alcance.
  • Si debes eliminar: Mantén prefix_mismatch_behavior: "drop_block" configurado a partir de ese momento. Después de cada eliminación, la API omite los bloques de pensamiento invalidados, en esa solicitud y en todas las posteriores. Así, Claude continúa sin el pensamiento que produjo después de la captura de pantalla eliminada.
  • Si debes eliminar en Claude Sonnet 5.5 o Claude Haiku 5.5: prefix_mismatch_behavior funciona solo con thinking: {"type": "adaptive"}. Con cualquier otra configuración de pensamiento en esos modelos, mantén el historial solo de anexado o elimina todos los bloques thinking y redacted_thinking posteriores a la captura de pantalla eliminada.

Diagnostica problemas de clics

Si los clics no aciertan en sus objetivos, la causa suele ser una de las siguientes:

Sigue las mejores prácticas de implementación

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        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}")

Migra desde computer_20251124

Una integración de computer_20251124 funciona sin cambios en los modelos indicados para esa versión en Versiones anteriores de la herramienta. Actualiza la integración antes de moverla a un modelo que no acepte computer_20251124, como Claude Opus 5.5 en la Claude API.

Para actualizar, realiza los siguientes cambios en conjunto:

1. Quita el encabezado beta. Omite anthropic-beta: computer-use-2025-11-24 de tus solicitudes. Con el SDK, quita betas y llama a la Messages API a través del cliente estándar en lugar del espacio de nombres beta.
2. Cambia la entrada de tools. Establece type en computer_toolset_20260801 y elimina name, display_width_px, display_height_px, display_number y enable_zoom. El conjunto de herramientas rechaza cada uno de estos campos.
3. Elige si mantener el zoom habilitado. El zoom está habilitado de forma predeterminada en el conjunto de herramientas, mientras que enable_zoom tiene como valor predeterminado false. Si tu entorno no implementa el zoom, agrega "configs": {"zoom": {"enabled": false}} para mantener el comportamiento anterior; de lo contrario, impleméntalo (consulta Acciones disponibles).
4. Maneja cada bloque de un turno. Actualiza tu bucle de agente para iterar sobre cada bloque tool_use de una respuesta en lugar de leer solo el primero, y para despachar según el name del bloque junto con toolset_name en lugar de según input.action. Las entradas de los miembros ya no contienen un campo action; los campos restantes no cambian.
5. Ejecuta los bloques en orden y usa el texto de detención. Ejecuta los bloques de forma secuencial, detente en el primer fallo y responde a los bloques restantes con Not executed: an earlier computer action in this turn failed. como se describe en Acciones por lotes. Si tu bucle aún no puede ejecutar lotes, Parámetros de la herramienta explica cómo limitar a Claude a una acción por turno.
6. Repite toolset_name en los resultados. Agrega "toolset_name": "computer" a cada tool_result que responda a una llamada de un miembro. Los resultados solo pueden contener contenido text e image.
7. Admite repeat en key. El miembro key acepta un conteo opcional repeat de 1 a 100. Un controlador que ignore los campos no reconocidos presionaría la tecla una sola vez, así que haz que tu controlador de key respete repeat.
8. Redimensiona las capturas de pantalla tú mismo. El conjunto de herramientas rechaza una captura de pantalla o imagen de zoom que supere los límites de imagen del modelo en lugar de reducir su escala. Redimensiona antes de devolver la imagen y sigue escalando las coordenadas como se describe en Ajusta el tamaño de las capturas de pantalla a los límites de imagen.
9. Quita las opciones no admitidas. Mueve cualquier defer_loading de la entrada a configs, con el mismo valor en cada miembro habilitado. Las demás opciones no admitidas en las entradas de conjuntos de herramientas se enumeran en Conjuntos de herramientas de cliente.

Esta es la entrada de tools antes del cambio, enviada con el encabezado anthropic-beta: computer-use-2025-11-24:

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

Esta es la entrada de tools después del cambio, enviada sin encabezado beta. El objeto configs mantiene el zoom desactivado para coincidir con la entrada anterior, que no establece enable_zoom; omite configs por completo para aceptar el valor predeterminado y permitir que Claude use el zoom:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

El siguiente par muestra un bloque tool_use antes y después del cambio. El nombre de la acción pasa de input.action a name, y el bloque incorpora toolset_name:

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

Versiones anteriores de la herramienta

Hay dos versiones anteriores de la herramienta de uso de computadora disponibles en beta. Cada una requiere su encabezado beta en cada solicitud, y sus parámetros están documentados en la referencia de la API de Messages betaVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. Con el SDK, pasa el encabezado mediante betas y usa el espacio de nombres beta; solo la herramienta de uso de computadora necesita el encabezado, no las herramientas bash o de editor de texto en la misma solicitud.

En Amazon Bedrock, Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5 también aceptan la herramienta computer_20251124 con el encabezado beta computer-use-2025-11-24. Con la API InvokeModel de Amazon Bedrock, envía computer-use-2025-11-24 en el arreglo anthropic_beta del cuerpo de la solicitud en lugar de en un encabezado. Para esa API, consulta Claude en Amazon Bedrock (bedrock-runtime).

Limitaciones

1. Latencia: La latencia del uso de computadora para interacciones humano-IA podría ser demasiado lenta en comparación con las acciones de computadora habituales dirigidas por humanos. Concéntrate 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 computadora: Claude podría cometer errores o alucinar al generar coordenadas específicas mientras genera acciones. La salida de pensamiento resumido de Claude puede ayudarte a entender el razonamiento del modelo e identificar posibles problemas; establece display: "summarized" en la configuración de pensamiento, porque los modelos que admiten el conjunto de herramientas omiten el texto de pensamiento de forma predeterminada.
3. Precisión y fiabilidad en la selección de herramientas: Claude podría cometer errores o alucinar al seleccionar herramientas mientras genera acciones, o realizar acciones inesperadas para resolver problemas. Además, la fiabilidad podría ser menor al interactuar con aplicaciones de nicho o con varias aplicaciones a la vez. Redacta las indicaciones al modelo con cuidado cuando solicites tareas complejas.
4. Fiabilidad del desplazamiento: La acción de desplazamiento admite control de dirección (arriba, abajo, izquierda, derecha) y una cantidad especificada. En aplicaciones donde el desplazamiento no surte efecto, las alternativas de teclado como Page Down pueden ayudar.
5. Interacción con hojas de cálculo: Usa las acciones de control fino del mouse (left_mouse_down, left_mouse_up) y combinaciones con teclas modificadoras para seleccionar celdas individuales. Las operaciones complejas en hojas de cálculo aún podrían requerir varios intentos.
6. Creación de cuentas y generación de contenido en plataformas sociales y de comunicación: Aunque Claude visita sitios web, su capacidad para crear cuentas, generar y compartir contenido o, de otro modo, suplantar a humanos en sitios web y plataformas de redes sociales es limitada.
7. Vulnerabilidades: Los jailbreaks y la inyección de prompts pueden afectar al uso de computadora como a cualquier sistema de IA de frontera, incluso mediante instrucciones incrustadas en páginas web o imágenes; aplica las precauciones de Consideraciones de seguridad.
8. Acciones inapropiadas o ilegales: Según los Términos de Servicio de Anthropic, no debes emplear el uso de computadora para violar ninguna ley ni la Política de Uso Aceptable.

Revisa y verifica siempre con cuidado las acciones y los registros del uso de computadora de Claude. No uses Claude para tareas que requieran precisión perfecta ni información sensible de usuarios 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 mouse, 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 las capturas y las solicitudes de acciones en tiempo real como parte de la llamada a la API. La retención de esas solicitudes a la API se rige por API y retención de datos.

Como tu aplicación controla dónde y cómo se almacenan los datos del uso de computadora, el uso de computadora es apto para ZDR.

Precios

El uso de computadora sigue los precios estándar de uso de herramientas. Al usar la herramienta de uso de computadora:

Sobrecarga de la definición del conjunto de herramientas: Declarar computer_toolset_20260801 con sus miembros predeterminados agrega aproximadamente 4,500 tokens de entrada a una solicitud (aproximadamente 4,590 en Claude Sonnet 5 y aproximadamente 4,520 en los demás modelos compatibles), lo que cubre las definiciones de las herramientas miembro y la indicación del sistema de uso de herramientas. Deshabilitar zoom con configs elimina aproximadamente 410 de esos tokens. El recuento exacto de una solicitud se informa en el campo usage de la respuesta, y puedes estimarlo de antemano con el endpoint de conteo de tokens.

Versiones anteriores de la herramienta: Las siguientes cifras se aplican a las versiones de herramienta computer_20251124 y computer_20250124, no a computer_toolset_20260801:

• Sobrecarga de la indicación del sistema: 466–499 tokens agregados a la indicación del sistema
• Definición de la herramienta: aproximadamente 735 tokens de entrada por definición de herramienta (medido con computer_20250124)

Consumo adicional de tokens:

• Imágenes de capturas de pantalla y de zoom devueltas en los resultados de herramientas, facturadas como entrada de imagen (consulta Precios de visión)
• Resultados de ejecución de herramientas devueltos a Claude

Próximos pasos