Road-Maintenance-Connector

Der Road-Maintenance-Connector überwacht ein Postfach und macht aus den in diesen E-Mails angekündigten Straßenarbeiten Straßensperrungen in Yggio.

Straßenarbeiten werden üblicherweise per E-Mail angekündigt, als genehmigter Verkehrszeichenplan. Die Entscheidung ist bereits gefallen; die E-Mail trägt das Ergebnis und ist zum Lesen durch einen Menschen geschrieben: Freitext, ein Anhang, ein Straßenname, ein Zeitraum. Der Connector ruft das Postfach ab, übergibt jede Nachricht einem LLM zum Lesen und legt aus dem, was das LLM extrahiert, die Straßensperrung an. Niemand muss etwas abtippen.

Wofür die Sperrungen anschließend genutzt werden, einschließlich der Routenführung von Rettungs- und kommunalen Fahrzeugen um sie herum, siehe Straßenhindernisse.

So funktioniert es

1. Der Connector ruft ein Postfach über IMAP in einem von Ihnen gewählten Intervall ab.
2. Eine Nachricht wird nur verarbeitet, wenn ihr Absender auf der Liste der freigegebenen Absender steht. Alles andere wird ignoriert, sodass eine beliebige E-Mail keine Straße sperren kann.
3. Die Nachricht wird an einen KI-Agenten übergeben, einen separaten KI-Connector, der als Parser arbeitet, sie liest und die strukturierten Angaben zurückgibt.
4. Aus dem Ergebnis wird in Yggio eine Straßensperrung angelegt.
5. Navigation in Yggio führt dann darum herum und findet den schnellsten Weg an der Sperrung vorbei, für ein Auto oder einen Lkw.

Bevor Sie beginnen

Sie brauchen einen bereits angelegten KI-Connector vom Typ Agent, denn der Road-Maintenance-Connector wählt bei der Einrichtung einen aus. Ein MCP-Connector erscheint nicht in der Liste: MCP treibt den Chat-Assistenten an, während Agent einen einzelnen LLM-Aufruf mit festem System-Prompt ausführt, und genau das braucht das Auswerten einer E-Mail. Siehe KI-Connector.

Geben Sie diesem Agenten einen System-Prompt, der beschreibt, was aus der E-Mail zu extrahieren ist, und setzen Sie sein Antwortformat auf JSON, damit sich das Ergebnis direkt verwenden lässt.

Sie brauchen außerdem ein Postfach, das der Connector lesen kann, und die Adressen, die daran schreiben dürfen.

Den Connector anlegen

1. Gehen Sie zu Connectors → Neuer Connector → Road Maintenance.
2. Wählen Sie Retention Policy und Flow und fahren Sie fort.
3. Füllen Sie die Angaben zum Connector aus:

Postfach

Feld	Beschreibung
Host	Hostname des IMAP-Servers, zum Beispiel imap.example.com
Port	IMAP-Port, normalerweise 993
Username	Das Postfachkonto
Password	Das Postfachpasswort
TLS	Ob über TLS verbunden wird. Normalerweise true
Poll interval	Wie oft auf neue Post geprüft wird, in Millisekunden. 60000 ist eine Minute

Freigegebene Absender

Eine Liste von E-Mail-Adressen, deren Nachrichten verarbeitet werden. Fügen Sie je Adresse einen Eintrag hinzu.

Halten Sie sie so eng, wie der Betrieb es zulässt. Diese Liste ist die Zugriffssteuerung für die gesamte Funktion: Eine Adresse darauf kann dazu führen, dass eine Straße als gesperrt markiert wird, sie sollte also die Auftragnehmer und Sachbearbeiter enthalten, die Straßenarbeiten ankündigen dürfen, und sonst niemanden.

KI-Agent

Wählen Sie den KI-Connector, der die Nachrichten auswertet. Es werden nur Connectors vom Typ Agent aufgeführt.

Der Agent wird mit der Rolle parser und einem Zweck gespeichert, einer kurzen Beschreibung dessen, wofür er da ist, was hilfreich ist, sobald später mehr als ein Agent beteiligt ist.

4. Bestätigen Sie die Angaben und legen Sie den Connector an.

Beispiel: der Parser-Agent

Dies ist die Agentenkonfiguration aus dem Projekt, für das der Connector gebaut wurde, mit ersetzten Zugangsdaten und Adressen. Betrachten Sie sie als funktionierenden Ausgangspunkt und nicht als Spezifikation: Der Prompt entscheidet, wie gut die E-Mails gelesen werden, und er sollte auf die Dokumente abgestimmt werden, die Ihre Absender tatsächlich schreiben.

Der System-Prompt

Setzen Sie dies als System-Prompt am KI-Connector, mit dem Antwortformat JSON Object und einer niedrigen Temperatur, hier 0.3, denn die Aufgabe ist Extraktion und nicht Formulierung.

Der Prompt ist auf Englisch verfasst und bleibt unübersetzt: Es ist der Text, der an das Modell geht, und ihn zu übersetzen würde ändern, was er bewirkt.

You are an emergency service operator helping fire brigades navigate around road blocks in Sweden. Analyze the road closure information and provide location details and structured query in a format suitable for geocoding. Here is an example for "freeform_query" converted into URI component: encodeURIComponent("Klosterbrunnsgatan, Visby, 111 57, Sweden") "Klosterbrunnsgatan%2C%20Visby%2C%20111%2057%2C%20Sweden". The timings mentioned in the email are in the Europe/Stockholm timezone. Convert these timings to UTC (Coordinated Universal Time) before returning the response. If only dates are specified (e.g., 'Monday 2024.10.28 - Friday 2024.11.22'), interpret them as local dates in the Europe/Stockholm timezone, starting at midnight (00:00) on the start date and ending at 23:59:59 on the end date. Ensure that the 'canPass' attribute in 'emergencyAccess' is set to 'false' if emergency vehicles cannot pass through the road block. Set it to 'true' only under the following conditions: (1) there is explicit information allowing emergency vehicles to pass, or (2) the road block's end time (`endTimeAt`) has already passed, meaning the road block is no longer active (`active`=false). Return a JSON object with a "roadBlocks" using this format: { "roadBlocks": { "connectorId": "TBU","userId": "TBU", "roadLocation": [{ "name": "TBU", "tag": "TBU", "active": boolean, "startTimeAt": "YYYY-MM-DDTHH:mm:ssZ", "endTimeAt": "YYYY-MM-DDTHH:mm:ssZ", "reportedAt": "YYYY-MM-DDTHH:mm:ssZ" (copy of startTimeAt), "roadBlockage": string, "lnglat": { "type": "Point", "coordinates": [number, number] ([lon, lat] points) }, "roadName": string, "roadSection": string, "city": string, "restrictionType": string, "emergencyAccess": { "canPass": boolean, "instructions": string, "alternativeRoutes": [{ "description": string, "path": { "type": "LineString", "coordinates": [[number, number]] (array of [lon, lat] points) }, "estimatedTime": string (e.g. "5 min"), "restrictions": string[] }], "osmDetails": { "wayIds": string[], "nodeIds": string[], "boundingBox": { "north": number, "south": number, "east": number, "west": number }, "overpassQuery": string } }, "location": { "structured": { "street": string, "city": string, "county": string, "state": string, "country": "Sweden", "postalcode": string, "amenity": string }, "freeform": string }, "freeformQuery": string }], "email": { "subject": string, "sender": string, "receivedAt": "YYYY-MM-DDTHH:mm:ssZ", "text": string } } } Respond with only this JSON object. Do not include any explanatory text, preamble, or markdown code fences; the output must start with { and end with } and be valid JSON.

Was der Prompt leistet

Fünf Aufgaben, jede aus einem Grund:

• Die Rolle setzen. Er nennt den Einsatzkontext vorweg, was alles Folgende verankert.
• Eine geokodierbare Adresse erzeugen. Die E-Mail nennt eine Straße; die Routing-Engine braucht Koordinaten. Der Prompt verlangt eine freeformQuery in einer Form, die ein Geokodierer annimmt, mit einem durchgearbeiteten Beispiel der URI-Kodierung.
• Die Zeitzone klären. Die E-Mails sind in Ortszeit verfasst, die Plattform speichert UTC. Der Prompt benennt die Ausgangszone und legt fest, was ein bloßer Datumsbereich bedeutet, Mitternacht bis 23:59:59, damit eine ganztägige Sperrung nicht als einzelner Zeitpunkt gelesen wird.
• Über die Rettungszufahrt entscheiden. canPass ist standardmäßig false und darf nur aus genannten Gründen true sein: ausdrückliche Erlaubnis in der E-Mail oder eine Sperrung, deren Endzeit verstrichen ist. Dass ein Parser das falsch rät, ist der Fehler, der am schwersten wiegt, deshalb ist die Regel als Positivliste formuliert.
• Die Ausgabeform festlegen. Die JSON-Struktur ist vollständig angegeben und endet mit der Anweisung, genau dieses Objekt und sonst nichts zurückzugeben.

Warum die Nur-JSON-Anweisung wichtig ist

Sie erlaubt es, denselben Prompt bei beiden Anbietern zu verwenden. OpenAI hat einen nativen JSON-Modus, dort ist die Anweisung doppelt gemoppelt. Anthropic hat keinen solchen Modus, und das JSON wird durch Auswerten des Modelltextes gewonnen: Ein Code-Fence und umgebende Leerzeichen werden toleriert, aber Fließtext um das JSON herum lässt das Auswerten scheitern. Genau das verhindert die Anweisung.

Für einen Anbieterwechsel ändern Sie Anbieter und Modell-ID und lassen alles andere unverändert.

Überprüfen

1. Senden Sie eine Testnachricht an das Postfach, von einer Adresse auf der Liste der freigegebenen Absender.
2. Warten Sie ein Abrufintervall ab.
3. Prüfen Sie, dass in Yggio ein Straßensperrungsgerät mit den Angaben aus der Nachricht erscheint.
4. Senden Sie eine Nachricht von einer Adresse, die nicht auf der Liste steht, und bestätigen Sie, dass nichts angelegt wird.

Fehlerbehebung

Es passiert überhaupt nichts. Prüfen Sie die IMAP-Zugangsdaten und ob Port und TLS-Einstellung dem entsprechen, was der Mail-Anbieter erwartet. Viele Anbieter verlangen zudem ein App-Passwort statt des Kontopassworts.

Manche E-Mails werden verarbeitet, andere nicht. Prüfen Sie den Absender gegen die Liste der freigegebenen Absender. Eine Adresse, die sich nur durch ein Alias oder eine Subdomain unterscheidet, passt nicht.

Straßensperrungen entstehen mit falschen oder fehlenden Angaben. Das liegt am Prompt des Agenten, nicht am Connector. Verfeinern Sie den System-Prompt am KI-Connector und bestätigen Sie, dass sein Antwortformat JSON ist.