Ferramenta de uso do computador

​

Visão geral

• 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

​

Compatibilidade de modelo

​

Considerações de segurança

​

Início rápido

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",  # ou outro modelo compatível
    max_tokens=1024,
    tools=[
        {
          "type": "computer_20250124",
          "name": "computer",
          "display_width_px": 1024,
          "display_height_px": 768,
          "display_number": 1,
        },
        {
          "type": "text_editor_20250124",
          "name": "str_replace_editor"
        },
        {
          "type": "bash_20250124",
          "name": "bash"
        }
    ],
    messages=[{"role": "user", "content": "Salve uma imagem de um gato na minha área de trabalho."}],
    betas=["computer-use-2025-01-24"]
)
print(response)

​

Como funciona o uso do computador

​

O ambiente de computação

1. 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.
2. 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 Claude interagir.
3. Aplicações: Aplicações Linux pré-instaladas como Firefox, LibreOffice, editores de texto e gerenciadores de arquivo que Claude pode usar para completar tarefas.
4. 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.
5. Loop do agente: Um programa que lida com comunicação entre Claude e o ambiente, enviando ações do Claude para o ambiente e retornando os resultados (capturas de tela, saídas de comando) de volta para Claude.

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

​

Como implementar o uso do computador

​

Comece com nossa implementação de referência

• 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 Claude e executa as ferramentas de uso do computador
• Uma interface web para interagir com o container, loop do agente e ferramentas.

​

Entendendo o loop multi-agente

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,  # Adicionar limite de iteração para prevenir loops infinitos
):
    """
    Um loop de agente simples para interações de uso do computador Claude.

    Esta função lida com o vai-e-vem entre:
    1. Enviar mensagens do usuário para Claude
    2. Claude solicitar usar ferramentas
    3. Sua aplicação executar essas ferramentas
    4. Enviar resultados das ferramentas de volta para Claude
    """
    # Configurar ferramentas e parâmetros da API
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # Configurar ferramentas - você já deve ter essas inicializadas em outro lugar
    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"}
    ]

    # Loop principal do agente (com limite de iteração para prevenir custos descontrolados da API)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Configurar parâmetro de pensamento opcional (para Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # Adicionar resposta do Claude ao histórico da conversa
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Verificar se Claude usou alguma ferramenta
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # Em uma aplicação real, você executaria a ferramenta aqui
                # Por exemplo: result = run_tool(block.name, block.input)
                result = {"result": "Ferramenta executada com sucesso"}

                # Formatar o resultado para Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Se nenhuma ferramenta foi usada, Claude terminou - retornar as mensagens finais
        if not tool_results:
            return messages

        # Adicionar resultados das ferramentas às mensagens para a próxima iteração com Claude
        messages.append({"role": "user", "content": tool_results})

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2024-10-22"]

​

Otimize o desempenho do modelo com prompting

1. Especifique tarefas simples e bem definidas e forneça instruções explícitas para cada passo.
2. Claude às vezes assume resultados de suas ações sem verificar explicitamente seus resultados. Para prevenir isso, você pode fazer prompt para 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.
3. 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 para o modelo 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 em seu prompt.
5. 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.

​

Prompts do sistema

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.

​

Ações disponíveis

• 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

• 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

// Tirar uma captura de tela
{
  "action": "screenshot"
}

// Clicar na posição
{
  "action": "left_click",
  "coordinate": [500, 300]
}

// Digitar texto
{
  "action": "type",
  "text": "Olá, mundo!"
}

// Rolar para baixo (Claude 4/3.7)
{
  "action": "scroll",
  "coordinate": [500, 400],
  "scroll_direction": "down",
  "scroll_amount": 3
}

​

Parâmetros da ferramenta

​

Habilite a capacidade de pensamento nos modelos Claude 4 e Claude Sonnet 3.7

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

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últiplos passos

[Pensando]
Preciso salvar uma imagem de um gato na área de trabalho. Deixe-me dividir isso em passos:

1. Primeiro, vou tirar uma captura de tela para ver o que está na área de trabalho
2. Então vou procurar por um navegador web para pesquisar imagens de gato
3. Depois de encontrar uma imagem adequada, vou precisar salvá-la na área de trabalho

Deixe-me começar tirando uma captura de tela para ver o que está disponível...

​

Aumentando o uso do computador com outras ferramentas

• 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)

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-01-24" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      },
      {
        "name": "get_weather",
        "description": "Obter o clima atual em um local específico",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "A cidade e estado, por exemplo São Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "A unidade de temperatura, seja 'celsius' ou 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Encontre voos de São Francisco para um lugar com clima mais quente."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

Construa um ambiente personalizado de uso do computador

• 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 Claude e executa os resultados 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

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"])
    # ... lidar com outras ações

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)
        
        # Retornar resultado para Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

while True:
    response = client.beta.messages.create(...)
    
    # Verificar se Claude usou alguma ferramenta
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # Não há mais uso de ferramenta, tarefa completa
        break
        
    # Continuar conversa com resultados das ferramentas
    messages.append({"role": "user", "content": tool_results})

​

Lidar com erros

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Falha ao capturar tela. Display pode estar bloqueado ou indisponível.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Coordenadas (1200, 900) estão fora dos limites do display (1024x768).",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Falha ao executar ação de clique. A aplicação pode não estar respondendo.",
      "is_error": true
    }
  ]
}

​

Siga as melhores práticas de implementação

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Permitir que a UI atualize

def validate_action(action_type, params):
    if action_type == "left_click":
        x, y = params.get("coordinate", (0, 0))
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordenadas fora dos limites"
    return True, None

import logging

def log_action(action_type, params, result):
    logging.info(f"Ação: {action_type}, Parâmetros: {params}, Resultado: {result}")

​

Entenda as limitações do uso do computador

1. Latência: a latência atual do uso do computador para interações humano-IA pode ser muito lenta comparada a ações regulares de computador dirigidas por humanos. Recomendamos focar em casos de uso onde 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 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.
3. 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. Adicionalmente, 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 para o modelo cuidadosamente ao solicitar tarefas complexas.
4. Confiabilidade de rolagem: Enquanto Claude Sonnet 3.5 v2 (descontinuado) 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 explicitamente rolar em qualquer direção (cima/baixo/esquerda/direita) por uma quantidade especificada.
5. Interação com planilhas: 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 de granularidade fina 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 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.
7. 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 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 containers 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 usuários finais sobre riscos relevantes e obter seu consentimento antes de habilitar ou solicitar permissões necessárias para funcionalidades 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 nossa Política de Uso Aceitável.

​

Preços

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

​

Próximos passos