Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Claude pode interagir com ambientes de computador através da ferramenta de uso de computador, que fornece capacidades de captura de tela e controle de mouse/teclado para interação autônoma com o desktop.
O uso de computador está em beta e requer um cabeçalho beta:
"computer-use-2025-11-24" para Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5"computer-use-2025-01-24" para Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1 (descontinuado), Claude Sonnet 4 (aposentado, exceto no Bedrock e Google Cloud) e Claude Opus 4 (aposentado, exceto no Google Cloud)Entre em contato através do formulário de feedback para compartilhar seu feedback sobre este recurso.
Este recurso é elegível para Zero Data Retention (ZDR). Quando sua organização possui um acordo de ZDR, os dados enviados por meio deste recurso não são armazenados após a resposta da API ser retornada.
O uso de computador é um recurso beta que permite que Claude interaja com ambientes de desktop. Esta ferramenta fornece:
Embora o uso de computador possa ser ampliado com outras ferramentas, como bash e editor de texto, para fluxos de trabalho de automação mais abrangentes, o uso de computador refere-se especificamente à capacidade da ferramenta de uso de computador de ver e controlar ambientes de desktop.
Para suporte de modelos, consulte a Referência de ferramentas.
O uso de computador é um recurso beta com riscos únicos, distintos dos recursos padrão da API. Esses riscos são ampliados ao interagir com a internet.
Para minimizar riscos, considere tomar precauções como:
Em algumas circunstâncias, Claude seguirá comandos encontrados em conteúdo mesmo quando eles conflitam com suas instruções. Por exemplo, instruções em páginas da web ou contidas em imagens podem sobrepor suas 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 "prompt injection" (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 de computador, classificadores serão executados automaticamente em seus prompts para sinalizar possíveis instâncias de injeções de prompt. Quando esses classificadores identificarem possíveis injeções de prompt em capturas de tela, eles automaticamente direcionarão 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 optar por desativá-la, entre em contato com o suporte.
Essas precauções continuam 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 de computador em seus próprios produtos.
Comece com a implementação de referência de uso de computador que inclui uma interface web, contêiner Docker, implementações de ferramentas de exemplo e um loop de agente.
Veja como começar com o uso de 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)Um cabeçalho beta é necessário apenas para a ferramenta de uso de computador.
O exemplo anterior mostra as três ferramentas sendo usadas juntas, o que requer o cabeçalho beta porque inclui a ferramenta de uso de computador.
Forneça ao Claude a ferramenta de uso de computador e um prompt do usuário
Claude seleciona a ferramenta de uso de computador
stop_reason de tool_use, sinalizando uma solicitação de uso de ferramentas.Extraia a entrada da ferramenta, avalie a ferramenta em um computador e retorne os resultados
user contendo um bloco de conteúdo tool_result.Claude continua chamando ferramentas de uso de computador até concluir a tarefa
stop_reason de tool_use e você deve retornar ao passo 3.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 solicitação de uso de ferramentas e sua aplicação respondendo ao Claude com os resultados da avaliação dessa solicitação.
O uso de computador requer um ambiente de computação em sandbox onde Claude possa interagir com segurança com aplicativos e a web. Esse ambiente inclui:
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.
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.
Aplicativos: Aplicativos Linux pré-instalados, como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos, que Claude pode usar para concluir tarefas.
Implementações de ferramentas: Código de integração que traduz as solicitações abstratas de ferramentas do Claude (como "mover o mouse" ou "tirar captura de tela") em operações reais no ambiente virtual.
Loop de 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 de computador, Claude não se conecta diretamente a esse ambiente. Em vez disso, sua aplicação:
Para segurança e isolamento, a implementação de referência executa tudo isso dentro de um contêiner Docker com mapeamentos de portas apropriados para visualizar e interagir com o ambiente.
Uma implementação de referência está disponível e inclui tudo o que você precisa para começar com o uso de computador:
O núcleo do uso de 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. O loop usa o cliente que você criou no Início rápido, uma lista de ferramentas no formato do array tools do Início rápido e o auxiliar de processamento de chamadas de ferramentas definido em Processe as chamadas de ferramentas do Claude. Aqui está um exemplo simplificado:
def sampling_loop(model, messages, max_iterations=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.beta.messages.create(
model=model,
max_tokens=4096,
messages=messages,
tools=TOOLS,
betas=["computer-use-2025-11-24"],
)
# Adicione a resposta do Claude ao histórico da conversa
messages.append({"role": "assistant", "content": response.content})
# Execute as ferramentas solicitadas pelo Claude e colete os resultados
tool_results = process_tool_calls(response)
if not tool_results:
return messages # No more tool use; task complete
# Envie os resultados das ferramentas de volta ao Claude para a próxima iteração
messages.append({"role": "user", "content": tool_results})
return messagesO loop continua até que Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou 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.
Aqui estão algumas dicas sobre como obter saídas da melhor qualidade:
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.<robot_credentials>. Usar o uso de computador em aplicativos 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.content de um turno do usuário, coloque o texto da instrução antes da imagem da captura de tela. Fornecer a descrição do alvo antes de a imagem ser processada melhora a precisão do clique.computer_20251124 com enable_zoom: true definido, Claude dá zoom em 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 dando zoom quando você espera, pergunte sobre uma região ou elemento específico em vez da tela como um todo.Se você encontrar repetidamente um conjunto claro de problemas ou souber com antecedência as tarefas que Claude precisará concluir, use o prompt do sistema para fornecer ao Claude dicas ou instruções explícitas sobre como realizar as tarefas com sucesso.
Para agentes que abrangem várias sessões, execute verificação de ponta a ponta no início de cada sessão, não apenas após a implementação. Verificações baseadas em navegador capturam regressões de sessões anteriores que a revisão apenas no nível do código não detecta. Consulte Harnesses eficazes para agentes de longa duração para detalhes.
Quando uma das ferramentas com esquema da Anthropic é solicitada através da Claude API, um prompt do sistema específico para uso de computador é gerado. Ele é 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 parâmetro system fornecido pelo usuário ainda é respeitado e usado na construção do prompt do sistema combinado.
A ferramenta de uso de computador suporta estas ações:
Ações básicas (todas as versões)
[x, y]Ações aprimoradas (computer_20250124 e posteriores)
Disponíveis em computer_20250124 e computer_20251124:
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:
computer_20250124enable_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 inspecionar.| Parâmetro | Obrigatório | Descrição |
|---|---|---|
type | Sim | Versão da ferramenta (computer_20251124 ou computer_20250124) |
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 |
enable_zoom | Não | Habilita a ação de zoom (apenas computer_20251124). Defina como true para permitir que Claude dê zoom em regiões específicas da tela. Padrão: false |
Importante: Sua aplicação deve executar explicitamente a ferramenta de uso de computador; Claude não pode executá-la diretamente. Você é responsável por implementar a captura de tela, os movimentos do mouse, as entradas de teclado e outras ações com base nas solicitações do Claude.
Para combinar o uso de computador com pensamento estendido, consulte Pensamento estendido.
Para uso de computador especificamente, benchmarks internos sugerem estas configurações de effort:
high como padrão; use low para cargas de trabalho de alto throughput ou sensíveis a custo.medium como padrão (melhor relação precisão-custo). Evite max, que adiciona custo de tokens sem melhorar a precisão em tarefas de UI. Nesses modelos, low usa menos tokens de saída do que desabilitar o pensamento completamente (menos erros significam menos tentativas), tornando-o uma opção forte para loops sensíveis a custo.Para adicionar outras ferramentas junto com o uso de 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.
A implementação de referência tem como objetivo ajudá-lo a começar com o uso de computador. Ela inclui todos os componentes necessários para que Claude use um computador. No entanto, você pode construir seu próprio ambiente de uso de computador para atender às suas necessidades. Você precisará de:
tool_use usando suas implementações de ferramentasA ferramenta de uso de 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 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 interagirá. Isso normalmente envolve configurar o Xvfb (X Virtual Framebuffer) ou tecnologia semelhante.
Implemente manipuladores de ações
Crie funções para lidar com cada tipo de ação que Claude possa solicitar:
def capture_screenshot():
return "<screenshot data>"
def click_at(x, y):
return f"clicked at ({x}, {y})"
def type_text(text):
return f"typed: {text}"
def handle_computer_action(action_type, params):
if action_type == "screenshot":
return capture_screenshot()
elif action_type == "left_click":
x, y = params["coordinate"]
return click_at(x, y)
elif action_type == "type":
return type_text(params["text"])
# Trate outras ações conforme necessário
return f"unhandled action: {action_type}"Processe as chamadas de ferramentas do Claude
Extraia e execute as chamadas de ferramentas das respostas do Claude:
def process_tool_calls(response):
tool_results = []
for block in response.content:
if block.type == "tool_use":
action = block.input["action"]
result = handle_computer_action(action, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
}
)
return tool_resultsImplemente o loop de agente
Crie um loop que continue até que Claude conclua a tarefa:
def sampling_loop(model, messages, max_iterations=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.beta.messages.create(
model=model,
max_tokens=4096,
messages=messages,
tools=TOOLS,
betas=["computer-use-2025-11-24"],
)
# Adicione a resposta do Claude ao histórico da conversa
messages.append({"role": "assistant", "content": response.content})
# Execute as ferramentas solicitadas pelo Claude e colete os resultados
tool_results = process_tool_calls(response)
if not tool_results:
return messages # No more tool use; task complete
# Envie os resultados das ferramentas de volta ao Claude para a próxima iteração
messages.append({"role": "user", "content": tool_results})
return messagesAo implementar a ferramenta de uso de computador, vários erros podem ocorrer. Veja como tratá-los:
As capturas de tela enviadas para a ferramenta de computador devem caber dentro dos limites de tamanho de imagem do Claude (consulte limites de tamanho de imagem). A API reduz a escala de imagens grandes demais antes que Claude as veja, e Claude retorna coordenadas para a imagem que ele vê, então depender da redução de escala do lado do servidor deixa você sem o fator de escala necessário para mapear essas coordenadas de volta para sua tela. Apenas imagens acima dos limites de solicitação separados da API (por exemplo, mais de 8.000 px em um lado) são rejeitadas com um erro de validação em vez de terem a escala reduzida.
Os limites variam por modelo. Claude Sonnet 5, Claude Opus 4.8 e Claude Opus 4.7 aceitam até 2576 pixels na borda mais longa; modelos anteriores aceitam até 1568 pixels na borda mais longa e aproximadamente 1,15 megapixels no total. O exemplo a seguir usa os limites de 1568 px / 1,15 MP dos modelos anteriores; substitua pelo limite do seu modelo.
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 pelo Claude de volta para o espaço original da tela:
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)
# Ao capturar a captura de tela
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)
# Redimensione a imagem para as dimensões escaladas antes de enviar ao Claude
screenshot = capture_and_resize(scaled_width, scaled_height)
# Ao lidar com as coordenadas do Claude, escale-as de volta
def execute_click(x, y):
screen_x = x / scale
screen_y = y / scale
perform_click(screen_x, screen_y)Displays Retina do macOS capturam capturas de tela com uma proporção de pixels do dispositivo de 2, então a imagem tem o dobro da resolução das coordenadas lógicas da tela. Reduza a escala da captura de tela em 2x antes de enviar, ou divida pela metade as coordenadas que Claude retorna antes de emitir o clique.
Se os cliques errarem seus alvos, a causa geralmente é uma das seguintes:
| Sintoma | Causa provável | Tente |
|---|---|---|
| Cliques consistentemente deslocados em uma direção | display_width_px/display_height_px não correspondem às dimensões da imagem realmente enviada | Garanta que as dimensões do display correspondam exatamente à captura de tela que você envia |
| Cliques caem na área certa, mas erram o alvo | O alvo é muito pequeno, detalhes foram perdidos ao reduzir a escala de uma fonte 4K+, ou a proporção foi distorcida | Defina enable_zoom: true; capture com DPI mais baixo ou recorte para a região relevante; preserve a proporção ao redimensionar |
| Claude clica no elemento completamente errado | Instrução ambígua, ou elementos visualmente semelhantes próximos | Use prompts posicionais ("o botão azul Enviar no canto inferior direito"); divida a interação em passos menores |
| A precisão é consistentemente ruim | Resolução muito baixa | Tente 1280x720 como linha de base |
A escolha do modelo afeta a precisão do clique. Claude Sonnet 4.6 é mecanicamente mais preciso ao clicar do que Claude Opus 4.6 e é mais robusto quando as capturas de tela exigem forte redução de escala. Claude Opus 4.7 reduz essa diferença: sua precisão de clique é aproximadamente comparável à do Sonnet 4.6, e seu limite de resolução mais alto significa que menos redução de escala é necessária.
O uso de computador está em beta. Tenha em mente as seguintes limitações:
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.
Precisão e confiabilidade da visão computacional: Claude pode cometer erros ou alucinar ao produzir coordenadas específicas enquanto gera ações. O pensamento estendido pode ajudá-lo a entender o raciocínio do modelo e identificar possíveis problemas.
Precisão e confiabilidade na 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 aplicativos de nicho ou múltiplos aplicativos ao mesmo tempo. Instrua o modelo cuidadosamente ao solicitar tarefas complexas.
Confiabilidade da rolagem: A ação de rolagem suporta controle de direção (para cima, para baixo, esquerda, direita) e uma quantidade especificada. Em aplicativos onde a rolagem não tem efeito, alternativas de teclado como Page Down podem ajudar.
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 múltiplas tentativas.
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.
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, Claude seguirá comandos encontrados em conteúdo, às vezes mesmo quando eles conflitam com suas instruções. Por exemplo, instruções em páginas da web ou contidas em imagens podem sobrepor suas instruções ou fazer com que Claude cometa erros. Considere o seguinte:
Ações inapropriadas 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 Claude para tarefas que exijam precisão perfeita ou informações sensíveis do usuário sem supervisão humana.
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 as solicitações de ação em tempo real como parte da chamada de API. A retenção dessas solicitações de API é regida por API e retenção de dados.
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 de ZDR em todos os recursos, consulte API e retenção de dados.
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:
| Modelo | Tokens de entrada por definição de ferramenta |
|---|---|
| Modelos Claude 4.x | 735 tokens |
Consumo adicional de tokens:
Se você também estiver usando as ferramentas bash ou editor de texto junto com o uso do computador, essas ferramentas têm seus próprios custos de tokens, conforme documentado em suas respectivas páginas.
Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para correção.
Comece com a implementação completa baseada em Docker
Conecte Claude a ferramentas e APIs externas. Veja onde as ferramentas são executadas, quando Claude as chama e qual ferramenta se adequa à sua tarefa.
Recomendações baseadas em benchmarks para resolução, esforço de pensamento e gerenciamento de contexto
Was this page helpful?