Ferramenta de uso do computador

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



Visão geral

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

• Captura de tela: Ver o que está atualmente exibido na tela
• Controle do mouse: Clicar, arrastar e mover o cursor
• Entrada de teclado: Digitar texto e usar atalhos de teclado
• Automação de desktop: Interagir com qualquer aplicação 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 refere-se especificamente à capacidade da ferramenta de uso do computador de ver e controlar ambientes de desktop.

Para suporte de modelos, consulte a Referência de ferramentas.



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, Claude seguirá comandos encontrados em conteúdo mesmo que entrem em conflito com as instruções do usuário. Por exemplo, instruções para Claude em páginas web ou contidas em imagens podem substituir instruções ou fazer com que Claude cometa erros. Tome precauções para isolar Claude de dados e ações sensíveis para evitar riscos relacionados a injeção de prompt.

A Anthropic treinou o modelo para resistir a essas injeções de prompt e adicionou uma camada extra de defesa. 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), então se você quiser desativá-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 com o uso do computador:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",  # or another compatible model
    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."}],
    betas=["computer-use-2025-11-24"],
)
print(response)



Como funciona o uso do computador

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



O ambiente de computação

O uso do computador requer um ambiente de computação isolado (sandbox) onde Claude possa interagir com segurança com aplicações e a web. Este ambiente inclui:

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

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

3. Aplicações: Aplicações Linux pré-instaladas como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos que Claude pode usar para concluir tarefas.

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

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

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

1. Recebe as requisições de uso de ferramentas de Claude
2. Traduz essas requisições em ações no seu ambiente de computação
3. Captura os resultados (como capturas de tela e saídas de comandos)
4. Retorna esses resultados para 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 com o uso do computador:

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



Entendendo o loop agêntico

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

O loop continua até que Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou até que o limite máximo de iterações seja atingido. Essa salvaguarda previne 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 saídas da melhor qualidade:

1. Especifique tarefas simples e bem definidas e forneça instruções explícitas para cada etapa.
2. Claude às vezes assume resultados de suas ações sem verificar explicitamente seus resultados. Para evitar isso, você pode instruir Claude com 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. Alguns elementos de UI (como menus suspensos e barras de rolagem) podem ser difíceis para Claude manipular usando movimentos do mouse. Se você enfrentar isso, tente instruir o modelo a usar atalhos de teclado.
4. Para tarefas repetíveis ou interações de UI, inclua capturas de tela de exemplo e chamadas de ferramentas de resultados bem-sucedidos no seu prompt.
5. Se você precisar que o modelo faça login, forneça o nome de usuário e a senha no seu prompt dentro de tags XML como <robot_credentials>. Usar o uso do computador em aplicações que exigem login aumenta o risco de resultados ruins como consequência de injeção de prompt. Revise Mitigar jailbreaks e injeções de prompt antes de fornecer credenciais de login ao modelo.
6. Ao construir o array content de um turno do usuário, coloque o texto de instrução antes da imagem de captura de tela. Fornecer a descrição do alvo antes de a imagem ser processada melhora a precisão do clique.
7. Ao usar computer_20251124 com enable_zoom: true definido, Claude amplia uma região quando perguntado sobre texto pequeno ou elementos específicos de UI que não são legíveis na resolução padrão da captura de tela, como nomes de arquivos em uma barra lateral, títulos de abas, texto da barra de status, números de linha ou rótulos de botões. Se Claude não estiver ampliando quando você espera, pergunte sobre uma região ou elemento específico em vez da tela como um todo.



Prompts do sistema

Quando uma das ferramentas com esquema da Anthropic é solicitada através da API do 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:

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.

Assim como no uso de ferramentas regular, 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: Capturar o display atual
• left_click: Clicar nas coordenadas [x, y]
• type: Digitar string de texto
• key: Pressionar tecla ou combinação de teclas (por exemplo, "ctrl+s")
• mouse_move: Mover cursor para coordenadas

Ações aprimoradas (computer_20250124) Disponíveis em todos os modelos que suportam uso do computador:

• scroll: Rolar em qualquer direção com controle de quantidade
• left_click_drag: Clicar e arrastar 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 refinado de clique
• hold_key: Manter uma tecla pressionada por uma duração especificada (em segundos)
• wait: Pausar entre ações

Ações aprimoradas (computer_20251124) Disponíveis em Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5:

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



Parâmetros da ferramenta



Combinando com pensamento estendido

Para combinar o uso do computador com pensamento estendido, consulte Pensamento estendido.



Complementando o uso do computador com outras ferramentas

Para adicionar outras ferramentas junto com o uso do computador, inclua-as no mesmo array tools. A seção Início rápido mostra esse padrão com a ferramenta bash e a ferramenta de editor de texto. Você pode adicionar suas próprias definições de ferramentas personalizadas da mesma forma.



Construa um ambiente personalizado de uso do computador

A implementação de referência foi criada para ajudar você a começar com o uso do 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 conteinerizado adequado para uso do computador com Claude
• Uma implementação de pelo menos uma das ferramentas de uso do computador com esquema da Anthropic
• Um loop de agente que interage com a API do Claude e executa os resultados de tool_use usando suas implementações de ferramentas
• Uma API ou UI que permite entrada do usuário para iniciar o loop de agente



Implemente a ferramenta de uso do computador

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



Trate erros

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



Dimensione capturas de tela para caber nos limites de imagem

Capturas de tela enviadas para a ferramenta de computador já devem caber dentro dos limites de tamanho de imagem de Claude (consulte limites de tamanho de imagem). A API não redimensiona imagens grandes demais; uma captura de tela que excede o limite é rejeitada com um erro de validação HTTP 400.

Se sua tela for maior que o limite, redimensione a captura de tela antes de enviá-la, defina display_width_px/display_height_px para as dimensões redimensionadas e escale as coordenadas retornadas por Claude de volta para o espaço da tela original:



Diagnostique problemas de clique

Se os cliques erram seus alvos, a causa geralmente é uma das seguintes:



Siga as melhores práticas de implementação



Entenda as limitações do uso de computador

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

1. Latência: A "latency" (latência) atual do uso de computador para interações humano-IA pode ser muito lenta em comparação com ações regulares de computador dirigidas por humanos. 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: O Claude pode cometer erros ou alucinar ao gerar coordenadas específicas durante a geração de ações. O pensamento estendido pode ajudar você a entender o raciocínio do modelo e identificar possíveis problemas.
3. Precisão e confiabilidade na seleção de ferramentas: O 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 várias aplicações ao mesmo tempo. Elabore o prompt do modelo com cuidado ao solicitar tarefas complexas.
4. Confiabilidade da rolagem: A ação de rolagem suporta controle de direção (para cima, para baixo, esquerda, direita) e uma quantidade especificada. Em aplicações onde a rolagem não surte efeito, alternativas de teclado como Page Down podem ajudar.
5. Interação com planilhas: Use as ações de controle refinado do mouse (left_mouse_down, left_mouse_up) e combinações de teclas modificadoras para selecionar células individuais. Operações complexas em planilhas ainda podem exigir várias tentativas.
6. Criação de contas e geração de conteúdo em plataformas sociais e de comunicação: Embora o 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 de computador. Em algumas circunstâncias, o Claude seguirá comandos encontrados em conteúdo, às vezes até mesmo em conflito com as instruções do usuário. Por exemplo, instruções para o Claude em páginas da web ou contidas em imagens podem substituir instruções ou fazer com que o Claude cometa erros. Considere o seguinte: a. Limitar o uso de computador a ambientes confiáveis, como máquinas virtuais ou contêineres com privilégios mínimos b. Evitar dar ao uso de computador acesso 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 de computador em suas aplicações
8. Ações inadequadas ou ilegais: De acordo com os Termos de Serviço da Anthropic, você não deve empregar o uso de 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 de computador do Claude. Não use o 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 de computador é uma ferramenta do lado do cliente. Todas as capturas de tela, ações do mouse, entradas de teclado e quaisquer arquivos envolvidos em uma sessão são capturados e armazenados no seu ambiente, não pela Anthropic. A Anthropic processa as imagens de captura de tela e solicitações de ação em tempo real como parte da chamada de API, mas não as retém após a resposta ser retornada.

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



Preços

O uso do computador segue a precificação padrão de uso de ferramentas. Ao usar a ferramenta de uso do computador:

Sobrecarga do prompt do sistema: O beta de uso do computador adiciona de 466 a 499 tokens ao prompt do sistema

Uso de tokens da ferramenta de uso do computador:

Consumo adicional de tokens:

• Imagens de captura de tela (consulte Precificação de Visão)
• Resultados de execução de ferramentas retornados ao Claude



Próximos passos