Referenz Agent-Tools - Alter Documentation

Diese Tools sind für Alters Computer Use-Subagenten (computer_use_task) registriert. Sie sind nur für LLM — für Modellaufrufe in einer Hintergrund-UI-Schleife, nicht für manuelle Einzelausführung in den meisten Fällen. Der Subagent erhält auch die primitiven Tools Perform, Scroll und Wait. Diese Seite behandelt die agentspezifischen Tools und gemeinsame Fenster-Zielregeln.

Hier starten

Lesen Sie die Computer-Use-Übersicht, um den Agenten mit einem goal-String aufzurufen.

Gemeinsamer Workflow

Window-ID-Formate

list_windows liefert zwei ID-Stile:

Format	Beispiel	Hinweise
`pid/title`	`4280/Mail — Inbox`	Lesbar; Titel kann sich ändern
Stabile `pid/windowNumber`	`4280/12345`	Bevorzugt wenn verfügbar — überlebt Titeländerungen

Übergeben Sie dieselbe windowID an read_screen_ax, perform, perform_sequence, scroll und computer_use_screenshot für jeden Schritt auf diesem Fenster.

Auflösungsreihenfolge

Wenn windowID weggelassen wird:

Explizite windowID im Tool-Aufruf
Verfolgtes Ziel — Fenster, das von open_app, open_urls oder vorherigen Tools in dieser Konversation aufgezeichnet wurde
Sitzungs-Fallback — während eines Hintergrundlaufs das Fenster in der Live-Vorschau (verhindert Drift, wenn Sie eine andere App fokussieren)
Vorderstes Fenster

Blockierte Apps

Computer Use verweigert das Öffnen, Lesen oder Steuern von Apps auf Ihrer Blockliste (Einstellungen → Computer use → Blocked apps). Passwortmanager sind standardmäßig blockiert. Tools liefern einen klaren Fehler, damit der Agent stoppt und die Blockierung meldet.

Standalone vs. im Agenten

Kontext	Verfügbar?
Im `computer_use_task`-Subagenten	Ja — vollständiger Satz unten
Ask-Anything-Parent-Agent	Indirekt — Parent soll `computer_use_task` aufrufen, nicht diese manuell ketten
Tools Manager manueller Lauf	Möglich zum Debuggen; nicht der primäre Workflow

Workspace-Tools (workspace_read, workspace_bash usw.) sind nicht in Computer Use verfügbar.

`read_screen_ax`

Anzeigename: Read Screen (AX) Gibt den Accessibility-Baum eines Fensters als Text zurück. Interaktive Elemente enthalten ein @elementID-Suffix für perform und perform_sequence. Kein Screenshot und keine Bildanalyse — strikt nur AX.

Parameter

Parameter	Erforderlich	Standard	Beschreibung
`windowID`	Nein	verfolgt → Sitzungs-Fallback → vorderstes	`pid/title` oder stabile `pid/windowNumber`

Wann der Agent es aufruft

Erster Schritt auf einem Fenster (vor jedem Klick oder Fill)
Nach Navigation, Dialogen, Scrollen oder Shortcuts, die die UI ändern
Vor der Auswahl von Combobox-/Listenoptionen, die im vorherigen Read nicht sichtbar waren

Ausgabe

Eingewickelt in <activeAppContext>…</activeAppContext>. Während Computer-Use-Läufen können passende Apps <appGuidance> anhängen (Calculator, Discord, Spotify, X.com usw.) mit schnelleren Techniken.

Beispiel

Zielschritt: Agent hat Mail bereits via open_app geöffnet und windowID: 5123/Mail — Inbox erhalten.

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

Liefert Zeilen mit Element-IDs wie Unread message row 1@MessageRow_0 für nachfolgende perform-Klicks.

vs. `get_active_app_context`

Get Active App Context fügt OCR aus Screenshots hinzu. Der Computer-Use-Agent bevorzugt read_screen_ax für Geschwindigkeit und Datenschutz, es sei denn, das Ziel erfordert visuelle Erfassung via computer_use_screenshot.

`perform_sequence`

Anzeigename: Perform Sequence Führt mehrere UI-Aktionen in einem Tool-Aufruf aus — schneller als separate perform-Aufrufe, wenn alle Zielelemente im aktuellen AX-Read sichtbar sind.

Parameter

Parameter	Erforderlich	Beschreibung
`steps`	Ja	Array von Aktionsobjekten (siehe unten)
`windowID`	Nein	Gilt für jeden Schritt

Jedes step-Objekt:

Feld	Erforderlich für	Beschreibung
`action`	—	`click` (Standard), `fill`, `type` oder `shortcut`
`elementID`	`click`, `fill`	ID nach `@` aus `read_screen_ax`
`text`	`fill`, `type`	Einzufügender Text
`shortcut`	`shortcut`	z. B. `cmd+k`, `escape`, `shift+enter`

Batching-Regeln

Alle elementID-Werte müssen aus dem selben read_screen_ax-Ergebnis stammen
Nur Aktionen batchen, die das Layout zwischen Schritten nicht ändern (Mehrfeld-Formular, Taschenrechnerausdruck via type)
Batching stoppen vor Navigation, App-Wechsel oder Menüs/Dialogen — dann neu lesen
Ausführung stoppt beim ersten fehlgeschlagenen Schritt und meldet, welcher Schritt fehlschlug

Beispiel

Dreifeld-Formular aus einem Read ausfüllen:

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

Spotify-Schnellsuche (nach Read des Hauptfensters):

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

Siehe Perform für Einzelaktions-Semantik (type vs. fill, Shortcut-Format).

`computer_use_screenshot`

Anzeigename: Computer Use Screenshot Erfasst ein bestimmtes App-Fenster als PNG. Nutzt keine globalen Screenshot-Shortcuts, screencapture oder interaktive Bereichsauswahl.

Parameter

Parameter	Erforderlich	Beschreibung
`windowID`	Nein	Gleiche Auflösungsreihenfolge wie bei anderen Tools

Wann nutzen

Ziel verlangt ausdrücklich Screenshots oder visuelle Artefakte
Vermeiden für routinemäßige UI-Inspektion — nutzen Sie read_screen_ax

Ausgabe

Text-Metadaten (app, title, windowID, Abmessungen) plus Bildanhang für das Modell.

Beispiel

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

Schlägt fehl, wenn die Bildschirmaufnahme-Berechtigung fehlt oder das Fenster minimiert/verborgen ist.

`list_windows`

Anzeigename: List Windows Listet offene Fenster laufender Anwendungen auf. Keine Parameter.

Rückgabe

Pro Fenster:

App-Name und Bundle-ID
Fenstertitel
Window ID (pid/title)
Stable Window ID wenn verfügbar
PID
⭐ (ACTIVE)-Marker am vordersten Fenster

Wann der Agent es aufruft

Zielfenster ist nicht die vorderste App und wurde in diesem Lauf nicht via open_app / open_urls geöffnet
Einmal pro Lauf reicht meist — zurückgegebene IDs wiederverwenden statt wiederholt zu listen

Beispielausgabe (gekürzt)

Open Windows (42 total):

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

Der Agent übergibt dann 4280/87 an read_screen_ax für ein Hintergrund-Scrape, während Sie in einer anderen App arbeiten.

`open_app`

Anzeigename: Open Application Startet oder fokussiert eine Mac-App. Liefert die Ziel-Window-ID für sofortige Folgeschritte — oft ohne list_windows.

Parameter

Parameter	Erforderlich	Beschreibung
`bundleId`	Ja	Bundle-ID (z. B. `com.apple.Calculator`) oder App-Name (`Calculator`, `Google Chrome`) — Namen werden automatisch aufgelöst

Verhalten

Hintergrundläufe: Wenn die App bereits läuft, stiehlt Alter keinen Fokus. Neue Starts nutzen wenn möglich nicht-aktivierendes Öffnen und stellen die vorherige Vordergrund-App wieder her.
Blockierte Apps: Mit Blocklisten-Fehler abgelehnt
Erfolgsantwort enthält Window ID und optionale Stable Window ID für nachfolgende Tools

Beispiel

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

Antwort enthält:

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

Primitive Tools im selben Agenten

Diese haben eigene Seiten; der Subagent nutzt sie mit denselben windowID-Regeln:

Tool	Seite	Agent-Hinweise
`perform`	Perform	Einzelner Klick/Fill/Type/Shortcut; `perform_sequence` beim Batching bevorzugen
`scroll`	Scroll	`milliseconds`-Dauer (Standard 3000); Chromium/Safari nutzen Tastatur-Scroll im Hintergrund
`wait`	Wait	Wenn AX-Read leer oder lädt — nicht vor jedem Schritt
`open_urls`	—	Öffnet URLs; während Computer Use an Agent-Browser geroutet

get_active_app_context ist nicht im Subagent-Toolset — nutzen Sie read_screen_ax.

Fehlerbehebung

Problem	Hinweis
`Window … not found`	`list_windows` erneut ausführen; Fenster wurde möglicherweise geschlossen
`elementID`-Fehler nach Batch	Layout geändert — mit `read_screen_ax` neu lesen
Blockierte App	Blockliste anpassen oder Ziel umformulieren
Screenshot fehlgeschlagen	Bildschirmaufnahme gewähren; Fenster sichtbar halten
Globale Shortcuts ignoriert	Erwartet im Hintergrundmodus — Agent nutzt `fill`/`type`, nicht ⌘C/⌘V

Hier starten

​Gemeinsamer Workflow

​Window-ID-Formate

​Auflösungsreihenfolge

​Blockierte Apps

​Standalone vs. im Agenten

​read_screen_ax

​Parameter

​Wann der Agent es aufruft

​Ausgabe

​Beispiel

​vs. get_active_app_context

​perform_sequence

​Parameter

​Batching-Regeln

​Beispiel

​computer_use_screenshot

​Parameter

​Wann nutzen

​Ausgabe

​Beispiel

​list_windows

​Rückgabe

​Wann der Agent es aufruft

​Beispielausgabe (gekürzt)

​open_app

​Parameter

​Verhalten

​Beispiel

​Primitive Tools im selben Agenten

​Fehlerbehebung

​Verwandte Docs

Gemeinsamer Workflow

Window-ID-Formate

Auflösungsreihenfolge

Blockierte Apps

Standalone vs. im Agenten

`read_screen_ax`

Parameter

Wann der Agent es aufruft

Ausgabe

Beispiel

vs. `get_active_app_context`

`perform_sequence`

Parameter

Batching-Regeln

Beispiel

`computer_use_screenshot`

Parameter

Wann nutzen

Ausgabe

Beispiel

`list_windows`

Rückgabe

Wann der Agent es aufruft

Beispielausgabe (gekürzt)

`open_app`

Parameter

Verhalten

Beispiel

Primitive Tools im selben Agenten

Fehlerbehebung

Verwandte Docs