Scheduled Tasks

Tool-Aufrufe, die automatisch in festen Intervallen laufen.

Ein Scheduled Task ist eine Tool-Ausführung ohne Benutzer. Du konfigurierst, welches Tool wann mit welchen Args laufen soll — die Plattform tut es dann in der Wiederholfrequenz automatisch.

#Wofür?

Klassiker:

• Jede Nacht neue E-Mails aus der Mailbox klassifizieren
• Alle 10 Minuten neue Bestellungen prüfen und bei bestimmten Kriterien auslösen
• Wöchentlich einen Report bauen und per E-Mail versenden
• Alle 2 Stunden OAuth-Tokens refreshen, die sonst ablaufen würden

#Datei

In deinem Workspace scheduled.php:

<?php
return [
    'scheduled' => [
        'process_new_orders' => [
            'enabled' => true,
            'tool' => 'processNewOrders',
            'interval' => '5min',
            'args' => ['dryRun' => false],
        ],

        'daily_report' => [
            'enabled' => true,
            'tool' => 'sendDailyReport',
            'at_time' => '09:00',
            'args' => ['recipients' => ['chef@kunde.de']],
        ],

        'refresh_tokens' => [
            'enabled' => true,
            'tool' => 'refreshAllOauthTokens',
            'interval' => '2h',
        ],
    ],
];

#Felder

Entweder interval oder at_time angeben.

#Intervall-Syntax (interval)

Periodische Wiederholung:

Intervalle laufen ab dem Zeitpunkt, an dem der Task zum ersten Mal getriggert wurde.

#Uhrzeit-Syntax (at_time)

Für täglich wiederkehrende Läufe zu einer festen Uhrzeit:

'at_time' => '09:00',     // jeden Morgen um 9 Uhr
'at_time' => '03:30',     // jede Nacht um 3:30

Zeiten beziehen sich auf die Serverzeit (typisch Europe/Berlin — beim Betreiber prüfen).

#Tool-Anforderungen

Das aufgerufene Tool …

• … muss Handler-basiert oder API-basiert definiert sein (genau wie Chat-Tools)
• … bekommt args aus der Scheduled-Task-Definition
• … sollte idempotent sein — kann passieren, dass ein Lauf doppelt ausgeführt wird (z. B. nach Server-Neustart)
• … sollte schnell sein — Long-Running-Jobs (>60s) lieber in mehrere kleinere zerlegen

#Testen

Ein Scheduled Task ist technisch „nur" ein Tool-Aufruf. Testen wie jedes andere Tool:

tm test-tool processNewOrders

# mit den Args aus scheduled.php und dry-run:
tm test-tool processNewOrders dryRun=true --dry-run

#Beobachten

Wenn ein Scheduled Task live läuft:

tm monitor

Scheduled-Runs erscheinen mit Typ CRON:

03:00:05 [ OK  ] CRON  processNewOrders   2.1s
10:00:03 [ OK  ] CRON  sendDailyReport    5.4s

Volle Logs:

tm logs --lines 500

#Deaktivieren

'daily_report' => [
    'enabled' => false,   // ← das reicht
    // ... Rest bleibt unverändert ...
],

Bewusst enabled-Flag statt Code löschen — so bleibt die Definition dokumentiert und du kannst sie per Toggle reaktivieren.

#Ausführung durch die Plattform

Die Aktivierung und Ausführung übernimmt die Betriebsseite automatisch — du musst nichts einrichten. Sobald scheduled.php synchronisiert ist, greift die Plattform die Intervalle auf und startet die Runs.

#Caveats

• Keine Garantien auf Minutengenauigkeit. Bei hoher Last oder kurzen Ausfällen kann ein Run ein paar Sekunden später starten.
• Kein Benutzer-Kontext — Tools, die Session oder Upload-Kontext brauchen, funktionieren hier nicht. Nutze Tools, die sich nur auf Args und Server-State stützen.
• Fehlschläge werden geloggt, nicht retried. Wenn ein Run fehlschlägt, läuft der nächste wie geplant weiter. Baue bei Bedarf eigene Retry-Logik in den Handler.