Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
O 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 o desktop.
O uso do computador é um recurso beta que permite ao Claude interagir com ambientes de desktop. Esta ferramenta fornece:
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.
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 em conteúdo mesmo quando eles entrarem em conflito com suas instruções. Por exemplo, instruções em páginas da web ou contidas em imagens podem substituir suas instruções ou fazer com que o Claude cometa erros. Tome precauções para isolar o Claude de dados e ações sensíveis para evitar riscos relacionados à 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 identificarem possíveis injeções de prompt em capturas de tela, eles direcionarão automaticamente 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.
Comece com a implementação de referência de uso do 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 do computador:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5", # 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)Forneça ao Claude a ferramenta de uso do computador e um prompt do usuário
O Claude seleciona a ferramenta de uso do computador
stop_reason de tool_use, sinalizando uma requisiçã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.O Claude continua chamando ferramentas de uso do computador até concluir a tarefa
stop_reason de tool_use e você deve retornar à etapa 3.A repetição das etapas 3 e 4 sem entrada do usuário é chamada de "agent loop" (loop de agente), ou seja, o Claude respondendo com uma requisição de uso de ferramentas e sua aplicação respondendo ao Claude com os resultados da avaliação dessa requisição.
O uso do computador requer um ambiente de computação isolado (sandbox) onde o Claude possa interagir com segurança com aplicações e a web. Este ambiente inclui:
Display virtual: Um servidor de display X11 virtual (usando Xvfb) que renderiza a interface de desktop que o 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 no Linux, que fornece uma interface gráfica consistente para o Claude interagir.
Aplicações: Aplicações Linux pré-instaladas, como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos, que o Claude pode usar para concluir tarefas.
Implementações de ferramentas: Código de integração que traduz as requisições abstratas de ferramentas do Claude (como "mover mouse" ou "capturar tela") em operações reais no ambiente virtual.
Loop de agente: Um programa que gerencia 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 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 porta 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 do computador:
O núcleo do uso do computador é o "agent loop" (loop de agente): um ciclo em que o Claude solicita ações de ferramentas, sua aplicação as executa e retorna os resultados ao Claude. O loop usa o cliente que você criou no Início rápido, uma lista de ferramentas estruturada como o 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 o Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou até que o limite máximo de iterações seja atingido. Essa proteção 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.
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 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.content de um turno do usuário, coloque o texto da instrução antes da imagem de captura de tela. Fornecer a descrição do alvo antes que a imagem seja processada melhora a precisão do clique.computer_20251124 com enable_zoom: true definido, o 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 o Claude não estiver ampliando quando você espera, pergunte sobre uma região ou elemento específico em vez da tela como um todo.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 parâmetro system fornecido pelo usuário ainda é respeitado e usado na construção do prompt do sistema combinado.
A ferramenta de uso do 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 no Claude Opus 5, 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 ser inspecionada.| 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 | Habilitar ação de zoom (apenas computer_20251124). Defina como true para permitir que o Claude amplie regiões específicas da tela. Padrão: false |
Para combinar o uso do computador com pensamento, consulte Pensamento.
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.
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 o 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:
tool_use usando suas implementações de ferramentasA 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 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 o Claude irá interagir. Isso normalmente envolve configurar o Xvfb (X Virtual Framebuffer) ou tecnologia similar.
Implemente manipuladores de ações
Crie funções para lidar com cada tipo de ação que o Claude pode 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 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 o 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 do computador, vários erros podem ocorrer. Veja como tratá-los:
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 imagens grandes demais antes que o Claude as veja, e o Claude retorna coordenadas para a imagem que ele vê, então depender da redução 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 requisiçã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 serem reduzidas.
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 da tela original:
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 processar as coordenadas do Claude, redimensione-as de volta para cima
def execute_click(x, y):
screen_x = x / scale
screen_y = y / scale
perform_click(screen_x, screen_y)Se os cliques erram 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 uma fonte 4K+, ou a proporção de aspecto foi distorcida | Defina enable_zoom: true; capture em DPI mais baixo ou recorte para a região relevante; preserve a proporção de aspecto ao redimensionar |
| O Claude clica no elemento errado completamente | 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 etapas menores |
| A precisão é consistentemente ruim | Resolução muito baixa | Tente 1280x720 como linha de base |
O uso do computador está em beta. Tenha em mente as seguintes limitações:
Latência: A "latency" (latência) atual do uso do computador para interações humano-IA pode ser muito lenta em comparação com ações regulares de computador direcionadas 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 de 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.
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. Instrua o modelo cuidadosamente ao solicitar tarefas complexas.
Confiabilidade de 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 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 de planilha ainda podem exigir várias tentativas.
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.
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, o Claude seguirá comandos encontrados em conteúdo, às vezes mesmo quando eles entram em conflito com suas instruções. Por exemplo, instruções em páginas da web ou contidas em imagens podem substituir suas instruções ou fazer com que o Claude cometa erros. Considere o seguinte:
Ações inadequadas 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 o Claude para tarefas que exijam precisão perfeita ou informações sensíveis do usuário sem supervisão humana.
O uso do 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 em seu ambiente, não pela Anthropic. A Anthropic processa as imagens de captura de tela e requisições de ação em tempo real como parte da chamada de API. A retenção para essas requisições de API é regida por API e retenção de dados.
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 de ZDR em todos os recursos, consulte API e retenção de dados.
O uso de computador segue o preço padrão de uso de ferramentas. Ao usar a ferramenta de uso de computador:
Sobrecarga do prompt do sistema: O beta de uso de computador adiciona 466–499 tokens ao prompt do sistema
Uso de tokens da ferramenta de uso de computador:
| Modelo | Tokens de entrada por definição de ferramenta |
|---|---|
| Modelos Claude 4.x | 735 tokens |
Consumo adicional de tokens:
Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para solução.
Comece com a implementação completa baseada em Docker
Conecte o Claude a ferramentas e APIs externas. Veja onde as ferramentas são executadas, quando o Claude as chama e qual ferramenta se adequa à sua tarefa.
Recomendações com benchmarks para resolução, esforço de pensamento e gerenciamento de contexto
| Supported models |
|
|---|---|
| Supported platforms |
|
Was this page helpful?