Claude 4 Opus e Sonnet, junto com Claude Sonnet 3.7 e Claude Sonnet 3.5 (novo), são capazes de interagir com ferramentas que podem manipular um ambiente de desktop de computador. Os modelos Claude 4 usam versões atualizadas de ferramentas otimizadas para a nova arquitetura. Claude Sonnet 3.7 introduz ferramentas adicionais e permite que você ative o pensamento, dando mais insights sobre o processo de raciocínio do modelo.

O uso do computador é um recurso beta. Esteja ciente de que o uso do computador apresenta riscos únicos que são distintos dos recursos de API padrão ou interfaces de chat. Esses riscos são aumentados ao usar o computador para interagir com a internet. Para minimizar os riscos, considere tomar precauções como:

  1. Use uma máquina virtual dedicada ou contêiner com privilégios mínimos para evitar ataques diretos ao sistema ou acidentes.
  2. Evite dar ao modelo acesso a dados sensíveis, como informações de login de conta, para evitar roubo de informações.
  3. Limite o acesso à internet a uma lista de permissões de domínios para reduzir a exposição a conteúdo malicioso.
  4. Peça a um humano para confirmar decisões que possam resultar em consequências significativas no mundo real, bem como quaisquer tarefas que exijam consentimento afirmativo, como aceitar cookies, executar transações financeiras ou concordar com termos de serviço.

Em algumas circunstâncias, o Claude seguirá comandos encontrados em conteúdo, mesmo que isso entre em conflito com as instruções do usuário. Por exemplo, instruções do Claude em páginas da web ou contidas em imagens podem substituir instruções ou fazer com que o Claude cometa erros. Sugerimos tomar precauções para isolar o 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 solicitar 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 circuito), então se você quiser optar por não usá-la e desativá-la, entre em contato conosco.

Ainda sugerimos tomar precauções para isolar o Claude de dados e ações sensíveis para evitar riscos relacionados à injeção de prompt.

Finalmente, informe os usuários finais sobre os riscos relevantes e obtenha seu consentimento antes de habilitar o uso do computador em seus próprios produtos.

Implementação de referência para uso do computador

Comece rapidamente com nossa implementação de referência para 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 obter a versão mais recente do repositório para acessar esses novos recursos.

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 - mal podemos esperar para ouvir de você!

Aqui está um exemplo de como fornecer ferramentas de uso do computador para o Claude usando a API Messages:

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-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​
Como funciona o uso do computador

1. Forneça ao Claude ferramentas de uso do computador e um prompt do usuário

  • Adicione ferramentas de uso do computador definidas pela Anthropic à sua solicitação de API.
  • Inclua um prompt do usuário que possa exigir essas ferramentas, por exemplo, “Salve uma imagem de um gato na minha área de trabalho.”

2. Claude decide usar uma ferramenta

  • Claude carrega as definições armazenadas de ferramentas de uso do computador e avalia se alguma ferramenta pode ajudar com a consulta do usuário.
  • Se sim, Claude constrói uma solicitação de uso de ferramenta formatada corretamente.
  • A resposta da API tem um stop_reason de tool_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 de user contendo um bloco de conteúdo tool_result.

4. Claude continua chamando ferramentas de uso do computador até completar a tarefa

  • Claude analisa os resultados da ferramenta para determinar se é necessário mais uso de ferramentas ou se a tarefa foi concluída.
  • Se Claude decidir que precisa de outra ferramenta, ele responde com outro stop_reason de tool_use e você deve retornar ao passo 3.
  • Caso contrário, ele elabora uma resposta de texto para o usuário.

Referimos-nos à repetição das etapas 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 seu aplicativo 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 o Claude pode interagir com segurança com aplicativos e a web. Este ambiente inclui:

  1. 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.

  2. Ambiente de desktop: Uma interface leve com gerenciador de janelas (Mutter) e painel (Tint2) executando no Linux, que fornece uma interface gráfica consistente para o Claude interagir.

  3. Aplicativos: Aplicativos Linux pré-instalados como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos que o Claude pode usar para completar tarefas.

  4. Implementações de ferramentas: Código de integração que traduz as solicitações de ferramentas abstratas do Claude (como “mover mouse” ou “tirar screenshot”) em operações reais no ambiente virtual.

  5. Loop do 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 comando) de volta ao Claude.

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

  1. Recebe as solicitações de uso de ferramentas do Claude
  2. Traduz-as em ações no seu ambiente de computação
  3. Captura os resultados (capturas de tela, saídas de comando, etc.)
  4. Retorna esses resultados ao 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:

​
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, seu aplicativo as executa e retorna resultados ao 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,  # Adiciona limite de iteração para evitar loops infinitos
):
    """
    Um loop de agente simples para interações de uso do computador com Claude.

    Esta função lida com o vai-e-vem entre:
    1. Enviar mensagens do usuário para Claude
    2. Claude solicitando usar ferramentas
    3. Seu aplicativo executando essas ferramentas
    4. Enviando resultados de 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 tê-las inicializado 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 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 do Claude
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking
        )

        # Adicionar a resposta do Claude ao histórico de conversas
        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 o Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou o limite máximo de iteração seja atingido. Esta salvaguarda evita possíveis loops infinitos que poderiam resultar em custos inesperados de API.

Para cada versão das ferramentas, você deve usar a flag beta correspondente em sua solicitação de API:

Recomendamos experimentar a implementação de referência antes de ler o restante desta documentação.

​
Otimize o desempenho do modelo com prompting

Aqui estão algumas dicas sobre como obter as melhores saídas de qualidade:

  1. Especifique tarefas simples e bem definidas e forneça instruções explícitas para cada etapa.
  2. O Claude às vezes presume os resultados de suas ações sem verificar explicitamente seus resultados. Para evitar isso, você pode solicitar ao Claude com Após cada etapa, tire uma captura de tela 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. Só quando você confirmar que uma etapa foi executada corretamente deve passar para a próxima.
  3. Alguns elementos de UI (como menus suspensos e barras de rolagem) podem ser difíceis para o 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 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 o nome de usuário e a senha em seu prompt dentro de tags xml como <robot_credentials>. O uso do 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 credenciais de login ao modelo.

Se você encontrar repetidamente um conjunto claro de problemas ou souber antecipadamente as tarefas que o Claude precisará completar, use o prompt do sistema para fornecer ao Claude dicas explícitas ou instruções sobre como realizar as tarefas com sucesso.

​
Prompts do sistema

Quando uma das ferramentas definidas pela Anthropic é solicitada via API da Anthropic, um prompt de sistema específico para uso do computador é gerado. É semelhante ao prompt de sistema de uso de ferramentas, 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 no uso regular de ferramentas, o campo system_prompt fornecido pelo usuário ainda é respeitado e usado na construção do prompt de sistema combinado.

​
Entenda as ferramentas definidas pela Anthropic

Como um beta, essas definições de ferramentas estão sujeitas a alterações.

Fornecemos um conjunto de ferramentas que permitem ao Claude usar computadores efetivamente. Ao especificar uma ferramenta definida pela Anthropic, os campos description e tool_schema não são necessários ou permitidos.

Ferramentas definidas pela Anthropic são executadas pelo usuário

As ferramentas definidas pela Anthropic são definidas pela Anthropic, mas você deve avaliar explicitamente os resultados da ferramenta e retornar os tool_results ao Claude. Como com qualquer ferramenta, o modelo não executa automaticamente a ferramenta.

Fornecemos um conjunto de ferramentas definidas pela Anthropic, com cada ferramenta tendo versões otimizadas para Claude 4, Claude Sonnet 3.7 e Claude Sonnet 3.5:

O campo type identifica a ferramenta e seus parâmetros para fins de validação, o campo name é o nome da ferramenta exposto ao modelo.

Se você quiser solicitar ao modelo que use uma dessas ferramentas, pode se referir explicitamente à ferramenta pelo campo name. O campo name deve ser único dentro da lista de ferramentas; você não pode definir uma ferramenta com o mesmo nome de uma ferramenta definida pela Anthropic na mesma chamada de API.

Não recomendamos definir ferramentas com os nomes de ferramentas definidas pela Anthropic. Embora você ainda possa redefinir ferramentas com esses nomes (desde que o nome da ferramenta seja único em seu bloco tools), fazer isso pode resultar em desempenho degradado do modelo.

​
Habilite o recurso de pensamento no Claude 4 e Claude Sonnet 3.7

Claude Sonnet 3.7 introduziu um novo recurso 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 o Claude está abordando um problema e pode ser particularmente valioso para depuração ou fins educacionais.

Para habilitar 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 o Claude pode usar para pensar. Isso é subtraído do seu orçamento geral de max_tokens.

Quando o pensamento está habilitado, o 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 equívocos
  3. Aprender com a abordagem do 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:

[Thinking]
Preciso salvar uma imagem de um gato na área de trabalho. Vamos dividir isso em etapas:

1. Primeiro, vou tirar uma captura de tela para ver o que está na área de trabalho
2. Depois, vou procurar um navegador web para buscar imagens de gatos
3. Depois de encontrar uma imagem adequada, precisarei salvá-la na área de trabalho

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

​
Combine o uso do computador com outras ferramentas

Você pode combinar uso regular de ferramentas com as ferramentas definidas pela Anthropic para uso do computador.

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-opus-4-20250514",
    "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"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​
Construa um ambiente personalizado de uso do computador

A implementação de referência foi criada para ajudá-lo 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:

  • Um ambiente virtualizado ou em contêiner 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 da 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

​
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:

  1. Latência: a latência atual de uso do computador para interações humano-IA pode ser muito lenta em comparação com ações regulares de computador dirigidas por humanos. 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 durante a geração de 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 na seleção de ferramentas: 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 aplicativos de nicho ou vários aplicativos ao mesmo tempo. Recomendamos que os usuários solicitem ao modelo cuidadosamente ao solicitar tarefas complexas.
  4. Confiabilidade de rolagem: Embora Claude Sonnet 3.5 (novo) tivesse limitações com rolagem, Claude Sonnet 3.7 introduz ações dedicadas de rolagem 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.
  5. Interação com planilhas: Cliques de 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 refinados 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 o Claude visite sites, estamos limitando sua capacidade 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. Podemos atualizar esse recurso 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 do computador. Em algumas circunstâncias, o Claude seguirá comandos encontrados em conteúdo, às vezes mesmo em conflito com as instruções do usuário. Por exemplo, instruções do Claude em páginas da web ou contidas em imagens podem substituir instruções ou fazer com que o Claude cometa erros. 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 acesso de uso do computador a contas ou dados sensíveis sem supervisão rigorosa c. Informar os usuários finais sobre os riscos relevantes e obter seu consentimento antes de habilitar ou solicitar permissões necessárias para recursos de uso do 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 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 o Claude para tarefas que exijam precisão perfeita ou informações sensíveis do usuário sem supervisão humana.

​
Preços

Veja a documentação de preços de uso de ferramentas para uma explicação detalhada de como as solicitações da API de Uso de Ferramentas do Claude são precificadas.

Como um subconjunto de solicitações de uso de ferramentas, as solicitações de uso do computador são precificadas da mesma forma que qualquer outra solicitação da API do Claude.

Também incluímos automaticamente um prompt de sistema especial para o modelo, que permite o uso do computador.

ModeloEscolha de ferramentaContagem de tokens do prompt do sistema
Claude 4 Opus & Sonnetauto
any, tool		466 tokens
499 tokens
Claude Sonnet 3.7auto
any, tool		466 tokens
499 tokens
Claude Sonnet 3.5 (novo)auto
any, tool		466 tokens
499 tokens

Além dos tokens base, os seguintes tokens de entrada adicionais são necessários para as ferramentas definidas pela Anthropic:

FerramentaTokens de entrada adicionais
computer_20250124 (Claude 4)735 tokens
computer_20250124 (Claude Sonnet 3.7)735 tokens
computer_20241022 (Claude Sonnet 3.5)683 tokens
text_editor_20250429 (Claude 4)700 tokens
text_editor_20250124 (Claude Sonnet 3.7)700 tokens
text_editor_20241022 (Claude Sonnet 3.5)700 tokens
bash_20250124 (Claude 4)245 tokens
bash_20250124 (Claude Sonnet 3.7)245 tokens
bash_20241022 (Claude Sonnet 3.5)245 tokens

Se você habilitar o pensamento com Claude 4 ou Claude Sonnet 3.7, os tokens usados para pensar serão contabilizados em seu orçamento de max_tokens com base no budget_tokens que você especificar no parâmetro de pensamento.