Ferramenta de uso de computador

O Claude pode interagir com ambientes de computador por meio da "computer use tool" (ferramenta de uso de computador), que fornece recursos de captura de tela e controle de mouse/teclado para interação autônoma com o desktop.

A ferramenta de uso de computador é um "client toolset" (conjunto de ferramentas do cliente) definido pela Anthropic, conforme descrito em conjuntos de ferramentas do cliente: uma única entrada {"type": "computer_toolset_20260801"} em tools dá ao Claude 17 ferramentas membro, como screenshot, left_click, type e zoom, e sua aplicação executa cada chamada em um ambiente que você controla. Atualmente, ela não está disponível no Claude Managed Agents. As chamadas do Claude são blocos tool_use cujo name é o membro e que carregam "toolset_name": "computer", frequentemente várias por turno (uma ação em lote).

Para tarefas que permanecem dentro de páginas web, a ferramenta de uso de navegador é a opção mais adequada: suas ferramentas membro leem e atuam na própria página, e ela não precisa de um ambiente de desktop completo.

Considerações de segurança

O uso de computador apresenta riscos únicos, distintos dos recursos padrão da API. Esses riscos são ampliados ao interagir com a internet.

Em algumas circunstâncias, o Claude seguirá comandos encontrados no conteúdo mesmo quando eles conflitarem com suas instruções. Por exemplo, instruções em páginas web ou contidas em imagens podem sobrepor 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 analisarão automaticamente o que as ferramentas retornam, como capturas de tela, para sinalizar possíveis injeções de prompt. Quando esses classificadores identificam uma possível injeção de prompt, eles orientam automaticamente o modelo a verificar se a instrução realmente veio de você antes de agir com base nela.

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. As precauções acima continuam importantes mesmo com esses classificadores em funcionamento.

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.

Início rápido

Adicione o conjunto de ferramentas de uso de computador ao array tools de uma requisição da Messages API como {"type": "computer_toolset_20260801"}. A requisição não precisa de cabeçalho beta. Este exemplo também declara a ferramenta de editor de texto e a ferramenta bash, que o Claude normalmente usa junto com o uso de computador:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"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."}],
)
print(response)

Quando o Claude atua no desktop, a resposta tem um stop_reason de tool_use e contém um ou mais blocos tool_use de membros, cada um nomeando uma ferramenta membro e carregando "toolset_name": "computer". No meio desta tarefa, depois que o Claude viu uma captura de tela do desktop, uma resposta pode ter esta aparência:

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Sua aplicação executa cada chamada em ordem em seu próprio ambiente, retorna um bloco tool_result por bloco tool_use e chama a API novamente; Como funciona o uso de computador descreve esse loop, e o restante desta página mostra como implementá-lo.

Como funciona o uso de computador

1. 1

   Forneça ao Claude a ferramenta de uso de computador e um prompt do usuário

   • Adicione o conjunto de ferramentas de uso de computador (e, opcionalmente, outras ferramentas) ao array tools da sua requisição à API.
   • Inclua um prompt do usuário que exija interação com o desktop, por exemplo, "Salve uma foto de um gato na minha área de trabalho."
2. 2

   O Claude responde com chamadas de ferramentas membro

   • O Claude avalia se atuar no desktop pode ajudar com a consulta do usuário.
   • Se sim, o Claude responde com um ou mais blocos tool_use de membros, como screenshot, left_click ou type, cada um carregando "toolset_name": "computer". Uma resposta com vários desses blocos é uma ação em lote.
   • A resposta da API tem um stop_reason de tool_use, sinalizando uma solicitação de uso de ferramentas.
3. 3

   Execute as chamadas em ordem e retorne os resultados

   • Itere sobre cada bloco tool_use na resposta, em ordem. Para cada um, faça o despacho com base no name do membro junto com toolset_name, e execute essa ação com o input do bloco em seu contêiner ou máquina virtual.
   • Continue a conversa com uma nova mensagem user que contenha um bloco tool_result por bloco tool_use, correspondidos por tool_use_id e cada um ecoando "toolset_name": "computer". Retorne uma imagem para screenshot e zoom; um texto curto como OK é suficiente para as outras ações.
   • Se uma ação falhar, retorne is_error: true para esse bloco e responda ao restante do lote conforme descrito em Ações em lote.
4. 4

   O Claude continua até que a tarefa seja concluída

   • O Claude analisa os resultados das ferramentas para determinar se mais ações são necessárias ou se a tarefa foi concluída.
   • Se o Claude determinar que mais ações são necessárias, ele responde com outro stop_reason de tool_use e você deve retornar à etapa 3.
   • Caso contrário, ele retorna uma resposta em texto ao usuário.

A repetição das etapas 3 e 4 sem entrada do usuário é chamada de "agent loop" (loop do agente), ou seja, o 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.

Ações em lote

O Claude pode planejar uma sequência curta de ações, como clicar, digitar e depois fazer uma captura de tela, e retorná-las juntas em uma única resposta. Isso é chamado de "batch action" (ação em lote); ela usa o mesmo formato de resposta do uso paralelo de ferramentas com uma diferença: você executa os blocos em ordem, em vez de simultaneamente.

Uma resposta com um lote de três ações tem esta aparência:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

Retorne um bloco tool_result para cada bloco tool_use, correspondidos por tool_use_id, todos na próxima mensagem user. Todo resultado de uma ferramenta membro deve carregar "toolset_name": "computer"; um resultado que o omita, ou que nomeie um conjunto de ferramentas diferente do seu bloco tool_use, é rejeitado. Apenas os resultados de screenshot e zoom precisam de uma imagem; para os outros membros, uma confirmação curta em texto como OK é suficiente (cursor_position retorna as coordenadas como texto):

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

Execute os blocos em ordem e pare na primeira falha. As ações posteriores em um lote geralmente dependem das anteriores: o type neste exemplo insere texto no que quer que o clique anterior tenha focado. Execute os blocos sequencialmente na ordem em que aparecem em content e, se um falhar, não execute os demais. Todo bloco tool_use ainda precisa de um tool_result, portanto responda ao lote da seguinte forma:

• Para cada ação que teve sucesso, retorne seu resultado normal.
• Para a ação que falhou, retorne is_error: true com uma descrição em texto do que deu errado.
• Para cada ação posterior no lote, retorne is_error: true com exatamente este texto (a ferramenta de uso de navegador usa seu próprio texto de interrupção):

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

O Claude então vê quais ações tiveram sucesso, qual falhou e quais foram ignoradas, e replaneja em seu próximo turno. Uma requisição que deixe qualquer bloco tool_use do lote sem resposta é rejeitada com um invalid_request_error, portanto um loop do agente que leia apenas o primeiro bloco falha em sua próxima chamada. Se sua aplicação pede a um humano que confirme ações com consequências, faça essa verificação antes de cada bloco ser executado, porque um lote pode concluir uma ação de várias etapas dentro de um único turno.

O Claude normalmente termina um lote com screenshot para poder observar o resultado antes de decidir o que fazer em seguida. Quando um lote não termina com uma, sua aplicação pode anexar uma captura de tela como um bloco image extra no último resultado do lote para que o Claude sempre veja o estado atual da tela, o que economiza uma ida e volta em comparação com esperar que o Claude peça. Você também pode instruir o Claude a terminar cada lote com uma captura de tela (consulte Otimize o desempenho do modelo com prompts).

O ambiente de computação

O uso de computador requer um ambiente de computação em sandbox onde o Claude possa interagir com segurança com aplicações e com a web. Esse ambiente inclui:

1. Display virtual: Um servidor de display X11 virtual (usando Xvfb) que renderiza a interface de desktop que o Claude verá por meio 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) rodando em Linux, que fornece uma interface gráfica consistente para o Claude interagir.

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

4. Implementações das ferramentas: Código de integração que traduz as solicitações abstratas de ferramentas do Claude (como "mover o mouse" ou "fazer captura de tela") 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 ao ambiente e retornando os resultados (capturas de tela, saídas de comandos) de volta ao Claude.

Quando você usa o uso de computador, o Claude não se conecta diretamente a esse ambiente. Em vez disso, sua aplicação:

1. Recebe as solicitações de uso de ferramentas do Claude
2. Traduz essas solicitações em ações no seu ambiente de computação
3. Captura os resultados (como capturas de tela e saídas de comandos)
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 os mapeamentos de porta apropriados para visualizar e interagir com o ambiente.

Como implementar o uso de computador

Atualizando uma integração existente com computer_20251124? Comece por Migrar de computer_20251124; o restante desta seção se aplica tanto a integrações novas quanto migradas.

Entenda o loop do agente

O núcleo do uso de computador é o "loop do 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, um array tools que declara apenas o conjunto de ferramentas de uso de computador e o helper de processamento de chamadas de ferramentas em Implemente a ferramenta de uso de computador. Se você também declarar outras ferramentas, como as ferramentas bash e de editor de texto do Início rápido, faça o despacho dos blocos tool_use delas na mesma passagem; o helper responde apenas às chamadas de membros do uso de computador, e o loop trata um turno sem chamadas respondidas como concluído. Aqui está um exemplo simplificado:

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 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.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

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

        # Execute as ações solicitadas pelo Claude, em ordem, e colete os resultados
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Envie todos os resultados de volta ao Claude em uma única mensagem do usuário
        messages.append({"role": "user", "content": tool_results})

    return messages

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

Otimize o desempenho do modelo com prompts

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 instruir o Claude com 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.
3. Alguns elementos de interface (como menus suspensos e barras de rolagem) podem ser difíceis para o Claude manipular usando movimentos do mouse. Se você passar por isso, tente instruir o modelo a usar atalhos de teclado.
4. Para tarefas repetíveis ou interações de interface, inclua em seu prompt capturas de tela de exemplo e chamadas de ferramentas de resultados bem-sucedidos.
5. Se você precisar que o modelo faça login, forneça a ele o nome de usuário e a senha em seu prompt dentro de tags XML como <robot_credentials>. Usar o uso de computador em aplicações que exigem login aumenta o risco de resultados ruins em decorrência de injeção de prompt. Revise Mitigar jailbreaks e injeções de prompt antes de fornecer credenciais de login ao modelo.
6. Ao construir o array 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 dos cliques.
7. O Claude usa a ação zoom para inspecionar uma região em resolução total quando questionado sobre texto pequeno ou elementos específicos da interface 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 usando zoom quando você espera, pergunte sobre uma região ou elemento específico em vez da tela como um todo.
8. Se você quiser que toda ação em lote termine com uma captura de tela, diga isso no prompt do sistema, por exemplo, End each group of actions with a screenshot so you can verify the result before continuing.

Prompts do sistema

Quando você inclui a ferramenta de uso de computador em uma requisição, a API gera um "system prompt" (prompt do sistema) específico para uso de computador. 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ções disponíveis

Cada ação é uma ferramenta membro do conjunto de ferramentas de uso de computador: o Claude nomeia o membro em um bloco tool_use que carrega "toolset_name": "computer", e o input do bloco contém apenas os parâmetros desse membro, sem campo action. O conjunto de ferramentas tem 17 ferramentas membro:

Tenha em mente o seguinte ao implementar os membros:

• As coordenadas estão em pixels da captura de tela. Todo valor de coordinate, start_coordinate e region, e a posição que cursor_position informa, está no espaço de pixels das capturas de tela do display inteiro que você retorna, com a origem no canto superior esquerdo. As imagens de zoom não mudam isso: após um zoom, o Claude ainda expressa coordenadas no espaço da captura de tela completa, nunca em relação à imagem ampliada. Se você reduzir as capturas de tela antes de retorná-las, amplie as coordenadas do Claude de volta antes de aplicá-las ao display real (consulte Dimensione as capturas de tela para caber nos limites de imagem).
• Todos os membros estão habilitados por padrão, incluindo zoom. Se seu ambiente não consegue produzir imagens de zoom, retenha o membro com configs (consulte Parâmetros da ferramenta) em vez de deixá-lo habilitado e retornar erros. Se o Claude chamar um membro que você reteve ou não implementa, retorne um tool_result com is_error: true para esse bloco.
• Faça o despacho com base no par (toolset_name, name). toolset_name é o que marca um bloco como uma ação de computador: uma ferramenta personalizada na mesma requisição pode compartilhar o nome de um membro, e uma versão posterior do conjunto de ferramentas pode adicionar membros (consulte Conjuntos de ferramentas do cliente).

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

Parâmetros da ferramenta

A entrada do conjunto de ferramentas no array tools aceita quatro parâmetros; as regras que eles compartilham com o conjunto de ferramentas de uso de navegador estão listadas em Conjuntos de ferramentas do cliente.

Por exemplo, esta entrada retém zoom para um ambiente que não o implementa e define um ponto de interrupção de cache na definição do conjunto de ferramentas:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

Se seu loop do agente só consegue executar uma ação por ida e volta, defina disable_parallel_tool_use como true em tool_choice; o Claude então retorna no máximo um bloco tool_use de membro por turno (consulte Desabilitar o uso paralelo de ferramentas).

A entrada rejeita estes parâmetros de versões anteriores da ferramenta, e uma requisição que inclua qualquer um deles retorna um invalid_request_error:

• name: os nomes dos membros são fixados pela versão do conjunto de ferramentas.
• display_width_px, display_height_px e display_number: as coordenadas estão sempre no espaço de pixels das capturas de tela que você retorna.
• enable_zoom: zoom é uma ferramenta membro que você controla por meio de configs.

A entrada também não pode ser declarada na mesma requisição que uma entrada computer_20251124 ou outra ferramenta chamada computer. Para strict, input_examples, posicionamento de defer_loading, tool_choice, streaming e restrições de chamador, consulte Conjuntos de ferramentas do cliente.

Combinando com pensamento

Para combinar o uso de computador com pensamento, consulte Pensamento.

Ampliando o uso de computador com outras ferramentas

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.

Para tarefas que permanecem dentro de páginas web, você também pode declarar a ferramenta de uso de navegador na mesma requisição: os dois conjuntos de ferramentas funcionam de forma independente, cada um em seu próprio sistema de coordenadas, e as chamadas a membros que compartilham um nome, como screenshot ou key, são diferenciadas por toolset_name.

Construa um ambiente personalizado de uso de computador

A implementação de referência tem como objetivo ajudar você a começar com o uso de computador. Ela inclui todos os componentes necessários para que o 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:

• Um ambiente virtualizado ou em contêiner adequado para uso de computador com o Claude
• Uma implementação das ações da ferramenta de uso de computador
• Um loop do agente que interaja com a Claude API e execute os resultados de tool_use usando suas implementações de ferramentas
• Uma API ou interface que permita a entrada do usuário para iniciar o loop do agente

Implemente 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 em outras ferramentas; o schema está incorporado ao modelo do Claude e não pode ser modificado.

1. 1

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

2. 2

   Implemente os handlers de ações

   Crie funções para tratar cada tipo de ação que o Claude possa solicitar:

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Dados de imagem de placeholder; um executor real captura a tela e retorna os bytes PNG
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot responde com um bloco de imagem em vez de texto: retorne a lista de conteúdo do resultado
       return [
           {
               "type": "image",
               "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate é opcional; sem ele, clique onde o cursor já está
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # Trate outras ações conforme necessário
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Processe as chamadas de ferramentas do Claude

   Extraia e execute as chamadas de ferramentas das respostas do Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # Apenas o conjunto de ferramentas computer é declarado; roteie outras ferramentas aqui se você as adicionar
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # Uma string ou uma lista de blocos de conteúdo, como a imagem da captura de tela
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   Implemente o loop do agente

   Envolva as duas etapas anteriores em um loop que envie os resultados de volta e repita até que o Claude não retorne nenhuma chamada de ferramenta membro; Entenda o loop do agente mostra esse loop em cada linguagem.

Trate erros

Informe uma ação com falha ao Claude como um tool_result com is_error: true e uma descrição curta, e inclua "toolset_name": "computer" como em qualquer outro resultado de membro. Se a ação com falha fazia parte de uma ação em lote, responda aos blocos restantes do lote com o texto de interrupção mostrado lá em vez de executá-los.

Por exemplo, quando a captura de tela falha:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

Use o mesmo formato para coordenadas fora dos limites do display e para ações que falham ao executar, com uma mensagem que diga o que deu errado.

Dimensione as capturas de tela para caber nos limites de imagem

As capturas de tela e imagens de zoom que você retorna ao conjunto de ferramentas de uso de computador já devem caber nos limites de tamanho de imagem do seu modelo: o conjunto de ferramentas não recebe dimensões de display e a API não reduz a escala para você, portanto uma imagem de tool_result grande demais é rejeitada com um erro de validação. Como o Claude retorna coordenadas no espaço de pixels da imagem que ele vê, guarde o fator de escala que você usou para poder mapear essas coordenadas de volta à sua tela.

Se sua tela for maior que o limite, redimensione cada captura de tela antes de retorná-la e escale as coordenadas retornadas pelo Claude de volta ao espaço original da tela. Como o conjunto de ferramentas não recebe dimensões de display, o redimensionamento e o escalonamento de coordenadas no código da sua aplicação são tudo de que você precisa:

import math

screen_width, screen_height = 1512, 982


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 para o tamanho original
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Ao escolher uma resolução de display e retornar capturas de tela:

• Para tarefas gerais de desktop, use 1024x768 ou 1280x720; para aplicações web, use 1280x800 ou 1366x768.
• Evite resoluções acima de 1920x1080 para prevenir problemas de desempenho.
• Codifique as capturas de tela como PNG ou JPEG em base64 e considere comprimir capturas de tela grandes para melhorar o desempenho.
• Inclua metadados relevantes, como timestamp ou estado do display.
• Se você usar resoluções mais altas, garanta que as coordenadas sejam escaladas com precisão.

Gerenciar o histórico de capturas de tela

Loops de agente longos acumulam capturas de tela rapidamente (aproximadamente 1.000–1.800 tokens de entrada cada). Os limites de requisição da API também se aplicam. Quando uma única requisição carrega mais de 20 imagens, cada imagem nela fica sujeita a um limite por lado mais rigoroso. Um loop que mantém seu histórico de capturas de tela atinge essa contagem em algumas dezenas de turnos, então redimensione cada captura de tela para que nenhum lado exceda 2000 px ou remova capturas de tela mais antigas para manter 20 ou menos na requisição.

Para manter o cache de prompt eficaz enquanto limita o contexto:

• Coloque um breakpoint cache_control após o "system prompt" (prompt do sistema) e as definições de ferramentas, e até mais três no último bloco tool_result de cada um dos turnos mais recentes, avançando-os a cada turno. Dentro de uma ação em lote, marcadores em vários blocos funcionam como um único breakpoint, mas cada um ainda conta para o limite de quatro. Por isso, use um por turno.
• Remova capturas de tela antigas em lotes, não uma a cada turno. Descartar uma captura de tela a cada turno altera o prefixo a cada turno e invalida o cache. Um padrão razoável é manter as três últimas capturas de tela e fazer a remoção a cada 25 turnos, para que o prefixo permaneça idêntico byte a byte entre os eventos de remoção. Se suas capturas de tela excederem 2000 px em qualquer lado, escolha um intervalo que mantenha cada requisição com 20 imagens ou menos.
• No Claude Fable 5.1, Claude Opus 5.5 e Claude Sonnet 5.5, evite fazer a remoção no cliente: remover uma captura de tela anterior invalida todos os blocos de pensamento posteriores em todas as requisições que ainda contêm esses turnos. Em vez disso, redimensione as capturas de tela para 2000 px ou menos por lado e use a limpeza de resultados de ferramentas no lado do servidor para descartar as antigas do contexto. Se você precisar fazer a remoção, mantenha prefix_mismatch_behavior: "drop_block" definido a partir de então. Após cada remoção, Claude continua sem o pensamento produzido desde a captura de tela removida, nessa requisição e em todas as posteriores. No Claude Sonnet 5.5, block_binding funciona apenas com thinking: {"type": "adaptive"}. Com between_tools, mantenha o histórico somente com acréscimos, ou remova os blocos de pensamento a partir do turno editado.

Diagnosticar problemas de clique

Se os cliques erram seus alvos, a causa geralmente é uma das seguintes:

Seguir 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)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging


def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

Migrar de computer_20251124

Atualizar de computer_20251124 para o toolset é opcional: os modelos listados para computer_20251124 em Versões anteriores da ferramenta continuam aceitando-o com seu cabeçalho beta, então uma integração existente continua funcionando até que você a altere. Os modelos Claude 5.5 e posteriores são a exceção na Claude API e no Google Cloud: lá eles aceitam apenas o toolset. Atualize uma integração antes de movê-la para um deles. No Amazon Bedrock, o Claude Opus 5.5 e o Claude Sonnet 5.5 continuam aceitando computer_20251124. Para atualizar, faça as seguintes alterações em conjunto:

1. Remova o cabeçalho beta. Retire anthropic-beta: computer-use-2025-11-24 das suas requisições. Nos SDKs, remova o parâmetro betas e chame a Messages API por meio do cliente padrão em vez do namespace beta.
2. Altere a entrada tools. Defina type como computer_toolset_20260801 e exclua name, display_width_px, display_height_px, display_number e enable_zoom. O toolset rejeita cada um desses campos.
3. Escolha se deseja manter o zoom habilitado. O zoom é habilitado por padrão no toolset, enquanto enable_zoom tem como padrão false. Se seu ambiente não implementa zoom, adicione "configs": {"zoom": {"enabled": false}} para manter o comportamento anterior; caso contrário, implemente-o (consulte Ações disponíveis).
4. Trate todos os blocos em um turno. Atualize seu loop de agente para iterar sobre cada bloco tool_use em uma resposta em vez de ler apenas o primeiro, e para despachar com base no name do bloco junto com toolset_name em vez de input.action. As entradas dos membros não contêm mais um campo action; os campos restantes permanecem inalterados.
5. Execute os blocos em ordem e use o texto de interrupção. Execute os blocos sequencialmente, pare na primeira falha e responda aos blocos restantes com Not executed: an earlier computer action in this turn failed. conforme descrito em Ações em lote. Se seu loop ainda não consegue executar lotes, Parâmetros da ferramenta explica como limitar Claude a uma ação por turno.
6. Repita toolset_name nos resultados. Adicione "toolset_name": "computer" a cada tool_result que responde a uma chamada de membro. Os resultados podem conter apenas conteúdo text e image.
7. Suporte repeat em key. O membro key aceita uma contagem repeat opcional de 1 a 100. Um manipulador que ignora campos não reconhecidos pressionaria a tecla uma vez, então faça seu manipulador de key respeitar repeat.
8. Redimensione as capturas de tela você mesmo. O toolset rejeita uma captura de tela ou imagem de zoom que exceda os limites de imagem do modelo em vez de reduzi-la. Redimensione antes de retornar a imagem e continue escalando as coordenadas conforme descrito em Dimensionar capturas de tela para caber nos limites de imagem.
9. Remova opções não suportadas. Mova qualquer defer_loading da entrada para configs, com o mesmo valor em cada membro habilitado. As outras opções não suportadas em entradas de toolset estão listadas em Toolsets do cliente.

Esta é a entrada tools antes da alteração, enviada com o cabeçalho anthropic-beta: computer-use-2025-11-24:

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

Esta é a entrada tools após a alteração, enviada sem cabeçalho beta. O objeto configs mantém o zoom desativado para corresponder à entrada anterior, que não define enable_zoom; omita configs completamente para aceitar o padrão e permitir que Claude faça zoom:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

O par a seguir mostra um bloco tool_use antes e depois da alteração. O nome da ação passa de input.action para name, e o bloco ganha toolset_name:

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

Versões anteriores da ferramenta

Duas versões anteriores da ferramenta de uso de computador permanecem disponíveis em beta para integrações existentes, para modelos que não suportam o toolset e em plataformas onde o toolset não está disponível atualmente. Cada uma requer seu cabeçalho beta em toda requisição, e seus parâmetros estão documentados na referência beta da Messages API. Nos SDKs, passe o cabeçalho por meio do parâmetro betas e use o namespace beta; apenas a ferramenta de uso de computador precisa do cabeçalho, não as ferramentas bash ou de editor de texto na mesma requisição.

Limitações

1. Latência: A latência atual do uso de computador para interações humano-IA pode ser muito lenta em comparação com ações de computador regulares 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.
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. A saída de pensamento resumido do Claude pode ajudar você a entender o raciocínio do modelo e identificar possíveis problemas; defina display: "summarized" na configuração de pensamento, porque os modelos que suportam o toolset omitem o texto de pensamento por padrão.
3. Precisão e confiabilidade da 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 aplicações de nicho ou várias aplicações ao mesmo tempo. Elabore o prompt do modelo com cuidado ao solicitar tarefas complexas.
4. Confiabilidade da 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.
5. Interação com planilhas: Use as ações de controle fino 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 várias tentativas.
6. Criação de contas e geração de conteúdo em plataformas sociais e de comunicação: Embora Claude visite sites, sua capacidade de criar contas, gerar e compartilhar conteúdo ou de outra forma se envolver em personificação humana em sites e plataformas de mídia social é limitada.
7. Vulnerabilidades: Jailbreaks e injeção de prompt podem afetar o uso de computador assim como podem afetar qualquer sistema de IA de fronteira, inclusive por meio de instruções incorporadas em páginas web ou imagens; aplique as precauções em Considerações de segurança.
8. 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 os registros de uso de computador do Claude. Não use Claude para tarefas que exijam precisão perfeita ou informações sensíveis de usuários sem supervisão humana.

Retenção de dados

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 requisiçõ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 ZDR em todos os recursos, consulte API e retenção de dados.

Preços

O uso do computador segue os preços padrão de uso de ferramentas. Ao usar a ferramenta de uso do computador:

Sobrecarga da definição do toolset: Declarar computer_toolset_20260801 com seus membros padrão adiciona cerca de 4.500 tokens de entrada a uma requisição (cerca de 4.520 no Claude Fable 5, Claude Mythos 5, Claude Opus 5 e Claude Opus 4.8, e cerca de 4.590 no Claude Sonnet 5), o que cobre as definições das ferramentas membros e o prompt do sistema de uso de ferramentas. Desabilitar zoom com configs remove cerca de 410 desses tokens. A contagem exata para uma requisição é informada no usage da resposta, e você pode estimá-la antecipadamente com o endpoint de contagem de tokens.

Versões anteriores da ferramenta: Os valores a seguir se aplicam às versões de ferramenta computer_20251124 e computer_20250124, não à computer_toolset_20260801:

• Sobrecarga do prompt do sistema: 466–499 tokens adicionados ao prompt do sistema
• Definição da ferramenta: cerca de 735 tokens de entrada por definição de ferramenta (medido com computer_20250124)

Consumo adicional de tokens:

• Imagens de captura de tela e de zoom retornadas nos resultados das ferramentas, cobradas como entrada de imagem (consulte Preços de visão)
• Resultados da execução de ferramentas retornados ao Claude

Próximos passos

Compatibility