Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Esempio pratico: CRM automatizzato

Lezione 13 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Un CRM guidato dalla conversazione
  2. Il database simulato
  3. Le funzioni CRUD
  4. Specifiche degli strumenti JSON
  5. Dispatch e il loop
  6. Quattro scenari e cosa insegnano
  7. Passare alla produzione senza riscrivere tutto
  8. Punti chiave

Un CRM guidato dalla conversazione

Immagina un CRM in cui i commerciali non devono più navigare interfacce complesse. Parlano con un assistente che crea, aggiorna e recupera automaticamente i contatti. È esattamente ciò che il function calling ti permette di costruire. La differenza rispetto al tracciatore di pagamenti della lezione precedente è significativa: finora il modello si limitava a leggere dati. Qui, scrive dati, spostando il focus dell’esercizio verso la validazione, la conferma e la gestione dei duplicati.

Implementerai un CRM conversazionale con operazioni CRUD (Create, Read, Update, Delete) su un database di contatti.

Il database simulato

Un dizionario Python funge da database per questa dimostrazione. Due contatti sono sufficienti: un cliente e un prospect. Questa configurazione ci permette di testare più avanti nella lezione una transizione di stato.

import json
import os
from mistralai.client import Mistral

# Database contatti in memoria (in produzione: PostgreSQL, MongoDB, ecc.)
contacts_db = {
    "CT001": {
        "name": "Marie Dupont",
        "email": "[email protected]",
        "company": "TechCorp",
        "role": "Chief Technology Officer",
        "phone": "+33 6 12 34 56 78",
        "status": "client",
        "notes": "Interested in the enterprise solution"
    },
    "CT002": {
        "name": "Pierre Martin",
        "email": "[email protected]",
        "company": "StartupIO",
        "role": "CEO",
        "phone": "+33 6 98 76 54 32",
        "status": "prospect",
        "notes": "Meeting scheduled for April"
    }
}

next_id = 3  # Contatore per i nuovi contatti

Le funzioni CRUD

get_contact e search_contacts gestiscono le operazioni di lettura. Quest’ultima accetta un argomento per il campo di ricerca per evitare di creare più funzioni quasi identiche. create_contact è la prima funzione che modifica lo stato del sistema e illustra una regola spesso trascurata nelle modalità conversazionali: i controlli di unicità devono risiedere nel tuo codice, mai nel prompt fornito al modello. Nulla impedisce a un commerciale di dettare due volte lo stesso contatto; la verifica dell’email all’inizio della funzione restituisce duplicate_email con l’ID esistente, permettendo al modello di spiegare il rifiuto con precisione.

update_contact utilizza un approccio ai campi opzionali: vengono modificati solo i campi forniti e la funzione restituisce un elenco di ciò che è effettivamente cambiato. Questo elenco non è decorativo: permette all’assistente di confermare la modifica con una frase esatta piuttosto che con un vago “fatto”.

def get_contact(contact_id: str) -> str:
    """Recupera le informazioni per un contatto."""
    if contact_id in contacts_db:
        contact = contacts_db[contact_id].copy()
        contact["contact_id"] = contact_id
        return json.dumps(contact, ensure_ascii=False)
    return json.dumps({"error": f"Contact {contact_id} not found"})


def search_contacts(query: str, field: str = "name") -> str:
    """Cerca contatti per nome, azienda o stato."""
    results = []
    for cid, contact in contacts_db.items():
        if field in contact and query.lower() in contact[field].lower():
            entry = contact.copy()
            entry["contact_id"] = cid
            results.append(entry)

    if results:
        return json.dumps({"results": results, "count": len(results)},
                          ensure_ascii=False)
    return json.dumps({"results": [], "count": 0,
                        "message": f"No contact found for '{query}' in '{field}'"})


def create_contact(name: str, email: str, company: str,
                   role: str = "", phone: str = "",
                   status: str = "prospect", notes: str = "") -> str:
    """Crea un nuovo contatto nel CRM."""
    global next_id

    # Controlla se l'email esiste già
    for cid, contact in contacts_db.items():
        if contact["email"].lower() == email.lower():
            return json.dumps({
                "error": "duplicate_email",
                "message": f"A contact with this email already exists: {cid}"
            })

    contact_id = f"CT{next_id:03d}"
    next_id += 1

    contacts_db[contact_id] = {
        "name": name,
        "email": email,
        "company": company,
        "role": role,
        "phone": phone,
        "status": status,
        "notes": notes
    }

    return json.dumps({
        "success": True,
        "contact_id": contact_id,
        "message": f"Contact {name} created with ID {contact_id}"
    }, ensure_ascii=False)


def update_contact(contact_id: str, **fields) -> str:
    """Aggiorna uno o più campi di un contatto esistente."""
    if contact_id not in contacts_db:
        return json.dumps({"error": f"Contact {contact_id} not found"})

    updated_fields = []
    for key, value in fields.items():
        if key in contacts_db[contact_id]:
            contacts_db[contact_id][key] = value
            updated_fields.append(key)

    if updated_fields:
        return json.dumps({
            "success": True,
            "contact_id": contact_id,
            "updated_fields": updated_fields,
            "message": f"Contact {contact_id} updated: {', '.join(updated_fields)}"
        }, ensure_ascii=False)

    return json.dumps({"error": "No valid fields to update"})

Il parametro ensure_ascii=False presente in diversi ritorni non è un dettaglio estetico: senza di esso, “Interested” diventerebbe una stringa di sequenze di escape Unicode nel contesto del modello, risultando meno leggibile e più costosa in termini di token.

Specifiche degli strumenti JSON

Due meccanismi garantiscono qui la maggior parte dell’affidabilità. L’enum su status impedisce al modello di inventare valori: deve scegliere tra prospect, client, partner e inactive, proteggendo l’integrità dei tuoi dati senza validazioni aggiuntive. L’array required fa il resto distinguendo i campi obbligatori da quelli opzionali: per create_contact, un contatto senza nome, email o azienda non ha senso, mentre un numero di telefono può arrivare dopo.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_contact",
            "description": "Retrieves all information for a contact by ID",
            "parameters": {
                "type": "object",
                "properties": {
                    "contact_id": {
                        "type": "string",
                        "description": "Contact ID (e.g., CT001)"
                    }
                },
                "required": ["contact_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_contacts",
            "description": "Searches for contacts by name, company, or status",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search term"
                    },
                    "field": {
                        "type": "string",
                        "enum": ["name", "company", "status", "role"],
                        "description": "Field to search in (default: name)"
                    }
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "create_contact",
            "description": "Creates a new contact in the CRM",
            "parameters": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Full name of the contact"
                    },
                    "email": {
                        "type": "string",
                        "description": "Email address of the contact"
                    },
                    "company": {
                        "type": "string",
                        "description": "Company name"
                    },
                    "role": {
                        "type": "string",
                        "description": "Job title or function within the company"
                    },
                    "phone": {
                        "type": "string",
                        "description": "Phone number"
                    },
                    "status": {
                        "type": "string",
                        "enum": ["prospect", "client", "partner", "inactive"],
                        "description": "Contact status"
                    },
                    "notes": {
                        "type": "string",
                        "description": "Free-form notes about the contact"
                    }
                },
                "required": ["name", "email", "company"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "update_contact",
            "description": "Updates information for an existing contact",
            "parameters": {
                "type": "object",
                "properties": {
                    "contact_id": {
                        "type": "string",
                        "description": "ID of the contact to modify (e.g., CT001)"
                    },
                    "name": {"type": "string", "description": "New name"},
                    "email": {"type": "string", "description": "New email"},
                    "company": {"type": "string", "description": "New company"},
                    "role": {"type": "string", "description": "New job title"},
                    "phone": {"type": "string", "description": "New phone number"},
                    "status": {
                        "type": "string",
                        "enum": ["prospect", "client", "partner", "inactive"],
                        "description": "New status"
                    },
                    "notes": {"type": "string", "description": "New notes"}
                },
                "required": ["contact_id"]
            }
        }
    }
]

Dispatch e il loop

Poiché le funzioni non dipendono da oggetti esterni, il dizionario di dispatch si riduce a una mappatura diretta. Il messaggio di sistema, tuttavia, porta due vincoli comportamentali assenti dal codice: confermare ogni azione di creazione o aggiornamento con i dettagli e richiedere le informazioni mancanti prima di creare un contatto. Senza questa seconda istruzione, il modello tende a riempire i campi obbligatori con valori plausibili.

available_functions = {
    "get_contact": get_contact,
    "search_contacts": search_contacts,
    "create_contact": create_contact,
    "update_contact": update_contact,
}

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"

messages = [
    {
        "role": "system",
        "content": "You are a CRM assistant. You help sales reps "
                   "manage their contacts. Respond in English. "
                   "When you create or modify a contact, confirm "
                   "the action with details. Request missing "
                   "information before creating a contact."
    }
]

Quattro scenari e cosa insegnano

Il primo scenario mostra il modello che sceglie field="company" da solo anche se l’utente non ha specificato nulla: l’enum dello schema ha fornito le opzioni e la formulazione della domanda ha fatto il resto. Il secondo fornisce informazioni in modo disordinato, senza etichette, e il modello le distribuisce correttamente tra nome, email, azienda e titolo. Il terzo è il più ricco: “Switch Pierre Martin to client” non contiene alcun ID, quindi il modello deve concatenare una ricerca e poi un aggiornamento, inferendo nel frattempo la nota contestuale. Il quarto ci ricorda che il modello può riutilizzare una funzione dal suo uso letterale per rispondere a una domanda di conteggio.

# Scenario 1: Cerca un contatto
chat("Find me contacts at TechCorp")
# -> Il modello chiama search_contacts(query="TechCorp", field="company")
# -> "I found 1 contact at TechCorp: Marie Dupont (CT001),
#     Chief Technology Officer, status client."

# Scenario 2: Crea un contatto
chat("Add a new contact: Sophie Laurent, [email protected], "
     "DataViz, Data Scientist")
# -> Il modello chiama create_contact(name="Sophie Laurent",
#     email="[email protected]", company="DataViz", role="Data Scientist")
# -> "Contact created successfully! Sophie Laurent (CT003) has been added
#     as a prospect at DataViz."

# Scenario 3: Aggiorna uno stato
chat("Switch Pierre Martin to client, he just signed")
# -> Il modello cerca prima Pierre Martin, poi chiama
#    update_contact(contact_id="CT002", status="client",
#                   notes="Contract signed in April 2026")
# -> "Pierre Martin (CT002) is now marked as a client.
#     I added a note about the contract signature."

# Scenario 4: Domanda senza funzione dedicata
chat("How many prospects do we have?")
# -> Il modello chiama search_contacts(query="prospect", field="status")
# -> "You currently have 1 prospect: Sophie Laurent at DataViz."

Passare alla produzione senza riscrivere tutto

Il dizionario in memoria scompare ovviamente non appena ci sono più utenti. Sostituirlo con un database reale, tuttavia, richiede di toccare solo un livello: la funzione interroga l’ORM o l’API del tuo CRM e restituisce comunque la stessa stringa JSON.

# Le funzioni chiamano l'ORM o l'API del tuo CRM
def get_contact_production(contact_id: str) -> str:
    """Versione di produzione con PostgreSQL."""
    contact = db.session.query(Contact).filter_by(id=contact_id).first()
    if contact:
        return json.dumps(contact.to_dict(), ensure_ascii=False)
    return json.dumps({"error": f"Contact {contact_id} not found"})

Il resto del codice—strumenti, dispatch, loop di conversazione—rimane identico. Questa è la forza di questa architettura: cambiano solo le funzioni di logica di business, mentre il livello conversazionale rimane ignaro delle tue scelte di persistenza.

Punti chiave

  • Il function calling trasforma un LLM in un’interfaccia naturale per un CRM
  • Le operazioni CRUD si mappano direttamente su funzioni con JSON Schema
  • Il modello può concatenare ricerca e aggiornamento in un’unica conversazione
  • L’architettura è disaccoppiata: cambia il database senza toccare la logica di conversazione
  • Il messaggio di sistema è cruciale per guidare il modello su conferme e informazioni mancanti