Ferramenta de uso do computador
Claude pode interagir com ambientes de computador através da ferramenta de uso do computador, que fornece capacidades de captura de tela e controle de mouse/teclado para interação autônoma com desktop.
Claude pode interagir com ambientes de computador através da ferramenta de uso do computador, que fornece capacidades de captura de tela e controle de mouse/teclado para interação autônoma com desktop.
O uso do computador está atualmente em beta e requer um cabeçalho beta:
"computer-use-2025-01-24"
(modelos Claude 4 e 3.7)"computer-use-2024-10-22"
(Claude Sonnet 3.5)
Visão geral
O uso do computador é uma funcionalidade beta que permite ao Claude interagir 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 aumentado 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.
Compatibilidade de modelos
O uso do computador está disponível para os seguintes modelos Claude:
Modelo | Versão da Ferramenta | Flag Beta |
---|---|---|
Claude 4 Opus & Sonnet | computer_20250124 | computer-use-2025-01-24 |
Claude Sonnet 3.7 | computer_20250124 | computer-use-2025-01-24 |
Claude Sonnet 3.5 (novo) | computer_20241022 | computer-use-2024-10-22 |
Os modelos Claude 4 usam versões de ferramentas atualizadas otimizadas para a nova arquitetura. Claude Sonnet 3.7 introduz capacidades adicionais incluindo a funcionalidade de pensamento para mais insights sobre o processo de raciocínio do modelo.
Considerações de segurança
O uso do computador é uma funcionalidade beta com riscos únicos distintos das funcionalidades padrão da API. Esses riscos são aumentados ao interagir com a internet. Para minimizar riscos, considere tomar precauções como:
- Use uma máquina virtual dedicada ou contêiner com privilégios mínimos para prevenir ataques diretos ao sistema ou acidentes.
- Evite dar ao modelo acesso a dados sensíveis, como informações de login de contas, para prevenir roubo de informações.
- Limite o acesso à internet a uma lista de domínios permitidos para reduzir a exposição a conteúdo malicioso.
- Peça a um humano para confirmar decisões que podem resultar em consequências significativas no mundo real, bem como quaisquer tarefas que requeiram consentimento afirmativo, como aceitar cookies, executar transações financeiras ou concordar com termos de serviço.
Em algumas circunstâncias, Claude seguirá comandos encontrados no conteúdo mesmo se conflitar com as instruções do usuário. Por exemplo, instruções do Claude em páginas web ou contidas em imagens podem sobrescrever instruções ou causar erros no Claude. Sugerimos tomar precauções para isolar Claude de dados e ações sensíveis para evitar riscos relacionados à injeção de prompt.
Treinamos o modelo para resistir a essas injeções de prompt e adicionamos uma camada extra de defesa. Se você usar nossas ferramentas de uso do computador, executaremos automaticamente classificadores 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 direcionarão automaticamente o modelo para pedir confirmação do usuário antes de prosseguir com a próxima ação. Reconhecemos que 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 optar por não participar e desligá-la, por favor entre em contato conosco.
Ainda sugerimos tomar precauções para isolar Claude de dados e ações sensíveis para evitar riscos relacionados à injeção de prompt.
Finalmente, por favor informe os usuários finais sobre riscos relevantes e obtenha seu consentimento antes de habilitar o uso do computador em seus próprios produtos.
Implementação de referência do uso do computador
Comece rapidamente com nossa implementação de referência do uso do computador que inclui uma interface web, contêiner Docker, implementações de ferramentas de exemplo e um loop de agente.
Nota: A implementação foi atualizada para incluir novas ferramentas para Claude 4 e Claude Sonnet 3.7. Certifique-se de puxar a versão mais recente do repositório para acessar essas novas funcionalidades.
Por favor use este formulário para fornecer feedback sobre a qualidade das respostas do modelo, a própria API ou a qualidade da documentação - não podemos esperar para ouvir de você!
Início rápido
Aqui está como começar com o uso do computador:
Requisitos de cabeçalho beta:
- Claude 4 e Sonnet 3.7: Cabeçalho beta necessário apenas para a ferramenta de uso do computador
- Claude Sonnet 3.5: Cabeçalho beta necessário para ferramentas de computador, bash e editor de texto
O exemplo acima mostra todas as três ferramentas sendo usadas juntas, o que requer o cabeçalho beta para qualquer modelo Claude, pois inclui a ferramenta de uso do computador.
Como funciona o uso do computador
1. Forneça ao Claude a ferramenta de uso do computador e um prompt do usuário
- Adicione a ferramenta de uso do computador (e opcionalmente outras ferramentas) à sua solicitação da API.
- Inclua um prompt do usuário que requer interação com desktop, por exemplo, “Salve uma imagem de um gato na minha área de trabalho.”
2. Claude decide usar a ferramenta de uso do computador
- Claude avalia se a ferramenta de uso do computador pode ajudar com a consulta do usuário.
- Se sim, Claude constrói uma solicitação de uso de ferramenta formatada adequadamente.
- A resposta da API tem um
stop_reason
detool_use
, sinalizando a intenção do Claude.
3. Extraia a entrada da ferramenta, avalie a ferramenta em um computador e retorne os resultados
- Do seu lado, extraia o nome da ferramenta e a entrada da solicitação do Claude.
- Use a ferramenta em um contêiner ou Máquina Virtual.
- Continue a conversa com uma nova mensagem
user
contendo um bloco de conteúdotool_result
.
4. Claude continua chamando ferramentas de uso do computador até completar a tarefa
- Claude analisa os resultados da ferramenta para determinar se mais uso de ferramenta é necessário ou se a tarefa foi completada.
- Se Claude decidir que precisa de outra ferramenta, ele responde com outro
stop_reason
detool_use
e você deve retornar ao passo 3. - Caso contrário, ele elabora uma resposta de texto para o usuário.
Nos referimos à repetição dos passos 3 e 4 sem entrada do usuário como o “loop do agente” - ou seja, 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 Claude pode interagir com segurança com aplicações e a web. Este ambiente inclui:
-
Display virtual: Um servidor de display virtual X11 (usando Xvfb) que renderiza a interface do desktop que Claude verá através de capturas de tela e controlará com ações de mouse/teclado.
-
Ambiente de desktop: Uma UI leve com gerenciador de janelas (Mutter) e painel (Tint2) executando no Linux, que fornece uma interface gráfica consistente para Claude interagir.
-
Aplicações: Aplicações Linux pré-instaladas como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos que Claude pode usar para completar tarefas.
-
Implementações de ferramentas: Código de integração que traduz solicitações abstratas de ferramentas do Claude (como “mover mouse” ou “tirar captura de tela”) em operações reais no ambiente virtual.
-
Loop do agente: Um programa que lida com a comunicação entre 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 para Claude.
Quando você usa o uso do computador, Claude não se conecta diretamente a este ambiente. Em vez disso, sua aplicação:
- Recebe as solicitações de uso de ferramenta do Claude
- As traduz em ações em seu ambiente de computação
- Captura os resultados (capturas de tela, saídas de comandos, etc.)
- 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 nossa implementação de referência
Construímos uma implementação de referência que 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 do agente que interage com a API Anthropic e executa as ferramentas de uso do computador
- Uma interface web para interagir com o contêiner, loop do agente e ferramentas.
Entendendo o loop multi-agente
O núcleo do uso do computador é o “loop do agente” - um ciclo onde Claude solicita ações de ferramentas, sua aplicação as executa e retorna resultados para Claude. Aqui está um exemplo simplificado:
O loop continua até que Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou o limite máximo de iteração seja atingido. Esta salvaguarda previne possíveis loops infinitos que poderiam resultar em custos inesperados da API.
Ao usar a ferramenta de uso do computador, você deve incluir a flag beta apropriada para sua versão do modelo:
Nota: Para Claude 4 e Sonnet 3.7, a flag beta é necessária apenas para a ferramenta de uso do computador. Para Claude Sonnet 3.5, a flag beta é necessária para ferramentas de computador, bash e editor de texto.
Recomendamos experimentar a implementação de referência antes de ler o resto desta documentação.
Otimize o desempenho do modelo com prompting
Aqui estão algumas dicas sobre como obter as melhores saídas de qualidade:
- Especifique tarefas simples e bem definidas e forneça instruções explícitas para cada passo.
- Claude às vezes assume resultados de suas ações sem verificar explicitamente seus resultados. Para prevenir isso, você pode fazer prompt ao Claude com
Após cada passo, tire uma captura de tela e avalie cuidadosamente se você alcançou o resultado correto. Mostre explicitamente seu pensamento: "Eu avaliei o passo X..." Se não estiver correto, tente novamente. Apenas quando você confirmar que um passo foi executado corretamente deve prosseguir para o próximo.
- Alguns elementos da UI (como dropdowns e barras de rolagem) podem ser complicados para Claude manipular usando movimentos do mouse. Se você experimentar isso, tente fazer prompt ao modelo para usar atalhos de teclado.
- Para tarefas repetíveis ou interações de UI, inclua capturas de tela de exemplo e chamadas de ferramentas de resultados bem-sucedidos em seu prompt.
- Se você precisar que o modelo faça login, forneça a ele o nome de usuário e senha em seu prompt dentro de tags xml como
<robot_credentials>
. Usar o uso do computador dentro de aplicações que requerem login aumenta o risco de resultados ruins como resultado de injeção de prompt. Por favor revise nosso guia sobre mitigar injeções de prompt antes de fornecer ao modelo credenciais de login.
Se você encontrar repetidamente um conjunto claro de problemas ou souber antecipadamente as tarefas que Claude precisará completar, use o prompt do sistema para fornecer ao Claude dicas ou instruções explícitas sobre como fazer as tarefas com sucesso.
Prompts do sistema
Quando uma das ferramentas definidas pela Anthropic é solicitada via API Anthropic, um prompt do sistema específico para uso do computador é gerado. É similar ao prompt do sistema de uso de ferramenta 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.
Como com o 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 essas 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 (ex., “ctrl+s”)
- mouse_move - Mover cursor para coordenadas
Ações aprimoradas (computer_20250124
)
Disponível em Claude 4 e Claude Sonnet 3.7:
- 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 de clique de granularidade fina
- hold_key - Segurar uma tecla enquanto executa outras ações
- wait - Pausar entre ações
Parâmetros da ferramenta
Parâmetro | Obrigatório | Descrição |
---|---|---|
type | Sim | Versão da ferramenta (computer_20250124 ou computer_20241022 ) |
name | Sim | Deve ser “computer” |
display_width_px | Sim | Largura do display em pixels |
display_height_px | Sim | Altura do display em pixels |
display_number | Não | Número do display para ambientes X11 |
Mantenha a resolução do display em ou abaixo de 1280x800 (WXGA) para melhor desempenho. Resoluções mais altas podem causar problemas de precisão devido ao redimensionamento de imagem.
Importante: A ferramenta de uso do computador deve ser explicitamente executada por sua aplicação - Claude não pode executá-la diretamente. Você é responsável por implementar a captura de tela, movimentos do mouse, entradas de teclado e outras ações baseadas nas solicitações do Claude.
Habilite a capacidade de pensamento em Claude 4 e Claude Sonnet 3.7
Claude Sonnet 3.7 introduziu uma nova capacidade de “pensamento” que permite ver o processo de raciocínio do modelo enquanto ele trabalha através de tarefas complexas. Esta funcionalidade ajuda você a entender como Claude está abordando um problema e pode ser particularmente valiosa para depuração ou propósitos educacionais.
Para habilitar o pensamento, adicione um parâmetro thinking
à sua solicitação da API:
O parâmetro budget_tokens
especifica quantos tokens Claude pode usar para pensar. Isso é subtraído do seu orçamento geral de max_tokens
.
Quando o pensamento está habilitado, Claude retornará seu processo de raciocínio como parte da resposta, o que pode ajudá-lo a:
- Entender o processo de tomada de decisão do modelo
- Identificar possíveis problemas ou equívocos
- Aprender com a abordagem do Claude para resolução de problemas
- Obter mais visibilidade em operações complexas de múltiplos passos
Aqui está um exemplo de como a saída de pensamento pode parecer:
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 editor de texto)
- Integrar com APIs ou serviços personalizados (ferramentas personalizadas)
Construa um ambiente de uso do computador personalizado
A implementação de referência é destinada a ajudá-lo a começar com o uso do computador. Ela inclui todos os componentes necessários para ter Claude usando um computador. No entanto, você pode construir seu próprio ambiente para uso do computador para atender às suas necessidades. Você precisará:
- Um ambiente virtualizado ou containerizado 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 Anthropic 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 do 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á incorporado no modelo do Claude e não pode ser modificado.
Configure seu ambiente de computação
Crie um display virtual ou conecte-se a um display existente com o qual Claude irá interagir. Isso tipicamente envolve configurar Xvfb (X Virtual Framebuffer) ou tecnologia similar.
Implemente manipuladores de ação
Crie funções para lidar com cada tipo de ação que Claude pode solicitar:
Processe as chamadas de ferramenta do Claude
Extraia e execute chamadas de ferramenta das respostas do Claude:
Implemente o loop do agente
Crie um loop que continua até Claude completar a tarefa:
Lidar com erros
Ao implementar a ferramenta de uso do computador, vários erros podem ocorrer. Aqui está como lidar com eles:
Siga as melhores práticas de implementação
Entenda 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:
- Latência: a latência atual do uso do computador para interações humano-IA pode ser muito lenta comparada às ações regulares de computador dirigidas por humanos. Recomendamos focar em casos de uso onde a velocidade não é crítica (ex., coleta de informações em segundo plano, testes automatizados de software) em ambientes confiáveis.
- Precisão e confiabilidade da visão computacional: Claude pode cometer erros ou alucinar ao produzir coordenadas específicas enquanto gera ações. Claude Sonnet 3.7 introduz a capacidade de pensamento que pode ajudá-lo a entender o raciocínio do modelo e identificar possíveis problemas.
- Precisão e confiabilidade da seleção de ferramentas: Claude pode cometer erros ou alucinar ao selecionar ferramentas enquanto gera 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. Recomendamos que os usuários façam prompt ao modelo cuidadosamente ao solicitar tarefas complexas.
- Confiabilidade da rolagem: Enquanto Claude Sonnet 3.5 (novo) tinha limitações com rolagem, Claude Sonnet 3.7 introduz 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.
- Interação com planilhas: Cliques do mouse para interação com planilhas melhoraram em 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 de granularidade fina e combinando teclas modificadoras com cliques. - Criação de contas e geração de conteúdo em plataformas sociais e de comunicação: Embora Claude visite websites, estamos limitando sua capacidade de criar contas ou gerar e compartilhar conteúdo ou de outra forma se envolver em personificação humana através de websites e plataformas de mídia social. Podemos atualizar essa capacidade no futuro.
- Vulnerabilidades: Vulnerabilidades como jailbreaking ou injeção de prompt podem persistir através de 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 até mesmo em conflito com as instruções do usuário. Por exemplo, instruções do Claude em páginas web ou contidas em imagens podem sobrescrever instruções ou causar erros no Claude. Recomendamos: 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 ao uso do computador acesso a contas ou dados sensíveis sem supervisão rigorosa c. Informar usuários finais sobre riscos relevantes e obter seu consentimento antes de habilitar ou solicitar permissões necessárias para func ionalidades de uso do computador em suas aplicações
- 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 nossa 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 requerem precisão perfeita ou informações sensíveis do usuário sem supervisão humana.
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:
Model | Input tokens per tool definition |
---|---|
Claude 4 / Sonnet 3.7 | 735 tokens |
Claude Sonnet 3.5 | 683 tokens |
Additional token consumption:
- Screenshot images (see Vision pricing)
- Tool execution results returned to Claude
If you’re also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.