KI-Agenten & Tools

Agenten und Tools werden in der Datei .ironflock/ai-template.yml im Repository Ihrer App definiert.

Agentenstruktur

Jeder Schlüssel auf oberster Ebene definiert einen Agenten:


my_agent:
    tool_description: |
        When to delegate to this agent and what context to provide.
        These are instructions for the IronFlock AI, not for your agent.
 
    system_prompt: |
        Define your agent's role, expertise, and guardrails.
        Describe when to use each tool and the expected output format.
 
    main: true
    max_context_tokens: 50000
    messages_after_summary: 6
    max_iterations: 10
    tools:
        my_tool:
            description: What this tool does and when to call it.
            topic: my_app.my_wamp_topic
            parameters:
                my_param:
                    type: string
                    description: What this parameter controls.
                    required: true

Agentenfelder

Feld	Beschreibung
`tool_description`	Anweisungen für die IronFlock-KI, wann an diesen Agenten delegiert werden soll. Referenzieren Sie hier keine internen Tools.
`system_prompt`	Definiert die Rolle, das Fachwissen, die verfügbaren Tools und das erwartete Ausgabeformat des Agenten.
`main`	`true` = für die IronFlock-KI sichtbar. `false` = Sub-Agent, nur über Delegation erreichbar.
`max_context_tokens`	Token-Limit pro Anfrage (~1,3 Tokens pro Wort).
`messages_after_summary`	Anzahl der letzten Nachrichten, die im Gesprächsverlauf nicht zusammengefasst werden.
`max_iterations`	Maximale Anzahl von Tool-Aufruf-Runden, bevor der Agent stoppt. Verhindert Endlosschleifen.

Tool-Typen

WAMP-Topic-Tools

Diese Tools rufen eine WAMP-Prozedur auf, die von Ihrem Edge-Code registriert wurde:


tools:
    get_sensor_data:
        description: Retrieves the latest sensor readings from the device.
        topic: sensors.get_latest
        parameters:
            sensor_id:
                type: string
                description: The sensor to query.
                required: true

Das WAMP-Topic muss von der Edge-Komponente Ihrer App registriert sein. Rückgabewerte sollten lesbarer Text oder strukturierte Daten sein, die die KI interpretieren kann.

Delegations-Tools

Diese Tools delegieren an einen anderen Agenten, der in derselben Datei definiert ist:


tools:
    configure_machine:
        description: Handles complex machine configuration tasks.
        delegate: machine_expert

Parametertypen

Typ	Beschreibung
`string`	Texteingabe
`number`	Numerischer Wert
`boolean`	Wahr/Falsch
`object`	Strukturiertes JSON-Objekt
`array`	Liste von Werten

Sub-Agenten & Delegation

Für komplexe Domänen können Sie Ihre KI-Integration in mehrere spezialisierte Agenten aufteilen. Sub-Agenten übernehmen fokussierte Aufgaben, während der Hauptagent die Orchestrierung übernimmt.

Hauptagenten vs. Sub-Agenten

Eigenschaft	Hauptagent (`main: true`)	Sub-Agent (`main: false`)
Sichtbarkeit	Bei der IronFlock-KI registriert	Für die IronFlock-KI nicht sichtbar
Zugriff	Wird direkt von der IronFlock-KI aufgerufen	Nur über Delegation von einem anderen Agenten erreichbar
Anwendungsfall	Einstiegspunkt für die KI Ihrer App	Spezialisiertes Domänenwissen

Wann Sub-Agenten verwenden

Verwenden Sie Sub-Agenten, wenn:

Ein einzelner Agent zu viele Tools hätte (mehr als 8–10)
Verschiedene Aufgaben unterschiedliche System-Prompts oder Fachkenntnisse erfordern
Sie komplexe Workflows isolieren möchten (z. B. Konfiguration vs. Überwachung)
Sie unterschiedliche Token-Limits oder Iterationszahlen für verschiedene Aufgaben benötigen

Delegationsablauf


User → IronFlock AI → Main Agent → Sub-Agent → WAMP Tool → Edge Device
                                  ↓
                           Result flows back

Der Hauptagent entscheidet anhand seines System-Prompts und der Beschreibung des Delegations-Tools, wann delegiert wird. Der Sub-Agent arbeitet unabhängig, nutzt seine eigenen Tools und gibt die Ergebnisse an den Hauptagenten zurück, der sie für den Benutzer zusammenfasst.

Best Practices

Tool-Beschreibungen formulieren

Das Feld tool_description richtet sich an die IronFlock-KI — es bestimmt, wann Ihr Agent aufgerufen wird. Formulieren Sie es aus der Perspektive der IronFlock-KI:

Gut:


tool_description: |
    Delegate to this agent when the user asks about OPC UA devices,
    PLC configuration, or industrial network scanning. Provide the
    device name or network information if available.

Schlecht:


tool_description: |
    I am an OPC UA expert that can scan networks and configure PLCs.
    My tools include network_scan and read_catalog.

Referenzieren Sie keine internen Tools in tool_description — die IronFlock-KI muss diese nicht kennen.

System-Prompts formulieren

Der system_prompt definiert das Verhalten Ihres Agenten. Beinhalten Sie:

Rolle — Was der Agent ist und was er weiß.
Verfügbare Tools — Listen Sie jedes Tool auf und wann es verwendet werden soll.
Ausgabeformat — Wie Antworten strukturiert sein sollen.
Leitplanken — Was der Agent NICHT tun soll.


system_prompt: |
    You are a sensor data specialist for industrial temperature monitoring.
 
    Available tools:
    - get_reading: Use when asked for current sensor values
    - get_history: Use when asked about trends or historical data
    - set_threshold: Use when asked to configure alert limits
 
    Always include measurement units in responses.
    Never modify sensor thresholds without explicit user confirmation.
    If a sensor is not responding, suggest checking the device connection.

WAMP-Tool-Design

Lesbare Daten zurückgeben — Der KI-Agent interpretiert die Rückgabewerte Ihres Tools. Geben Sie strukturierten Text oder JSON zurück, keine rohen Binärdaten.
Fehlermeldungen einbinden — Wenn ein Tool fehlschlägt, geben Sie eine beschreibende Fehlermeldung zurück, die die KI an den Benutzer weitergeben kann.
Parameter einfach halten — Verwenden Sie nach Möglichkeit primitive Typen (string, number, boolean). Komplexe verschachtelte Objekte erschweren es der KI, korrekte Aufrufe zu erstellen.
Pflichtparameter kennzeichnen — Setzen Sie required: true immer für obligatorische Eingaben.

Agenten-Dimensionierung

Einstellung	Empfehlung
`max_context_tokens`	30.000 – 50.000 für die meisten Agenten
`messages_after_summary`	4 – 6 Nachrichten
`max_iterations`	5 – 10 (bei mehrstufigen Workflows erhöhen)

Höhere Werte ermöglichen komplexere Interaktionen, verbrauchen aber mehr Tokens. Beginnen Sie konservativ und erhöhen Sie die Werte, wenn Agenten an Grenzen stoßen.

Agenten testen

Fügen Sie Ihrer App ein Testgerät hinzu.
Öffnen Sie den IronFlock-KI-Chat.
Stellen Sie Fragen, die Ihren Agenten auslösen sollten.
Überprüfen Sie, ob die KI korrekt delegiert und Ihre Tools die erwarteten Daten zurückgeben.
Testen Sie Fehlerfälle — was passiert, wenn ein Gerät offline ist oder ein Tool einen Fehler zurückgibt?

Vollständiges Beispiel


# Main agent - visible to IronFlock AI
factory_agent:
    main: true
    tool_description: |
        Delegate to this agent for factory automation tasks,
        including machine configuration and production monitoring.
 
    system_prompt: |
        You are a factory automation assistant. You can monitor
        production lines and configure machines.
 
        For complex machine configuration, delegate to the
        machine_config_agent using the configure_machine tool.
 
    tools:
        get_production_stats:
            description: Get current production statistics.
            topic: factory.stats
            parameters:
                line_id:
                    type: string
                    required: true
 
        configure_machine:
            description: Handles complex machine setup and configuration.
            delegate: machine_config_agent
 
# Sub-agent - only reachable via delegation
machine_config_agent:
    main: false
    system_prompt: |
        You are a machine configuration specialist. You can read
        machine parameters, update settings, and validate configurations.
 
        Always verify the current state before making changes.
        Confirm changes with the user before applying.
 
    tools:
        read_config:
            description: Read current machine configuration.
            topic: machines.read_config
            parameters:
                machine_id:
                    type: string
                    required: true
 
        write_config:
            description: Apply new configuration to a machine.
            topic: machines.write_config
            parameters:
                machine_id:
                    type: string
                    required: true
                config:
                    type: object
                    description: Configuration key-value pairs to apply.
                    required: true