Ferramenta de uso do computador

O Claude pode interagir com ambientes de computador por meio da ferramenta de uso do computador, que fornece capacidades de captura de tela e controle de mouse/teclado para interação autônoma com o desktop. No WebArena, um benchmark para navegação web autônoma em sites reais, o Claude alcança resultados de ponta entre sistemas de agente único, demonstrando forte capacidade de completar tarefas de navegador em múltiplas etapas de ponta a ponta.

Visão geral

O uso do computador é um recurso beta que permite ao Claude interagir com ambientes de desktop. Esta ferramenta fornece:

• Captura de tela: Veja o que está sendo exibido atualmente na tela
• Controle do mouse: Clique, arraste e mova o cursor
• Entrada de teclado: Digite texto e use atalhos de teclado
• Automação de desktop: Interaja com qualquer aplicativo ou interface

Embora o uso do computador possa ser complementado com outras ferramentas como bash e editor de texto para fluxos de trabalho de automação mais abrangentes, o uso do computador se refere especificamente à capacidade da ferramenta de uso do computador de ver e controlar ambientes de desktop.

Compatibilidade de modelos

O uso do computador está disponível para os seguintes modelos Claude:

Considerações de segurança

O uso do computador é um recurso beta com riscos únicos distintos dos recursos padrão da API. Esses riscos são maiores ao interagir com a internet.

Em algumas circunstâncias, o Claude seguirá comandos encontrados no conteúdo mesmo que conflitem com as instruções do usuário. Por exemplo, instruções do Claude em páginas web ou contidas em imagens podem substituir instruções ou fazer o Claude cometer erros. Tome precauções para isolar o Claude de dados e ações sensíveis para evitar riscos relacionados à injeção de prompt.

O modelo foi treinado para resistir a essas injeções de prompt, e uma camada extra de defesa foi adicionada. Se você usar as ferramentas de uso do computador, classificadores serão executados automaticamente em seus prompts para sinalizar possíveis instâncias de injeções de prompt. Quando esses classificadores identificam possíveis injeções de prompt em capturas de tela, eles automaticamente direcionam o modelo a pedir confirmação do usuário antes de prosseguir com a próxima ação. Essa proteção extra não será ideal para todos os casos de uso (por exemplo, casos de uso sem um humano no loop), portanto, se você quiser desativar e desligá-la, entre em contato com o suporte.

Essas precauções continuam sendo importantes mesmo com a camada de defesa do classificador em vigor.

Informe os usuários finais sobre os riscos relevantes e obtenha o consentimento deles antes de habilitar o uso do computador em seus próprios produtos.

Início rápido

Veja como começar a usar o uso do computador:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20251124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ]
  }'

Como funciona o uso do computador

A repetição dos passos 3 e 4 sem entrada do usuário é chamada de "loop de agente" (ou seja, o Claude respondendo com uma solicitação de uso de ferramenta e sua aplicação respondendo ao Claude com os resultados da avaliação dessa solicitação).

O ambiente de computação

O uso do computador requer um ambiente de computação isolado onde o Claude pode interagir com segurança com aplicativos e a web. Este ambiente inclui:

1. Display virtual: Um servidor de display X11 virtual (usando Xvfb) que renderiza a interface de desktop que o Claude verá por meio de capturas de tela e controlará com ações de mouse/teclado.

2. Ambiente de desktop: Uma interface de usuário leve com gerenciador de janelas (Mutter) e painel (Tint2) rodando no Linux, que fornece uma interface gráfica consistente para o Claude interagir.

3. Aplicativos: Aplicativos Linux pré-instalados como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos que o Claude pode usar para completar tarefas.

4. Implementações de ferramentas: Código de integração que traduz as solicitações abstratas de ferramentas do Claude (como "mover mouse" ou "tirar captura de tela") em operações reais no ambiente virtual.

5. Loop de agente: Um programa que lida com a comunicação entre o Claude e o ambiente, enviando as ações do Claude para o ambiente e retornando os resultados (capturas de tela, saídas de comandos) de volta ao Claude.

Quando você usa o uso do computador, o Claude não se conecta diretamente a este ambiente. Em vez disso, sua aplicação:

1. Recebe as solicitações de uso de ferramenta do Claude
2. As traduz em ações no seu ambiente de computação
3. Captura os resultados (capturas de tela, saídas de comandos, etc.)
4. Retorna esses resultados ao Claude

Para segurança e isolamento, a implementação de referência executa tudo isso dentro de um contêiner Docker com mapeamentos de porta apropriados para visualizar e interagir com o ambiente.

Como implementar o uso do computador

Comece com a implementação de referência

Uma implementação de referência está disponível e inclui tudo o que você precisa para começar rapidamente com o uso do computador:

• Um ambiente containerizado adequado para uso do computador com Claude
• Implementações das ferramentas de uso do computador
• Um loop de agente que interage com a API Claude e executa as ferramentas de uso do computador
• Uma interface web para interagir com o contêiner, loop de agente e ferramentas.

Entendendo o loop de múltiplos agentes

O núcleo do uso do computador é o "loop de agente" - um ciclo onde o Claude solicita ações de ferramentas, sua aplicação as executa e retorna os resultados ao Claude. Aqui está um exemplo simplificado:

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Add iteration limit to prevent infinite loops
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
        if "20250124" in tool_version
        else "computer-use-2024-10-22"
    )

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {
            "type": f"computer_{tool_version}",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        },
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"},
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Call the Claude API
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking,
        )

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

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": result}
                )

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

O loop continua até que o Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou o limite máximo de iterações seja atingido. Essa salvaguarda evita possíveis loops infinitos que poderiam resultar em custos inesperados de API.

Experimente a implementação de referência antes de ler o restante desta documentação.

Otimize o desempenho do modelo com prompting

Aqui estão algumas dicas sobre como obter as melhores saídas de qualidade:

1. Especifique tarefas simples e bem definidas e forneça instruções explícitas para cada etapa.
2. O Claude às vezes assume os resultados de suas ações sem verificar explicitamente seus resultados. Para evitar isso, você pode solicitar ao Claude com Após cada etapa, tire uma captura de tela e avalie cuidadosamente se você alcançou o resultado correto. Mostre explicitamente seu raciocínio: "Avaliei a etapa X..." Se não estiver correto, tente novamente. Somente quando você confirmar que uma etapa foi executada corretamente você deve passar para a próxima.
3. Alguns elementos de interface do usuário (como menus suspensos e barras de rolagem) podem ser difíceis para o Claude manipular usando movimentos do mouse. Se você encontrar isso, tente solicitar ao modelo que use atalhos de teclado.
4. Para tarefas repetíveis ou interações de interface do usuário, inclua capturas de tela de exemplo e chamadas de ferramentas de resultados bem-sucedidos em seu prompt.
5. Se você precisar que o modelo faça login, forneça o nome de usuário e a senha em seu prompt dentro de tags xml como <robot_credentials>. Usar o uso do computador em aplicativos que exigem login aumenta o risco de resultados ruins como resultado de injeção de prompt. Revise o guia sobre mitigação de injeções de prompt antes de fornecer ao modelo credenciais de login.

Prompts do sistema

Quando uma das ferramentas definidas pela Anthropic é solicitada via API Claude, um prompt do sistema específico para uso do computador é gerado. É semelhante ao prompt do sistema de uso de ferramentas, mas começa com:

Você tem acesso a um conjunto de funções que pode usar para responder à pergunta do usuário. Isso inclui acesso a um ambiente de computação isolado. Você NÃO tem atualmente a capacidade de inspecionar arquivos ou interagir com recursos externos, exceto invocando as funções abaixo.

Assim como no uso regular de ferramentas, o campo system_prompt fornecido pelo usuário ainda é respeitado e usado na construção do prompt do sistema combinado.

Ações disponíveis

A ferramenta de uso do computador suporta estas ações:

Ações básicas (todas as versões)

• screenshot - Captura o display atual
• left_click - Clica nas coordenadas [x, y]
• type - Digita uma string de texto
• key - Pressiona uma tecla ou combinação de teclas (por exemplo, "ctrl+s")
• mouse_move - Move o cursor para as coordenadas

Ações aprimoradas (computer_20250124) Disponíveis nos modelos Claude 4 e Claude Sonnet 3.7:

• scroll - Rola em qualquer direção com controle de quantidade
• left_click_drag - Clica e arrasta entre coordenadas
• right_click, middle_click - Botões adicionais do mouse
• double_click, triple_click - Múltiplos cliques
• left_mouse_down, left_mouse_up - Controle fino de clique
• hold_key - Mantém uma tecla pressionada por uma duração especificada (em segundos)
• wait - Pausa entre ações

Ações aprimoradas (computer_20251124) Disponíveis no Claude Opus 4.6 e Claude Opus 4.5:

• Todas as ações de computer_20250124
• zoom - Visualiza uma região específica da tela em resolução completa. Requer enable_zoom: true na definição da ferramenta. Aceita um parâmetro region com coordenadas [x1, y1, x2, y2] definindo os cantos superior esquerdo e inferior direito da área a inspecionar.

Parâmetros da ferramenta

Habilitar capacidade de pensamento nos modelos Claude 4 e Claude Sonnet 3.7

O Claude Sonnet 3.7 introduziu uma nova capacidade de "pensamento" que permite ver o processo de raciocínio do modelo enquanto ele trabalha em tarefas complexas. Este recurso ajuda você a entender como o Claude está abordando um problema e pode ser particularmente valioso para fins de depuração ou educacionais.

Para habilitar o pensamento, adicione um parâmetro thinking à sua solicitação de API:

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

O parâmetro budget_tokens especifica quantos tokens o Claude pode usar para pensar. Isso é subtraído do seu orçamento geral de max_tokens.

Quando o pensamento está habilitado, o Claude retornará seu processo de raciocínio como parte da resposta, o que pode ajudá-lo a:

1. Entender o processo de tomada de decisão do modelo
2. Identificar possíveis problemas ou equívocos
3. Aprender com a abordagem do Claude para resolução de problemas
4. Obter mais visibilidade em operações complexas de múltiplas etapas

Aqui está um exemplo de como a saída de pensamento pode parecer:

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

Aumentando o uso do computador com outras ferramentas

A ferramenta de uso do computador pode ser combinada com outras ferramentas para criar fluxos de trabalho de automação mais poderosos. Isso é particularmente útil quando você precisa:

• Executar comandos do sistema (ferramenta bash)
• Editar arquivos de configuração ou scripts (ferramenta de editor de texto)
• Integrar com APIs ou serviços personalizados (ferramentas personalizadas)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20251124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

Construir um ambiente personalizado de uso do computador

A implementação de referência tem como objetivo ajudá-lo a começar a usar o computador. Ela inclui todos os componentes necessários para que Claude use um computador. No entanto, você pode construir seu próprio ambiente para uso do computador de acordo com suas necessidades. Você precisará de:

• Um ambiente virtualizado ou em contêiner adequado para uso do computador com Claude
• Uma implementação de pelo menos uma das ferramentas de uso do computador definidas pela Anthropic
• Um loop de agente que interage com a API Claude e executa os resultados de tool_use usando suas implementações de ferramentas
• Uma API ou interface de usuário que permite a entrada do usuário para iniciar o loop de agente

Implementar a ferramenta de uso do computador

A ferramenta de uso do computador é implementada como uma ferramenta sem esquema. Ao usar essa ferramenta, você não precisa fornecer um esquema de entrada como com outras ferramentas; o esquema está integrado ao modelo Claude e não pode ser modificado.

Tratar erros

Ao implementar a ferramenta de uso do computador, vários erros podem ocorrer. Veja como tratá-los:

Tratar o dimensionamento de coordenadas para resoluções mais altas

A API limita imagens a um máximo de 1568 pixels na borda mais longa e aproximadamente 1,15 megapixels no total (consulte redimensionamento de imagem para detalhes). Por exemplo, uma tela de 1512x982 é reduzida para aproximadamente 1330x864. Claude analisa essa imagem menor e retorna coordenadas nesse espaço, mas sua ferramenta executa cliques no espaço original da tela.

Isso pode fazer com que as coordenadas de clique do Claude errem seus alvos, a menos que você trate a transformação de coordenadas.

Para corrigir isso, redimensione as screenshots você mesmo e escale as coordenadas do Claude de volta:

import math


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# When capturing screenshot
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Resize image to scaled dimensions before sending to Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# When handling Claude's coordinates, scale them back up
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Seguir as melhores práticas de implementação

Entender as limitações do uso do computador

A funcionalidade de uso do computador está em beta. Embora as capacidades do Claude sejam de ponta, os desenvolvedores devem estar cientes de suas limitações:

1. Latência: a latência atual do uso do computador para interações humano-IA pode ser muito lenta em comparação com ações de computador direcionadas por humanos regulares. Concentre-se em casos de uso onde a velocidade não é crítica (por exemplo, coleta de informações em segundo plano, testes automatizados de software) em ambientes confiáveis.
2. Precisão e confiabilidade da visão computacional: Claude pode cometer erros ou alucinar ao gerar coordenadas específicas durante a geração de ações. Claude Sonnet 3.7 introduz a capacidade de raciocínio que pode ajudá-lo a entender o raciocínio do modelo e identificar possíveis problemas.
3. Precisão e confiabilidade na seleção de ferramentas: Claude pode cometer erros ou alucinar ao selecionar ferramentas durante a geração de ações ou tomar ações inesperadas para resolver problemas. Além disso, a confiabilidade pode ser menor ao interagir com aplicações de nicho ou múltiplas aplicações ao mesmo tempo. Instrua o modelo com cuidado ao solicitar tarefas complexas.
4. Confiabilidade de rolagem: Claude Sonnet 3.7 introduziu ações de rolagem dedicadas com controle de direção que melhora a confiabilidade. O modelo agora pode rolar explicitamente em qualquer direção (cima/baixo/esquerda/direita) por uma quantidade especificada.
5. Interação com planilhas: Os cliques do mouse para interação com planilhas melhoraram no Claude Sonnet 3.7 com a adição de ações de controle de mouse mais precisas como left_mouse_down, left_mouse_up e novo suporte a teclas modificadoras. A seleção de células pode ser mais confiável usando esses controles refinados e combinando teclas modificadoras com cliques.
6. Criação de contas e geração de conteúdo em plataformas sociais e de comunicação: Embora Claude visite sites, a capacidade do Claude de criar contas ou gerar e compartilhar conteúdo ou de outra forma se envolver em personificação humana em sites e plataformas de mídia social é limitada. Essa capacidade pode ser atualizada no futuro.
7. Vulnerabilidades: Vulnerabilidades como jailbreaking ou injeção de prompt podem persistir em sistemas de IA de fronteira, incluindo a API beta de uso do computador. Em algumas circunstâncias, Claude seguirá comandos encontrados no conteúdo, às vezes mesmo em conflito com as instruções do usuário. Por exemplo, instruções do Claude em páginas da web ou contidas em imagens podem substituir instruções ou fazer com que Claude cometa erros. Considere o seguinte: a. Limitar o uso do computador a ambientes confiáveis, como máquinas virtuais ou contêineres com privilégios mínimos b. Evitar dar acesso ao uso do computador a contas ou dados sensíveis sem supervisão rigorosa c. Informar os usuários finais sobre os riscos relevantes e obter seu consentimento antes de habilitar ou solicitar permissões necessárias para recursos de uso do computador em suas aplicações
8. Ações inapropriadas ou ilegais: De acordo com os termos de serviço da Anthropic, você não deve empregar o uso do computador para violar quaisquer leis ou a Política de Uso Aceitável.

Sempre revise e verifique cuidadosamente as ações e logs de uso do computador do Claude. Não use Claude para tarefas que exigem precisão perfeita ou informações sensíveis do usuário sem supervisão humana.

Retenção de dados

O uso do computador é uma ferramenta do lado do cliente. Todas as screenshots, ações do mouse, entradas do teclado e quaisquer arquivos envolvidos em uma sessão são capturados e armazenados em seu ambiente, não pela Anthropic. A Anthropic processa as imagens de screenshot e as solicitações de ação em tempo real como parte da chamada de API, mas não as retém após o retorno da resposta.

Como sua aplicação controla onde e como os dados de uso do computador são armazenados, o uso do computador é elegível para ZDR. Para elegibilidade ZDR em todos os recursos, consulte API e retenção de dados.

Preços

Computer use follows the standard tool use pricing. When using the computer use tool:

System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt

Computer use tool token usage:

Additional token consumption:

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

Próximos passos