Eingebaute Tools

Alle Agenten in Selu haben Zugriff auf eingebaute Tools, die Kernfunktionalität bereitstellen. Diese Tools werden vom Orchestrator selbst implementiert und unterliegen dem gleichen Tool-Richtlinien-System wie Capability-Tools.

Ereignissystem

emit_event

Ermöglicht es Agenten, Ereignisse auszulösen, die andere Agenten oder externe Benachrichtigungen auslösen können.

{
  "name": "emit_event",
  "parameters": {
    "event_type": "user_action",
    "data": {
      "action": "document_created",
      "document_id": "doc_123"
    }
  }
}

Parameter:

event_type (string, erforderlich) — Der Typ des auszulösenden Ereignisses
data (object, optional) — Zusätzliche Ereignis-Payload-Daten

Ereignisse werden an alle aktiven Ereignisabonnements geliefert, die dem Ereignistyp und eventuell konfigurierten Filtern entsprechen.

Agenten-Delegation

delegate_to_agent

Ermöglicht es Agenten, Aufgaben an andere Spezialagenten im System weiterzugeben.

{
  "name": "delegate_to_agent",
  "parameters": {
    "agent_id": "email-specialist",
    "message": "Sende eine Nachfass-E-Mail an client@example.com über den Projektstatus"
  }
}

Parameter:

agent_id (string, erforderlich) — ID des Zielagenten, an den delegiert wird
message (string, erforderlich) — Die Aufgabenbeschreibung für den Zielagenten

Der delegierte Agent läuft mit seinem eigenen Kontext und Tool-Berechtigungen. Die Antwort wird direkt an den delegierenden Agenten zurückgegeben.

Dauerhafter Speicher

Agenten können dauerhaft Schlüssel-Wert-Daten speichern, die Container-Neustarts und Session-Resets überleben. Speicher ist pro Agent und pro Benutzer begrenzt.

store_get

Ruft einen gespeicherten Wert nach Schlüssel ab.

{
  "name": "store_get",
  "parameters": {
    "key": "user_preferences"
  }
}

Parameter:

key (string, erforderlich) — Der abzurufende Schlüssel

Rückgabe: Der gespeicherte Wert als String oder null, wenn der Schlüssel nicht existiert.

store_set

Speichert dauerhaft ein Schlüssel-Wert-Paar.

{
  "name": "store_set",
  "parameters": {
    "key": "user_preferences",
    "value": "{\"theme\": \"dark\", \"notifications\": true}"
  }
}

Parameter:

key (string, erforderlich) — Der Schlüssel, unter dem gespeichert wird
value (string, erforderlich) — Der zu speichernde Wert (komplexe Daten als JSON serialisieren)

Rückgabe: Bestätigungsnachricht.

store_delete

Löscht einen gespeicherten Schlüssel.

{
  "name": "store_delete",
  "parameters": {
    "key": "old_setting"
  }
}

Parameter:

key (string, erforderlich) — Der zu löschende Schlüssel

Rückgabe: Bestätigungsnachricht, auch wenn der Schlüssel nicht existierte.

store_list

Listet alle gespeicherten Schlüssel-Wert-Paare für diesen Agenten und Benutzer auf.

{
  "name": "store_list",
  "parameters": {}
}

Parameter: Keine.

Rückgabe: JSON-Objekt mit allen gespeicherten Schlüssel-Wert-Paaren.

Zeitplanung und Erinnerungen

set_schedule

Erstellt einen wiederkehrenden Zeitplan mit einem Cron-Ausdruck.

{
  "name": "set_schedule",
  "parameters": {
    "prompt": "Überprüfe meine E-Mails und gib mir eine Zusammenfassung",
    "cron_expression": "0 45 6 * * 1-5",
    "cron_description": "Werktags um 6:45 Uhr",
    "name": "morgen-email-zusammenfassung",
    "timezone": "Europe/Berlin"
  }
}

Parameter:

prompt (string, erforderlich) — Was der Agent bei jedem Lauf tun soll
cron_expression (string, erforderlich) — 6-Feld-Cron-Ausdruck (Sekunde Minute Stunde Tag-des-Monats Monat Wochentag, wobei 0=Sonntag)
cron_description (string, erforderlich) — Menschenlesbare Zeitbeschreibung
name (string, erforderlich) — Kurzer Name für den Zeitplan (Kebab-Case, max. 30 Zeichen)
timezone (string, optional) — IANA-Zeitzone für die Interpretation der Cron-Zeiten (standardmäßig die konfigurierte Zeitzone des Benutzers)

Wichtige Hinweise:

Verwende das 6-Feld-Cron-Format: Sekunde Minute Stunde Tag-des-Monats Monat Wochentag
Wochentag: 0=Sonntag, 1=Montag, …, 6=Samstag
Beispiel: 0 45 6 * * 1-5 bedeutet “um 6:45 Uhr an Werktagen”
Wenn der Zeitplan ausgelöst wird, kann der Agent alle seine Tools zur Erfüllung der Aufgabe verwenden

set_reminder

Plant eine einmalige zukünftige Agentenaktion.

{
  "name": "set_reminder",
  "parameters": {
    "prompt": "Überprüfe das Wetter und sende mir ein Update",
    "fire_at": "2026-03-08T10:00:00Z",
    "name": "wetter-check-sonntag"
  }
}

Parameter:

prompt (string, erforderlich) — Was der Agent tun soll, wenn die Erinnerung ausgelöst wird
fire_at (string, erforderlich) — ISO 8601 Datum/Zeit in UTC, wann die Erinnerung ausgelöst werden soll
name (string, erforderlich) — Kurzer Name für die Erinnerung (Kebab-Case, max. 30 Zeichen)

Wichtige Hinweise:

Das fire_at muss ein zukünftiger Zeitstempel sein
Zeiten sollten in UTC (ISO 8601 Format) angegeben werden
Wenn die Erinnerung ausgelöst wird, kann der Agent alle seine Tools zur Erfüllung der Aufgabe verwenden
Ausgelöste Erinnerungen werden nach 7 Tagen automatisch bereinigt

Der Agent sollte lokale Benutzerzeiten in UTC umwandeln, bevor er dieses Tool aufruft. Für wiederkehrende Zeitpläne verwende stattdessen set_schedule.

Tool-Genehmigungsnachrichten

Verbesserte Genehmigungsaufforderungen

Beim Aufrufen eines Tools mit einer “Fragen”-Richtlinie können Agenten ein _approval_message-Feld einschließen, um benutzerfreundliche Erklärungen zu geben:

{
  "name": "send_email",
  "parameters": {
    "to": "client@example.com",
    "subject": "Projekt-Update",
    "body": "...",
    "_approval_message": "Ich möchte eine Projekt-Update-E-Mail an den Kunden senden."
  }
}

Wichtige Hinweise:

Das _approval_message-Feld ist intern und wird vor der tatsächlichen Tool-Ausführung entfernt
Nachrichten unter 140 Zeichen halten
Aus der Perspektive des Agenten in verständlicher Sprache schreiben
Dies macht Genehmigungsanfragen viel benutzerfreundlicher, besonders in externen Kanälen wie iMessage

Tool-Richtlinien

Alle eingebauten Tools unterliegen der Tool-Richtlinien-Durchsetzung:

Erlauben — Tool wird sofort ohne Benutzerbestätigung ausgeführt
Fragen — Benutzer erhält eine Bestätigungsanfrage vor Tool-Ausführung
Blockieren — Tool-Aufruf wird verweigert und Agent erhält eine Fehlermeldung

Tool-Richtlinien können global von Admins gesetzt und von einzelnen Benutzern überschrieben werden.

Verwendung in der Agent-Entwicklung

Bei der Entwicklung von Agenten kannst du sie anweisen, diese eingebauten Tools in deinen agent.md- oder Capability-prompt.md-Dateien zu verwenden:

## Speicher

Du kannst Informationen zwischen Unterhaltungen mit den store_*-Tools speichern:
- Verwende `store_set`, um Benutzereinstellungen, Sync-Checkpoints oder andere dauerhafte Daten zu speichern
- Verwende `store_get`, um zuvor gespeicherte Informationen abzurufen
- Verwende `store_list`, um alle gespeicherten Daten zu sehen
- Verwende `store_delete`, um veraltete Informationen zu entfernen

## Zeitplanung und Erinnerungen

Wenn Benutzer nach wiederkehrenden Aufgaben oder einmaligen Erinnerungen fragen:
- Verwende `set_schedule` für wiederkehrende Anfragen (täglich, werktags, jeden Montag, etc.)
- Verwende `set_reminder` für einmalige zukünftige Anfragen (morgen, nächsten Sonntag, in 2 Stunden, etc.)
- Parse natürlichsprachliche Zeitangaben in entsprechende Cron-Ausdrücke oder UTC-Zeitstempel
- Erstelle klare Prompts, die beschreiben, was passieren soll
- Generiere aussagekräftige Namen für Zeitpläne und Erinnerungen

## Tool-Genehmigung

Schließe immer `_approval_message` in Tool-Aufrufe ein, um freundliche Erklärungen zu geben:
- Schreibe kurze, verständliche Beschreibungen dessen, was du tun möchtest
- Verwende die Benutzerperspektive: "Ich möchte..." anstatt technischer Details
- Dies hilft Benutzern, Tool-Verwendung zu verstehen und zu genehmigen, besonders in externen Kanälen

Fehlerbehandlung

Eingebaute Tools geben Fehlermeldungen zurück, wenn:

Erforderliche Parameter fehlen
Parameterwerte ungültig sind (z.B. falsch formatierte Zeitstempel, ungültige Cron-Ausdrücke)
Tool-Richtlinie die Ausführung blockiert
Systemfehler während der Ausführung auftreten

Agenten sollten diese Fehler elegant behandeln und hilfreiches Feedback an Benutzer geben.

Implementierungsdetails

Eingebaute Tools sind:

Direkt im Selu-Orchestrator implementiert
Nicht containerisiert (im Gegensatz zu Capability-Tools)
Für alle Agenten verfügbar, unabhängig von installierten Capabilities
Den gleichen Berechtigungs- und Genehmigungsabläufen wie Capability-Tools unterworfen
Mit dem gleichen Benutzerkontext wie der aufrufende Agent ausgeführt

Sie verwenden die spezielle Capability-ID __builtin__ im Tool-Richtlinien-System.