---
title: Ferramenta de uso de computador
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool
description: Dê ao Claude controle de captura de tela, mouse e teclado de um ambiente de desktop com a ferramenta de uso do computador, o conjunto de ferramentas do cliente computer_toolset_20260801.
featureMetadata:
status: ga
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-opus-4-8
- claude-haiku-5-5
supportedPlatforms:
Claude API: ga
Claude Platform on AWS: beta
Amazon Bedrock: beta
Google Cloud: ga
Microsoft Foundry: beta
details:
- Na Claude API e no Google Cloud, os modelos Claude 5.5 e posteriores oferecem suporte ao uso de computador apenas por meio do conjunto de ferramentas `computer_toolset_20260801` e retornam um erro para as versões anteriores da ferramenta `computer_20251124` e `computer_20250124`. Para migrar uma integração existente, consulte [Migrar 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 [Migre o uso de computador para o toolset](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.
- No Amazon Bedrock, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 aceitam a versão anterior da ferramenta `computer_20251124`, assim como Claude Opus 5 e Claude Sonnet 5.
- Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6 e Claude Opus 4.5 oferecem suporte ao uso de computador apenas por meio da versão anterior 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).
- Plataformas diferentes da Claude API e do Google Cloud atualmente oferecem apenas as [versões beta anteriores da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions).
---
**Comece com os 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 [uma integração de 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.
O Claude pode interagir com ambientes de computador por meio da "computer use tool" (ferramenta de uso de computador), que fornece recursos de captura de tela e controle de mouse/teclado para interação autônoma com o desktop.
A ferramenta de uso de computador é um "client toolset" (conjunto de ferramentas do cliente) definido pela Anthropic, conforme descrito em [conjuntos de ferramentas do cliente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets): uma única entrada `{"type": "computer_toolset_20260801"}` em `tools` dá ao Claude 17 ferramentas membro, como `screenshot`, `left_click`, `type` e `zoom`, e sua aplicação executa cada chamada em um ambiente que você controla. Atualmente, ela não está disponível no [Claude Managed Agents](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 por turno (uma [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 de 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 atuam na própria página, e ela não precisa de um ambiente de desktop completo.
O uso de computador está disponível na Claude API e no [Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai) como o conjunto de ferramentas `computer_toolset_20260801`; consulte [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#compatibility) para ver os modelos compatíveis.
As integrações existentes com `computer_20251124` continuam funcionando 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), e as versões anteriores da ferramenta continuam disponíveis em beta para modelos e plataformas que não oferecem suporte ao conjunto de ferramentas. Consulte [Migrar de `computer_20251124`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124) para fazer a atualização, ou [Versões anteriores da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) para ver os cabeçalhos beta.
## Considerações de segurança
O uso de computador apresenta riscos únicos, distintos dos recursos padrão da API. Esses riscos são ampliados ao interagir com a internet.
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 prevenir roubo de informações.
3. Limitar o acesso à internet a uma lista de permissões de domínios 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.
Em algumas circunstâncias, o Claude seguirá comandos encontrados no conteúdo mesmo quando eles conflitarem com suas instruções. Por exemplo, instruções em páginas web ou contidas em imagens podem sobrepor suas instruções ou fazer com que o Claude cometa erros. Tome precauções para isolar o Claude de dados e ações sensíveis para evitar riscos relacionados à injeção de prompt.
A Anthropic treinou o modelo para resistir a essas injeções de prompt e adicionou uma camada extra de defesa. Se você usar as ferramentas de uso do computador, classificadores analisarão automaticamente o que as ferramentas retornam, como capturas de tela, para sinalizar possíveis injeções de prompt. Quando esses classificadores identificam uma possível injeção de prompt, eles orientam automaticamente o modelo a verificar se a instrução realmente veio de você antes de agir com base nela.
Essa proteção extra não será ideal para todos os casos de uso (por exemplo, casos de uso sem um humano no loop), então, se você quiser desativá-la, [entre em contato com o suporte](https://support.claude.com/en/). As precauções acima continuam importantes mesmo com esses classificadores em funcionamento.
Informe os usuários finais sobre os riscos relevantes e obtenha o consentimento deles antes de habilitar o uso de computador em seus próprios produtos.
## Início rápido
Adicione o conjunto de ferramentas de uso de computador ao array `tools` de uma requisição da [Messages API](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 o Claude normalmente usa junto com o uso de computador:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-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 MessageParam
{
Role = Role.User,
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: '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: "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
```
Quando o Claude atua no desktop, a resposta tem um `stop_reason` de `tool_use` e contém um ou mais blocos `tool_use` de membros, cada um nomeando uma ferramenta membro e carregando `"toolset_name": "computer"`. No meio desta tarefa, depois que o Claude viu uma captura de tela do desktop, uma resposta pode ter esta aparência:
```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 em seu próprio ambiente, retorna um bloco `tool_result` por bloco `tool_use` e chama a API novamente; [Como funciona o uso de computador](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
* Adicione o toolset de uso de computador (e, opcionalmente, outras ferramentas) ao array `tools` da sua requisição à API.
* Inclua um prompt do usuário que exija interação com o desktop, por exemplo, "Salve uma foto de um gato na minha área de trabalho."
* O Claude avalia se agir no desktop pode ajudar com a consulta do usuário.
* Em caso afirmativo, o Claude responde com um ou mais blocos `tool_use` de membros, como `screenshot`, `left_click` ou `type`, cada um carregando `"toolset_name": "computer"`. Uma resposta com vários desses blocos é uma [ação em lote](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.
* Itere sobre cada bloco `tool_use` na resposta, em ordem. Para cada um, faça o despacho com base no `name` do membro junto com `toolset_name` e execute essa ação com o `input` do bloco no seu contêiner ou máquina virtual.
* Continue a conversa com uma nova mensagem `user` que contenha um bloco `tool_result` por bloco `tool_use`, correspondidos por `tool_use_id` e cada um 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).
* O Claude analisa os resultados das ferramentas para determinar se mais ações são necessárias ou se a tarefa foi concluída.
* Se o Claude determinar que mais ações são necessárias, ele responde com outro `stop_reason` `tool_use` e você deve retornar à etapa 3.
* Caso contrário, ele retorna uma resposta em texto ao usuário.
A repetição das etapas 3 e 4 sem entrada do usuário é chamada de "agent loop" (loop do agente), ou seja, o Claude respondendo com uma solicitação de uso de ferramentas e sua aplicação respondendo ao Claude com os resultados da avaliação dessa solicitação.
### Ações em lote
O Claude pode planejar uma sequência curta de ações, como clicar, digitar e depois fazer uma captura de tela, e retorná-las juntas em uma única resposta. Isso é chamado de "batch action" (ação em lote); ela usa o mesmo formato de resposta do [uso paralelo de ferramentas](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, em vez de 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`, correspondidos por `tool_use_id`, todos na próxima mensagem `user`. Todo resultado de uma ferramenta membro deve carregar `"toolset_name": "computer"`; um resultado que o omita, ou que nomeie um conjunto de ferramentas diferente do seu bloco `tool_use`, é rejeitado. Apenas os resultados de `screenshot` e `zoom` precisam de uma imagem; para os outros membros, uma confirmação curta em texto como `OK` é suficiente (`cursor_position` retorna as coordenadas como texto):
```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.** As ações posteriores em um lote geralmente dependem das anteriores: o `type` neste exemplo insere texto no que quer que o clique anterior tenha focado. Execute os blocos sequencialmente na ordem em que aparecem em `content` e, se um falhar, não execute os demais. Todo bloco `tool_use` ainda precisa de um `tool_result`, portanto responda ao lote da seguinte forma:
* Para cada ação que teve sucesso, retorne seu resultado normal.
* Para a ação que falhou, retorne `is_error: true` com uma descrição em texto do que deu errado.
* Para cada ação posterior no lote, retorne `is_error: true` com exatamente este texto (a ferramenta de uso de navegador usa seu próprio [texto de interrupção](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."
}
```
O Claude então vê quais ações tiveram sucesso, qual falhou e quais foram ignoradas, e replaneja em seu próximo turno. Uma requisição que deixe qualquer bloco `tool_use` do lote sem resposta é rejeitada com um `invalid_request_error`, portanto um loop do agente que leia apenas o primeiro bloco falha em sua próxima chamada. Se sua aplicação pede a um humano que confirme ações com consequências, faça essa verificação antes de cada bloco ser executado, porque um lote pode concluir uma ação de várias etapas dentro de um único turno.
O Claude normalmente termina um lote com `screenshot` para poder observar o resultado antes de 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 o Claude sempre veja o estado atual da tela, o que economiza uma ida e volta em comparação com esperar que o Claude a solicite. Você também pode instruir o Claude 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 de computação
O uso de computador requer um ambiente de computação em sandbox onde o Claude possa interagir com segurança com aplicações e com a web. Esse ambiente inclui:
1. **Display virtual:** Um servidor de display X11 virtual (usando Xvfb) que renderiza a interface de desktop que o Claude verá por meio de capturas de tela e controlará com ações de mouse/teclado.
2. **Ambiente de desktop:** Uma interface leve com gerenciador de janelas (Mutter) e painel (Tint2) rodando em Linux, que fornece uma interface gráfica consistente para o Claude interagir.
3. **Aplicações:** Aplicações Linux pré-instaladas, como Firefox, LibreOffice, editores de texto e gerenciadores de arquivos, que o Claude pode usar para concluir tarefas.
4. **Implementações das ferramentas:** Código de integração que traduz as solicitações abstratas de ferramentas do Claude (como "mover o mouse" ou "fazer captura de tela") em operações reais no ambiente virtual.
5. **Loop do agente:** Um programa que gerencia a comunicação entre o Claude e o ambiente, enviando as ações do Claude ao ambiente e retornando os resultados (capturas de tela, saídas de comandos) de volta ao Claude.
Quando você usa o uso de computador, o Claude não se conecta diretamente a esse ambiente. Em vez disso, sua aplicação:
1. Recebe as solicitações de uso de ferramentas do Claude
2. Traduz essas solicitações em ações no seu ambiente de computação
3. Captura os resultados (como capturas de tela e saídas de comandos)
4. Retorna esses resultados ao Claude
Para segurança e isolamento, a implementação de referência executa tudo isso dentro de um contêiner Docker com os mapeamentos de porta apropriados para visualizar e interagir com o ambiente.
***
## Como implementar o uso de computador
Atualizando uma integração existente com `computer_20251124`? Comece por [Migrar de `computer_20251124`](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 migradas.
A [implementação de referência de uso de computador](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) é um exemplo funcional completo: um [ambiente em contêiner](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/Dockerfile) adequado para uso de computador, implementações das [ferramentas de uso de computador](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools), um [loop do agente](https://github.com/anthropics/anthropic-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.
### Entenda o loop do agente
O núcleo do uso de computador é o "loop do agente": um ciclo em que o Claude solicita ações de ferramentas, sua aplicação as executa e retorna os resultados ao Claude. O loop usa o cliente que você criou no [Início rápido](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#quick-start), um array `tools` que declara apenas o conjunto de ferramentas de uso de computador e o helper de processamento de chamadas de ferramentas em [Implemente a ferramenta de uso de computador](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, faça o despacho dos blocos `tool_use` delas na mesma passagem; o helper responde apenas às chamadas de membros do uso de computador, e o loop trata um turno sem chamadas respondidas como concluído. Aqui está um exemplo simplificado:
```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,
)
# Adicione a resposta do Claude ao histórico da conversa
messages.append({"role": "assistant", "content": response.content})
# Execute as ações solicitadas pelo Claude, em ordem, e colete os resultados
tool_results = process_tool_calls(response)
if not tool_results:
return messages # No more tool use; task complete
# Envie todos os resultados de volta ao Claude em uma única mensagem do usuário
messages.append({"role": "user", "content": tool_results})
return messages
```
```typescript TypeScript
async function samplingLoop(
model: string,
messages: Anthropic.MessageParam[],
maxIterations = 10
): Promise {
// Execute o loop do agente de uso de computador até Claude parar de solicitar ferramentas
// ou o limite de iterações ser atingido.
for (let i = 0; i < maxIterations; i++) {
const response = await client.messages.create({
model,
max_tokens: 4096,
messages,
tools
});
// Adicione a resposta do Claude ao histórico da conversa
messages.push({ role: "assistant", content: response.content });
// Execute as ferramentas que Claude solicitou e colete os resultados
const toolResults = processToolCalls(response);
if (toolResults.length === 0) {
return messages; // No more tool use; task complete
}
// Envie os resultados das ferramentas de volta ao Claude para a próxima iteração
messages.push({ role: "user", content: toolResults });
}
return messages;
}
```
```csharp C#
async Task> SamplingLoop(
Model model,
List messages,
int maxIterations = 10
)
{
// Execute o loop do agente de uso de computador até que Claude pare de solicitar ferramentas
// ou o limite de iterações seja atingido.
for (var i = 0; i < maxIterations; i++)
{
var response = await client.Messages.Create(
new MessageCreateParams
{
Model = model,
MaxTokens = 4096,
Messages = messages,
Tools = tools,
}
);
// Adicione a resposta do Claude ao histórico da conversa
messages.Add(
new()
{
Role = Role.Assistant,
Content = response
.Content.Select(block => new ContentBlockParam(block.Json))
.ToList(),
}
);
// Execute as ferramentas que Claude solicitou e colete os resultados
var toolResults = ProcessToolCalls(response);
if (toolResults.Count == 0)
{
return messages; // No more tool use; task complete
}
// Envie os resultados das ferramentas de volta ao Claude para a próxima iteração
messages.Add(new() { Role = Role.User, Content = toolResults });
}
return messages;
}
```
```go Go
// samplingLoop executa o loop do agente de uso de computador até o Claude parar
// de solicitar ferramentas ou o limite de iterações ser atingido.
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
}
// Adiciona a resposta do Claude ao histórico da conversa
messages = append(messages, response.ToParam())
// Executa as ações solicitadas pelo Claude, em ordem, e coleta os resultados
toolResults := processToolCalls(response)
if len(toolResults) == 0 {
return messages, nil // No more tool use; task complete
}
// Envia todos os resultados de volta ao Claude em uma única mensagem de usuário
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 samplingLoop(Model model, List messages, int maxIterations) {
for (int i = 0; i < maxIterations; i++) {
Message response = client.messages().create(MessageCreateParams.builder()
.model(model)
.maxTokens(4096)
.messages(messages)
.addTool(COMPUTER_TOOLSET)
.build());
// Adicione a resposta do Claude ao histórico da conversa
messages.add(MessageParam.builder()
.role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(response.content().stream().map(ContentBlock::toParam).toList())
.build());
// Execute as ferramentas que o Claude solicitou e colete os resultados
List toolResults = processToolCalls(response);
if (toolResults.isEmpty()) {
return messages; // No more tool use; task complete
}
// Envie os resultados das ferramentas de volta ao Claude para a próxima iteração
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(toolResults)
.build());
}
return messages;
}
```
```php PHP
/**
* Run the computer-use agent loop until Claude stops requesting tools
* or the iteration limit is reached.
*/
function samplingLoop(string $model, array $messages, int $maxIterations = 10): array
{
global $client, $tools;
for ($i = 0; $i < $maxIterations; $i++) {
$response = $client->messages->create(
model: $model,
maxTokens: 4096,
messages: $messages,
tools: $tools,
);
// Adiciona a resposta do Claude ao histórico da conversa
$messages[] = MessageParam::with(role: Role::ASSISTANT, content: $response->content);
// Executa as ferramentas que o Claude solicitou e coleta os resultados
$toolResults = processToolCalls($response);
if ($toolResults === []) {
return $messages; // No more tool use; task complete
}
// Envia os resultados das ferramentas de volta ao Claude para a próxima iteração
$messages[] = MessageParam::with(role: Role::USER, content: $toolResults);
}
return $messages;
}
```
```ruby Ruby
# Executa o loop do agente de uso de computador até o Claude parar de solicitar ferramentas
# ou o limite de iterações ser atingido.
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
)
# Adiciona a resposta do Claude ao histórico da conversa
messages << { role: "assistant", content: response.content }
# Executa as ações que o Claude solicitou, em ordem, e coleta os resultados
tool_results = process_tool_calls(response)
return messages if tool_results.empty? # No more tool use; task complete
# Envia todos os resultados de volta ao Claude em uma única mensagem do usuário
messages << { role: "user", content: tool_results }
end
messages
end
```
O loop continua até que o Claude responda sem solicitar nenhuma ferramenta (conclusão da tarefa) ou até que o limite máximo de iterações seja atingido. Essa proteção evita possíveis loops infinitos que poderiam resultar em custos inesperados de API.
### Otimize o desempenho do modelo com prompts
1. Especifique tarefas simples e bem definidas e forneça instruções explícitas para cada etapa.
2. O Claude às vezes presume os resultados de suas ações sem verificá-los explicitamente. Para evitar isso, você pode instruir o Claude com `After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. 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 o Claude manipular usando movimentos do mouse. Se você passar por isso, tente instruir o modelo a usar atalhos de teclado.
4. Para tarefas repetíveis ou interações de interface, inclua em seu prompt capturas de tela de exemplo e chamadas de ferramentas de resultados bem-sucedidos.
5. Se você precisar que o modelo faça login, forneça a ele o nome de usuário e a senha em seu prompt dentro de tags XML como ``. Usar o uso de computador em aplicações que exigem login aumenta o risco de resultados ruins em decorrência de injeção de prompt. Revise [Mitigar jailbreaks e injeções de prompt](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) antes de fornecer credenciais de login ao modelo.
6. Ao construir o array `content` de um turno do usuário, coloque o texto da instrução *antes* da imagem da captura de tela. Fornecer a descrição do alvo antes de a imagem ser processada melhora a precisão dos cliques.
7. O Claude usa a ação `zoom` para inspecionar uma região em resolução total quando questionado sobre texto pequeno ou elementos específicos da interface que não são legíveis na resolução padrão da captura de tela, como nomes de arquivos em uma barra lateral, títulos de abas, texto da barra de status, números de linha ou rótulos de botões. Se o Claude não estiver usando zoom quando você espera, pergunte sobre uma região ou elemento específico em vez da tela como um todo.
8. Se você quiser que toda [ação em lote](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 o Claude precisará concluir, use o prompt do sistema para fornecer ao Claude dicas ou instruções explícitas sobre como realizar as tarefas com sucesso.
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 em navegador detectam regressões de sessões anteriores que a revisão apenas em nível de código não detecta. 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 "system prompt" (prompt do sistema) específico para 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 regular, o parâmetro `system` fornecido pelo usuário ainda é respeitado e usado na construção do prompt do sistema combinado.
### Ações disponíveis
Cada ação é uma ferramenta membro do conjunto de ferramentas de uso de computador: o Claude nomeia o membro em um bloco `tool_use` que carrega `"toolset_name": "computer"`, e o `input` do bloco contém apenas os parâmetros desse membro, sem campo `action`. O conjunto de ferramentas tem 17 ferramentas membro:
| Membro | Entrada | Descrição |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `screenshot` | Nenhuma (`{}`) | Captura o display inteiro e o 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 do display em resolução total e a retorna como uma imagem, dimensionada para caber nas dimensões habituais da sua captura de tela com a proporção preservada. Isso permite que o Claude leia texto pequeno 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 um elemento. |
| `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 digitar | 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): 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 indicada. |
| `wait` | `duration`: segundos, até 300 | Pausa antes da próxima ação, por exemplo, enquanto uma aplicação carrega. |
Tenha em mente o seguinte ao implementar os membros:
* **As coordenadas estão em pixels da captura de tela.** Todo valor de `coordinate`, `start_coordinate` e `region`, e a posição que `cursor_position` informa, está no espaço de pixels das capturas de tela do display inteiro que você retorna, com a origem no canto superior esquerdo. As imagens de zoom não mudam isso: após um `zoom`, o Claude ainda expressa coordenadas no espaço da captura de tela completa, nunca em relação à imagem ampliada. Se você reduzir as capturas de tela antes de retorná-las, amplie as coordenadas do Claude de volta antes de aplicá-las ao display real (consulte [Dimensione as capturas de tela para caber nos limites de imagem](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
* **Todos os membros estão habilitados por padrão, incluindo `zoom`.** Se seu ambiente não consegue produzir imagens de zoom, retenha o membro com `configs` (consulte [Parâmetros da ferramenta](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 o Claude chamar um membro que você reteve ou não implementa, retorne um `tool_result` com `is_error: true` para esse bloco.
* **Faça o despacho com base no par (`toolset_name`, `name`).** `toolset_name` é o que marca um bloco como uma ação de computador: uma ferramenta personalizada na mesma requisição pode compartilhar o nome de um membro, e uma versão posterior do conjunto de ferramentas pode adicionar membros (consulte [Conjuntos de ferramentas do cliente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets)).
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 pela duração desse 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 }
}
```
Ampliar 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 curto em texto 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": {}
}
```
### Parâmetros da ferramenta
A entrada do conjunto de ferramentas no array `tools` aceita quatro parâmetros; as regras que eles compartilham com o conjunto de ferramentas de uso de navegador estão listadas em [Conjuntos de ferramentas do cliente](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 [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 de [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) na definição do conjunto de ferramentas; apenas 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 | Apenas `["direct"]`. |
Por exemplo, esta entrada retém `zoom` para um ambiente que não o implementa e define um ponto de interrupção de cache na definição do conjunto de ferramentas:
```json
{
"type": "computer_toolset_20260801",
"configs": {
"zoom": { "enabled": false }
},
"cache_control": { "type": "ephemeral" }
}
```
Se seu loop do agente só consegue executar uma ação por ida e volta, defina `disable_parallel_tool_use` como `true` em `tool_choice`; o Claude então retorna no máximo um bloco `tool_use` de membro por turno (consulte [Desabilitar o uso paralelo de ferramentas](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 conjunto de ferramentas.
* `display_width_px`, `display_height_px` e `display_number`: as coordenadas estão sempre no espaço de pixels das capturas de tela que você retorna.
* `enable_zoom`: zoom é uma ferramenta membro que você controla por meio de `configs`.
A entrada também não pode ser declarada na mesma requisição que uma entrada `computer_20251124` ou outra ferramenta chamada `computer`. Para `strict`, `input_examples`, posicionamento de `defer_loading`, `tool_choice`, streaming e restrições de chamador, consulte [Conjuntos de ferramentas do cliente](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).
Para a ferramenta anterior `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 alto volume 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 adiciona custo de 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 opção forte para loops sensíveis a custo.
### 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 de 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 conjuntos de ferramentas funcionam de forma independente, cada um em seu próprio sistema de coordenadas, e as chamadas a membros que compartilham um nome, como `screenshot` ou `key`, são diferenciadas por `toolset_name`.
### Construa um ambiente personalizado de uso de computador
A [implementação de referência](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) tem como objetivo ajudar você a começar com o uso de computador. Ela inclui todos os componentes necessários para que o Claude use um computador. No entanto, você pode construir seu próprio ambiente de uso de computador para atender às suas necessidades. Você precisará de:
* Um ambiente virtualizado ou em contêiner adequado para uso de computador com o Claude
* Uma implementação das ações da ferramenta de uso de computador
* Um loop do agente que interaja com a Claude API e execute os resultados de `tool_use` usando suas implementações de ferramentas
* Uma API ou interface que permita a entrada do usuário para iniciar o loop do agente
### Implemente a ferramenta de uso de computador
A ferramenta de uso de computador é implementada como uma ferramenta sem schema. Ao usar esta ferramenta, você não precisa fornecer um schema de entrada como em outras ferramentas; o schema está incorporado ao modelo do Claude e não pode ser modificado.
Crie um display virtual ou conecte-se a um display existente com o qual o Claude irá interagir. Isso normalmente envolve configurar o Xvfb (X Virtual Framebuffer) ou tecnologia semelhante.
Crie funções para tratar cada tipo de ação que o Claude possa solicitar:
```python Python
# Dados de imagem de placeholder; um executor real captura a tela e retorna os bytes PNG
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def capture_screenshot() -> list[ImageBlockParam]:
# screenshot responde com um bloco de imagem em vez de texto: retorne a lista de conteúdo do resultado
return [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": PLACEHOLDER_PNG,
},
}
]
def click(coordinate=None):
if coordinate is None:
return "clicked at current cursor"
x, y = coordinate
return f"clicked at ({x}, {y})"
def type_text(text):
return f"typed: {text}"
def handle_computer_action(name, tool_input):
match name:
case "screenshot":
return capture_screenshot()
case "left_click":
# coordinate é opcional; sem ele, clique onde o cursor já está
return click(tool_input.get("coordinate"))
case "type":
return type_text(tool_input["text"])
# Trate outras ações conforme necessário
raise ValueError(f"Unknown or unimplemented member: {name}")
```
```typescript TypeScript
// Dados de imagem de placeholder; um executor real captura a tela como bytes PNG
const PLACEHOLDER_PNG =
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
function captureScreenshot(): Anthropic.ImageBlockParam[] {
// screenshot responde com um bloco de imagem em vez de texto
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 é opcional no conjunto de ferramentas; sem ela, clique na posição do 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;
}
// Trate outras ações conforme necessário
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// Dados de imagem de placeholder; um executor real captura a tela e retorna os bytes PNG
const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
// screenshot responde com um bloco de imagem em vez de texto: retorne a lista de conteúdo do resultado
List 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 input
) =>
action switch
{
"screenshot" => CaptureScreenshot(),
// coordinate é opcional em membros de click; sem ele, clique onde o cursor está
"left_click" when input.TryGetValue("coordinate", out var xy) => ClickAt(
xy[0].GetInt32(),
xy[1].GetInt32()
),
"left_click" => ClickAtCursor(),
"type" => TypeText(input["text"].GetString()!),
// Trate outras ações conforme necessário
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG substitui uma captura real: um executor retorna a
// tela como dados PNG codificados em base64.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// captureScreenshot retorna um bloco de imagem em vez de texto.
func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{{
OfImage: &anthropic.ImageBlockParam{
Source: anthropic.ImageBlockParamSourceUnion{
OfBase64: &anthropic.Base64ImageSourceParam{
MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
Data: placeholderPNG,
},
},
},
}}
}
// textContent encapsula texto como conteúdo de tool_result.
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 é opcional; sem ele, clica onde o cursor já está
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
}
// Trate outras ações conforme necessário
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// Alcançado quando a entrada de um membro não tem um campo ou um campo tem o tipo errado
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 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 point = (List) 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());
// Trate outras ações conforme necessário
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// Substituto para bytes PNG reais; um executor real captura a tela
const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
function captureScreenshot(): array
{
// screenshot responde com um bloco de imagem em vez de texto, então retorne a lista de conteúdo do resultado
$image = [
'type' => 'image',
'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
];
return [$image];
}
function clickAt(?array $coordinate): string
{
// left_click pode omitir coordinate; nesse caso, o clique ocorre onde o cursor já está
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']),
// Trate outras ações conforme necessário
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# Dados de imagem de exemplo; um executor real captura a tela como PNG.
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
# screenshot responde com um bloco de imagem em vez de texto
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 é opcional; sem ele, clica onde o cursor já está
click(input[:coordinate])
when "type"
type_text(input[:text])
# Trate outras ações conforme necessário
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
Extraia e execute as chamadas de ferramentas das respostas do Claude:
```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:
# Apenas o conjunto de ferramentas computer é declarado; roteie outras ferramentas aqui se você as adicionar
if block.type != "tool_use" or block.toolset_name != "computer":
continue
result: ToolResultBlockParam = {
"type": "tool_result",
"tool_use_id": block.id,
"toolset_name": "computer",
}
if failed:
result["content"] = NOT_EXECUTED
result["is_error"] = True
else:
try:
# Uma string ou uma lista de blocos de conteúdo, como a imagem da captura de tela
result["content"] = handle_computer_action(block.name, block.input)
except Exception as err:
result["content"] = f"Error: {err}"
result["is_error"] = True
failed = True
tool_results.append(result)
return tool_results
```
```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") {
// Este exemplo declara apenas o toolset computer; roteie outras ferramentas
// aqui se você as adicionar.
continue;
}
if (failed) {
// Um lote para na primeira falha; responda às ações posteriores como não executadas
toolResults.push(computerResult(block.id, HALT_TEXT, true));
continue;
}
try {
// Uma string, ou a lista de blocos de imagem que screenshot retorna
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 ProcessToolCalls(Message response)
{
List toolResults = [];
var failed = false;
foreach (var block in response.Content)
{
if (!block.TryPickToolUse(out var toolUse))
{
continue;
}
if (toolUse.ToolsetName != "computer")
{
// Este exemplo declara apenas o conjunto de ferramentas computer; roteie outras ferramentas
// aqui se você as adicionar.
continue;
}
if (failed)
{
// Um lote para na primeira falha; responda às ações posteriores sem executá-las
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "computer",
}
);
continue;
}
try
{
// Uma string, ou a lista de blocos de imagem que screenshot retorna
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 monta o resultado de uma ação de computador. Diferente de um
// resultado de ferramenta comum, ele deve repetir o nome do toolset.
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 executa em ordem as ações de computador na resposta do Claude e
// monta um tool_result por bloco tool_use. Após a primeira falha, ignora
// o restante: o Claude as planejou supondo que as ações anteriores tiveram sucesso.
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:
// Este exemplo declara apenas o toolset de computador; roteie outras ferramentas aqui se adicioná-las.
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 {
// Texto, ou o bloco de imagem que screenshot retorna
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 per tool_use block. After the first failure, skip the rest:
* Claude planned them assuming the earlier actions succeeded.
*/
List processToolCalls(Message response) {
List toolResults = new ArrayList<>();
boolean failed = false;
for (ContentBlock block : response.content()) {
// Este exemplo declara apenas o conjunto de ferramentas de computador; roteie outras ferramentas aqui se você as adicionar.
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 input =
(Map) toolUse._input().asObject().get();
// Uma string ou o bloco de imagem que screenshot retorna
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) {
// Este exemplo declara apenas o conjunto de ferramentas computer; roteie outras ferramentas aqui se você adicioná-las.
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'computer') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'computer'];
if ($failed) {
// Um lote para na primeira falha; as ações restantes são respondidas sem serem executadas
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// Uma string, ou a lista de blocos de imagem que screenshot retorna
$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."
# Executa as ações de computador na resposta do Claude em ordem e cria um
# tool_result por bloco tool_use. Após a primeira falha, pula o restante:
# o Claude as planejou assumindo que as ações anteriores tiveram sucesso.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# Este exemplo declara apenas o conjunto de ferramentas de computador; roteie outras ferramentas aqui
# se você as adicionar.
next unless block.type == :tool_use && 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
# Uma String, ou os blocos de conteúdo de imagem que screenshot retorna
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
```
Envolva as duas etapas anteriores em um loop que envie os resultados de volta e repita até que o Claude não retorne nenhuma chamada de ferramenta membro; [Entenda o loop do agente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop) mostra esse loop em cada linguagem.
### Trate erros
Informe uma ação com falha ao Claude como um `tool_result` com `is_error: true` e uma descrição curta, e inclua `"toolset_name": "computer"` como em qualquer outro resultado de membro. Se a ação com falha fazia parte de uma [ação em lote](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 lá 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 do display e para ações que falham ao executar, com uma mensagem que diga o que deu errado.
### Dimensione as capturas de tela para caber nos limites de imagem
As capturas de tela e imagens de zoom que você retorna ao conjunto de ferramentas de uso de computador já devem caber nos [limites de tamanho de imagem](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size) do seu modelo: o conjunto de ferramentas não recebe dimensões de display e a API não reduz a escala para você, portanto uma imagem de `tool_result` grande demais é rejeitada com um erro de validação. Como o Claude retorna coordenadas no espaço de pixels da imagem que ele vê, guarde o fator de escala que você usou para poder mapear essas coordenadas de volta à sua tela.
Os limites variam por modelo. O Claude Opus 4.7 e modelos posteriores, incluindo todos os modelos que oferecem suporte a `computer_toolset_20260801`, aceitam até 2576 pixels na borda mais longa e 4784 tokens visuais no total (`⌈width / 28⌉ × ⌈height / 28⌉`, aproximadamente 3,75 megapixels); modelos anteriores aceitam até 1568 pixels na borda mais longa e aproximadamente 1,15 megapixels no total (consulte [Resolução e custo de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size) para ver o nível de cada modelo). O exemplo a seguir usa os limites de 1568 px / 1,15 MP dos modelos anteriores. Para um modelo do nível de alta resolução, dimensione pelo limite de tokens visuais em vez de um total de pixels, por exemplo com o helper de redimensionamento em [Redimensione sua imagem antes de enviar](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#resize-your-image-before-uploading).
Se sua tela for maior que o limite, redimensione cada captura de tela antes de retorná-la e escale as coordenadas retornadas pelo Claude de volta ao espaço original da tela. Como o conjunto de ferramentas não recebe dimensões de display, o redimensionamento e o escalonamento de coordenadas no código da sua aplicação são tudo de que você precisa:
```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 capturar a captura de tela
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)
# Redimensione a imagem para as dimensões escaladas antes de enviar ao Claude
screenshot = capture_and_resize(scaled_width, scaled_height)
# Ao lidar com as coordenadas do Claude, escale-as de volta para o tamanho original
def execute_click(x, y):
screen_x = x / scale
screen_y = y / scale
perform_click(screen_x, screen_y)
```
```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 capturar 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 enviar ao Claude
const screenshot = captureAndResize(scaledWidth, scaledHeight);
// Ao lidar com as coordenadas do Claude, escale-as de volta para cima
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 capturar a tela
double scale = GetScaleFactor(screenWidth, screenHeight);
int scaledWidth = (int)(screenWidth * scale);
int scaledHeight = (int)(screenHeight * scale);
// Redimensiona a imagem para as dimensões escaladas antes de enviar ao Claude
var screenshot = CaptureAndResize(scaledWidth, scaledHeight);
// Ao lidar com as coordenadas do Claude, escale-as de volta para cima
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 capturar 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 enviar ao Claude
screenshot := captureAndResize(scaledWidth, scaledHeight)
// Ao lidar com as coordenadas do Claude, escale-as de volta para cima
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 capturar 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 enviar ao Claude
var screenshot = captureAndResize(scaledWidth, scaledHeight);
// Ao lidar com as coordenadas do Claude, escale-as de volta para cima
BiConsumer 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 capturar 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 enviar ao Claude
$screenshot = captureAndResize($scaledWidth, $scaledHeight);
// Ao lidar com as coordenadas do Claude, escale-as de volta para cima
$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 capturar 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
# Redimensione a imagem para as dimensões escaladas antes de enviar ao Claude
screenshot = capture_and_resize(scaled_width, scaled_height)
# Ao lidar com as coordenadas do Claude, escale-as de volta para o tamanho original
execute_click = ->(x, y) { perform_click(x / scale, y / scale) }
```
**Displays Retina do macOS** capturam telas com uma proporção de pixels do dispositivo de 2, portanto a imagem tem o dobro da resolução das coordenadas lógicas da tela. Reduza a captura de tela em 2x antes de enviar, ou divida pela metade as coordenadas que o Claude retorna antes de emitir o clique.
Ao escolher uma resolução de display e retornar capturas de tela:
* Para tarefas gerais de desktop, use 1024x768 ou 1280x720; para aplicações web, use 1280x800 ou 1366x768.
* Evite resoluções acima de 1920x1080 para prevenir problemas de desempenho.
* Codifique as capturas de tela como PNG ou JPEG em base64 e considere comprimir capturas de tela grandes para melhorar o desempenho.
* Inclua metadados relevantes, como timestamp ou estado do display.
* Se você usar resoluções mais altas, garanta que as coordenadas sejam escaladas com precisão.
### Gerenciar o histórico de capturas de tela
Loops de agente longos acumulam capturas de tela rapidamente (aproximadamente 1.000–1.800 tokens de entrada cada). Os [limites de requisição](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits) da API também se aplicam. Quando uma única requisição carrega mais de 20 imagens, cada imagem nela fica sujeita a um limite por lado mais rigoroso. Um loop que mantém seu histórico de capturas de tela atinge essa contagem em algumas dezenas de turnos, então redimensione cada captura de tela para que nenhum lado exceda 2000 px ou remova capturas de tela mais antigas para manter 20 ou menos na requisição.
Para manter o [cache de prompt](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 "system prompt" (prompt do sistema) e as definições de ferramentas, e até mais três no último bloco `tool_result` de cada um dos turnos mais recentes, avançando-os a cada turno. Dentro de uma [ação em lote](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions), marcadores em vários blocos funcionam como um único breakpoint, mas cada um ainda conta para o limite de quatro. Por isso, use um por turno.
* Remova capturas de tela antigas em *lotes*, não uma a cada turno. Descartar uma captura de tela a cada turno altera o prefixo a cada turno e invalida o cache. Um padrão razoável é manter as três últimas capturas de tela e fazer a remoção a cada 25 turnos, para que o prefixo permaneça idêntico byte a byte entre os eventos de remoção. Se suas capturas de tela excederem 2000 px em qualquer lado, escolha um intervalo que mantenha cada requisição com 20 imagens ou menos.
* Nos modelos Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5, evite fazer a remoção no cliente: remover uma captura de tela anterior [invalida todos os "thinking blocks" (blocos de pensamento) posteriores](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserved-in-conversation) em cada requisição que ainda carrega esses turnos. Em vez disso, redimensione as capturas de tela para 2000 px ou menos por lado e use a [limpeza de resultados de ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing#tool-result-clearing) no lado do servidor para descartar as antigas do contexto. Se você precisar fazer a remoção, mantenha [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserved-thinking-controls) definido a partir de então; após cada remoção, o Claude continua sem o pensamento produzido desde a captura de tela removida, nessa requisição e em todas as posteriores. No Claude Sonnet 5.5, `block_binding` funciona apenas com `thinking: {"type": "adaptive"}`. Com `between_tools`, mantenha o histórico apenas com acréscimos, ou remova os blocos de pensamento a partir do turno editado. No Claude Haiku 5.5, `block_binding` funciona apenas com `thinking: {"type": "adaptive"}`; com `thinking: {"type": "disabled"}`, mantenha o histórico apenas com acréscimos, ou remova os blocos de pensamento a partir do turno editado.
### Diagnosticar problemas de clique
Se os cliques erram seus alvos, a causa geralmente é uma das seguintes:
| Sintoma | Causa provável | Tente |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cliques consistentemente deslocados em uma direção | As coordenadas do 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 escalonamento | Escale cada coordenada pela razão entre o tamanho da sua tela e o tamanho da sua captura de tela antes de clicar (consulte [Dimensionar 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 uma fonte 4K+, ou a proporção de aspecto foi distorcida | Mantenha o membro `zoom` habilitado e implemente-o para que Claude possa inspecionar a região em resolução total; capture em DPI mais baixo ou recorte para a região relevante; preserve a proporção de aspecto ao redimensionar |
| Claude clica no elemento completamente errado | Instrução ambígua, ou elementos visualmente semelhantes próximos | Use prompts posicionais ("o botão azul Enviar no canto inferior direito"); divida a interação em etapas menores |
| A precisão é consistentemente ruim | Resolução muito baixa | Tente 1280x720 como linha de base |
**A escolha do modelo afeta a precisão do clique.** Entre os modelos que usam a ferramenta anterior `computer_20251124`, o Claude Sonnet 4.6 é mecanicamente mais preciso ao clicar do que o Claude Opus 4.6 e é mais robusto quando as capturas de tela exigem redução intensa. O 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 menos redução é necessária.
### Seguir as melhores práticas de implementação
Algumas aplicações precisam de tempo para responder às ações:
```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 {
clickAt(x, y);
await setTimeout(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
```
Verifique se as ações solicitadas são seguras e válidas:
```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 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 params) {
if (actionType.equals("left_click") && params.containsKey("coordinate")) {
List coord = (List) 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
```
Mantenha um registro de todas as ações para solução de problemas:
```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
```
***
## Migrar de `computer_20251124`
Atualizar de `computer_20251124` para o toolset é opcional: os modelos listados para `computer_20251124` em [Versões anteriores da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions) continuam aceitando-a com seu cabeçalho beta, então uma integração existente continua funcionando até que você a altere. Os modelos Claude 5.5 e posteriores são a exceção na Claude API e no Google Cloud: lá eles aceitam apenas o toolset. Atualize uma integração antes de movê-la para um deles. No Amazon Bedrock, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5 aceitam `computer_20251124`. Para atualizar, faça as seguintes alterações em conjunto:
1. **Remova o cabeçalho beta.** Retire `anthropic-beta: computer-use-2025-11-24` das suas requisições. 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 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 cada bloco `tool_use` em uma resposta em vez de ler apenas o primeiro, e para despachar com base no `name` do bloco junto com `toolset_name` em vez de `input.action`. As entradas dos membros não contêm mais um campo `action`; os campos restantes permanecem inalterados.
5. **Execute os blocos em ordem e use o texto de interrupção.** Execute os blocos sequencialmente, pare na primeira falha e responda aos blocos restantes com `Not executed: an earlier computer action in this turn failed.` conforme descrito em [Ações em lote](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions). Se 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 `repeat` opcional de 1 a 100. Um manipulador que ignora campos não reconhecidos pressionaria a tecla uma vez, então faça seu manipulador de `key` respeitar `repeat`.
8. **Redimensione as capturas de tela você mesmo.** O toolset rejeita uma captura de tela ou imagem de zoom que exceda os limites de imagem do modelo em vez de reduzi-la. Redimensione antes de retornar a imagem e continue escalando as coordenadas conforme descrito em [Dimensionar capturas de tela para caber nos limites de imagem](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 cada membro habilitado. As outras opções não suportadas em entradas de toolset estão listadas em [Toolsets do 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` completamente para aceitar o padrão e permitir que Claude faça 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 uso de computador continuam disponíveis em beta para integrações existentes, para modelos que não suportam o toolset e em plataformas onde o toolset não está disponível atualmente. Cada uma exige seu [cabeçalho beta](https://platform.claude.com/docs/pt-BR/api/beta-headers) em todas as requisiçõ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 de computador precisa do cabeçalho, não as ferramentas bash ou de editor de texto na mesma requisiçã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; no Amazon Bedrock, também Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.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 Bedrock e no Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)), Claude Sonnet 4 ([desativado, exceto no Bedrock e no Google Cloud](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) e Claude Opus 4 ([desativado, exceto no Google Cloud](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) |
***
## Limitações
1. **Latência:** A latência atual do uso de computador para interações humano-IA pode ser muito lenta em comparação com ações de computador regulares dirigidas por humanos. Concentre-se em casos de uso onde a velocidade não é crítica (por exemplo, coleta de informações em segundo plano, testes automatizados de software) em ambientes confiáveis.
2. **Precisão e confiabilidade da visão computacional:** Claude pode cometer erros ou alucinar ao gerar coordenadas específicas durante a geração de ações. A saída de [pensamento resumido](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#summarized-thinking) do Claude pode ajudar você a entender o raciocínio do modelo e identificar possíveis problemas; defina `display: "summarized"` na configuração de pensamento, porque os modelos que suportam o toolset omitem o texto de pensamento por padrão.
3. **Precisão e confiabilidade da seleção de ferramentas:** Claude pode cometer erros ou alucinar ao selecionar ferramentas durante a geração de ações ou tomar ações inesperadas para resolver problemas. Além disso, a confiabilidade pode ser menor ao interagir com aplicações de nicho ou várias aplicações ao mesmo tempo. Elabore o prompt do modelo com cuidado ao solicitar tarefas complexas.
4. **Confiabilidade da rolagem:** A ação de rolagem suporta controle de direção (para cima, para baixo, esquerda, direita) e uma quantidade especificada. Em aplicações onde a rolagem não tem efeito, alternativas de teclado como Page Down podem ajudar.
5. **Interação com planilhas:** Use as ações de controle fino do mouse (`left_mouse_down`, `left_mouse_up`) e combinações de teclas modificadoras para selecionar células individuais. Operações complexas em planilhas ainda podem exigir várias tentativas.
6. **Criação de contas e geração de conteúdo em plataformas sociais e de comunicação:** Embora Claude visite sites, sua capacidade de criar contas, gerar e compartilhar conteúdo ou de outra forma se envolver em personificação humana em sites e plataformas de mídia social é limitada.
7. **Vulnerabilidades:** Jailbreaks e injeção de prompt podem afetar o uso de computador assim como podem afetar qualquer sistema de IA de fronteira, inclusive por meio de instruções incorporadas em páginas web ou imagens; aplique as precauções em [Considerações de segurança](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#security-considerations).
8. **Ações inapropriadas ou ilegais:** De acordo com os Termos de Serviço da Anthropic, você não deve empregar o uso de computador para violar quaisquer leis ou a Política de Uso Aceitável.
Sempre revise e verifique cuidadosamente as ações e os registros de uso de computador do Claude. Não use Claude para tarefas que exijam precisão perfeita ou informações sensíveis de usuários sem supervisão humana.
## Retenção de dados
O uso de computador é uma ferramenta do lado do cliente. Todas as capturas de tela, ações do mouse, entradas de teclado e quaisquer arquivos envolvidos em uma sessão são capturados e armazenados no seu ambiente, não pela Anthropic. A Anthropic processa as imagens de captura de tela e as solicitações de ação em tempo real como parte da chamada de API. A retenção dessas requisições de API é regida por [API e retenção de dados](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. Para elegibilidade ZDR em todos os recursos, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
## 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
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.
## Próximos passos
Comece a partir do driver de um parceiro ou escreva o seu próprio em Python ou TypeScript. O SDK executa o loop e o callback de aprovação que você passar.
Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para correção.
Comece com a implementação completa baseada em Docker
Conecte Claude a ferramentas e APIs externas. Veja onde as ferramentas são executadas, quando Claude as chama e qual ferramenta se adequa à sua tarefa.
Recomendações com benchmarks para resolução, esforço de pensamento e gerenciamento de contexto
Permita que Claude navegue, leia e interaja com páginas da web no seu próprio ambiente de navegador, para tarefas que permanecem dentro do navegador.