Referência de ferramentas do agente

Estas ferramentas estão registradas para o subagente Computer Use do Alter (computer_use_task). São apenas para LLM — projetadas para o modelo chamar durante um loop de UI em segundo plano, não para execução manual pontual na maioria dos casos. O subagente também recebe as ferramentas primitivas Perform, Scroll e Wait. Esta página cobre as ferramentas específicas do agente e as regras compartilhadas de direcionamento de janela.

Comece aqui

Leia a visão geral do Computer Use para invocar o agente com uma string goal.

Fluxo de trabalho compartilhado

Formatos de ID de janela

list_windows retorna dois estilos de ID:

Formato	Exemplo	Notas
`pid/title`	`4280/Mail — Inbox`	Legível; o título pode mudar
`pid/windowNumber` estável	`4280/12345`	Preferido quando disponível — sobrevive a mudanças de título

Passe o mesmo windowID para read_screen_ax, perform, perform_sequence, scroll e computer_use_screenshot em cada etapa dessa janela.

Ordem de resolução

Quando windowID é omitido:

windowID explícito na chamada da ferramenta
Alvo rastreado — janela registrada por open_app, open_urls ou ferramentas anteriores nesta conversa
Fallback de sessão — durante execução em segundo plano, a janela mostrada na pré-visualização ao vivo (evita deriva quando você refoca outro app)
Janela em primeiro plano

Apps bloqueados

O Computer Use recusa abrir, ler ou controlar apps na sua lista de bloqueio (Settings → Computer use → Blocked apps). Gerenciadores de senha são bloqueados por padrão. As ferramentas retornam um erro claro para o agente parar de iterar e reportar o bloqueio.

Autônomo vs dentro do agente

Contexto	Disponível?
Dentro do subagente `computer_use_task`	Sim — conjunto completo abaixo
Agente pai Ask Anything	Indiretamente — o pai deve chamar `computer_use_task`, não encadear estas manualmente
Execução manual no Tools Manager	Possível para depuração; não é o fluxo principal

Ferramentas de workspace (workspace_read, workspace_bash, etc.) não estão disponíveis dentro do Computer Use.

`read_screen_ax`

Nome de exibição: Read Screen (AX) Retorna a árvore de acessibilidade de uma janela como texto. Elementos interativos incluem o sufixo @elementID para uso com perform e perform_sequence. Sem captura de tela nem análise visual — estritamente apenas AX.

Parâmetros

Parâmetro	Obrigatório	Padrão	Descrição
`windowID`	Não	rastreado → fallback de sessão → primeiro plano	`pid/title` ou `pid/windowNumber` estável

Quando o agente chama

Primeira etapa em uma janela (antes de qualquer clique ou preenchimento)
Depois de navegação, diálogos, rolagem ou atalhos que alterem a UI
Antes de escolher opções de combobox/lista que não estavam visíveis na leitura anterior

Saída

Envolvido em <activeAppContext>…</activeAppContext>. Durante execuções do Computer Use, apps correspondentes podem acrescentar <appGuidance> (Calculator, Discord, Spotify, X.com, etc.) com técnicas mais rápidas.

Exemplo

Etapa do objetivo: o agente já abriu o Mail via open_app e recebeu windowID: 5123/Mail — Inbox.

read_screen_ax({ "windowID": "5123/Mail — Inbox" })

Retorna linhas com IDs de elemento como Unread message row 1@MessageRow_0 para cliques perform subsequentes.

vs `get_active_app_context`

Get Active App Context adiciona OCR de capturas de tela. O agente Computer Use prefere read_screen_ax por velocidade e privacidade, a menos que o objetivo exija captura visual via computer_use_screenshot.

`perform_sequence`

Nome de exibição: Perform Sequence Executa várias ações de UI em uma chamada de ferramenta — mais rápido que invocações perform separadas quando todos os elementos alvo já estão visíveis na leitura AX atual.

Parâmetros

Parâmetro	Obrigatório	Descrição
`steps`	Sim	Array de objetos de ação (veja abaixo)
`windowID`	Não	Aplicado a cada etapa

Cada objeto step:

Campo	Obrigatório para	Descrição
`action`	—	`click` (padrão), `fill`, `type` ou `shortcut`
`elementID`	`click`, `fill`	ID após `@` de `read_screen_ax`
`text`	`fill`, `type`	Texto a inserir
`shortcut`	`shortcut`	ex.: `cmd+k`, `escape`, `shift+enter`

Regras de agrupamento

Todos os valores elementID devem vir do mesmo resultado de read_screen_ax
Agrupe apenas ações que não alterem o layout entre etapas (formulário de vários campos, expressão de calculadora via type)
Pare o agrupamento antes de navegação, troca de app ou abertura de menus/diálogos — depois releia
A execução para na primeira etapa com falha e informa qual etapa falhou

Exemplo

Preencher formulário de três campos visível em uma leitura:

{
  "windowID": "5123/Signup",
  "steps": [
    { "action": "fill", "elementID": "FirstName", "text": "Alex" },
    { "action": "fill", "elementID": "LastName", "text": "Rivera" },
    { "action": "fill", "elementID": "Email", "text": "[email protected]" }
  ]
}

Busca rápida no Spotify (após ler a janela principal):

{
  "steps": [
    { "action": "shortcut", "shortcut": "cmd+k" },
    { "action": "type", "text": "Debussy Clair de Lune" }
  ]
}

Veja Perform para semântica de ação única (type vs fill, formato de atalho).

`computer_use_screenshot`

Nome de exibição: Computer Use Screenshot Captura uma janela de app específica como PNG. Não usa atalhos globais de captura, screencapture nem seleção interativa de região.

Parâmetros

Parâmetro	Obrigatório	Descrição
`windowID`	Não	Mesma ordem de resolução das outras ferramentas

Quando usar

O objetivo pede explicitamente capturas de tela ou artefatos visuais
Evite para inspeção rotineira de UI — use read_screen_ax em vez disso

Saída

Metadados de texto (app, title, windowID, dimensões) mais anexo de imagem para o modelo.

Exemplo

computer_use_screenshot({ "windowID": "9042/Google Chrome — Dashboard" })

Falha se a permissão Screen Recording estiver ausente ou a janela estiver minimizada/oculta.

`list_windows`

Nome de exibição: List Windows Enumera janelas abertas de aplicativos em execução. Sem parâmetros.

Retorna

Para cada janela:

Nome do app e identificador de bundle
Título da janela
Window ID (pid/title)
Stable Window ID quando disponível
PID
Marcador ⭐ (ACTIVE) na janela em primeiro plano

Quando o agente chama

A janela alvo não é o app em primeiro plano e não foi aberta via open_app / open_urls nesta execução
Uma vez por execução costuma bastar — reutilize os IDs retornados em vez de listar repetidamente

Saída de exemplo (abreviada)

Open Windows (42 total):

Safari (com.apple.Safari):
  - Window: "Apple — Homepage" ⭐ (ACTIVE)
    Window ID: 4280/Apple — Homepage
    Stable Window ID: 4280/87
    PID: 4280

O agente então passa 4280/87 para read_screen_ax para um scrape em segundo plano enquanto você trabalha em outro app.

`open_app`

Nome de exibição: Open Application Inicia ou foca um aplicativo Mac. Retorna o ID da janela alvo para acompanhamento imediato — muitas vezes sem chamar list_windows.

Parâmetros

Parâmetro	Obrigatório	Descrição
`bundleId`	Sim	Identificador de bundle (ex.: `com.apple.Calculator`) ou nome legível do app (`Calculator`, `Google Chrome`) — nomes são resolvidos automaticamente

Comportamento

Execuções em segundo plano: Se o app já está em execução, o Alter não rouba o foco. Novos lançamentos usam abertura não ativadora quando possível e restauram seu app em primeiro plano anterior.
Apps bloqueados: Recusados com erro de lista de bloqueio
A resposta de sucesso inclui Window ID e Stable Window ID opcional para passar às ferramentas subsequentes

Exemplo

{ "bundleId": "com.apple.Calculator" }

A resposta inclui:

Target window: Calculator - Calculator
Window ID: 6012/Calculator
Pass this windowID to read_screen_ax, perform, perform_sequence, and scroll...

Ferramentas primitivas no mesmo agente

Estas têm páginas dedicadas; o subagente as usa com as mesmas regras de windowID:

Ferramenta	Página	Notas do agente
`perform`	Perform	Clique/preenchimento/type/atalho único; prefira `perform_sequence` ao agrupar
`scroll`	Scroll	Duração `milliseconds` (padrão 3000); Chromium/Safari usam rolagem por teclado em segundo plano
`wait`	Wait	Use quando a leitura AX estiver vazia ou carregando — não antes de cada etapa
`open_urls`	—	Abre URLs; roteado para o navegador do agente durante Computer Use

get_active_app_context não está no conjunto de ferramentas do subagente — use read_screen_ax em vez disso.

Solução de problemas

Problema	Orientação
`Window … not found`	Execute `list_windows` novamente; a janela pode ter sido fechada
Falhas de `elementID` após agrupamento	Layout mudou — releia com `read_screen_ax`
App bloqueado	Ajuste a lista de bloqueio ou reformule o objetivo para pular esse app
Captura falhou	Conceda Screen Recording; garanta que a janela esteja visível
Atalhos globais ignorados	Esperado no modo segundo plano — o agente usa `fill`/`type`, não ⌘C/⌘V

Comece aqui

​Fluxo de trabalho compartilhado

​Formatos de ID de janela

​Ordem de resolução

​Apps bloqueados

​Autônomo vs dentro do agente

​read_screen_ax

​Parâmetros

​Quando o agente chama

​Saída

​Exemplo

​vs get_active_app_context

​perform_sequence

​Parâmetros

​Regras de agrupamento

​Exemplo

​computer_use_screenshot

​Parâmetros

​Quando usar

​Saída

​Exemplo

​list_windows

​Retorna

​Quando o agente chama

​Saída de exemplo (abreviada)

​open_app

​Parâmetros

​Comportamento

​Exemplo

​Ferramentas primitivas no mesmo agente

​Solução de problemas

​Documentação relacionada

Fluxo de trabalho compartilhado

Formatos de ID de janela

Ordem de resolução

Apps bloqueados

Autônomo vs dentro do agente

`read_screen_ax`

Parâmetros

Quando o agente chama

Saída

Exemplo

vs `get_active_app_context`

`perform_sequence`

Parâmetros

Regras de agrupamento

Exemplo

`computer_use_screenshot`

Parâmetros

Quando usar

Saída

Exemplo

`list_windows`

Retorna

Quando o agente chama

Saída de exemplo (abreviada)

`open_app`

Parâmetros

Comportamento

Exemplo

Ferramentas primitivas no mesmo agente

Solução de problemas

Documentação relacionada