Einen gehosteten ScanKit-Scanner mit Hermes Agent verbinden

Dokument-Workflows starten normalerweise mit einer Datei, die bereits irgendwo gelandet ist: einer E-Mail, einem Formular oder einem geteilten Laufwerk. Dieser Beitrag zeigt ein anderes Muster: Der Workflow startet in dem Moment, in dem jemand ein Dokument fotografiert, direkt aus dem Handy-Browser, ganz ohne App-Installation.

Sie verbinden einen ScanKit-Hosted-Scanner mit Hermes Agent, sodass jeder Scan automatisch einen Agent-Lauf auslöst, der das Dokument verarbeitet.

Was Sie bauen werden

Ein Kamera-Scanner, der:

• Direkt im Smartphone-Browser funktioniert (keine App nötig)
• Das Dokument automatisch erkennt, zuschneidet und bereinigt
• Den fertigen Scan (PDF mit eingebetteter OCR-Textebene) an einen Webhook sendet
• Einen Hermes-Agent-Lauf startet, der die Datei herunterlädt und verarbeitet

Am Ende haben Sie einen funktionierenden Eingangsworkflow: Foto rein, verarbeitetes Ergebnis aus Ihrer Agent-Pipeline raus.

Wie die Teile zusammenspielen

Handykamera → ScanKit-Hosted-Scanner → Webhook → Hermes Agent → Ihre Verarbeitung

Der Scanner übernimmt den mühsamen Teil (Perspektivkorrektur, Zuschnitt, Bereinigung, PDF-Erzeugung). Hermes Agent übernimmt den intelligenten Teil (Dokument lesen, Felder extrahieren, Folgeaktionen auslösen).

Voraussetzungen

• Ein ScanKit.io-Konto (der kostenlose Tarif reicht)
• Eine Hermes-Agent-Installation (eine Maschine, die aus dem Internet erreichbar ist, oder ein Tunnel)
• Etwa 10 Minuten

---

Schritt 1: Ihren Hosted-Scanner erstellen

Gehen Sie zum ScanKit-Dashboard und öffnen Sie Instant Scanners.

1. Klicken Sie auf Neuen Scanner erstellen und nennen Sie ihn z.B. Document Intake
2. Wählen Sie eine Markenfarbe und laden Sie bei Bedarf ein Logo hoch
3. Lassen Sie das Webhook-URL-Feld vorerst leer
4. Klicken Sie auf Erstellen

Ihr Scanner bekommt einen teilbaren Link und einen QR-Code. Öffnen Sie ihn einmal auf Ihrem Handy, um zu bestätigen, dass der Erfassungsablauf funktioniert. Er scannt, schneidet zu und bereinigt Dokumente, dann bietet er das Ergebnis als PDF mit eingebetteter OCR-Textebene an.

---

Schritt 2: Einen Webhook-Endpunkt in Hermes Agent erstellen

Hermes Agent kann eingehende Webhooks nativ empfangen. Der Endpunkt ist ein Abonnement unter der Webhook-Plattform.

1. Stellen Sie sicher, dass die Webhook-Plattform in ~/.hermes/config.yaml aktiviert ist:

platforms:
  webhook:
    enabled: true
    extra:
      host: "127.0.0.1"
      port: 8644
      secret: "<your-hmac-secret>"

2. Abonnieren Sie eine Route für Scanner-Uploads:

hermes webhook subscribe scan-intake \
  --prompt "A scan from scanner {scanner_name} just arrived. Open the uploaded file, extract the text, and summarize it." \
  --skills "ocr-and-documents" \
  --deliver log

3. Prüfen Sie, ob die Route antwortet:

curl http://127.0.0.1:8644/health
# {"status":"ok"}

Das Abonnement validiert Anfragen mit einer HMAC-Signatur. Da der ScanKit-Hosted-Scanner nur eine URL senden kann (kein benutzerdefiniertes Header-Feld), verwenden Sie das URL-als-Geheimnis-Muster: Abonnieren Sie mit --secret INSECURE_NO_AUTH und geben Sie der Route einen unerratbaren Namen. Die vollständige URL ist dann die Zugangsberechtigung, halten Sie sie also privat.

---

Schritt 3: Den Endpunkt erreichbar machen

Wenn Ihre Hermes-Agent-Installation hinter NAT läuft, machen Sie den Loopback-Endpunkt mit einem Tunnel erreichbar:

cloudflared tunnel --url http://127.0.0.1:8644

Das Protokoll druckt eine öffentliche URL wie https://<random>.trycloudflare.com. Verifizieren Sie sie:

curl https://<random>.trycloudflare.com/health
# {"status":"ok"}

Für den Produktionsbetrieb verwenden Sie einen benannten Tunnel oder einen festen Hostnamen, weil Quick-Tunnel-URLs bei jedem Neustart wechseln.

---

Schritt 4: Den Scanner mit dem Webhook verbinden

Zurück im ScanKit-Dashboard:

1. Öffnen Sie Ihren Scanner
2. Fügen Sie im Feld Webhook URL die vollständige öffentliche Webhook-URL ein (einschließlich /webhooks/<route>)
3. Klicken Sie auf Aktualisieren

Ihr Scanner ist jetzt mit dem Agent-Endpunkt verknüpft.

---

Was der Webhook empfängt

Wenn ein Scan abgeschlossen ist, sendet der Hosted-Scanner das Ergebnis als multipart/form-data mit zwei Teilen an Ihre Webhook-URL:

Teil	Inhalt
file	Der Scan als PDF (mit eingebetteter OCR-Textebene) oder JPEG
metadata	Ein JSON-Blob mit scanner_id, scanner_name, page_count, timestamp

Beispiel-Metadaten:

{
  "scanner_id": 123,
  "scanner_name": "Document Intake",
  "page_count": 1,
  "timestamp": "2026-09-01T00:00:00.000Z"
}

In Hermes werden die Prompt-Platzhalter aus der obersten JSON-Ebene aufgelöst. {scanner_name} und {page_count} funktionieren daher direkt in Ihrem Abonnement-Prompt. {__raw__} gibt den gesamten Payload aus, und die Datei selbst wird vom Adapter im Posteingang gespeichert, sodass Ihr Agent-Lauf sie mit den Datei-Werkzeugen öffnen kann.

Wenn Sie keinen ScanKit-Scanner verwenden und dieselbe Route selbst mit POST ansprechen, gilt dieselbe Struktur: ein file-Teil plus ein metadata-JSON-Teil.

---

Minimales Handler-Beispiel

Ein Abonnement-Prompt, der den Scan liest und ablegt:

hermes webhook subscribe scan-intake \
  --prompt "A document scan from scanner {scanner_name} ({page_count} page(s)) just arrived. \
Open the uploaded file, extract its text, save a summary next to it, and reply with a one-line confirmation." \
  --skills "ocr-and-documents" \
  --deliver log

Der Webhook-Agent erhält den Dateipfad und die Metadaten automatisch; er muss den Multipart-Body nicht selbst parsen.

---

Was Sie darauf aufbauen können

Sobald der Scan in Ihrer Agent-Pipeline landet, gilt dasselbe Muster wie bei jeder webhook-getriggerten Automatisierung:

• Rechnungen: Lieferant, Betrag und Datum extrahieren, dann an die Buchhaltung übergeben
• Lieferscheine: Das PDF lesen, die Bestellung abgleichen, den Empfänger benachrichtigen
• Formulare: Die Felder in ein CRM oder eine Datenbank übernehmen
• Verträge: Klassifizieren und zusammenfassen, dann in einen Dokumentenspeicher ablegen

Der Hosted-Scanner beseitigt die Erfassungs-Reibung; der Agent erledigt den Rest. Kein App-Store, keine Plugins, kein OCR-Klebecode.

Ein Hinweis zu Dokumentdaten

Scans sind sensibel. Die ScanKit-Pipeline verarbeitet das Bild und liefert einen sauberen Scan; das Dokument muss für die Verarbeitung die EU nicht verlassen. Ihr Webhook sollte HTTPS verwenden, und das Muster mit der unerratbaren URL bedeutet, dass der Endpunkt selbst das Geheimnis ist. Rotieren Sie ihn, falls er durchsickert.

---

Das Fazit: Ein Handy-Foto wird in Sekunden zu einem verarbeiteten Workflow-Eingang, ohne App und ohne Infrastruktur über ein einziges Webhook-Abonnement hinaus. Probieren Sie es mit einem kostenlosen ScanKit-Konto.

Fragen oder Feedback? Schreiben Sie uns auf X oder per E-Mail.