Herramienta de uso de computadora

Claude puede interactuar con entornos de computadora a través de la herramienta de "computer use" (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 ("client toolset") 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 por turno (una acción por lotes).

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

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 seguirá comandos encontrados en el contenido incluso cuando entren 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 para evitar riesgos relacionados con la 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 las herramientas de uso de computadora, unos clasificadores analizarán automáticamente lo que devuelven las herramientas, como las capturas de pantalla, para señalar posibles inyecciones de prompts. Cuando estos clasificadores identifican una posible inyección de prompts, guiarán automáticamente al modelo para que verifique si la instrucción realmente provino de ti antes de actuar en consecuencia.

Esta protección adicional no será ideal para todos los casos de uso (por ejemplo, casos de uso sin una persona en el ciclo), así que si deseas excluirte y desactivarla, contacta a soporte. Las precauciones anteriores siguen siendo importantes incluso con estos clasificadores en funcionamiento.

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

Agrega el conjunto de herramientas de uso de computadora al arreglo tools de una solicitud de la Messages API como {"type": "computer_toolset_20260801"}. La solicitud no necesita encabezado beta. Este ejemplo también declara la herramienta de editor de texto y la herramienta bash, que Claude normalmente usa 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 ha visto 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 llama a la API de nuevo; Cómo funciona el uso de computadora describe ese ciclo, 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 llevando "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

   • Itera sobre cada bloque tool_use en 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 corto como OK es suficiente para las demás acciones.
   • Si una acción falla, devuelve is_error: true para ese bloque y responde el resto del lote como se describe en Acciones por lotes.
4. 4

   Claude continúa hasta que la tarea esté completa

   • 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 y debes volver 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 se conoce como el "agent loop" (ciclo del agente), es decir, Claude respondiendo con una solicitud de uso de herramientas y tu aplicación respondiendo 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 una "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 concurrentemente.

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 diferente al de su bloque tool_use, es rechazado. Solo los resultados de screenshot y zoom necesitan una imagen; para los demás miembros, un breve acuse de recibo en texto como OK es suficiente (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 en un lote normalmente dependen de las anteriores: el type en este ejemplo introduce texto en lo que sea que el clic anterior haya enfocado. Ejecuta los bloques secuencialmente en el orden en que aparecen en content, y si uno falla, no ejecutes el resto. Cada bloque tool_use aún necesita un tool_result, así que responde el 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 en texto de lo que salió mal.
• Para cada acción posterior en el lote, devuelve is_error: true con exactamente este texto (la herramienta de uso de 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 entonces ve qué acciones tuvieron éxito, cuál falló y cuáles se omitieron, y replanifica en su siguiente turno. Una solicitud que deje sin responder cualquier bloque tool_use del lote es rechazada con un invalid_request_error, por lo que un ciclo del agente que lea solo el primer bloque falla en su siguiente llamada. Si tu aplicación pide a un humano que confirme acciones con consecuencias, haz esa verificación antes de que se ejecute cada bloque, porque un lote puede completar una acción de varios pasos dentro de un solo turno.

Claude normalmente termina 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 vea 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 indicarle a Claude que termine cada lote con una captura de pantalla (consulta Optimiza el rendimiento del modelo con prompts).

El entorno de cómputo

El uso de computadora requiere un entorno de cómputo aislado (sandbox) donde Claude pueda interactuar de forma segura con aplicaciones y la web. Este entorno incluye:

1. Pantalla virtual: Un servidor de pantalla virtual X11 (usando Xvfb) que renderiza la interfaz de escritorio que Claude verá a través de capturas de pantalla y controlará con acciones de mouse/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 con la que Claude puede interactuar.

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 mouse" o "tomar captura de pantalla") en operaciones reales en el entorno virtual.

5. Ciclo del 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 usas el uso de computadora, Claude no se conecta directamente a este entorno. En su lugar, tu aplicación:

1. Recibe las solicitudes de uso de herramientas de Claude
2. Las traduce en acciones en tu entorno de cómputo
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 los mapeos de puertos apropiados para ver e interactuar con el entorno.

Cómo implementar el uso de computadora

¿Estás actualizando una integración existente de computer_20251124? Comienza con Migrar desde computer_20251124; el resto de esta sección aplica tanto a integraciones nuevas como migradas.

Comprende el ciclo del agente

El núcleo del uso de computadora es el "ciclo del agente": un ciclo donde Claude solicita acciones de herramientas, tu aplicación las ejecuta y devuelve los resultados a Claude. El ciclo 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 el ayudante de procesamiento de llamadas a herramientas de Implementa la herramienta de uso de computadora. Si también declaras otras herramientas, como las herramientas bash y de editor de texto del Inicio rápido, despacha sus bloques tool_use en la misma pasada; el ayudante responde solo las llamadas a miembros de uso de computadora, y el ciclo trata un turno sin llamadas respondidas como terminado. Aquí hay 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,
        )

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

        # Ejecuta las acciones que Claude solicitó, en orden, y recopila los resultados
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Envía todos los resultados de vuelta a Claude en un solo mensaje de usuario
        messages.append({"role": "user", "content": tool_results})

    return messages

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

Optimiza el rendimiento del modelo con prompts

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 verificarlos explícitamente. Para prevenir esto puedes indicarle a Claude 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 (como menús desplegables y barras de desplazamiento) pueden ser difíciles de manipular para Claude usando movimientos del mouse. Si experimentas esto, intenta indicarle al modelo que use atajos de teclado.
4. Para tareas o interacciones de interfaz repetibles, 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 proporcionar 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 sobre texto pequeño o elementos específicos de la interfaz que no son legibles a 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 sobre una región o elemento específico en lugar de la pantalla en su conjunto.
8. Si quieres que cada acción por lotes termine con una captura de pantalla, dilo en la indicación del sistema, por ejemplo, End each group of actions with a screenshot so you can verify the result before continuing.

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 regular, 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 reporta 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 relativas a la imagen ampliada. Si reduces las capturas de pantalla antes de devolverlas, escala las coordenadas de Claude de vuelta hacia arriba antes de aplicarlas a la pantalla real (consulta Dimensiona las capturas de pantalla para ajustarse 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, retén 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 retenido 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 agregar 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 de navegador se enumeran en Conjuntos de herramientas de cliente.

Por ejemplo, esta entrada retiene 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 ciclo del agente solo puede ejecutar una acción por viaje de ida y vuelta, establece disable_parallel_tool_use en true en tool_choice; Claude entonces 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 a través de configs.

La entrada tampoco 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 restricciones de llamador, consulta Conjuntos de herramientas de cliente.

Combinación con el pensamiento

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

Aumentar el uso de computadora con otras herramientas

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

Para tareas que permanecen dentro de páginas web, también puedes declarar la herramienta de uso de navegador en la misma solicitud: los dos conjuntos de herramientas funcionan de forma independiente, cada uno en su propio marco de coordenadas, y las llamadas a miembros que comparten nombre, como screenshot o key, se distinguen por toolset_name.

Construye un entorno de uso de computadora personalizado

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 construir tu propio entorno para el uso de computadora que se adapte a tus necesidades. Necesitarás:

• 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 ciclo del agente que interactúe con la Claude API 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 ciclo del agente

Implementa 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 puede modificarse.

1. 1

   Configura tu entorno de cómputo

   Crea una pantalla virtual o conéctate a una pantalla existente con la que Claude interactuará. 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 podría solicitar:

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Datos de imagen de marcador de posición; un ejecutor real captura la pantalla y devuelve los bytes PNG
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot responde con un bloque de imagen en lugar de texto: devuelve la lista de contenido del resultado
       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 es opcional; sin él, haz clic donde ya está el cursor
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # Maneja otras acciones según sea necesario
       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

   

   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:
           # Solo se declara el conjunto de herramientas computer; enruta otras herramientas aquí si las agregas
           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:
                   # Una cadena, o una lista de bloques de contenido como la imagen de la captura de pantalla
                   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 ciclo del agente

   Envuelve los dos pasos anteriores en un ciclo que envíe los resultados de vuelta y se repita hasta que Claude no devuelva llamadas a herramientas miembro; Comprende el ciclo del agente muestra este ciclo en cada lenguaje.

Maneja los errores

Reporta una acción fallida a Claude como un tool_result con is_error: true y una descripción corta, e incluye "toolset_name": "computer" como en cualquier otro resultado de miembro. Si la acción fallida era parte de una acción por lotes, responde los bloques restantes del lote con el texto de detención mostrado 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 logran ejecutarse, con un mensaje que diga qué salió mal.

Dimensiona las capturas de pantalla para ajustarse 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 recibe dimensiones de pantalla y la API no reduce la escala por ti, por lo que una imagen de tool_result demasiado grande es rechazada con un error de validación. Dado que Claude devuelve coordenadas en el espacio de píxeles de la imagen que ve, conserva el factor de escala que usaste para poder mapear 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 devueltas por Claude de vuelta al espacio original de la pantalla. Dado que el conjunto de herramientas no recibe dimensiones de pantalla, el redimensionamiento y el escalado de coordenadas en el código de tu aplicación son 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 la 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 hacia arriba
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 de pantalla 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 estén escaladas con precisión.

Gestionar 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 alcanza ese número en unas pocas docenas de turnos, así que redimensiona cada captura de pantalla para que ningún lado supere los 2000 px o elimina las capturas de pantalla más antiguas para mantener 20 o menos en la solicitud.

Para mantener efectivo 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 uno por turno.
• Elimina las capturas de pantalla antiguas por lotes, no una en cada turno. Descartar una captura de pantalla en cada turno cambia el prefijo en cada turno e invalida la caché. Un valor predeterminado razonable es conservar las últimas tres capturas de pantalla y hacer la eliminación cada 25 turnos, de modo que el prefijo permanezca idéntico byte a byte entre eventos de eliminación; si tus capturas de pantalla superan los 2000 px en cualquiera de sus lados, elige un intervalo que mantenga cada solicitud en 20 imágenes o menos.
• En Claude Fable 5.1, Claude Opus 5.5 y Claude Sonnet 5.5, evita eliminar capturas en el cliente: quitar una captura de pantalla anterior invalida todos los bloques de pensamiento posteriores en cada solicitud que todavía contenga esos turnos. En su lugar, redimensiona las capturas de pantalla a 2000 px o menos por lado y usa la eliminación de resultados de herramientas del lado del servidor para quitar las antiguas del contexto. Si debes eliminarlas, mantén configurado prefix_mismatch_behavior: "drop_block" a partir de ese momento; después de cada eliminación, Claude continúa sin el pensamiento producido desde la captura de pantalla eliminada, en esa solicitud y en todas las posteriores. En Claude Sonnet 5.5, block_binding solo funciona con thinking: {"type": "adaptive"}. Con between_tools, mantén el historial en modo de solo anexado, o elimina los bloques de pensamiento desde el turno editado en adelante.

Diagnosticar problemas de clics

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

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

Migrar desde computer_20251124

Actualizar de computer_20251124 al conjunto de herramientas es opcional: los modelos listados para computer_20251124 en Versiones anteriores de la herramienta siguen aceptándola con su encabezado beta, por lo que una integración existente sigue funcionando hasta que la cambies. Los modelos Claude 5.5 y posteriores son la excepción en la Claude API y Google Cloud: allí solo aceptan el conjunto de herramientas. Actualiza una integración antes de moverla a uno de ellos. En Amazon Bedrock, Claude Opus 5.5 y Claude Sonnet 5.5 siguen aceptando computer_20251124. Para actualizar, realiza los siguientes cambios en conjunto:

1. Elimina el encabezado beta. Quita anthropic-beta: computer-use-2025-11-24 de tus solicitudes. En los SDK, elimina el parámetro betas y llama a la API de Messages 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 en un turno. Actualiza tu bucle de agente para iterar sobre cada bloque tool_use en 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 secuencialmente, detente en el primer fallo y responde 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 miembro. Los resultados solo pueden contener contenido text e image.
7. Admite repeat en key. El miembro key acepta un conteo repeat opcional de 1 a 100. Un manejador que ignore los campos no reconocidos presionaría la tecla una sola vez, así que haz que tu manejador 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 reducirla. Redimensiona antes de devolver la imagen y sigue escalando las coordenadas como se describe en Dimensionar capturas de pantalla para ajustarse a los límites de imagen.
9. Elimina 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 del 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 haga 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 adquiere 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

Dos versiones anteriores de la herramienta de uso de computadora siguen disponibles en beta para integraciones existentes, para modelos que no admiten el conjunto de herramientas y en plataformas donde el conjunto de herramientas no está disponible actualmente. Cada una requiere su encabezado beta en cada solicitud, y sus parámetros están documentados en la referencia de la API de Messages beta. En los SDK, pasa el encabezado a través del parámetro 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.

Limitaciones

1. Latencia: La "latency" (latencia) actual del uso de computadora para interacciones entre humanos e IA podría ser demasiado lenta en comparación con las acciones de computadora habituales dirigidas por humanos. Enfócate en casos de uso donde la velocidad no sea crítica (por ejemplo, recopilación de información en segundo plano, pruebas de software automatizadas) en entornos de confianza.
2. Precisión y confiabilidad 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 comprender 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 confiabilidad de la selección de herramientas: Claude podría cometer errores o alucinar al seleccionar herramientas mientras genera acciones, o tomar acciones inesperadas para resolver problemas. Además, la confiabilidad podría ser menor al interactuar con aplicaciones de nicho o con varias aplicaciones a la vez. Indica al modelo con cuidado cuando solicites tareas complejas.
4. Confiabilidad 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 tiene 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 de 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 participar en la suplantación de humanos en sitios web y plataformas de redes sociales es limitada.
7. Vulnerabilidades: Los jailbreaks y la inyección de prompts pueden afectar el uso de computadora como pueden afectar a cualquier sistema de IA de frontera, incluso a través de 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 registros de uso de computadora de Claude. No uses Claude para tareas que requieran precisión perfecta o 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 capturas de pantalla y las solicitudes de acciones en tiempo real como parte de la llamada a la API. La retención de esas solicitudes de API se rige por API y retención de datos.

Dado 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 la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.

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,520 en Claude Fable 5, Claude Mythos 5, Claude Opus 5 y Claude Opus 4.8, y aproximadamente 4,590 en Claude Sonnet 5), 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 para una solicitud se informa en el campo usage de la respuesta, y puedes estimarlo con anticipación 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

Compatibility