Benutzerdefinierte Agenten erstellen¶

Erstellen Sie Ihre eigenen Automatisierungs-Workflows mit benutzerdefinierten Agenten.

Überblick¶

Agenten sind Markdown-Dateien, die mehrstufige Arbeitsabläufe definieren. DeskAgent lädt sie von folgenden Orten:

Schnellstart¶

1. Agenten-Datei erstellen¶

Erstellen Sie agents/mein_agent.md:

# Agent: Belege verarbeiten

Belege scannen und Ausgabendaten extrahieren.

## Aufgabe

1. Den ausgewählten PDF-Anhang lesen
2. Lieferant, Datum, Betrag extrahieren
3. Als CSV in die Zwischenablage kopieren

## Ausgabe

CSV-Format: Datum, Lieferant, Betrag, Kategorie

2. In der Konfiguration registrieren¶

Fügen Sie dies zu config/agents.json hinzu:

"mein_agent": {
  "category": "finance",
  "description": "Ausgabendaten aus Belegen extrahieren",
  "input": "PDF-Beleganhang",
  "output": "CSV-Ausgabendaten",
  "ai": "gemini",
  "enabled": true,
  "icon": "receipt",
  "allowed_mcp": "outlook|clipboard",
  "order": 50
}

3. DeskAgent neu starten¶

Der Agent erscheint nach einem Neustart in der WebUI.

Konfigurationsoptionen¶

{
  "category": "finance",           // UI-Kategorie
  "description": "Kurzbeschreibung", // Wird in der UI angezeigt
  "input": "Was erwartet wird",      // Beschreibung der Eingabe
  "output": "Was erzeugt wird",    // Beschreibung der Ausgabe
  "ai": "claude_sdk",              // Zu verwendendes KI-Backend
  "enabled": true,                 // In UI anzeigen
  "icon": "receipt",               // Name des Material Icons
  "allowed_mcp": "outlook|sepa",   // Erlaubte MCP-Server
  "allowed_tools": ["tool1"],      // Bestimmte Tools (optional)
  "knowledge": "company|products", // Zu ladende Wissensdateien
  "anonymize": true,               // PII-Schutz aktivieren
  "order": 50                      // Sortierreihenfolge in der UI
}

Kategorien¶

Material Icons¶

Agenten-Markdown-Vorlage¶

# Agent: {Titel}

{Kurze Beschreibung dessen, was dieser Agent tut}

## Kontext

{Hintergrundinformationen, die die KI benötigt}

## Workflow

1. **Schritt 1** - {Beschreibung}
2. **Schritt 2** - {Beschreibung}
3. **Schritt 3** - {Beschreibung}

## Verfügbare Tools

- `tool_name` - Was es tut

## Ausgabeformat

{Wie die Ergebnisse formatiert werden sollen}

## Wichtig

- {Kritische Hinweise oder Warnungen}

MCP-Server & Tools¶

Sicherheitsfunktionen¶

Ebene 1: MCP-Filterung¶

Beschränken Sie, welche MCP-Server der Agent verwenden kann:

"allowed_mcp": "outlook|clipboard"

Ebene 2: Tool-Whitelist¶

Beschränken Sie auf bestimmte Tools:

"allowed_mcp": "filesystem",
"allowed_tools": ["read_file", "list_directory"]

Ebene 3: Pfadbeschränkungen¶

Beschränken Sie den Zugriff auf das Dateisystem:

"filesystem": {
  "read": ["{{TEMP_DIR}}/**"],
  "write": ["{{TEMP_DIR}}/**"]
}

PII-Anonymisierung¶

Aktivieren Sie dies für Agenten, die externe Daten verarbeiten:

"anonymize": true

Ersetzt persönliche Daten durch Platzhalter: - Namen → [PERSON_1] - E-Mails → [EMAIL_1] - IBANs → [IBAN_1]

Voreingaben¶

Sammeln Sie Benutzereingaben, bevor der Agent ausgeführt wird:

---
{
  "inputs": [
    {
      "name": "files",
      "type": "file",
      "label": "PDFs auswählen",
      "required": true,
      "multiple": true,
      "accept": ".pdf"
    },
    {
      "name": "note",
      "type": "text",
      "label": "Notizen",
      "placeholder": "Optional..."
    }
  ]
}
---

# Agent: Dokumente verarbeiten

Zu verarbeitende Dateien: {{INPUT.files}}
Zusätzliche Notizen: {{INPUT.note}}

Eingabetypen¶

Dateieingabe:

{
  "name": "files",
  "type": "file",
  "multiple": true,
  "accept": ".pdf,.docx"
}

Texteingabe:

{
  "name": "description",
  "type": "text",
  "multiline": true,
  "rows": 5
}

Agent-as-Tool¶

Stellen Sie Ihren Agenten als strukturiertes MCP-Tool bereit, das andere Agenten mit typisierten Parametern aufrufen koennen. Dies ermoeglicht Multi-Agent-Workflows, bei denen ein Supervisor spezialisierte Sub-Agents orchestriert.

Warum Agent-as-Tool?¶

Tool-Definition¶

Fuegen Sie eine tool Sektion zum Frontmatter Ihres Agenten hinzu:

---
{
  "ai": "gemini",
  "allowed_mcp": "outlook|paperless",
  "tool": {
    "name": "process_invoices",
    "description": "Rechnungs-E-Mails verarbeiten und zu Paperless hochladen",
    "parameters": {
      "invoices": {
        "type": "array",
        "description": "Zu verarbeitende Rechnungs-E-Mails",
        "required": true
      }
    },
    "returns": {
      "type": "object",
      "properties": {
        "uploaded": {"type": "integer"},
        "actions": {"type": "array"}
      }
    }
  }
}
---

# Agent: Rechnungsverarbeitung
...

Tool-Schema¶

Parameter-Typen: string, array, object, integer, boolean

Agent-Tools aufrufen¶

Agent-Tools sind automatisch fuer andere Agenten verfuegbar:

# Strukturierter Aufruf (wenn tool definiert):
process_invoices(invoices=[
    {"entry_id": "AAA...", "subject": "Rechnung", "sender": "lieferant@beispiel.de"}
])

# Wird intern umgewandelt zu:
run_agent("invoice_processor", inputs='{"invoices": [...]}')

Supervisor-Pattern¶

Nutzen Sie Claude fuer Orchestrierung, Gemini fuer Bulk-Verarbeitung:

daily_check_supervisor (Claude)
    |
    +-- classify_emails (Gemini)  -- 60% guenstiger
    |
    +-- process_invoices (Gemini) -- 60% guenstiger

Vorteile: Qualitaets-Orchestrierung + kosteneffektive Sub-Tasks = ~20-40% Ersparnis

Agent-Tools auflisten¶

Nutzen Sie list_agent_tools() um registrierte Tools zu sehen:

{
  "count": 2,
  "tools": [
    {"name": "classify_emails", "agent": "email_classifier", "parameters": ["emails"]},
    {"name": "process_invoices", "agent": "invoice_processor", "parameters": ["invoices"]}
  ]
}

Platzhalter¶

Verwendung im Agenten-Markdown:

Best Practices¶

Debugging¶

Überprüfen Sie die Protokolle nach der Ausführung:

• workspace/.logs/system.log - Server-Protokolle
• workspace/.logs/agent_latest.txt - Letzter Agenten-Durchlauf

Beispiele¶

Siehe deskagent/agents/ für integrierte Beispiele:

• daily_check.md - Workflow zur E-Mail-Triage
• create_offer.md - Angebot aus E-Mail
• check_payments.md - Zahlungsabgleich