Agenti AI e Strumenti

Agenti e strumenti sono definiti nel file .ironflock/ai-template.yml nel repository della tua app.

Struttura degli Agenti

Ogni chiave di primo livello definisce un agente:


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

Campi degli Agenti

Campo	Descrizione
`tool_description`	Istruzioni per l’AI IronFlock su quando delegare a questo agente. Non fare riferimento a strumenti interni qui.
`system_prompt`	Definisce il ruolo dell’agente, le competenze, gli strumenti disponibili e il formato di output atteso.
`main`	`true` = visibile all’AI IronFlock. `false` = sub-agente, raggiungibile solo tramite delega.
`max_context_tokens`	Limite di token per richiesta (~1,3 token per parola).
`messages_after_summary`	Numero di messaggi recenti mantenuti non riassunti nella cronologia della conversazione.
`max_iterations`	Numero massimo di round di chiamate agli strumenti prima che l’agente si fermi. Previene i loop infiniti.

Tipi di Strumenti

Strumenti WAMP Topic

Questi strumenti chiamano una procedura WAMP registrata dal codice edge:


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

Il topic WAMP deve essere registrato dal componente edge della tua app. I valori restituiti devono essere testo leggibile o dati strutturati che l’AI può interpretare.

Strumenti di Delega

Questi strumenti delegano a un altro agente definito nello stesso file:


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

Tipi di Parametri

Tipo	Descrizione
`string`	Input testuale
`number`	Valore numerico
`boolean`	Vero/falso
`object`	Oggetto JSON strutturato
`array`	Lista di valori

Sub-Agenti e Delega

Per domini complessi, suddividi la tua integrazione AI in più agenti specializzati. I sub-agenti gestiscono attività specifiche mentre l’agente principale orchestra.

Agenti Principali vs. Sub-Agenti

Proprietà	Agente Principale (`main: true`)	Sub-Agente (`main: false`)
Visibilità	Registrato con l’AI IronFlock	Nascosto all’AI IronFlock
Accesso	Invocato direttamente dall’AI IronFlock	Raggiungibile solo tramite delega da un altro agente
Caso d’uso	Punto di ingresso per l’AI dell’app	Competenza specializzata nel dominio

Quando Usare i Sub-Agenti

Usa i sub-agenti quando:

Un singolo agente avrebbe troppi strumenti (più di 8–10)
Attività diverse richiedono system prompt o competenze diverse
Vuoi isolare flussi di lavoro complessi (es. configurazione vs. monitoraggio)
Hai bisogno di limiti di token o conteggi di iterazioni diversi per attività diverse

Flusso di Delega


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

L’agente principale decide quando delegare in base al suo system prompt e alla descrizione dello strumento di delega. Il sub-agente viene eseguito in modo indipendente, usa i propri strumenti e restituisce i risultati all’agente principale, che li riassume per l’utente.

Best Practice

Scrivere le Descrizioni degli Strumenti

Il campo tool_description è per l’AI IronFlock — determina quando il tuo agente viene invocato. Scrivilo dalla prospettiva dell’AI IronFlock:

Corretto:


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.

Scorretto:


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

Non fare riferimento a strumenti interni in tool_description — l’AI IronFlock non ha bisogno di conoscerli.

Scrivere i System Prompt

Il system_prompt definisce il comportamento del tuo agente. Includi:

Ruolo — Cosa è l’agente e cosa sa.
Strumenti disponibili — Elenca ogni strumento e quando usarlo.
Formato di output — Come strutturare le risposte.
Guardrail — Cosa l’agente NON deve fare.


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.

Progettazione degli Strumenti WAMP

Restituisci dati leggibili — L’agente AI interpreterà i valori restituiti dai tuoi strumenti. Restituisci testo strutturato o JSON, non dati binari grezzi.
Includi messaggi di errore — Quando uno strumento fallisce, restituisci un messaggio di errore descrittivo che l’AI può comunicare all’utente.
Mantieni i parametri semplici — Usa tipi primitivi (string, number, boolean) quando possibile. Gli oggetti annidati complessi rendono più difficile per l’AI costruire chiamate corrette.
Segna i parametri obbligatori — Imposta sempre required: true per gli input obbligatori.

Dimensionamento degli Agenti

Impostazione	Raccomandazione
`max_context_tokens`	30.000 – 50.000 per la maggior parte degli agenti
`messages_after_summary`	4 – 6 messaggi
`max_iterations`	5 – 10 (aumenta per flussi di lavoro multi-step)

Valori più alti consentono interazioni più complesse ma costano più token. Inizia in modo conservativo e aumenta se gli agenti raggiungono i limiti.

Test degli Agenti

Aggiungi un dispositivo di test alla tua app.
Apri la chat AI IronFlock.
Fai domande che dovrebbero attivare il tuo agente.
Verifica che l’AI deleghi correttamente e che i tuoi strumenti restituiscano i dati attesi.
Testa i casi di errore — cosa succede quando un dispositivo è offline o uno strumento restituisce un errore?

Esempio Completo


# 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