Référence des outils agent - Alter Documentation

Ces outils sont enregistrés pour le subagent Computer Use d’Alter (computer_use_task). Ils sont réservés au LLM — conçus pour que le modèle les appelle pendant une boucle UI en arrière-plan, pas pour une exécution manuelle ponctuelle dans la plupart des cas. Le subagent reçoit aussi les outils primitifs Perform, Scroll et Wait. Cette page couvre les outils spécifiques à l’agent et les règles partagées de ciblage de fenêtre.

Commencer ici

Lisez l’aperçu Computer Use pour invoquer l’agent avec une chaîne goal.

Workflow partagé

Formats d’ID de fenêtre

list_windows renvoie deux styles d’ID :

Format	Exemple	Notes
`pid/title`	`4280/Mail — Inbox`	Lisible ; le titre peut changer
`pid/windowNumber` stable	`4280/12345`	Préféré quand disponible — survit aux changements de titre

Passez le même windowID à read_screen_ax, perform, perform_sequence, scroll et computer_use_screenshot à chaque étape sur cette fenêtre.

Ordre de résolution

Quand windowID est omis :

windowID explicite dans l’appel d’outil
Cible suivie — fenêtre enregistrée par open_app, open_urls ou des outils antérieurs dans cette conversation
Repli de session — pendant une exécution en arrière-plan, la fenêtre affichée dans l’aperçu en direct (évite la dérive quand vous refocalisez une autre app)
Fenêtre au premier plan

Apps bloquées

Computer Use refuse d’ouvrir, lire ou contrôler les apps de votre liste de blocage (Settings → Computer use → Blocked apps). Les gestionnaires de mots de passe sont bloqués par défaut. Les outils renvoient une erreur claire pour que l’agent arrête de boucler et vous signale le blocage.

Autonome vs dans l’agent

Contexte	Disponible ?
Dans le subagent `computer_use_task`	Oui — ensemble complet ci-dessous
Agent parent Ask Anything	Indirectement — le parent doit appeler `computer_use_task`, pas enchaîner ces outils manuellement
Exécution manuelle Tools Manager	Possible pour le débogage ; ce n’est pas le workflow principal

Les outils workspace (workspace_read, workspace_bash, etc.) ne sont pas disponibles dans Computer Use.

`read_screen_ax`

Nom d’affichage : Read Screen (AX) Renvoie l’arbre d’accessibilité d’une fenêtre sous forme de texte. Les éléments interactifs incluent un suffixe @elementID pour perform et perform_sequence. Pas de capture d’écran ni d’analyse visuelle — strictement AX uniquement.

Paramètres

Paramètre	Requis	Par défaut	Description
`windowID`	Non	suivi → repli session → premier plan	`pid/title` ou `pid/windowNumber` stable

Quand l’agent l’appelle

Première étape sur une fenêtre (avant tout clic ou remplissage)
Après navigation, dialogues, défilement ou raccourcis qui modifient l’UI
Avant de choisir des options combobox/liste qui n’étaient pas visibles lors de la lecture précédente

Sortie

Enveloppé dans <activeAppContext>…</activeAppContext>. Pendant les exécutions Computer Use, les apps correspondantes peuvent ajouter <appGuidance> (Calculator, Discord, Spotify, X.com, etc.) avec des techniques plus rapides.

Exemple

Étape d’objectif : l’agent a déjà ouvert Mail via open_app et reçu windowID: 5123/Mail — Inbox.

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

Renvoie des lignes avec des IDs d’élément comme Unread message row 1@MessageRow_0 pour les clics perform suivants.

vs `get_active_app_context`

Get Active App Context ajoute de l’OCR depuis des captures d’écran. L’agent Computer Use préfère read_screen_ax pour la vitesse et la confidentialité, sauf si l’objectif exige une capture visuelle via computer_use_screenshot.

`perform_sequence`

Nom d’affichage : Perform Sequence Exécute plusieurs actions UI en un seul appel d’outil — plus rapide que des invocations perform séparées quand tous les éléments cibles sont déjà visibles dans la lecture AX actuelle.

Paramètres

Paramètre	Requis	Description
`steps`	Oui	Tableau d’objets d’action (voir ci-dessous)
`windowID`	Non	Appliqué à chaque étape

Chaque objet step :

Champ	Requis pour	Description
`action`	—	`click` (par défaut), `fill`, `type` ou `shortcut`
`elementID`	`click`, `fill`	ID après `@` depuis `read_screen_ax`
`text`	`fill`, `type`	Texte à saisir
`shortcut`	`shortcut`	p. ex. `cmd+k`, `escape`, `shift+enter`

Règles de regroupement

Toutes les valeurs elementID doivent provenir du même résultat read_screen_ax
Ne regroupez que les actions qui ne changent pas la mise en page entre les étapes (formulaire multi-champs, expression calculatrice via type)
Arrêtez le regroupement avant navigation, changement d’app ou ouverture de menus/dialogues — puis relisez
L’exécution s’arrête à la première étape en échec et indique quelle étape a échoué

Exemple

Remplir un formulaire à trois champs visible en une lecture :

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

Recherche rapide Spotify (après lecture de la fenêtre principale) :

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

Voir Perform pour la sémantique d’action unique (type vs fill, format de raccourci).

`computer_use_screenshot`

Nom d’affichage : Computer Use Screenshot Capture une fenêtre d’app spécifique en PNG. N’utilise pas les raccourcis globaux de capture, screencapture ni la sélection interactive de région.

Paramètres

Paramètre	Requis	Description
`windowID`	Non	Même ordre de résolution que les autres outils

Quand l’utiliser

L’objectif demande explicitement des captures d’écran ou des artefacts visuels
À éviter pour l’inspection UI courante — utilisez read_screen_ax à la place

Sortie

Métadonnées texte (app, title, windowID, dimensions) plus une pièce jointe image pour le modèle.

Exemple

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

Échoue si l’autorisation Screen Recording est absente ou si la fenêtre est minimisée/masquée.

`list_windows`

Nom d’affichage : List Windows Énumère les fenêtres ouvertes des applications en cours d’exécution. Aucun paramètre.

Renvoie

Pour chaque fenêtre :

Nom de l’app et identifiant de bundle
Titre de la fenêtre
Window ID (pid/title)
Stable Window ID quand disponible
PID
Marqueur ⭐ (ACTIVE) sur la fenêtre au premier plan

Quand l’agent l’appelle

La fenêtre cible n’est pas l’app au premier plan et n’a pas été ouverte via open_app / open_urls dans cette exécution
Une fois par exécution suffit en général — réutilisez les IDs renvoyés au lieu de lister à répétition

Exemple de sortie (abrégé)

Open Windows (42 total):

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

L’agent passe ensuite 4280/87 à read_screen_ax pour un scrape en arrière-plan pendant que vous travaillez dans une autre app.

`open_app`

Nom d’affichage : Open Application Lance ou met au premier plan une application Mac. Renvoie l’ID de fenêtre cible pour un suivi immédiat — souvent sans appeler list_windows.

Paramètres

Paramètre	Requis	Description
`bundleId`	Oui	Identifiant de bundle (p. ex. `com.apple.Calculator`) ou nom d’app lisible (`Calculator`, `Google Chrome`) — les noms sont résolus automatiquement

Comportement

Exécutions en arrière-plan : Si l’app est déjà lancée, Alter ne vole pas le focus. Les nouveaux lancements utilisent une ouverture non activante quand c’est possible et restaurent votre app au premier plan précédente.
Apps bloquées : Refusées avec erreur de liste de blocage
La réponse de succès inclut Window ID et Stable Window ID optionnel à passer aux outils suivants

Exemple

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

La réponse inclut :

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

Outils primitifs dans le même agent

Ceux-ci ont des pages dédiées ; le subagent les utilise avec les mêmes règles windowID :

Outil	Page	Notes agent
`perform`	Perform	Clic/remplissage/type/raccourci unique ; préférez `perform_sequence` pour le regroupement
`scroll`	Scroll	Durée `milliseconds` (par défaut 3000) ; Chromium/Safari utilisent le défilement clavier en arrière-plan
`wait`	Wait	À utiliser quand la lecture AX est vide ou en chargement — pas avant chaque étape
`open_urls`	—	Ouvre des URL ; routé vers le navigateur agent pendant Computer Use

get_active_app_context n’est pas dans l’ensemble d’outils du subagent — utilisez read_screen_ax à la place.

Dépannage

Problème	Conseil
`Window … not found`	Relancez `list_windows` ; la fenêtre a peut-être été fermée
Échecs `elementID` après regroupement	Mise en page modifiée — relisez avec `read_screen_ax`
App bloquée	Ajustez la liste de blocage ou reformulez l’objectif pour ignorer cette app
Capture échouée	Accordez Screen Recording ; assurez-vous que la fenêtre est visible
Raccourcis globaux ignorés	Attendu en mode arrière-plan — l’agent utilise `fill`/`type`, pas ⌘C/⌘V

Commencer ici

​Workflow partagé

​Formats d’ID de fenêtre

​Ordre de résolution

​Apps bloquées

​Autonome vs dans l’agent

​read_screen_ax

​Paramètres

​Quand l’agent l’appelle

​Sortie

​Exemple

​vs get_active_app_context

​perform_sequence

​Paramètres

​Règles de regroupement

​Exemple

​computer_use_screenshot

​Paramètres

​Quand l’utiliser

​Sortie

​Exemple

​list_windows

​Renvoie

​Quand l’agent l’appelle

​Exemple de sortie (abrégé)

​open_app

​Paramètres

​Comportement

​Exemple

​Outils primitifs dans le même agent

​Dépannage

​Docs associées

Workflow partagé

Formats d’ID de fenêtre

Ordre de résolution

Apps bloquées

Autonome vs dans l’agent

`read_screen_ax`

Paramètres

Quand l’agent l’appelle

Sortie

Exemple

vs `get_active_app_context`

`perform_sequence`

Paramètres

Règles de regroupement

Exemple

`computer_use_screenshot`

Paramètres

Quand l’utiliser

Sortie

Exemple

`list_windows`

Renvoie

Quand l’agent l’appelle

Exemple de sortie (abrégé)

`open_app`

Paramètres

Comportement

Exemple

Outils primitifs dans le même agent

Dépannage

Docs associées