Ferramenta de uso de computador

Claude pode interagir com ambientes de computador através da ferramenta de uso de computador, que fornece recursos de captura de tela e controle de mouse/teclado para interação autônoma de desktop.

Visão geral

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

• Captura de tela: Veja o que está sendo exibido na tela
• Controle de mouse: Clique, arraste e mova o cursor
• Entrada de teclado: Digite texto e use atalhos de teclado
• Automação de desktop: Interaja com qualquer aplicativo ou interface

Embora o uso de computador possa ser aumentado com outras ferramentas como bash e editor de texto para fluxos de trabalho de automação mais abrangentes, o uso de computador especificamente se refere à capacidade da ferramenta de uso de computador de ver e controlar ambientes de desktop.

Compatibilidade de modelo

O uso de computador está disponível para os seguintes modelos Claude:

Considerações de segurança

Início rápido

Veja como começar com o uso de computador:

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 foto de um gato na minha área de trabalho."}],
    betas=["computer-use-2025-01-24"]
)
print(response)

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": 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 foto de um gato na minha área de trabalho."
      }
    ]
  }'

Como funciona o uso de computador

Nos referimos à repetição das etapas 3 e 4 sem entrada do usuário como o "loop de agente" - ou seja, Claude respondendo com uma solicitação de uso de ferramenta e seu aplicativo respondendo a Claude com os resultados da avaliação dessa solicitação.

O ambiente de computação

O uso de computador requer um ambiente de computação em sandbox onde Claude pode interagir com segurança com aplicativos e a web. Este ambiente inclui:

1. Exibição virtual: Um servidor de exibição 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 interface de usuário leve com gerenciador de janelas (Mutter) e painel (Tint2) em execução no Linux, que fornece uma interface gráfica consistente para Claude interagir.

3. Aplicativos: Aplicativos Linux pré-instalados 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 solicitações de ferramentas abstratas de Claude (como "mover mouse" ou "tirar screenshot") em operações reais no ambiente virtual.

5. Loop de agente: Um programa que manipula 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 comando) de volta para Claude.

Quando você usa o uso de computador, Claude não se conecta diretamente a este ambiente. Em vez disso, seu aplicativo:

1. Recebe solicitações de uso de ferramenta de 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

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 de 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 de computador:

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

Entendendo o loop multi-agente

O núcleo do uso de computador é o "loop de agente" - um ciclo onde Claude solicita ações de ferramenta, seu aplicativo as executa e retorna resultados para Claude. Aqui está um exemplo simplificado:

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

    Esta função manipula a troca entre:
    1. Enviar mensagens do usuário para Claude
    2. Claude solicitando usar ferramentas
    3. Seu aplicativo executando essas ferramentas
    4. Enviar resultados de ferramentas de volta para Claude
    """
    # Configurar ferramentas e parâmetros de 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 estas 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 de agente principal (com limite de iteração para evitar custos de API descontrolados)
    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 a resposta de Claude ao histórico de 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 um aplicativo 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 - retorne as mensagens finais
        if not tool_results:
            return messages

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

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 proteção evita possíveis loops infinitos que podem resultar em custos de API inesperados.

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 os melhores resultados de 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 solicitar a Claude com Após cada etapa, tire uma screenshot e avalie cuidadosamente se você alcançou o resultado correto. Mostre explicitamente seu pensamento: "Avaliei a etapa X..." Se não estiver correto, tente novamente. Apenas quando você confirmar que uma etapa foi executada corretamente, você deve passar para a próxima.
3. Alguns elementos da interface do usuário (como menus suspensos e barras de rolagem) podem ser complicados para Claude manipular usando movimentos do mouse. Se você experimentar isso, tente solicitar ao modelo que use atalhos de teclado.
4. Para tarefas repetíveis ou interações de interface do usuário, inclua capturas de tela de exemplo e chamadas de ferramenta de resultados bem-sucedidos em seu prompt.
5. Se você precisar que o modelo faça login, forneça-o com o nome de usuário e senha em seu prompt dentro de tags xml como <robot_credentials>. Usar o uso de computador em aplicativos que exigem login aumenta o risco de resultados ruins como resultado de injeção de prompt. Por favor, revise nosso guia sobre mitigação de injeções de prompt antes de fornecer ao modelo credenciais de login.

Prompts do sistema

Quando uma das ferramentas definidas pela Anthropic é solicitada através da API Claude, um prompt do sistema específico de uso de computador é gerado. É semelhante 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 em sandbox. 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 de ferramenta 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 de computador suporta estas ações:

Ações básicas (todas as versões)

• screenshot - Capturar a exibição atual
• left_click - Clique nas coordenadas [x, y]
• type - Digite a string de texto
• key - Pressione a tecla ou combinação de teclas (por exemplo, "ctrl+s")
• mouse_move - Mova o cursor para as coordenadas

Ações aprimoradas (computer_20250124) Disponível em modelos Claude 4 e Claude Sonnet 3.7:

• scroll - Role em qualquer direção com controle de quantidade
• left_click_drag - Clique e arraste entre coordenadas
• right_click, middle_click - Botões de mouse adicionais
• double_click, triple_click - Múltiplos cliques
• left_mouse_down, left_mouse_up - Controle de clique refinado
• hold_key - Mantenha uma tecla pressionada enquanto executa outras ações
• wait - Pausa entre ações

Parâmetros da ferramenta

Ativar o recurso de pensamento em modelos Claude 4 e Claude Sonnet 3.7

Claude Sonnet 3.7 introduziu uma nova capacidade de "pensamento" que permite que você veja o processo de raciocínio do modelo enquanto ele trabalha em tarefas complexas. Este recurso ajuda você a entender como Claude está abordando um problema e pode ser particularmente valioso para fins de depuração ou educacionais.

Para ativar o pensamento, adicione um parâmetro thinking à sua solicitação de API:

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

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á ativado, Claude retornará seu processo de raciocínio como parte da resposta, o que pode ajudá-lo a:

1. Entender o processo de tomada de decisão do modelo
2. Identificar possíveis problemas ou conceitos errados
3. Aprender com a abordagem de Claude para resolução de problemas
4. Obter mais visibilidade em operações complexas de múltiplas etapas

Aqui está um exemplo de como a saída de pensamento pode parecer:

[Pensamento]
Preciso salvar uma foto de um gato na área de trabalho. Deixe-me dividir isso em etapas:

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

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

Aumentando o uso de computador com outras ferramentas

A ferramenta de uso de 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 personalizadas ou serviços (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, '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
    }
  }'

Construir um ambiente de uso de computador personalizado

A implementação de referência é destinada a ajudá-lo a começar com o uso de computador. Inclui todos os componentes necessários para que Claude use um computador. No entanto, você pode construir seu próprio ambiente para uso de computador para atender às suas necessidades. Você precisará:

• Um ambiente virtualizado ou containerizado adequado para uso de computador com Claude
• Uma implementação de pelo menos uma das ferramentas de uso de computador definidas pela Anthropic
• Um loop de agente que interage com a API Claude e executa os resultados de tool_use usando suas implementações de ferramentas
• Uma API ou interface do usuário que permite entrada do usuário para iniciar o loop de agente

Implementar a ferramenta de uso de computador

A ferramenta de uso de computador é implementada como uma ferramenta sem schema. Ao usar esta ferramenta, você não precisa fornecer um schema de entrada como com outras ferramentas; o schema é incorporado ao modelo de Claude e não pode ser modificado.

Manipular erros

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

Seguir as melhores práticas de implementação

Entender as limitações do uso de computador

A funcionalidade de uso de computador está em beta. Embora as capacidades de Claude sejam de ponta, os desenvolvedores devem estar cientes de suas limitações:

1. Latência: a latência atual de uso de computador para interações humano-IA pode ser muito lenta em comparação com ações de computador direcionadas por humanos regulares. Recomendamos focar 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: Claude pode cometer erros ou alucinar ao gerar coordenadas específicas enquanto gera ações. Claude Sonnet 3.7 introduz o recurso 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. Além disso, a confiabilidade pode ser menor ao interagir com aplicativos de nicho ou múltiplos aplicativos ao mesmo tempo. Recomendamos que os usuários solicitem o modelo com cuidado ao solicitar tarefas complexas.
4. Confiabilidade de rolagem: Claude Sonnet 3.7 introduziu ações de rolagem dedicadas com controle de direção que melhoram a confiabilidade. O modelo agora pode rolar explicitamente em qualquer direção (para cima/para baixo/esquerda/direita) por uma quantidade especificada.
5. Interação com planilhas: Os 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 refinados e combinando teclas modificadoras com cliques.
6. Criação de conta e geração de conteúdo em plataformas sociais e de comunicações: Embora Claude visite sites, estamos limitando sua capacidade de criar contas ou gerar e compartilhar conteúdo ou de outra forma se envolver em representação humana em sites e plataformas de mídia social. Podemos atualizar essa capacidade 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, Claude seguirá comandos encontrados em conteúdo, às vezes até em conflito com as instruções do usuário. Por exemplo, instruções Claude em páginas da web ou contidas em imagens podem substituir instruções ou fazer com que Claude cometa erros. Recomendamos: 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 acesso de uso de computador a contas sensíveis ou dados sem supervisão rigorosa c. Informar os usuários finais sobre os riscos relevantes e obter seu consentimento antes de ativar ou solicitar permissões necessárias para recursos de uso de computador em seus aplicativos
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 nenhuma lei ou nossa Política de Uso Aceitável.

Sempre revise e verifique cuidadosamente as ações e logs de uso de computador de Claude. Não use Claude para tarefas que exigem 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:

Additional token consumption:

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

Próximas etapas