Claude Platform Docs
MensagensFerramentas

Ferramenta de uso do computador

Dê ao Claude controle de capturas de tela, mouse e teclado de um ambiente de desktop com a ferramenta de uso do computador, o conjunto de ferramentas de cliente computer_toolset_20260801.

Claude pode interagir com ambientes de computador por meio da 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 (toolset de cliente) definido pela Anthropic: uma 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. No momento, 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 em um único turno (uma “batch action” (ação em lote)).

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

Consulte Suporte da API para ver os modelos e plataformas que oferecem suporte ao conjunto de ferramentas. Versões anteriores da ferramenta lista o cabeçalho beta de cada versão anterior e os modelos com os quais usá-la.

Considerações de segurança

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

Em algumas circunstâncias, Claude segue comandos encontrados no conteúdo mesmo quando eles entram em conflito com suas instruções. Por exemplo, instruções em páginas web ou contidas em imagens podem substituir suas instruções ou fazer com que Claude cometa erros. Tome precauções para isolar Claude de dados e ações sensíveis a fim de evitar riscos relacionados a “prompt injection” (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 a ferramenta de uso de computador, classificadores analisam automaticamente o que a ferramenta retorna, 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 o modelo a verificar se a instrução realmente veio de você antes de agir com base nela.

Essa proteção extra não é ideal para todos os casos de uso (por exemplo, casos de uso sem um humano no circuito), portanto, se você quiser optar por não usá-la e desativá-la, entre em contato com o suporte. As precauções listadas anteriormente 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 toolset de uso de computador ao array tools de uma requisição da Messages APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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 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 Claude age no desktop, a resposta tem um stop_reason igual a tool_use e contém um ou mais blocos tool_use de membro, cada um nomeando uma ferramenta membro e carregando "toolset_name": "computer". No meio desta tarefa, depois que Claude recebeu uma captura de tela do desktop, uma resposta pode ter esta aparência:

Output
{
  "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 no seu próprio ambiente, retorna um bloco tool_result para cada 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. Forneça ao Claude a ferramenta de uso de computador e um prompt do usuário

    • Adicione o toolset de uso de computador (e, opcionalmente, outras ferramentas) ao array tools da sua requisição de 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. Claude responde com chamadas de ferramentas membro

    • Claude avalia se agir no desktop pode ajudar com a consulta do usuário.
    • Se sim, Claude responde com um ou mais blocos tool_use de membro, 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 igual a tool_use, sinalizando uma solicitação de uso de ferramentas.
  3. Execute as chamadas em ordem e retorne os resultados

    • Percorra cada bloco tool_use da 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 no seu contêiner ou máquina virtual.
    • Continue a conversa com uma nova mensagem user que contenha um bloco tool_result para cada bloco tool_use, correspondido por tool_use_id e cada um repetindo "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. Claude continua até que a tarefa seja concluída

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

As etapas 3 e 4, repetidas sem entrada do usuário, formam o “agent loop” (loop do agente): Claude responde com uma solicitação de uso de ferramentas, e sua aplicação responde ao Claude com os resultados da avaliação dessa solicitação.

Ações em lote

Claude pode planejar uma curta sequência de ações, como clicar, digitar e depois fazer uma captura de tela, e retorná-las juntas em uma única resposta. Isso é chamado de ação em lote; ela usa o mesmo formato de resposta que o uso paralelo de ferramentas, com uma diferença: você executa os blocos em ordem, e não 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, correspondido por tool_use_id, todos na próxima mensagem user. Todo resultado para uma ferramenta membro deve carregar "toolset_name": "computer"; um resultado que o omita, ou que nomeie um toolset diferente do seu bloco tool_use, é rejeitado. Somente os resultados de screenshot e zoom precisam de uma imagem; para os outros membros, um breve reconhecimento 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. Ações posteriores em um lote geralmente dependem das anteriores: o type neste exemplo insere texto no elemento que o clique anterior colocou em foco. 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, então responda ao lote da seguinte forma:

  • Para cada ação bem-sucedida, 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 do 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."
}

Claude então lê quais ações foram bem-sucedidas, 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 lê 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 executar cada bloco, porque um lote pode concluir uma ação de várias etapas em um único turno.

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

O ambiente computacional

O uso de computador requer um ambiente computacional isolado (sandbox) no qual Claude possa interagir com segurança com aplicações e com a web. Esse ambiente inclui:

  1. Tela virtual: Um servidor de exibição X11 virtual (usando Xvfb) que renderiza a interface do desktop que Claude recebe como capturas de tela e controla 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 Claude interagir.

  3. Aplicações: Aplicações Linux pré-instaladas, como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos, que 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 Claude e o ambiente, enviando as ações do Claude ao ambiente e retornando os resultados (capturas de tela, saídas de comandos) ao Claude.

Quando você usa o uso de computador, 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 computacional.
  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 mapeamentos de porta apropriados para visualizar e interagir com o ambiente.


Como implementar o uso de computador

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

Entenda o loop do agente

O núcleo do uso de computador é o “loop do agente”: um ciclo em que Claude solicita ações de ferramentas, e 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 toolset de uso de computador, e a função auxiliar de processamento de chamadas de ferramenta 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, despache os blocos tool_use delas na mesma passagem; a função auxiliar 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,
        )

        # Add Claude's response to the conversation history
        messages.append({"role": "assistant", "content": response.content})

        # Run the actions Claude requested, in order, and collect the results
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Send every result back to Claude in a single user message
        messages.append({"role": "user", "content": tool_results})

    return messages

O loop continua até que Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou até que o limite máximo de iterações seja atingido. Essa salvaguarda evita possíveis loops infinitos que poderiam resultar em custos inesperados de API.

Otimize o desempenho do modelo com prompts

  1. Especifique tarefas bem definidas e forneça instruções explícitas para cada etapa.
  2. Às vezes, Claude age como se suas ações tivessem sido bem-sucedidas sem verificar explicitamente os resultados. Para evitar isso, você pode instruir Claude com After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, 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 Claude manipular usando movimentos do mouse. Se você enfrentar isso, tente instruir o modelo a usar atalhos de teclado.
  4. Para tarefas repetíveis ou interações com a interface, inclua no seu prompt capturas de tela de exemplo e chamadas de ferramentas com resultados bem-sucedidos.
  5. Se você precisar que o modelo faça login, forneça o nome de usuário e a senha no 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 Mitigue jailbreaks e injeções de prompt antes de fornecer ao modelo credenciais de login.
  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. Claude usa a ação zoom para inspecionar uma região em resolução total quando perguntado sobre textos pequenos 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 Claude não estiver usando o 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.

Se você encontrar repetidamente um conjunto claro de problemas, ou souber com antecedência as tarefas que Claude precisa concluir, dê ao Claude dicas ou instruções explícitas para elas no prompt do sistema.

Para agentes que abrangem várias sessões, execute a verificação de ponta a ponta no início de cada sessão, não apenas após a implementação. Verificações baseadas no navegador detectam regressões de sessões anteriores que a revisão apenas no nível do código deixa passar. Consulte Harnesses eficazes para agentes de longa duração para mais detalhes.

Prompts do sistema

Quando você inclui a ferramenta de uso de computador em uma requisição, a API gera um prompt do sistema específico para o 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 comum, o parâmetro system fornecido pelo usuário continua sendo respeitado e usado na construção do prompt do sistema combinado.

Ações disponíveis

Cada ação é uma ferramenta membro do toolset de uso de computador: 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 nenhum campo action. O toolset tem 17 ferramentas membro:

MembroEntradaDescrição
screenshotNenhuma ({})Captura a tela inteira e a retorna como uma imagem.
zoomregion: [x0, y0, x1, y1], os cantos superior esquerdo e inferior direito da área a inspecionarCaptura apenas essa região da tela em resolução total e a retorna como uma imagem, redimensionada para caber nas dimensões habituais da sua captura de tela, preservando a proporção. Isso permite que Claude leia textos pequenos ou interfaces densas que não são legíveis em uma captura de tela completa reduzida.
left_clickcoordinate (opcional): [x, y]; text (opcional): teclas modificadoras a manter pressionadas durante o clique: shift, ctrl, alt, super (a tecla Command ou Windows), ou uma combinação unida por +, como ctrl+shiftClica com o botão esquerdo do mouse em coordinate, ou na posição atual do cursor quando coordinate é omitido.
right_click, middle_click, double_click, triple_clickIgual a left_clickOutros botões do mouse e cliques múltiplos.
left_click_dragstart_coordinate: [x, y]; coordinate: [x, y]; text (opcional): teclas modificadorasPressiona em start_coordinate, arrasta até coordinate e solta.
mouse_movecoordinate: [x, y]Move o cursor sem clicar, por exemplo, para passar o mouse sobre algo.
left_mouse_down, left_mouse_upNenhuma ({})Pressiona ou solta o botão esquerdo do mouse na posição atual do cursor, para arrastes que left_click_drag não consegue expressar. Mova o cursor com mouse_move primeiro.
cursor_positionNenhuma ({})Informa a posição [x, y] atual do cursor como texto.
scrollscroll_direction: "up", "down", "left" ou "right"; scroll_amount: número de cliques da roda de rolagem; coordinate (opcional): [x, y]; text (opcional): teclas modificadorasRola em coordinate, ou na posição atual do cursor.
typetext: a string a ser digitadaDigita texto literal no foco atual do teclado.
keytext: uma tecla ou uma combinação unida por +, como "Return", "ctrl+s" ou "alt+Tab"; repeat (opcional): de 1 a 100, padrão 1Pressiona uma tecla ou combinação de teclas repeat vezes.
hold_keytext: uma tecla ou combinação; duration: segundos, até 300Mantém uma tecla pressionada pela duração informada.
waitduration: segundos, até 300Pausa antes da próxima ação, por exemplo, enquanto uma aplicação carrega.

Tenha o seguinte em mente 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ão no espaço de pixels das capturas de tela da tela inteira que você retorna, com a origem no canto superior esquerdo. As imagens de zoom não mudam isso: após um zoom, 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 de volta as coordenadas do Claude antes de aplicá-las à tela real (consulte Dimensione capturas de tela para caber nos limites de imagem).
  • Todos os membros são habilitados por padrão, incluindo zoom. Se o seu ambiente não puder produzir imagens de zoom, retire o membro com configs (consulte Parâmetros da ferramenta) em vez de deixá-lo habilitado e retornar erros. Se Claude chamar um membro que você retirou ou não implementou, 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 do computador: uma ferramenta personalizada na mesma requisição pode compartilhar o nome de um membro, e uma versão posterior do toolset pode adicionar membros (consulte Toolsets de cliente).

Parâmetros da ferramenta

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

ParâmetroObrigatórioDescrição
typeSimcomputer_toolset_20260801
configsNãoConfigurações por membro, indexadas pelo nome do membro; cada membro aceita enabled (padrão true para todos os 17, incluindo zoom) e defer_loading (padrão false, para a busca de ferramentas), e os membros que você omitir mantêm seus padrões.
cache_controlNãoPonto de interrupção do cache de prompt na definição do toolset; somente na entrada. Um ponto de interrupção em qualquer bloco tool_use ou tool_result de um lote entra em vigor no final desse lote; consulte Uso de ferramentas com cache de prompt.
allowed_callersNãoSomente ["direct"].

Por exemplo, esta entrada retira zoom para um ambiente que não o implementa e define um ponto de interrupção de cache na definição do toolset:

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

Se o seu loop do agente só puder executar uma ação por ida e volta, defina disable_parallel_tool_use como true em tool_choice; 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 toolset.
  • 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: o 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 Toolsets de 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 do navegador na mesma requisição. Os dois toolsets funcionam de forma independente, cada um em seu próprio sistema de coordenadas. O valor de toolset_name distingue chamadas para membros que compartilham um nome, como screenshot ou key.

Construa um ambiente personalizado de uso de computador

A implementação de referência tem o objetivo de ajudar você a começar com o uso de computador. Ela inclui todos os componentes necessários para que Claude use um computador. No entanto, você pode criar seu próprio ambiente para o uso de computador de acordo com suas necessidades. Você precisa de:

  • Um ambiente virtualizado ou em contêiner adequado para o uso de computador com 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 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 essa ferramenta, você não precisa fornecer um schema de entrada como acontece com outras ferramentas; o schema é incorporado ao modelo do Claude e não pode ser modificado.

  1. Configure seu ambiente computacional

    Crie uma tela virtual ou conecte-se a uma tela existente com a qual Claude interage. Isso normalmente envolve configurar o Xvfb (X Virtual Framebuffer) ou uma tecnologia semelhante.

  2. Implemente os manipuladores de ações

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

    # Placeholder image data; a real executor captures the screen and returns the PNG bytes
    PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
    
    
    def capture_screenshot() -> list[ImageBlockParam]:
        # screenshot answers with an image block rather than text: return the result content list
        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 is optional; without it, click where the cursor already is
                return click(tool_input.get("coordinate"))
            case "type":
                return type_text(tool_input["text"])
        # Handle other actions as needed
        raise ValueError(f"Unknown or unimplemented member: {name}")
  3. Processe as chamadas de ferramentas do Claude

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

    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:
            # Only the computer toolset is declared; route other tools here if you add them
            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:
                    # A string, or a list of content blocks such as the screenshot image
                    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. Implemente o loop do agente

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

Trate erros

Informe uma ação com falha ao Claude como um tool_result com is_error: true e uma breve descrição, 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 ali 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 da tela e para ações que não conseguem ser executadas, com uma mensagem que diga o que deu errado.

Dimensione capturas de tela para caber nos limites de imagem

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

Se sua tela for maior que o limite, redimensione cada captura de tela antes de retorná-la e converta as coordenadas retornadas por Claude de volta para o espaço original da tela. Como o toolset não recebe dimensões de exibição, o redimensionamento e a conversão 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 fazer 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 enviá-la ao Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# Ao processar as coordenadas do Claude, escale-as de volta
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 exibição 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 da tela.
  • Se você usar resoluções mais altas, garanta que as coordenadas sejam convertidas com precisão.

Gerencie 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 contém 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 pode atingir essa contagem. Ou redimensione cada captura de tela para ficar abaixo desse limite, 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 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 atuam como um único breakpoint, mas cada um ainda conta para o limite de quatro, então use no máximo um em qualquer 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 remover 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 o limite mais rigoroso, escolha um intervalo que mantenha cada requisição com 20 imagens ou menos.
  • Evite fazer a remoção no cliente no Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 e Claude Mythos 5.1. O mesmo vale para Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5. Nesses modelos, remover uma captura de tela anterior de uma requisição invalida todos os blocos de pensamento posteriores já presentes no histórico dessa requisição e de todas as requisições posteriores.
    • Em vez disso: Redimensione as capturas de tela para ficar abaixo do limite mais rigoroso. A limpeza de resultados de ferramentas economiza tokens, mas as capturas de tela limpas ainda contam para os limites de requisição, então use a compactação sob demanda antes que um loop os atinja.
    • Se precisar fazer a remoção: Mantenha prefix_mismatch_behavior: "drop_block" definido a partir de então. Após cada remoção, a API descarta os blocos de pensamento invalidados, nessa requisição e em todas as posteriores. Assim, Claude continua sem o pensamento que produziu após a captura de tela removida.
    • Se precisar fazer a remoção no Claude Sonnet 5.5 ou no Claude Haiku 5.5: prefix_mismatch_behavior funciona apenas com thinking: {"type": "adaptive"}. Com qualquer outra configuração de pensamento nesses modelos, mantenha o histórico apenas com acréscimos ou remova todos os blocos thinking e redacted_thinking após a captura de tela removida.

Diagnostique problemas de clique

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

SintomaCausa provávelTente
Cliques consistentemente deslocados em uma direçãoAs coordenadas de Claude, que estão no espaço de pixels das capturas de tela que você retorna, estão sendo aplicadas a uma tela de tamanho diferente sem conversão de escalaConverta cada coordenada pela razão entre o tamanho da sua tela e o tamanho da sua captura de tela antes de clicar (consulte Dimensione capturas de tela para caber nos limites de imagem); em telas Retina do macOS, considere a proporção de pixels do dispositivo de 2x
Cliques caem na área certa, mas erram o alvoO alvo é muito pequeno, detalhes foram perdidos ao reduzir a escala de uma fonte 4K+ ou a proporção foi distorcidaMantenha o membro zoom habilitado e implemente-o para que Claude possa inspecionar a região em resolução total; capture com DPI menor ou recorte para a região relevante; preserve a proporção ao redimensionar
Claude clica no elemento totalmente erradoInstrução ambígua ou elementos visualmente semelhantes próximosUse prompts posicionais (“o botão azul Submit no canto inferior direito”); divida a interação em etapas menores
A precisão é consistentemente ruimResolução muito baixaTente 1280x720 como base

Siga as melhores práticas de implementação


Migre de computer_20251124

Uma integração computer_20251124 funciona sem alterações nos modelos listados para essa versão em Versões anteriores da ferramenta. Atualize a integração antes de movê-la para um modelo que não aceita computer_20251124, como Claude Opus 5.5 na Claude API.

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. Com o SDK, remova betas e chame a Messages API pelo 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 o 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 todos os blocos 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 o 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 opcional repeat de 1 a 100. Um handler que ignora campos não reconhecidos pressionaria a tecla uma vez, então faça seu handler 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 reduzir sua escala. Redimensione antes de retornar a imagem e continue convertendo as coordenadas conforme descrito em Dimensione 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 todos os membros habilitados. As outras opções não suportadas em entradas de toolset estão listadas em Toolsets de 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 inteiramente para aceitar o padrão e permitir que Claude use 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 “computer use” (uso do computador) estão disponíveis em beta. Cada uma requer seu cabeçalho beta em todas as solicitações, e seus parâmetros estão documentados na referência da Messages API betaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.. Com o SDK, passe o cabeçalho por meio de betas e use o namespace beta; apenas a ferramenta de uso do computador precisa do cabeçalho, não as ferramentas bash ou de editor de texto na mesma solicitação.

Versão da ferramentaCabeçalho betaUsar comParâmetros
computer_20251124computer-use-2025-11-24Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5Referência da APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.
computer_20250124computer-use-2025-01-24Claude Sonnet 4.5 (descontinuado), Claude Haiku 4.5, Claude Opus 4.1 (desativado, exceto no Claude Models on Google Cloud (Google managed) e no Bedrock), Claude Sonnet 4 (desativado, exceto no Claude Models on Google Cloud (Google managed) e no Bedrock) e Claude Opus 4 (desativado, exceto no Claude Models on Google Cloud (Google managed))Referência da APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.

No Amazon Bedrock, Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 também aceitam a ferramenta computer_20251124 com o cabeçalho beta computer-use-2025-11-24. Com a InvokeModel API do Amazon Bedrock, envie computer-use-2025-11-24 no array anthropic_beta do corpo da requisição em vez de em um cabeçalho. Para essa API, consulte Claude no Amazon Bedrock (bedrock-runtime).


Limitações

  1. Latency (latência): A latência do uso de computador para interações humano-IA pode ser lenta demais em comparação com ações de computador regulares dirigidas por humanos. Concentre-se em casos de uso em que 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 produzir coordenadas específicas durante a geração de ações. A saída de pensamento resumido de 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 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 aplicações de nicho ou com várias aplicações ao mesmo tempo. Escreva prompts para o 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, para a esquerda, para a direita) e uma quantidade especificada. Em aplicações em que 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 refinado do mouse (left_mouse_down, left_mouse_up) e combinações com 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 passar por humanos em sites e plataformas de mídia social é limitada.
  7. Vulnerabilidades: Jailbreaks e injeção de prompt podem afetar o uso de computador 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 inadequadas 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 logs de uso de computador de 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 à API. A retenção dessas requisições à 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.

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 conjunto de ferramentas: Declarar computer_toolset_20260801 com seus membros padrão adiciona cerca de 4.500 tokens de entrada a uma requisição (cerca de 4.590 no Claude Sonnet 5 e cerca de 4.520 nos outros modelos suportados), o que abrange as definições das ferramentas membro e o prompt do sistema de uso de ferramentas. Desativar zoom com configs remove cerca de 410 desses tokens. A contagem exata de 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

Comece com o driver de um parceiro ou escreva o seu próprio em Python ou TypeScript. O SDK executa o loop e o callback de aprovação que você passar.

Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para correção.

Comece com a implementação completa baseada em Docker.

Conecte Claude a ferramentas e APIs externas. Veja onde as ferramentas são executadas, quando Claude as chama e qual ferramenta se adequa à sua tarefa.

Recomendações baseadas em benchmarks para resolução, esforço de pensamento e gerenciamento de contexto.

Permita que Claude navegue, leia e interaja com páginas web no seu próprio ambiente de navegador, para tarefas que permanecem dentro do navegador.

Disponibilidade

Ferramenta de uso do computador
APIs
  • Messages API
  • Managed Agents Não compatível
Modelos
  • Claude Fable 5.2, Fable 5.1, Fable 5
  • Claude Mythos 5.2, Mythos 5.1, Mythos 5, Mythos Preview
  • Claude Opus 5.5, Opus 5, Opus 4.8
  • Claude Opus 4.7, Opus 4.6, Opus 4.5 Beta requer
  • Claude Sonnet 5.5, Sonnet 5
  • Claude Sonnet 4.6 Beta requer
  • Claude Sonnet 4.5 Beta requer
  • Claude Haiku 5.5
  • Claude Haiku 4.5 Beta requer

Endpoints aplicáveis

  • /v1/messages com o conjunto de ferramentas ou a ferramenta computer
Retenção zero de dadosElegível

Exclui Modelos cobertos

Ferramenta no lado do cliente em que capturas de tela e arquivos são capturados e armazenados no seu ambiente, não pela Anthropic. Saiba mais

HIPAAElegível

Esta página foi útil?