0Pricing
AI Agents · Lezione

Gestione del contesto e della cronologia dei clienti

Risposte personalizzate basate su acquisti precedenti, ticket e preferenze.

Gestione del contesto e della cronologia dei clienti è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Perché il contesto fa sembrare umani gli agenti

La differenza tra un agente del servizio clienti mediocre e uno eccellente è il contesto. Quando un agente dice «Vedo che il suo abbonamento si rinnova la prossima settimana: desidera sospenderlo prima di allora?», il cliente si sente riconosciuto, non semplicemente gestito.

Questa lezione illustra come creare un ricco livello di contesto del cliente per i propri agenti.

Schema del profilo del cliente

Definisca un profilo cliente standard che aggreghi i dati provenienti da più fonti. L'agente riceve questo dict all'inizio di ogni conversazione.

from dataclasses import dataclass, field
from datetime import date

@dataclass
class CustomerProfile:
    customer_id: str
    name: str
    email: str
    join_date: date
    subscription_tier: str          # 'free', 'pro', 'enterprise'
    account_age_days: int
    lifetime_value_usd: float
    previous_tickets: list[dict] = field(default_factory=list)
    recent_purchases: list[dict]  = field(default_factory=list)
    preferences: dict             = field(default_factory=dict)

    @property
    def is_long_term_customer(self) -> bool:
        return self.account_age_days > 365

if __name__ == '__main__':
    from datetime import date
    profile = CustomerProfile(
        customer_id='cust_1', name='Jane Doe', email='jane@example.com',
        join_date=date(2023, 1, 15), subscription_tier='pro',
        account_age_days=400, lifetime_value_usd=1250.50,
    )
    print(f'{profile.name} ({profile.subscription_tier}) - long-term customer: {profile.is_long_term_customer}')

Recupero della cronologia degli acquisti

Recuperi gli ultimi N ordini dal backend del Suo e-commerce. Includa la data dell'ordine, gli articoli, il totale e lo stato. In questo modo l'agente saprà che cosa ha acquistato il cliente e se ci sono problemi con ordini recenti.

import requests

SHOP_API = 'https://api.yourshop.com'
SHOP_KEY  = 'YOUR_SHOP_API_KEY'

def get_purchase_history(customer_id: str, limit: int = 10) -> list[dict]:
    resp = requests.get(
        f'{SHOP_API}/customers/{customer_id}/orders',
        headers={'Authorization': f'Bearer {SHOP_KEY}'},
        params={'limit': limit, 'sort': '-created_at'}
    )
    resp.raise_for_status()
    orders = resp.json()['orders']
    return [
        {
            'order_id':   o['id'],
            'date':       o['created_at'][:10],
            'total_usd':  o['total'],
            'status':     o['status'],
            'items':      [i['name'] for i in o['line_items']]
        }
        for o in orders
    ]

Recupero dei ticket di assistenza precedenti

Recuperi gli ultimi N ticket di assistenza per comprendere i problemi ricorrenti. Se lo stesso problema del cliente è stato risolto tre volte, si tratta di un problema del prodotto: lo segnali e lo inoltri di conseguenza.

def get_support_history(customer_id: str, limit: int = 5) -> list[dict]:
    resp = requests.get(
        f'{SHOP_API}/customers/{customer_id}/tickets',
        headers={'Authorization': f'Bearer {SHOP_KEY}'},
        params={'limit': limit, 'sort': '-created_at'}
    )
    resp.raise_for_status()
    tickets = resp.json()['tickets']
    return [
        {
            'ticket_id': t['id'],
            'subject':   t['subject'],
            'status':    t['status'],
            'resolved':  t.get('resolved_at', ''),
            'category':  t.get('category', 'general')
        }
        for t in tickets
    ]

def has_recurring_issue(tickets: list[dict], category: str) -> bool:
    return sum(1 for t in tickets if t['category'] == category) >= 3

Lettura del livello e dello stato dell'abbonamento

Il livello dell'abbonamento determina ciò a cui il cliente ha diritto. Un cliente Pro che chiede informazioni su una funzionalità non disponibile nel proprio piano richiede una risposta diversa da quella da fornire a un cliente Enterprise con la stessa domanda.

def get_subscription_info(customer_id: str) -> dict:
    resp = requests.get(
        f'{SHOP_API}/customers/{customer_id}/subscription',
        headers={'Authorization': f'Bearer {SHOP_KEY}'}
    )
    if resp.status_code == 404:
        return {'tier': 'free', 'status': 'active', 'renewal_date': None}
    resp.raise_for_status()
    sub = resp.json()
    return {
        'tier':         sub['plan'],
        'status':       sub['status'],        # active / past_due / canceled
        'renewal_date': sub.get('current_period_end', '')[:10],
        'cancel_at':    sub.get('cancel_at_period_end', False)
    }

Calcolo dell'anzianità dell'account

L'anzianità dell'account è un indicatore della fedeltà del cliente. Un cliente che è con Lei dal 2021 dovrebbe essere trattato in modo diverso da qualcuno che si è registrato ieri. Quando opportuno, menzioni da quanto tempo è cliente per creare un rapporto di fiducia.

from datetime import datetime, timezone

def calculate_account_age(join_date_str: str) -> dict:
    join = datetime.fromisoformat(join_date_str.replace('Z', '+00:00'))
    now  = datetime.now(timezone.utc)
    delta = now - join
    years  = delta.days // 365
    months = (delta.days % 365) // 30
    return {
        'days':   delta.days,
        'years':  years,
        'months': months,
        'label':  f'{years} year(s) and {months} month(s)' if years else f'{months} month(s)'
    }

age = calculate_account_age('2021-03-15T00:00:00Z')
print(age['label'])  # e.g. '5 year(s) and 2 month(s)'

Creazione della stringa di contesto per l'LLM

Converta il profilo del cliente in un blocco di contesto conciso da inserire nel prompt di sistema. Lo mantenga breve: includa solo i fatti direttamente pertinenti alla sessione in corso.

def build_context_block(profile: CustomerProfile) -> str:
    recent_order = profile.recent_purchases[0] if profile.recent_purchases else None
    last_ticket  = profile.previous_tickets[0]  if profile.previous_tickets  else None
    parts = [
        f'Customer: {profile.name} ({profile.email})',
        f'Account age: {profile.account_age_days} days | Tier: {profile.subscription_tier}',
        f'Lifetime value: USD {profile.lifetime_value_usd:.0f}',
    ]
    if recent_order:
        parts.append(
            f'Last order: {recent_order["date"]} — '
            f'{', '.join(recent_order["items"][:2])} ({recent_order["status"]})'
        )
    if last_ticket:
        parts.append(f'Last ticket: "{last_ticket["subject"]}" ({last_ticket["status"]})')
    return '\n'.join(parts)

Personalizzazione delle risposte con il contesto

Inserisca il blocco di contesto nel prompt di sistema, in modo che l'LLM lo richiami naturalmente nelle risposte senza che sia necessario indicarglielo esplicitamente.

import openai

client = openai.OpenAI(api_key='YOUR_OPENAI_KEY')

def respond_with_context(user_message: str, profile: CustomerProfile) -> str:
    context = build_context_block(profile)
    system_prompt = (
        f'You are a helpful customer service agent for ShopCo.\n'
        f'Customer context:\n{context}\n\n'
        f'Be warm and personal. Reference their history when relevant. '
        f'Address the customer by first name.'
    )
    resp = client.chat.completions.create(
        model='gpt-4o',
        messages=[
            {'role': 'system', 'content': system_prompt},
            {'role': 'user',   'content': user_message}
        ]
    )
    return resp.choices[0].message.content

Memorizzazione nella cache del contesto del cliente

Recuperare i dati del profilo da più API a ogni messaggio è lento e costoso. Memorizzi il profilo nella cache all'inizio della conversazione e aggiorni solo i campi che possono cambiare, come lo stato dell'ordine e lo stato del ticket.

import time

profile_cache: dict[str, dict] = {}  # customer_id -> {profile, fetched_at}
CACHE_TTL = 300  # 5 minutes

def get_cached_profile(customer_id: str) -> CustomerProfile | None:
    entry = profile_cache.get(customer_id)
    if entry and time.time() - entry['fetched_at'] < CACHE_TTL:
        return entry['profile']
    return None

def set_cached_profile(customer_id: str, profile: CustomerProfile):
    profile_cache[customer_id] = {
        'profile': profile,
        'fetched_at': time.time()
    }

Rilevamento di situazioni delicate dalla cronologia

La cronologia può rivelare schemi che richiedono una gestione particolare: un cliente i cui ultimi tre ordini erano difettosi, qualcuno che il mese scorso ha minacciato di annullare l'abbonamento oppure un utente che è con Lei da 7 anni.

def assess_risk_flags(profile: CustomerProfile) -> list[str]:
    flags = []

    # Check for cancellation risk
    cancel_keywords = ['cancel', 'unsubscribe', 'quit', 'competitor']
    for ticket in profile.previous_tickets:
        if any(kw in ticket.get('subject', '').lower() for kw in cancel_keywords):
            flags.append('cancellation_risk')
            break

    # Defective product pattern
    defective = sum(1 for o in profile.recent_purchases if o.get('status') == 'refunded')
    if defective >= 2:
        flags.append('product_quality_issue')

    # High-value customer
    if profile.lifetime_value_usd > 5000:
        flags.append('high_value_customer')

    return flags

Pipeline completa di assemblaggio del contesto

Combini tutte le fonti di dati in un'unica funzione assemble_context(), chiamata una volta all'inizio della conversazione.

from datetime import date

def assemble_context(email: str) -> CustomerProfile:
    # Try cache first
    # In production: look up customer_id from email in your user DB
    customer_id = 'CUST_123'

    cached = get_cached_profile(customer_id)
    if cached:
        return cached

    # Fetch from all sources
    sub    = get_subscription_info(customer_id)
    orders = get_purchase_history(customer_id)
    tickets = get_support_history(customer_id)

    profile = CustomerProfile(
        customer_id=customer_id,
        name='Alice Smith',
        email=email,
        join_date=date(2021, 3, 15),
        subscription_tier=sub['tier'],
        account_age_days=calculate_account_age('2021-03-15T00:00:00Z')['days'],
        lifetime_value_usd=1240.00,
        previous_tickets=tickets,
        recent_purchases=orders
    )
    set_cached_profile(customer_id, profile)
    return profile

Quale elemento del contesto del cliente consente più direttamente all'agente di dire «Vedo che è con noi dal 2021»?

Per personalizzare le risposte è necessario fare riferimento a punti dati specifici del profilo del cliente. Identificare il campo che consente questa affermazione è una domanda pratica di richiamo.

Riepilogo del contesto del cliente

Un ottimo agente del servizio clienti crea un profilo dettagliato a partire dalla cronologia degli acquisti, dai ticket di assistenza, dal livello dell'abbonamento e dall'anzianità dell'account. Inserisca un blocco di contesto conciso nel prompt di sistema, lo memorizzi nella cache per tutta la sessione e utilizzi i segnali di rischio per rilevare le situazioni delicate prima che degenerino.

Domande Frequenti

La lezione «Gestione del contesto e della cronologia dei clienti» è gratuita?

Sì — il testo completo di «Gestione del contesto e della cronologia dei clienti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Gestione del contesto e della cronologia dei clienti»?

Risposte personalizzate basate su acquisti precedenti, ticket e preferenze. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Gestione del contesto e della cronologia dei clienti»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Instradamento dei ticket e logica di escalation
  2. Integrazione CRM: Salesforce e HubSpot
  3. Protocolli di trasferimento a operatori umani
  4. Gestione del contesto e della cronologia dei clienti
← Torna a AI Agents