Agent-Integrationsleitfaden

Überblick

Dieser Leitfaden erklärt, wie ein LLM-basierter Agent UIAP nutzt, um eine Web-Anwendung zu verstehen und mit ihr zu interagieren. UIAP liefert dem Agenten strukturierten Kontext statt rohem HTML oder Screenshots.

Was der Agent erhält

1. Capabilities

Nach der Session-Initialisierung erhält der Agent ein Capability-Dokument mit:

• Verfügbare UI-Rollen und Zustände
• Registrierte Actions mit Risk-Levels
• Success-Signal-Typen
• Unterstützte Ausführungsmodi

2. Page Snapshots

Der PageGraph ist eine strukturierte Repräsentation des aktuellen Seitenzustands:

{
  "route": { "routeId": "videos.list", "url": "/videos" },
  "documents": [{
    "scopes": [{
      "id": "video.list",
      "kind": "list",
      "elements": [
        {
          "stableId": "video.new",
          "role": "button",
          "name": "Neues Video",
          "affordances": ["activatable"],
          "state": { "enabled": true, "visible": true },
          "defaultAction": "video.create"
        }
      ]
    }]
  }]
}

3. Deltas

Nach jeder Aktion oder Zustandsänderung erhält der Agent inkrementelle Updates statt voller Snapshots.

Agent-Loop

Ein typischer Agent-Loop folgt diesem Muster:

1. Snapshot/Delta empfangen
2. Aktuellen Zustand verstehen
3. Nächste Aktion basierend auf Ziel planen
4. action.request senden
5. Auf action.result warten
6. Erfolg über Signale verifizieren
7. Wiederholen oder abschliessen

Ausführungsmodi

UIAP unterstützt mehrere Ausführungsstrategien, in Präferenzreihenfolge:

1. appAction — Die App führt ihre eigene Geschäftslogik direkt aus
2. semanticDom — Das SDK interagiert mit DOM-Elementen über semantische Identität
3. browserInput — Low-Level Input-Simulation (Click, Type)
4. webdriver — Externe Browser-Automation (Fallback)
5. vision — Screenshot-basierte Interaktion (letzter Ausweg)

Der Agent sollte höherstufige Modi bevorzugen. UIAPs Design-Prinzip: DOM-first, Vision-second, Computer-Use-last-resort.

Policy-Awareness

Vor der Ausführung jeder Aktion muss der Agent die Policy-Antwort respektieren:

• allow — Fortfahren
• confirm — Zuerst Benutzerbestätigung einholen
• deny — Aktion ist nicht erlaubt
• handoff — Mensch muss diesen Schritt manuell ausführen

Erfolgsverifikation

Nach der Ausführung einer Aktion verifiziert der Agent den Erfolg über Signale:

success: [
  { kind: "route.changed", pattern: "/videos/:id" },
  { kind: "toast.contains", text: "erstellt" }
]

Das macht Agent-Verhalten deterministisch und verifizierbar, nicht nur “es sah so aus, als hätte es funktioniert.”