Connessioni esterne

Come funziona

Uno strumento di tipo HTTP consente al tuo agente di comunicare con sistemi esterni alla piattaforma durante una conversazione. I protocolli disponibili sono:

• HTTP — Chiamate ad API REST (GET, POST, PUT, PATCH, DELETE)
• MQTT — Messaggi a dispositivi IoT o broker di messaggistica
• OPC UA — Comunicazione diretta con macchinari industriali (PLC, SCADA (sistema di supervisione e controllo industriale), DCS)

Configurazione HTTP

Template del body

Il template del body definisce la struttura base della richiesta. I parametri che l'agente ottiene dall'utente vengono combinati con questo template. Cio consente di includere campi fissi (come API key o identificativi) senza che l'agente debba richiederli.

Configurazione MQTT

Configurazione OPC UA

Operazioni OPC UA

Pool di connessioni

La piattaforma mantiene un pool di connessioni OPC UA riutilizzabili. Questo significa che le connessioni non vengono aperte e chiuse ad ogni operazione, ma vengono riutilizzate automaticamente. Il pool e ottimizzato per:

• Massimo 5 connessioni per server
• Le connessioni inattive vengono chiuse dopo 5 minuti
• Riconnessione automatica se la connessione scade

Esempio: API REST

Scenario: Un agente che consulta il meteo tramite un'API esterna.

1. Crea uno strumento di connessione esterna.
2. Configura:
   • URL: https://api.weather.com/current
   • Metodo: GET
   • Header: {"Authorization": "Bearer tua-api-key"}
3. Aggiungi un parametro city affinche l'agente chieda la citta.
4. Assegna lo strumento all'agente.

Esempio: Dispositivo IoT (MQTT)

Scenario: Un agente che accende o spegne macchinari tramite MQTT.

1. Crea uno strumento di connessione esterna con protocollo MQTT.
2. Configura:
   • Broker: mqtt://192.168.1.100:1883
   • Topic: factory/machines/control
   • QoS: 1
3. Aggiungi parametri per machine_id e action (on/off).
4. Quando l'utente dice "accendi la macchina 5", l'agente pubblica il comando MQTT corrispondente.

Esempio: Macchinari industriali (OPC UA)

Scenario: Un agente che legge la temperatura di un sensore industriale su un PLC Siemens.

1. Crea uno strumento di connessione esterna con protocollo OPC UA.
2. Configura:
   • Server: opc.tcp://192.168.1.10:4840
   • Nodo: ns=2;s=Temperature
   • Operazione: Leggere valore
3. Non servono parametri — l'agente leggera il valore direttamente.
4. Quando l'utente dice "qual e la temperatura attuale", l'agente legge il nodo OPC UA e risponde con il valore.

Esempio: Scrivere un valore in un PLC

1. Configura lo strumento con operazione Scrivere valore.
2. Aggiungi un parametro temperatura_obiettivo (tipo number).
3. Quando l'utente dice "imposta la temperatura a 75 gradi", l'agente scrive il valore nel nodo OPC UA.

IoT Gateway

I gateway IoT (HMS Anybus, Siemens IOT2050, Moxa ioLogik, Advantech WISE) sono gia supportati nativamente — questi dispositivi espongono API REST o broker MQTT che puoi collegare direttamente usando i protocolli HTTP o MQTT:

Testare la connessione

Prima di assegnare lo strumento a un agente, puoi testare la connessione direttamente dal modulo di creazione. Il pannello di test:

1. Mostra quale flusso di dati verra eseguito in base al protocollo e all'operazione configurati.
2. Consente di specificare parametri di prova in formato JSON.
3. Esegue la connessione reale e mostra il risultato (successo/errore, tempo di risposta, dati ricevuti).