Docs/Scrivere una operation

# Scrivere una operation

Una operation è codice Python eseguito quando serve più di una risposta fissa: leggere un servizio esterno, fare un calcolo, consultare un database.

1. Crea il file

Le operations sono scoperte automaticamente: basta una funzione con prefisso action_ in un file della cartella delle operations.

python
# agent/operations/ask_capital.py
def action_ask_capital(intent_name: str = None, slots: dict = None) -> dict:
    slots = slots or {}
    country = slots.get("LOCATION")

    if not country:
        return {
            "response": "Di quale paese vuoi sapere la capitale?",
            "slots": {},
            "metadata": {"error": "missing_country"},
        }

    capital = CAPITALS.get(country.lower())
    if not capital:
        return {
            "response": f"Non ho la capitale di '{country}' a disposizione.",
            "slots": {},
            "metadata": {"error": "country_not_found"},
        }
    return {
        "response": f"La capitale è {capital}.",
        "slots": {},
        "metadata": {},
    }

La funzione action_ viene registrata come .

2. Collegala alla regola

Nella regola usa il nome preceduto da due underscore:

yaml
rules:
  ask_capital:
    slots:
      LOCATION:
        required: true
    wait: ask_capital_wait_response
    default: __ask_capital

Cosa restituire

  • Una stringa: return "Ciao!".
  • Oppure un dizionario con response, slots (valori da salvare nel contesto) e metadata.

Parametri disponibili, tutti opzionali: intent_name, slots, session_manager, entity_manager.

Chiamare un servizio esterno

  • Imposta sempre un timeout (per esempio 5 secondi).
  • Gestisci l'errore e restituisci un messaggio chiaro: un servizio fuori uso non deve rompere la conversazione.
  • Un paio di tentativi con breve attesa coprono gli errori passeggeri.
  • Se un dato cambia raramente, una mappa statica nel codice è più semplice e veloce di una chiamata di rete.

Per logica più complessa: una classe

python
from agent.operations.base import Operation

class MyOperation(Operation):
    @property
    def name(self) -> str:
        return "my_operation"

    def execute(self, intent_name: str, slots: dict = None) -> dict:
        return {"response": "Risposta", "slots": {}, "metadata": {}}

Prova veloce

Le operations sono funzioni normali: puoi testarle senza avviare il bot.

python
from agent.operations.ask_capital import action_ask_capital
print(action_ask_capital(slots={"LOCATION": "Francia"}))

Prossimo passo: [Allenare e validare i modelli](/guides/training-e-validazione).