---
title: Ferramenta de uso do computador
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool
description: 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.
featureMetadata:
  betaHeader: computer-use-2025-11-24, computer-use-2025-01-24
  zdr:
    eligibility: eligible
    note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Ferramenta no lado do cliente em que capturas de tela e arquivos são capturados e armazenados no seu ambiente, não pela Anthropic.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Amazon Bedrock: stable
    Amazon Bedrock (bedrock-runtime): stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Google managed): stable
    Microsoft Foundry: stable
  details:
    - Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 oferecem suporte ao uso do computador por meio do conjunto de ferramentas `computer_toolset_20260801`. Eles retornam um erro 400 para qualquer versão da ferramenta de uso do computador que não aceitam, como `computer_20251124` na Claude API. Para migrar uma integração `computer_20251124` para o conjunto de ferramentas, consulte [Migre de `computer_20251124`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Para migrar de `computer_20250124`, consulte [Mover o uso do computador para o conjunto de ferramentas](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#computer-use-toolset) no guia de migração do Claude Haiku 5.5.
    - Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5 oferecem suporte ao uso do computador apenas por meio da versão da ferramenta `computer_20251124`, que requer um cabeçalho beta; consulte [Versões anteriores da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions).
---

<Note>
  **Comece pelos toolsets do SDK:** Para `computer_toolset_20260801`, os SDKs de Python e TypeScript têm uma classe de toolset de computador, em beta. Comece a partir de [a integração de um parceiro](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-sdk#partner-integrations) ou consulte a seção [toolset de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-sdk#computer-toolset) da página de toolsets do SDK. Use esta página como referência da ferramenta ou quando você mesmo tratar as chamadas de ferramenta.
</Note>

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)](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets) 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](https://platform.claude.com/docs/pt-BR/managed-agents/tools). 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)](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions)).

Para tarefas que permanecem dentro de páginas web, a [ferramenta de uso do navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) é 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#availability-feature-support) para ver os modelos e plataformas que oferecem suporte ao conjunto de ferramentas. [Versões anteriores da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) 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.

<Warning>
  Para minimizar os riscos, considere tomar precauções como:

  1. Usar uma máquina virtual ou contêiner dedicado com privilégios mínimos para evitar ataques diretos ao sistema ou acidentes.
  2. Evitar dar ao modelo acesso a dados sensíveis, como informações de login de contas, para evitar roubo de informações.
  3. Limitar o acesso à internet a uma lista de domínios permitidos para reduzir a exposição a conteúdo malicioso.
  4. Pedir a um humano que confirme decisões que possam resultar em consequências significativas no mundo real e quaisquer tarefas que exijam consentimento afirmativo, como aceitar cookies, concluir transações financeiras ou concordar com termos de serviço.
</Warning>

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](https://support.claude.com/en/). 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 API](https://platform.claude.com/docs/pt-BR/api/messages/create) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool) e a [ferramenta bash](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool), que Claude normalmente usa junto com o uso de computador:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "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."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  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.
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await 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." }]
  });

  console.log(response);
  ```

  ```csharp C#
  var client = new AnthropicClient();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools =
      [
          new ComputerToolset20260801(),
          new ToolTextEditor20250728(),
          new ToolBash20250124(),
      ],
      Messages = [new UserMessageParam { Content = "Save a picture of a cat to my desktop." }],
  };

  var response = await client.Messages.Create(parameters);
  Console.WriteLine(response);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Tools: []anthropic.ToolUnionParam{
  		{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
  		{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
  		{OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Save a picture of a cat to my desktop.")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.ComputerToolset20260801;
  // ...
  import com.anthropic.models.messages.ToolBash20250124;
  import com.anthropic.models.messages.ToolTextEditor20250728;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(ComputerToolset20260801.builder().build())
          .addTool(ToolTextEditor20250728.builder().build())
          .addTool(ToolBash20250124.builder().build())
          .addUserMessage("Save a picture of a cat to my desktop.")
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => 'Save a picture of a cat to my desktop.'],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [
          ['type' => 'computer_toolset_20260801'],
          [
              'type' => 'text_editor_20250728',
              'name' => 'str_replace_based_edit_tool',
          ],
          [
              'type' => 'bash_20250124',
              'name' => 'bash',
          ],
      ],
  );

  echo $response;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::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." }
    ]
  )

  puts response
  ```
</CodeGroup>

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:

```json 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#how-computer-use-works) descreve esse loop, e o restante desta página mostra como implementá-lo.

***

## Como funciona o uso de computador

<Steps>
  <Step title="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.”
  </Step>

  <Step title="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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions).
    * A resposta da API tem um `stop_reason` igual a `tool_use`, sinalizando uma solicitação de uso de ferramentas.
  </Step>

  <Step title="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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions).
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use), 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:

```json
{
  "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):

```json
{
  "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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#batch-actions)):

```json
{
  "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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting)).

### 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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124); o restante desta seção se aplica tanto a integrações novas quanto às migradas.

<Tip>
  A [implementação de referência do uso de computador](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo) é um exemplo completo e funcional: um [ambiente em contêiner](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/Dockerfile) adequado para o uso de computador, implementações das [ferramentas de uso de computador](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools), um [loop do agente](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py) que chama a Claude API e executa as ferramentas, e uma interface web para o contêiner, o loop e as ferramentas. Para usar `computer_toolset_20260801`, escolha um [modelo que o suporte](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#availability-feature-support) e, em seguida, selecione o toolset em **Tool Versions** na barra lateral da interface web.
</Tip>

### 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#quick-start), 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#implement-the-computer-use-tool). 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:

<CodeGroup exclude="shell">
  ```python Python
  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
  ```

  ```typescript TypeScript
  async function samplingLoop(
    model: string,
    messages: Anthropic.MessageParam[],
    maxIterations = 10
  ): Promise<Anthropic.MessageParam[]> {
    // Run the computer-use agent loop until Claude stops requesting tools
    // or the iteration limit is reached.
    for (let iteration = 0; iteration < maxIterations; iteration++) {
      const response = await client.messages.create({
        model,
        max_tokens: 4096,
        messages,
        tools
      });

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

      // Run any tools Claude requested and collect results
      const toolResults = processToolCalls(response);
      if (toolResults.length === 0) {
        return messages; // No more tool use; task complete
      }

      // Send tool results back to Claude for the next iteration
      messages.push({ role: "user", content: toolResults });
    }

    return messages;
  }
  ```

  ```csharp C#
  async Task<List<MessageParam>> SamplingLoop(
      Model model,
      List<MessageParam> messages,
      int maxIterations = 10
  )
  {
      // Run the computer-use agent loop until Claude stops requesting tools
      // or the iteration limit is reached.
      for (var iteration = 0; iteration < maxIterations; iteration++)
      {
          var response = await client.Messages.Create(
              new MessageCreateParams
              {
                  Model = model,
                  MaxTokens = 4096,
                  Messages = messages,
                  Tools = tools,
              }
          );

          // Add Claude's response to the conversation history
          messages.Add(
              new AssistantMessageParam
              {
                  Content = response
                      .Content.Select(block => new ContentBlockParam(block.Json))
                      .ToList(),
              }
          );

          // Run any tools Claude requested and collect results
          var toolResults = ProcessToolCalls(response);
          if (toolResults.Count == 0)
          {
              return messages; // No more tool use; task complete
          }

          // Send tool results back to Claude for the next iteration
          messages.Add(new UserMessageParam { Content = toolResults });
      }

      return messages;
  }
  ```

  ```go Go
  // samplingLoop runs the computer-use agent loop until Claude stops
  // requesting tools or the iteration limit is reached.
  func samplingLoop(ctx context.Context, model anthropic.Model, messages []anthropic.MessageParam, maxIterations int) ([]anthropic.MessageParam, error) {
  	for range maxIterations {
  		response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  			Model:     model,
  			MaxTokens: 4096,
  			Messages:  messages,
  			Tools:     tools,
  		})
  		if err != nil {
  			return nil, err
  		}

  		// Add Claude's response to the conversation history
  		messages = append(messages, response.ToParam())

  		// Run the actions Claude requested, in order, and collect the results
  		toolResults := processToolCalls(response)
  		if len(toolResults) == 0 {
  			return messages, nil // No more tool use; task complete
  		}

  		// Send every result back to Claude in a single user message
  		messages = append(messages, anthropic.NewUserMessage(toolResults...))
  	}
  	return messages, nil
  }
  ```

  ```java Java
  /**
   * Run the computer-use agent loop until Claude stops requesting tools
   * or the iteration limit is reached.
   */
  List<MessageParam> samplingLoop(Model model, List<MessageParam> messages, int maxIterations) {
      for (int iteration = 0; iteration < maxIterations; iteration++) {
          Message response = client.messages().create(MessageCreateParams.builder()
              .model(model)
              .maxTokens(4096)
              .messages(messages)
              .addTool(COMPUTER_TOOLSET)
              .build());

          // Add Claude's response to the conversation history
          messages.add(response.toParam());

          // Run any tools Claude requested and collect results
          List<ContentBlockParam> toolResults = processToolCalls(response);
          if (toolResults.isEmpty()) {
              return messages; // No more tool use; task complete
          }

          // Send tool results back to Claude for the next iteration
          messages.add(MessageParam.ofUserOfContentBlockParams(toolResults));
      }
      return messages;
  }
  ```

  ```php PHP
  /**
   * Run the computer-use agent loop until Claude stops requesting tools
   * or the iteration limit is reached.
   */
  function samplingLoop(Model|string $model, array $messages, int $maxIterations = 10): array
  {
      global $client, $tools;

      for ($iteration = 0; $iteration < $maxIterations; $iteration++) {
          $response = $client->messages->create(
              model: $model,
              maxTokens: 4096,
              messages: $messages,
              tools: $tools,
          );

          // Add Claude's response to the conversation history
          $messages[] = MessageParam::with(role: Role::ASSISTANT, content: $response->content);

          // Run any tools Claude requested and collect results
          $toolResults = processToolCalls($response);
          if ($toolResults === []) {
              return $messages; // No more tool use; task complete
          }

          // Send tool results back to Claude for the next iteration
          $messages[] = MessageParam::with(role: Role::USER, content: $toolResults);
      }

      return $messages;
  }
  ```

  ```ruby Ruby
  # Run the computer-use agent loop until Claude stops requesting tools
  # or the iteration limit is reached.
  def sampling_loop(model, messages, max_iterations: 10)
    max_iterations.times do
      response = CLIENT.messages.create(
        model: model,
        max_tokens: 4096,
        messages: messages,
        tools: TOOLS
      )

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

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

      # Send every result back to Claude in a single user message
      messages << { role: "user", content: tool_results }
    end

    messages
  end
  ```
</CodeGroup>

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](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions) 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](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#tool-use-system-prompt), 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:

| Membro                                                        | Entrada                                                                                                                                                                                                                             | Descrição                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `screenshot`                                                  | Nenhuma (`{}`)                                                                                                                                                                                                                      | Captura a tela inteira e a retorna como uma imagem.                                                                                                                                                                                                                                                                    |
| `zoom`                                                        | `region`: `[x0, y0, x1, y1]`, os cantos superior esquerdo e inferior direito da área a inspecionar                                                                                                                                  | Captura 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_click`                                                  | `coordinate` (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+shift` | Clica 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_click` | Igual a `left_click`                                                                                                                                                                                                                | Outros botões do mouse e cliques múltiplos.                                                                                                                                                                                                                                                                            |
| `left_click_drag`                                             | `start_coordinate`: `[x, y]`; `coordinate`: `[x, y]`; `text` (opcional): teclas modificadoras                                                                                                                                       | Pressiona em `start_coordinate`, arrasta até `coordinate` e solta.                                                                                                                                                                                                                                                     |
| `mouse_move`                                                  | `coordinate`: `[x, y]`                                                                                                                                                                                                              | Move o cursor sem clicar, por exemplo, para passar o mouse sobre algo.                                                                                                                                                                                                                                                 |
| `left_mouse_down`, `left_mouse_up`                            | Nenhuma (`{}`)                                                                                                                                                                                                                      | 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_position`                                             | Nenhuma (`{}`)                                                                                                                                                                                                                      | Informa a posição `[x, y]` atual do cursor como texto.                                                                                                                                                                                                                                                                 |
| `scroll`                                                      | `scroll_direction`: `"up"`, `"down"`, `"left"` ou `"right"`; `scroll_amount`: número de cliques da roda de rolagem; `coordinate` (opcional): `[x, y]`; `text` (opcional): teclas modificadoras                                      | Rola em `coordinate`, ou na posição atual do cursor.                                                                                                                                                                                                                                                                   |
| `type`                                                        | `text`: a string a ser digitada                                                                                                                                                                                                     | Digita texto literal no foco atual do teclado.                                                                                                                                                                                                                                                                         |
| `key`                                                         | `text`: uma tecla ou uma combinação unida por `+`, como `"Return"`, `"ctrl+s"` ou `"alt+Tab"`; `repeat` (opcional): de 1 a 100, padrão 1                                                                                            | Pressiona uma tecla ou combinação de teclas `repeat` vezes.                                                                                                                                                                                                                                                            |
| `hold_key`                                                    | `text`: uma tecla ou combinação; `duration`: segundos, até 300                                                                                                                                                                      | Mantém uma tecla pressionada pela duração informada.                                                                                                                                                                                                                                                                   |
| `wait`                                                        | `duration`: segundos, até 300                                                                                                                                                                                                       | Pausa 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
* **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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#tool-parameters)) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets)).

<Accordion title="Exemplos de ações">
  Cada exemplo é um bloco `tool_use` completo, como aparece na resposta do Claude.

  Shift+clique em uma posição, por exemplo, para estender uma seleção. Diferentemente de `hold_key`, `text` mantém os modificadores pressionados apenas durante aquele clique ou rolagem:

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

  Arrastar de um ponto a outro:

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

  Rolar para baixo três cliques da roda:

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

  Pressionar Tab quatro vezes:

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

  Aplicar zoom para inspecionar uma região em resolução total:

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

  Informar a posição do cursor. Responda a esta chamada com um resultado de texto curto que forneça a posição em pixels da captura de tela, por exemplo, `X=512, Y=384`:

  ```json
  {
    "type": "tool_use",
    "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
    "name": "cursor_position",
    "toolset_name": "computer",
    "input": {}
  }
  ```
</Accordion>

### 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets).

| Parâmetro         | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`            | Sim         | `computer_toolset_20260801`                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `configs`         | Não         | Configuraçõ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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool#deferred-tool-loading)), e os membros que você omitir mantêm seus padrões.                                                                                                   |
| `cache_control`   | Não         | Ponto de interrupção do [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions). |
| `allowed_callers` | Não         | Somente `["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:

```json
{
  "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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)).

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets).

### Combinando com pensamento

Para combinar o uso de computador com pensamento, consulte [Pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking).

<Tip>
  Para a ferramenta `computer_20251124`, benchmarks internos nos modelos que a utilizam sugerem estas configurações de `effort`:

  * **Claude Opus 4.7:** use `high` como padrão; use `low` para cargas de trabalho de alta vazão ou sensíveis a custo.
  * **Claude Sonnet 4.6 e Claude Opus 4.6:** use `medium` como padrão (melhor relação entre precisão e custo). Evite `max`, que aumenta o custo em tokens sem melhorar a precisão em tarefas de interface. Nesses modelos, `low` usa *menos* tokens de saída do que desabilitar o pensamento completamente (menos erros significam menos novas tentativas), o que o torna uma ótima opção para loops sensíveis a custo.
</Tip>

### 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#quick-start) mostra esse padrão com a [ferramenta bash](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool) e a [ferramenta de editor de texto](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool). Você pode adicionar suas próprias [definições de ferramentas personalizadas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#combine-with-other-tools). 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](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo) 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Implemente os manipuladores de ações">
    Crie funções para lidar com cada tipo de ação que Claude possa solicitar:

    <CodeGroup exclude="shell">
      ```python Python
      # 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}")
      ```

      ```typescript TypeScript
      // Placeholder image data; a real executor captures the screen as PNG bytes
      const PLACEHOLDER_PNG =
        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";

      function captureScreenshot(): Anthropic.ImageBlockParam[] {
        // screenshot answers with an image block rather than text
        return [
          {
            type: "image",
            source: {
              type: "base64",
              media_type: "image/png",
              data: PLACEHOLDER_PNG
            }
          }
        ];
      }

      function clickAt(x: number, y: number): string {
        return `clicked at (${x}, ${y})`;
      }

      function clickAtCursor(): string {
        return "clicked at the current cursor position";
      }

      function typeText(text: string): string {
        return `typed: ${text}`;
      }

      function handleComputerAction(
        action: string,
        input: unknown
      ): string | Anthropic.ImageBlockParam[] {
        const params: object = typeof input === "object" && input !== null ? input : {};
        switch (action) {
          case "screenshot":
            return captureScreenshot();
          case "left_click":
            // coordinate is optional on the toolset; without one, click at the cursor
            if ("coordinate" in params && Array.isArray(params.coordinate)) {
              const [x, y] = params.coordinate;
              return clickAt(x, y);
            }
            return clickAtCursor();
          case "type":
            if ("text" in params) {
              return typeText(String(params.text));
            }
            break;
        }
        // Handle other actions as needed
        throw new Error(`Unknown or unimplemented member: ${action}`);
      }
      ```

      ```csharp C#
      // Placeholder image data; a real executor captures the screen and returns the PNG bytes
      const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";

      // screenshot answers with an image block rather than text: return the result content list
      List<Block> CaptureScreenshot() =>
          [
              new ImageBlockParam(
                  new Base64ImageSource { Data = PlaceholderPng, MediaType = MediaType.ImagePng }
              ),
          ];

      string ClickAt(int x, int y) => $"clicked at ({x}, {y})";

      string ClickAtCursor() => "clicked at the current cursor position";

      string TypeText(string text) => $"typed: {text}";

      ToolResultBlockParamContent HandleComputerAction(
          string action,
          IReadOnlyDictionary<string, JsonElement> input
      ) =>
          action switch
          {
              "screenshot" => CaptureScreenshot(),
              // coordinate is optional on click members; without it, click where the cursor is
              "left_click" when input.TryGetValue("coordinate", out var xy) => ClickAt(
                  xy[0].GetInt32(),
                  xy[1].GetInt32()
              ),
              "left_click" => ClickAtCursor(),
              "type" => TypeText(input["text"].GetString()!),
              // Handle other actions as needed
              _ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
          };
      ```

      ```go Go
      // placeholderPNG stands in for a real capture: an executor returns the
      // screen as base64-encoded PNG data.
      const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

      // captureScreenshot returns an image block rather than text.
      func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
      	return []anthropic.ToolResultBlockParamContentUnion{{
      		OfImage: &anthropic.ImageBlockParam{
      			Source: anthropic.ImageBlockParamSourceUnion{
      				OfBase64: &anthropic.Base64ImageSourceParam{
      					MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
      					Data:      placeholderPNG,
      				},
      			},
      		},
      	}}
      }

      // textContent wraps text as tool_result content.
      func textContent(text string) []anthropic.ToolResultBlockParamContentUnion {
      	return []anthropic.ToolResultBlockParamContentUnion{
      		{OfText: &anthropic.TextBlockParam{Text: text}},
      	}
      }

      func clickAt(x, y int) string {
      	return fmt.Sprintf("clicked at (%d, %d)", x, y)
      }

      func clickAtCursor() string {
      	return "clicked at the current cursor position"
      }

      func typeText(text string) string {
      	return fmt.Sprintf("typed: %s", text)
      }

      func handleComputerAction(action string, params map[string]any) ([]anthropic.ToolResultBlockParamContentUnion, error) {
      	switch action {
      	case "screenshot":
      		return captureScreenshot(), nil
      	case "left_click":
      		// coordinate is optional; without it, click where the cursor already is
      		coord, ok := params["coordinate"].([]any)
      		if !ok {
      			return textContent(clickAtCursor()), nil
      		}
      		if len(coord) == 2 {
      			x, xok := coord[0].(float64)
      			y, yok := coord[1].(float64)
      			if xok && yok {
      				return textContent(clickAt(int(x), int(y))), nil
      			}
      		}
      	case "type":
      		if text, ok := params["text"].(string); ok {
      			return textContent(typeText(text)), nil
      		}
      	// Handle other actions as needed
      	default:
      		return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
      	}
      	// Reached when a member's input is missing a field or a field has the wrong type
      	return nil, fmt.Errorf("invalid input for %s", action)
      }
      ```

      ```java Java
      /** Placeholder pixels; a real executor captures the screen and base64-encodes the PNG. */
      static final String PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";

      ToolResultBlockParam.Content captureScreenshot() {
          ImageBlockParam image = ImageBlockParam.builder()
              .source(Base64ImageSource.builder()
                  .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)
                  .data(PLACEHOLDER_PNG)
                  .build())
              .build();
          return ToolResultBlockParam.Content.ofBlocks(
              List.of(ToolResultBlockParam.Content.Block.ofImage(image)));
      }

      String clickAt(long x, long y) {
          return "clicked at (" + x + ", " + y + ")";
      }

      String clickAtCursor() {
          return "clicked at current cursor";
      }

      String typeText(String text) {
          return "typed: " + text;
      }

      /** Runs one computer toolset member; {@code action} is the tool_use block's name. */
      ToolResultBlockParam.Content handleComputerAction(String action, Map<String, JsonValue> input) {
          if (action.equals("screenshot")) {
              return captureScreenshot(); // the one member here that answers with an image block
          }
          String output = switch (action) {
              case "left_click" -> {
                  JsonValue coordinate = input.get("coordinate"); // optional on the toolset
                  if (coordinate == null) {
                      yield clickAtCursor();
                  }
                  List<JsonValue> point = (List<JsonValue>) coordinate.asArray().get();
                  long x = ((Number) point.get(0).asNumber().get()).longValue();
                  long y = ((Number) point.get(1).asNumber().get()).longValue();
                  yield clickAt(x, y);
              }
              case "type" -> typeText(input.get("text").asStringOrThrow());
              // Handle other actions as needed
              default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
          };
          return ToolResultBlockParam.Content.ofString(output);
      }
      ```

      ```php PHP
      // Stand-in for real PNG bytes; a real executor captures the screen
      const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';

      function captureScreenshot(): array
      {
          // screenshot answers with an image block rather than text, so return the result content list
          $image = [
              'type' => 'image',
              'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
          ];

          return [$image];
      }

      function clickAt(?array $coordinate): string
      {
          // left_click may omit coordinate, in which case the click lands where the cursor already is
          if ($coordinate === null) {
              return 'clicked at current cursor';
          }
          [$x, $y] = $coordinate;

          return "clicked at ({$x}, {$y})";
      }

      function typeText(string $text): string
      {
          return "typed: {$text}";
      }

      function handleComputerAction(string $name, array $input): string|array
      {
          return match ($name) {
              'screenshot' => captureScreenshot(),
              'left_click' => clickAt($input['coordinate'] ?? null),
              'type' => typeText($input['text']),
              // Handle other actions as needed
              default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
          };
      }
      ```

      ```ruby Ruby
      # Stand-in image data; a real executor captures the screen as a PNG.
      PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

      # screenshot answers with an image block rather than text
      def capture_screenshot
        [
          {
            type: "image",
            source: { type: "base64", media_type: "image/png", data: PLACEHOLDER_PNG }
          }
        ]
      end

      def click(coordinate = nil)
        return "clicked at current cursor" if coordinate.nil?

        x, y = coordinate
        "clicked at (#{x}, #{y})"
      end

      def type_text(text)
        "typed: #{text}"
      end

      def handle_computer_action(name, input)
        case name
        when "screenshot"
          capture_screenshot
        when "left_click"
          # coordinate is optional; without it, click where the cursor already is
          click(input[:coordinate])
        when "type"
          type_text(input[:text])
        # Handle other actions as needed
        else
          raise ArgumentError, "Unknown or unimplemented member: #{name}"
        end
      end
      ```
    </CodeGroup>
  </Step>

  <Step title="Processe as chamadas de ferramentas do Claude">
    Extraia e execute as chamadas de ferramentas das respostas do Claude:

    <CodeGroup exclude="shell">
      ```python Python
      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
      ```

      ```typescript TypeScript
      const HALT_TEXT = "Not executed: an earlier computer action in this turn failed.";

      function computerResult(
        toolUseId: string,
        content: string | Anthropic.ImageBlockParam[],
        isError?: boolean
      ): Anthropic.ToolResultBlockParam {
        return {
          type: "tool_result",
          tool_use_id: toolUseId,
          toolset_name: "computer",
          content,
          is_error: isError
        };
      }

      function processToolCalls(response: Anthropic.Message): Anthropic.ToolResultBlockParam[] {
        const toolResults: Anthropic.ToolResultBlockParam[] = [];
        let failed = false;
        for (const block of response.content) {
          if (block.type !== "tool_use") {
            continue;
          }
          if (block.toolset_name !== "computer") {
            // This example declares only the computer toolset; route other tools
            // here if you add them.
            continue;
          }
          if (failed) {
            // A batch stops at its first failure; answer later actions without running them
            toolResults.push(computerResult(block.id, HALT_TEXT, true));
            continue;
          }
          try {
            // A string, or the image block list that screenshot returns
            const result = handleComputerAction(block.name, block.input);
            toolResults.push(computerResult(block.id, result));
          } catch (error) {
            failed = true;
            const message = error instanceof Error ? error.message : String(error);
            toolResults.push(computerResult(block.id, `Error: ${message}`, true));
          }
        }
        return toolResults;
      }
      ```

      ```csharp C#
      const string HaltText = "Not executed: an earlier computer action in this turn failed.";

      List<ContentBlockParam> ProcessToolCalls(Message response)
      {
          List<ContentBlockParam> toolResults = [];
          var failed = false;
          foreach (var block in response.Content)
          {
              if (!block.TryPickToolUse(out var toolUse))
              {
                  continue;
              }

              if (toolUse.ToolsetName != "computer")
              {
                  // This example declares only the computer toolset; route other tools
                  // here if you add them.
                  continue;
              }

              if (failed)
              {
                  // A batch stops at its first failure; answer later actions without running them
                  toolResults.Add(
                      new ToolResultBlockParam(toolUse.ID)
                      {
                          Content = HaltText,
                          IsError = true,
                          ToolsetName = "computer",
                      }
                  );
                  continue;
              }

              try
              {
                  // A string, or the image block list that screenshot returns
                  var result = HandleComputerAction(toolUse.Name, toolUse.Input);
                  toolResults.Add(
                      new ToolResultBlockParam(toolUse.ID) { Content = result, ToolsetName = "computer" }
                  );
              }
              catch (Exception e)
              {
                  failed = true;
                  toolResults.Add(
                      new ToolResultBlockParam(toolUse.ID)
                      {
                          Content = $"Error: {e.Message}",
                          IsError = true,
                          ToolsetName = "computer",
                      }
                  );
              }
          }
          return toolResults;
      }
      ```

      ```go Go
      const notExecuted = "Not executed: an earlier computer action in this turn failed."

      // computerToolResult builds the result for one computer action. Unlike an
      // ordinary tool result, it must echo the toolset name.
      func computerToolResult(toolUseID string, content []anthropic.ToolResultBlockParamContentUnion, isError bool) anthropic.ContentBlockParamUnion {
      	result := anthropic.ToolResultBlockParam{
      		ToolUseID:   toolUseID,
      		ToolsetName: anthropic.String("computer"),
      		Content:     content,
      	}
      	if isError {
      		result.IsError = anthropic.Bool(true)
      	}
      	return anthropic.ContentBlockParamUnion{OfToolResult: &result}
      }

      // processToolCalls runs the computer actions in Claude's response in order and
      // builds one tool_result for each tool_use block. After the first failure it skips
      // the rest: Claude planned them assuming the earlier actions succeeded.
      func processToolCalls(response *anthropic.Message) []anthropic.ContentBlockParamUnion {
      	var toolResults []anthropic.ContentBlockParamUnion
      	failed := false
      	for _, block := range response.Content {
      		switch variant := block.AsAny().(type) {
      		case anthropic.ToolUseBlock:
      			// This example declares only the computer toolset; route other tools here if you add them.
      			if variant.ToolsetName != "computer" {
      				continue
      			}
      			if failed {
      				toolResults = append(toolResults, computerToolResult(variant.ID, textContent(notExecuted), true))
      				continue
      			}
      			var input map[string]any
      			var content []anthropic.ToolResultBlockParamContentUnion
      			err := json.Unmarshal(variant.Input, &input)
      			if err == nil {
      				// Text, or the image block that screenshot returns
      				content, err = handleComputerAction(variant.Name, input)
      			}
      			if err != nil {
      				failed = true
      				content = textContent("Error: " + err.Error())
      			}
      			toolResults = append(toolResults, computerToolResult(variant.ID, content, err != nil))
      		}
      	}
      	return toolResults
      }
      ```

      ```java Java
      /** The exact text the toolset contract prescribes for member calls skipped after a failure. */
      static final String HALT_TEXT = "Not executed: an earlier computer action in this turn failed.";

      /** Every result answering a computer toolset member echoes toolset_name. */
      ToolResultBlockParam.Builder computerResult(ToolUseBlock toolUse) {
          return ToolResultBlockParam.builder()
              .toolUseId(toolUse.id())
              .toolsetName("computer");
      }

      /**
       * Run the computer actions in Claude's response in order and build one
       * tool_result for each tool_use block. After the first failure, skip the rest:
       * Claude planned them assuming the earlier actions succeeded.
       */
      List<ContentBlockParam> processToolCalls(Message response) {
          List<ContentBlockParam> toolResults = new ArrayList<>();
          boolean failed = false;
          for (ContentBlock block : response.content()) {
              // This example declares only the computer toolset; route other tools here if you add them.
              if (!block.isToolUse() || !block.asToolUse().toolsetName().equals(Optional.of("computer"))) {
                  continue;
              }
              ToolUseBlock toolUse = block.asToolUse();
              ToolResultBlockParam result;
              if (failed) {
                  result = computerResult(toolUse)
                      .content(HALT_TEXT)
                      .isError(true)
                      .build();
              } else {
                  try {
                      Map<String, JsonValue> input =
                          (Map<String, JsonValue>) toolUse._input().asObject().get();
                      // A string, or the image block that screenshot returns
                      ToolResultBlockParam.Content output = handleComputerAction(toolUse.name(), input);
                      result = computerResult(toolUse)
                          .content(output)
                          .build();
                  } catch (RuntimeException e) {
                      failed = true;
                      result = computerResult(toolUse)
                          .content("Error: " + e.getMessage())
                          .isError(true)
                          .build();
                  }
              }
              toolResults.add(ContentBlockParam.ofToolResult(result));
          }
          return toolResults;
      }
      ```

      ```php PHP
      const HALT_TEXT = 'Not executed: an earlier computer action in this turn failed.';

      function processToolCalls(Message $response): array
      {
          $toolResults = [];
          $failed = false;
          foreach ($response->content as $block) {
              // This example declares only the computer toolset; route other tools here if you add them.
              if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'computer') {
                  continue;
              }
              $result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'computer'];
              if ($failed) {
                  // A batch stops at its first failure; the remaining actions are answered without running
                  $toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
                  continue;
              }
              try {
                  // A string, or the image block list that screenshot returns
                  $toolResults[] = [...$result, 'content' => handleComputerAction($block->name, $block->input)];
              } catch (\Throwable $e) {
                  $failed = true;
                  $toolResults[] = [...$result, 'content' => 'Error: ' . $e->getMessage(), 'is_error' => true];
              }
          }

          return $toolResults;
      }
      ```

      ```ruby Ruby
      NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."

      # Run the computer actions in Claude's response in order and build one
      # tool_result for each tool_use block. After the first failure, skip the rest:
      # Claude planned them assuming the earlier actions succeeded.
      def process_tool_calls(response)
        tool_results = []
        failed = false
        response.content.each do |block|
          # This example declares only the computer toolset; route other tools here
          # if you add them.
          next unless block.is_a?(Anthropic::Models::ToolUseBlock) && block.toolset_name == "computer"

          result = { type: "tool_result", tool_use_id: block.id, toolset_name: "computer" }
          if failed
            result.update(content: NOT_EXECUTED, is_error: true)
          else
            begin
              # A String, or the image content blocks that screenshot returns
              result[:content] = handle_computer_action(block.name, block.input)
            rescue => e
              result.update(content: "Error: #{e.message}", is_error: true)
              failed = true
            end
          end
          tool_results << result
        end
        tool_results
      end
      ```
    </CodeGroup>
  </Step>

  <Step title="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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop) mostra esse loop.
  </Step>
</Steps>

### 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions), 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:

```json
{
  "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](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size) 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.

<Note>
  Os limites variam por modelo. Claude Opus 4.7 e modelos posteriores, incluindo todos os modelos que suportam `computer_toolset_20260801`, aceitam até 2.576 pixels na borda longa e 4.784 tokens visuais no total (`⌈width / 28⌉ × ⌈height / 28⌉`, aproximadamente 3,75 megapixels). Modelos anteriores aceitam até 1.568 pixels na borda longa e aproximadamente 1,15 megapixel no total. Consulte [Resolução e custo em tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size) para o nível de cada modelo. O exemplo a seguir usa os limites de 1.568 px / 1,15 MP dos modelos anteriores. Para um modelo do nível de alta resolução, dimensione de acordo com o limite de tokens visuais em vez de um total de pixels, por exemplo com o auxiliar de redimensionamento em [Redimensione sua imagem antes de enviá-la](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#resize-your-image-before-uploading).
</Note>

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:

<CodeGroup exclude="shell">
  ```python Python
  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)
  ```

  ```typescript TypeScript
  const screenWidth = 1512;
  const screenHeight = 982;
  const MAX_LONG_EDGE = 1568;
  const MAX_PIXELS = 1_150_000;

  function getScaleFactor(width: number, height: number): number {
    const longEdge = Math.max(width, height);
    const totalPixels = width * height;

    const longEdgeScale = MAX_LONG_EDGE / longEdge;
    const totalPixelsScale = Math.sqrt(MAX_PIXELS / totalPixels);

    return Math.min(1.0, longEdgeScale, totalPixelsScale);
  }

  // Ao fazer a captura de tela
  const scale = getScaleFactor(screenWidth, screenHeight);
  const scaledWidth = Math.floor(screenWidth * scale);
  const scaledHeight = Math.floor(screenHeight * scale);

  // Redimensione a imagem para as dimensões escaladas antes de enviá-la ao Claude
  const screenshot = captureAndResize(scaledWidth, scaledHeight);

  // Ao lidar com as coordenadas do Claude, escale-as de volta para o tamanho original
  function executeClick(x: number, y: number): void {
    const screenX = x / scale;
    const screenY = y / scale;
    performClick(screenX, screenY);
  }
  ```

  ```csharp C#
  int screenWidth = 1512, screenHeight = 982;

  double GetScaleFactor(int width, int height)
  {
      // Calcula o fator de escala para atender às restrições da API.
      int longEdge = Math.Max(width, height);
      int totalPixels = width * height;

      double longEdgeScale = 1568.0 / longEdge;
      double totalPixelsScale = Math.Sqrt(1_150_000.0 / totalPixels);

      return Math.Min(1.0, Math.Min(longEdgeScale, totalPixelsScale));
  }

  // Ao fazer a captura de tela
  double scale = GetScaleFactor(screenWidth, screenHeight);
  int scaledWidth = (int)(screenWidth * scale);
  int scaledHeight = (int)(screenHeight * scale);

  // Redimensione a imagem para as dimensões escaladas antes de enviá-la ao Claude
  var screenshot = CaptureAndResize(scaledWidth, scaledHeight);

  // Ao lidar com as coordenadas do Claude, converta-as de volta para a escala original
  void ExecuteClick(int x, int y)
  {
      double screenX = x / scale;
      double screenY = y / scale;
      PerformClick(screenX, screenY);
  }
  ```

  ```go Go
  func getScaleFactor(width, height int) float64 {
  	longest := float64(max(width, height))
  	area := float64(width * height)
  	return min(1.0, 1568/longest, math.Sqrt(1_150_000/area))
  }

  // ...
  	screenWidth, screenHeight := 1512, 982

  	// Ao fazer a captura de tela
  	scale := getScaleFactor(screenWidth, screenHeight)
  	scaledWidth := int(float64(screenWidth) * scale)
  	scaledHeight := int(float64(screenHeight) * scale)

  	// Redimensione a imagem para as dimensões escaladas antes de enviá-la ao Claude
  	screenshot := captureAndResize(scaledWidth, scaledHeight)

  	// Ao processar as coordenadas do Claude, escale-as de volta para o tamanho original
  	executeClick := func(x, y int) {
  		performClick(float64(x)/scale, float64(y)/scale)
  	}
  ```

  ```java Java
  static double getScaleFactor(int width, int height) {
      return Math.min(
          1.0,
          Math.min(
              1568.0 / Math.max(width, height),
              Math.sqrt(1_150_000.0 / (width * height))
          )
      );
  }

  void main() {
      int screenWidth = 1512, screenHeight = 982;

      // Ao fazer a captura de tela
      double scale = getScaleFactor(screenWidth, screenHeight);
      int scaledWidth = (int)(screenWidth * scale);
      int scaledHeight = (int)(screenHeight * scale);

      // Redimensione a imagem para as dimensões escalonadas antes de enviá-la ao Claude
      var screenshot = captureAndResize(scaledWidth, scaledHeight);

      // Ao lidar com as coordenadas do Claude, reescale-as para o tamanho original
      BiConsumer<Integer, Integer> executeClick =
          (x, y) -> performClick(x / scale, y / scale);
  // ...
  }
  ```

  ```php PHP
  function getScaleFactor(int $width, int $height): float
  {
      return min(
          1.0,
          1568 / max($width, $height),
          sqrt(1_150_000 / ($width * $height)),
      );
  }

  $screenWidth = 1512;
  $screenHeight = 982;

  // Ao fazer a captura de tela
  $scale = getScaleFactor($screenWidth, $screenHeight);
  $scaledWidth = (int)($screenWidth * $scale);
  $scaledHeight = (int)($screenHeight * $scale);

  // Redimensione a imagem para as dimensões escaladas antes de enviá-la ao Claude
  $screenshot = captureAndResize($scaledWidth, $scaledHeight);

  // Ao lidar com as coordenadas do Claude, reescale-as para o tamanho original
  $executeClick = fn(int $x, int $y) => performClick($x / $scale, $y / $scale);
  ```

  ```ruby Ruby
  def get_scale_factor(width, height)
    [1.0, 1568.0 / [width, height].max, Math.sqrt(1_150_000.0 / (width * height))].min
  end

  screen_width, screen_height = 1512, 982

  # Ao fazer a captura de tela
  scale = get_scale_factor(screen_width, screen_height)
  scaled_width = (screen_width * scale).to_i
  scaled_height = (screen_height * scale).to_i

  # Redimensiona 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, reescale-as para o tamanho original
  execute_click = ->(x, y) { perform_click(x / scale, y / scale) }
  ```
</CodeGroup>

<Note>
  **Telas Retina do macOS** capturam telas com uma proporção de pixels do dispositivo de 2, então a imagem tem o dobro da resolução das coordenadas lógicas da tela. Reduza a escala da captura de tela em 2x antes de enviá-la ou divida pela metade as coordenadas que Claude retorna antes de executar o clique.
</Note>

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](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits) 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](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions), 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](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserved-in-conversation) 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](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing#tool-result-clearing) economiza tokens, mas as capturas de tela limpas ainda contam para os [limites de requisição](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits), então use a [compactação sob demanda](https://platform.claude.com/docs/pt-BR/build-with-claude/compaction-on-demand) antes que um loop os atinja.
  * **Se precisar fazer a remoção:** Mantenha [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking/prefix-checks#preserved-thinking-controls) 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:

| Sintoma                                            | Causa provável                                                                                                                                                               | Tente                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cliques consistentemente deslocados em uma direção | As 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 escala | Converta 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)); em telas Retina do macOS, considere a proporção de pixels do dispositivo de 2x |
| Cliques caem na área certa, mas erram o alvo       | O alvo é muito pequeno, detalhes foram perdidos ao reduzir a escala de uma fonte 4K+ ou a proporção foi distorcida                                                           | Mantenha 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 errado         | Instrução ambígua ou elementos visualmente semelhantes próximos                                                                                                              | Use prompts posicionais (“o botão azul Submit no canto inferior direito”); divida a interação em etapas menores                                                                                                                                                                                                                                                                                                   |
| A precisão é consistentemente ruim                 | Resolução muito baixa                                                                                                                                                        | Tente 1280x720 como base                                                                                                                                                                                                                                                                                                                                                                                          |

<Tip>
  **A escolha do modelo afeta a precisão do clique.** Entre os modelos que usam a ferramenta `computer_20251124`, Claude Sonnet 4.6 é mecanicamente mais preciso ao clicar do que Claude Opus 4.6 e é mais robusto quando as capturas de tela exigem grande redução de escala. Claude Opus 4.7 reduz essa diferença: sua precisão de clique é aproximadamente comparável à do Sonnet 4.6, e seu limite de resolução mais alto significa que é necessária menos redução de escala.
</Tip>

### Siga as melhores práticas de implementação

<AccordionGroup>
  <Accordion title="Adicione atrasos entre ações">
    Algumas aplicações precisam de tempo para responder às ações:

    <CodeGroup exclude="shell">
      ```python Python
      def click_and_wait(x, y, wait_time=0.5):
          click_at(x, y)
          time.sleep(wait_time)  # Allow UI to update
      ```

      ```typescript TypeScript
      async function clickAndWait(x: number, y: number, waitMs = 500): Promise<void> {
        clickAt(x, y);
        await new Promise((resolve) => setTimeout(resolve, waitMs)); // Allow UI to update
      }
      ```

      ```csharp C#
      static void ClickAndWait(int x, int y, double waitSeconds = 0.5)
      {
          ClickAt(x, y);
          Thread.Sleep(TimeSpan.FromSeconds(waitSeconds));  // Allow UI to update
      }
      ```

      ```go Go
      func clickAndWaitFor(x, y int, wait time.Duration) {
      	clickAt(x, y)
      	time.Sleep(wait) // Allow UI to update
      }

      func clickAndWait(x, y int) {
      	clickAndWaitFor(x, y, 500*time.Millisecond)
      }
      ```

      ```java Java
      void clickAndWait(int x, int y) throws InterruptedException {
          clickAndWait(x, y, 500);
      }

      void clickAndWait(int x, int y, long waitTimeMillis) throws InterruptedException {
          clickAt(x, y);
          Thread.sleep(waitTimeMillis);  // Allow UI to update
      }
      ```

      ```php PHP
      function clickAndWait(int $x, int $y, float $waitSeconds = 0.5): void
      {
          clickAt($x, $y);
          usleep((int) ($waitSeconds * 1_000_000));  // Allow UI to update
      }
      ```

      ```ruby Ruby
      def click_and_wait(x, y, wait_time: 0.5)
        click_at(x, y)
        sleep(wait_time) # Allow UI to update
      end
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Valide as ações antes de executá-las">
    Verifique se as ações solicitadas são seguras e válidas:

    <CodeGroup exclude="shell">
      ```python Python
      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
      ```

      ```typescript TypeScript
      const displayWidth = 1024;
      const displayHeight = 768;

      interface ActionParams {
        coordinate?: [number, number];
      }

      function validateAction(actionType: string, params: ActionParams): [boolean, string | null] {
        if (actionType === "left_click" && params.coordinate) {
          const [x, y] = params.coordinate;
          if (!(x >= 0 && x < displayWidth && y >= 0 && y < displayHeight)) {
            return [false, "Coordinates out of bounds"];
          }
        }
        return [true, null];
      }
      ```

      ```csharp C#
      const int DisplayWidth = 1024;
      const int DisplayHeight = 768;
      // ...
      static (bool IsValid, string? Error) ValidateAction(string actionType, IReadOnlyDictionary<string, JsonElement> parameters)
      {
          if (actionType == "left_click" && parameters.TryGetValue("coordinate", out JsonElement coordinate))
          {
              int x = coordinate[0].GetInt32();
              int y = coordinate[1].GetInt32();
              if (x is < 0 or >= DisplayWidth || y is < 0 or >= DisplayHeight)
              {
                  return (false, "Coordinates out of bounds");
              }
          }
          return (true, null);
      }
      ```

      ```go Go
      const (
      	displayWidth  = 1024
      	displayHeight = 768
      )

      func validateAction(actionType string, params map[string]any) (bool, string) {
      	raw, hasCoordinate := params["coordinate"]
      	if actionType == "left_click" && hasCoordinate {
      		coord, ok := raw.([]any)
      		if !ok || len(coord) != 2 {
      			return false, "Invalid coordinate"
      		}
      		x, y := int(coord[0].(float64)), int(coord[1].(float64))
      		if !(0 <= x && x < displayWidth && 0 <= y && y < displayHeight) {
      			return false, "Coordinates out of bounds"
      		}
      	}
      	return true, ""
      }
      ```

      ```java Java
      static final int DISPLAY_WIDTH = 1024;
      static final int DISPLAY_HEIGHT = 768;

      record Validation(boolean valid, String error) {}

      Validation validateAction(String actionType, Map<String, JsonValue> params) {
          if (actionType.equals("left_click") && params.containsKey("coordinate")) {
              List<JsonValue> coord = (List<JsonValue>) params.get("coordinate").asArray().get();
              long x = ((Number) coord.get(0).asNumber().get()).longValue();
              long y = ((Number) coord.get(1).asNumber().get()).longValue();
              if (!(0 <= x && x < DISPLAY_WIDTH && 0 <= y && y < DISPLAY_HEIGHT)) {
                  return new Validation(false, "Coordinates out of bounds");
              }
          }
          return new Validation(true, null);
      }
      ```

      ```php PHP
      const DISPLAY_WIDTH = 1024;
      const DISPLAY_HEIGHT = 768;

      /** @return array{bool, ?string} */
      function validateAction(string $actionType, array $params): array
      {
          if ($actionType === 'left_click' && isset($params['coordinate'])) {
              [$x, $y] = $params['coordinate'];
              if (!(0 <= $x && $x < DISPLAY_WIDTH && 0 <= $y && $y < DISPLAY_HEIGHT)) {
                  return [false, 'Coordinates out of bounds'];
              }
          }
          return [true, null];
      }
      ```

      ```ruby Ruby
      DISPLAY_WIDTH = 1024
      DISPLAY_HEIGHT = 768

      def validate_action(action_type, params)
        if action_type == "left_click" && params.key?(:coordinate)
          x, y = params[:coordinate]
          unless (0...DISPLAY_WIDTH).cover?(x) && (0...DISPLAY_HEIGHT).cover?(y)
            return [false, "Coordinates out of bounds"]
          end
        end
        [true, nil]
      end
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Registre as ações para depuração">
    Mantenha um registro de todas as ações para solução de problemas:

    <CodeGroup exclude="shell">
      ```python Python
      import logging


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

      ```typescript TypeScript
      function logAction(actionType: string, params: unknown, result: unknown): void {
        console.error(
          `Action: ${actionType}, Params: ${JSON.stringify(params)}, Result: ${JSON.stringify(
            result
          )}`
        );
      }
      ```

      ```csharp C#
      static void LogAction(string actionType, object? parameters, object? result)
      {
          Console.Error.WriteLine($"Action: {actionType}, Params: {parameters}, Result: {result}");
      }
      ```

      ```go Go
      func logAction(actionType string, params map[string]any, result any) {
      	log.Printf("Action: %s, Params: %v, Result: %v", actionType, params, result)
      }
      ```

      ```java Java
      import static java.lang.System.Logger.Level.INFO;

      static final System.Logger LOGGER = System.getLogger("computer-use");

      void logAction(String actionType, Object params, Object result) {
          LOGGER.log(INFO, "Action: {0}, Params: {1}, Result: {2}", actionType, params, result);
      }
      ```

      ```php PHP
      function logAction(string $actionType, array $params, mixed $result): void
      {
          error_log(sprintf(
              'Action: %s, Params: %s, Result: %s',
              $actionType,
              json_encode($params),
              json_encode($result),
          ));
      }
      ```

      ```ruby Ruby
      require "logger"

      LOGGER = Logger.new($stderr)

      def log_action(action_type, params, result)
        LOGGER.info("Action: #{action_type}, Params: #{params}, Result: #{result}")
      end
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions). 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` (csharp, go: `Betas`; java: `.addBeta()`) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#available-actions)).
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions). Se o seu loop ainda não consegue executar lotes, [Parâmetros da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#tool-parameters) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions).
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets).

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

```json
{
  "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:

```json
{
  "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`:

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

```json
{
  "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](https://platform.claude.com/docs/pt-BR/api/beta-headers) em todas as solicitações, e seus parâmetros estão documentados na [referência da Messages API beta](https://platform.claude.com/docs/pt-BR/api/beta/messages/create). Com o SDK, passe o cabeçalho por meio de `betas` (csharp, go: `Betas`; java: `.addBeta()`) 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 ferramenta | Cabeçalho beta            | Usar com                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Parâmetros                                                                           |
| -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `computer_20251124`  | `computer-use-2025-11-24` | Claude 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.5                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [Referência da API](https://platform.claude.com/docs/pt-BR/api/beta/messages/create) |
| `computer_20250124`  | `computer-use-2025-01-24` | Claude Sonnet 4.5 ([descontinuado](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)), Claude Haiku 4.5, Claude Opus 4.1 ([desativado, exceto no Claude Models on Google Cloud (Google managed) e no Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)), Claude Sonnet 4 ([desativado, exceto no Claude Models on Google Cloud (Google managed) e no Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) e Claude Opus 4 ([desativado, exceto no Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | [Referência da API](https://platform.claude.com/docs/pt-BR/api/beta/messages/create) |

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`)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy).

***

## 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](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#summarized-thinking) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#security-considerations).
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](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).

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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview#pricing). 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](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting).

**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](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size))
* Resultados da execução de ferramentas retornados ao Claude

<Note>
  Se você também estiver usando as ferramentas bash ou de editor de texto junto com o uso do computador, essas ferramentas têm seus próprios custos de tokens, conforme documentado em suas respectivas páginas.
</Note>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Toolset de computador nos SDKs" icon="code" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-sdk#computer-toolset">
    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.
  </Card>

  <Card title="Solução de problemas de uso de ferramentas" icon="wrench" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/troubleshooting-tool-use">
    Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para correção.
  </Card>

  <Card title="Implementação de referência" icon="github-logo" href="https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo">
    Comece com a implementação completa baseada em Docker.
  </Card>

  <Card title="Uso de ferramentas com Claude" icon="tool" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview">
    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.
  </Card>

  <Card title="Melhores práticas em detalhes" icon="book" href="https://claude.com/blog/best-practices-for-computer-and-browser-use-with-claude">
    Recomendações baseadas em benchmarks para resolução, esforço de pensamento e gerenciamento de contexto.
  </Card>

  <Card title="Ferramenta de uso do navegador" icon="browser" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool">
    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.
  </Card>
</CardGroup>

## Disponibilidade

Ferramenta de uso do computador está disponível ou em beta em modelos selecionados e é elegível para retenção zero de dados e prontidão para HIPAA.

### Suporte da API

#### [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages)

* Disponibilidade: Disponível

| Status     | Plataformas de nuvem                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Modelos                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disponível | Claude API, [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed)                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [Claude Fable 5.2](https://platform.claude.com/docs/pt-BR/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/pt-BR/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/pt-BR/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/pt-BR/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/pt-BR/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/pt-BR/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-4-8/overview) |
| Disponível | [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry)                                                                                                                                                                                                                                                                                                                                                                                                         | [Claude Fable 5.2](https://platform.claude.com/docs/pt-BR/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/pt-BR/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/pt-BR/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/pt-BR/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/pt-BR/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/pt-BR/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-4-8/overview)                        |
| Disponível | [Amazon Bedrock](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [Claude Fable 5.1](https://platform.claude.com/docs/pt-BR/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/pt-BR/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/pt-BR/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/pt-BR/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-4-8/overview)                                                                                                                                                                                                      |
| Disponível | [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [Claude Fable 5.2](https://platform.claude.com/docs/pt-BR/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/pt-BR/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/pt-BR/models/fable-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/pt-BR/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/pt-BR/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-4-8/overview)                                                                                                                                                                                                    |
| Beta       | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry) | [Claude Haiku 4.5](https://platform.claude.com/docs/pt-BR/models/haiku-4-5/overview), [Claude Opus 4.7](https://platform.claude.com/docs/pt-BR/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/pt-BR/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/pt-BR/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/pt-BR/models/opus-4-5/overview), [Claude Sonnet 4.5](https://platform.claude.com/docs/pt-BR/models/sonnet-4-5/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

#### [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview)

* Disponibilidade: Não disponível

### Cabeçalhos beta obrigatórios

[Visão geral dos cabeçalhos beta](https://platform.claude.com/docs/pt-BR/api/beta-headers)

Os cabeçalhos beta permitem que você acesse recursos experimentais e novas capacidades de modelos antes que eles se tornem parte da API padrão.

| Cabeçalho                 | Modelos                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `computer-use-2025-11-24` | [Claude Opus 4.7](https://platform.claude.com/docs/pt-BR/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/pt-BR/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/pt-BR/models/sonnet-4-6/overview), [Claude Opus 4.5](https://platform.claude.com/docs/pt-BR/models/opus-4-5/overview) |
| `computer-use-2025-01-24` | [Claude Haiku 4.5](https://platform.claude.com/docs/pt-BR/models/haiku-4-5/overview), [Claude Sonnet 4.5](https://platform.claude.com/docs/pt-BR/models/sonnet-4-5/overview)                                                                                                                                                                       |

### Tratamento de dados

[Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility)

| Item     | Retenção zero de dados                                                                                                                                                                                                                             | HIPAA    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Status   | Elegível (exclui [Modelos cobertos](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#model-specific-data-retention-requirements))                                                                                       | Elegível |
| Detalhes | 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#data-retention) | —        |

Endpoints aplicáveis:

* `/v1/messages` com o conjunto de ferramentas ou a ferramenta `computer`
