Come creare il tuo primo assistente IA personalizzato: una guida in 5 passaggi per principianti

La risposta più semplice e utile è questa: costruisci il tuo primo assistente IA personalizzato attorno a un compito specifico, un insieme chiaro di istruzioni e al massimo uno o due strumenti controllati . Non iniziare con uno sciame di agenti, un'enorme base di conoscenza o un'automazione in grado di modificare sistemi importanti. Un primo assistente dovrebbe essere facile da capire, facile da testare e facile da arrestare in caso di dubbi.

Questa guida utilizza Python e l'attuale SDK OpenAI Agents come percorso concreto, poiché gestisce già il ciclo dell'agente, gli strumenti, le sessioni di conversazione, i meccanismi di controllo e il tracciamento. Gli stessi principi di progettazione si applicano ad altri provider di modelli e framework. A partire da settembre 2026, l'SDK utilizza l'API Responses per impostazione predefinita per i modelli OpenAI. La documentazione ufficiale di OpenAI raccomanda di utilizzare direttamente l'API Responses di livello inferiore quando si desidera gestire autonomamente il ciclo e lo stato, e l'SDK Agents quando si desidera che il runtime gestisca una parte maggiore di tale orchestrazione. Consultare la panoramica dell'SDK OpenAI Agents .

Cosa stai costruendo esattamente?

Un assistente basato sull'intelligenza artificiale è molto più di una semplice chat. Come minimo, combina un ampio modello linguistico (LLM) , ovvero un modello che genera e interpreta il linguaggio, con istruzioni che ne definiscono il ruolo. Un assistente efficace può inoltre disporre di strumenti , ossia funzioni o servizi che è autorizzato a richiamare, e di una memoria , che conserva il contesto rilevante della conversazione tra un turno e l'altro.

Per un primo progetto, immaginate un piccolo "Assistente per il negozio" che risponda a domande su resi e spedizioni. Dovrebbe utilizzare una fonte di policy approvata anziché procedere per tentativi. Se non riesce a trovare una risposta approvata, dovrebbe specificarlo. Questo vincolo è più importante che dotare l'assistente di decine di funzionalità.

Prima di iniziare: scegli il percorso di compilazione corretto

Se desideri un assistente riutilizzabile all'interno della tua app, sito web, strumento interno o API, il percorso "code-first" descritto di seguito è l'ideale. Avrai bisogno di Python, di una chiave API OpenAI e di una minima esperienza di programmazione. La guida rapida ufficiale dell'SDK Agents mostra il flusso di installazione e di configurazione del primo agente.

Se avevi intenzione di creare un GPT personalizzato senza codice all'interno di ChatGPT, verifica prima l'idoneità del tuo account. A partire da settembre 2026, OpenAI dichiara che la creazione di nuovi GPT non è disponibile per gli account personali Free, Go, Plus o Pro. La creazione rimane disponibile negli spazi di lavoro Business, Enterprise ed Edu idonei, a condizione che le impostazioni e le autorizzazioni dello spazio di lavoro lo consentano. Le regole attuali sono documentate nella sezione GPT in ChatGPT . Questa procedura può essere più semplice per uno spazio di lavoro gestito, ma non è la soluzione universale per ogni singolo account.

Passaggio 1: Definire un'attività e una regola di errore

Prima di aprire l'editor, annota tre cose: a chi serve l'assistente, cosa dovrebbe fare e cosa non deve fare. Per l'Assistente alle vendite, una definizione pratica potrebbe essere: "Rispondere alle domande dei clienti su resi e spedizioni utilizzando le informazioni approvate dalle politiche aziendali. Non inventare mai una politica. In caso di dubbi, inoltrare i compiti a un operatore umano."

Questo evita un errore comune dei principianti: usare un'istruzione generica come "Sei un assistente utile". Le richieste generiche rendono difficile la valutazione perché quasi ogni risposta può sembrare accettabile. Un compito specifico, invece, fornisce un obiettivo misurabile.

Utilizza una piccola lista di controllo per il successo

• Risponde con il tono che hai richiesto.
• Utilizza informazioni approvate quando una questione di policy lo richiede.
• Dice "Non lo so" oppure chiede una conferma umana quando mancano le prove.
• Non rivela segreti, istruzioni nascoste o dati privati.

Passaggio 2: Creare l'agente minimo

Crea una cartella di progetto e un ambiente virtuale. Un ambiente virtuale è un ambiente Python isolato che mantiene i pacchetti di questo progetto separati dagli altri progetti presenti sul tuo computer.

mkdir first-ai-assistant
cd first-ai-assistant
python -m venv .venv

# macOS or Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

pip install openai-agents

Quindi, imposta la tua chiave API come variabile d'ambiente anziché inserirla direttamente nel tuo file Python:

# macOS or Linux
export OPENAI_API_KEY="your-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY="your-key-here" 

La guida rapida di OpenAI utilizza attualmente una OPENAI_API_KEYvariabile d'ambiente. Evitate di includere le chiavi reali nei sistemi di controllo versione, negli screenshot, nei ticket e nei repository pubblici.

Per la prima prova, potresti creare un agente con solo un nome e delle istruzioni. Tuttavia, una semplice demo conversazionale non dimostra ancora che l'assistente sia in grado di utilizzare informazioni aziendali affidabili. È proprio questo che aggiunge il passaggio successivo.

Passaggio 3: Aggiungere una capacità controllata e una memoria semplice

Uno strumento funzione è una normale funzione che il modello può richiamare quando necessita di informazioni esterne o di un'azione. L'SDK Agents può trasformare una funzione Python in uno strumento e derivarne lo schema di input dalla firma e dalla documentazione della funzione. OpenAI documenta questo comportamento nella guida agli strumenti dell'SDK Agents .

Iniziate con uno strumento di ricerca in sola lettura. Gli strumenti in sola lettura sono più sicuri per un primo assistente perché una chiamata errata non può inviare denaro, eliminare un record, pubblicare un post o modificare l'account di un cliente.

import asyncio
from agents import Agent, Runner, SQLiteSession
from agents.decorators import tool

@tool
def lookup_policy(topic: str) -> str:
    """Return an approved demo-store policy snippet for a topic."""
    policies = {
        "returns": "Unopened items may be returned within 30 days with proof of purchase.",
        "shipping": "Standard shipping usually takes 3 to 5 business days."
    }
    return policies.get(
        topic.lower(),
        "No approved policy was found for that topic."
    )

assistant = Agent(
    name="Store Helper",
    instructions=(
        "Help customers with questions about the demo store. "
        "Use lookup_policy for return or shipping policy questions. "
        "Never invent a policy. If the tool has no approved answer, say so. "
        "Keep answers concise and recommend human confirmation when needed."
    ),
    tools=[lookup_policy],
)

async def main():
    session = SQLiteSession("demo_user", "assistant_sessions.db")
    result = await Runner.run(
        assistant,
        "Can I return an unopened item after 20 days?",
        session=session,
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Esegui il file e poni diverse domande. L'esempio utilizza anche SQLiteSession. Una sessione memorizza la cronologia della conversazione in modo che l'assistente possa mantenere il contesto tra i turni senza che tu debba ricostruire manualmente l'intero elenco dei messaggi. Le opzioni di sessione correnti dell'SDK sono descritte nella documentazione ufficiale delle sessioni .

Quando è opportuno aggiungere i propri documenti?

Aggiungi documenti quando l'assistente necessita di informazioni che il modello di base non dovrebbe essere in grado di conoscere con certezza, come ad esempio le tue politiche, i manuali dei prodotti, le procedure o le FAQ interne. Non caricare tutto solo perché puoi. Inizia con il set minimo di documenti autorevoli necessari per svolgere il compito.

L'SDK attuale supporta funzionalità ospitate come la ricerca di file, la ricerca web e l'esecuzione di codice. Per una prima versione, mantieni l'interfaccia dello strumento semplice e aggiungi la ricerca di file solo dopo che il comportamento di base si è stabilizzato. Più ampio è il set di strumenti, più percorsi dovrai testare.

Passaggio 4: Testalo come un prodotto, non come una demo

Una buona risposta a una singola richiesta amichevole non è sufficiente. Crea un piccolo set di test prima di condividere l'assistente. Includi domande normali, domande ambigue, informazioni mancanti e richieste che tentano di ignorare le tue regole.

Per applicazioni più complesse, è consigliabile aggiungere dei meccanismi di controllo (guardrail) , ovvero controlli che convalidano o bloccano input, output o chiamate a strumenti. L'SDK Agents supporta i guardrail per input, output e strumenti; consultare la documentazione ufficiale sui guardrail . I guardrail sono particolarmente importanti prima di fornire a un assistente strumenti con effetti collaterali.

Fase 5: Implementare in modo mirato, osservare e migliorare

La prima implementazione non deve necessariamente essere un'app pubblica. Una pagina interna privata o una piccola API utilizzata da pochi utenti di test sono spesso soluzioni migliori. Limita le autorizzazioni dell'assistente, registra gli errori e fornisci agli utenti un modo chiaro per segnalare una risposta errata.

L'SDK Agents include una funzionalità di tracciamento integrata che registra eventi come la generazione di modelli, le chiamate a strumenti, i passaggi di consegne e le misure di sicurezza, consentendoti di comprendere cosa è successo durante un'esecuzione. OpenAI documenta il tracciamento e i relativi controlli nella guida al tracciamento . Esamina le tracce durante lo sviluppo, ma considerale potenzialmente sensibili perché, a seconda della configurazione, possono contenere input o output di modelli e strumenti.

Errori comuni da evitare

• Iniziate con più agenti. Un singolo agente con istruzioni chiare e un unico strumento è più facile da sottoporre a debug. Aggiungete agenti di passaggio o specialisti solo quando avete uno specifico problema di instradamento.
• Concedere troppa autorità agli strumenti. Iniziate con strumenti di sola lettura. Aggiungete approvazioni e controlli prima di consentire operazioni di scrittura, acquisto, eliminazione o modifica dell'account.
• Inserire segreti nei prompt. Le credenziali devono essere memorizzate in una configurazione sicura, non nelle istruzioni di sistema o nei file di conoscenza.
• Utilizzo di documenti disordinati o contraddittori. L'assistente non è in grado di risolvere in modo affidabile le regole aziendali che il materiale di origine fornito non è in grado di risolvere.
• Testare solo i casi di successo. Gli errori che interessano si verificano solitamente in richieste ambigue, conflittuali o incomplete.
• Presupponendo che la memoria equivalga alla verità. La memoria di una conversazione conserva il contesto; non rende corretta un'affermazione precedente.

Cosa dovresti costruire dopo?

Una volta che questo primo assistente si comporta in modo affidabile, il miglioramento successivo dovrebbe derivare da un'esigenza reale piuttosto che da una semplice lista di funzionalità. Se gli utenti necessitano di risposte da un insieme più ampio di documenti, è opportuno aggiungere la funzione di recupero o ricerca file. Se l'assistente deve eseguire un'azione aziendale, è necessario aggiungere uno strumento funzionale con ambito ristretto, con convalida e approvazione. Se le conversazioni si estendono su più turni, è opportuno migliorare la gestione delle sessioni. Se è necessario un instradamento specialistico, è consigliabile valutare l'utilizzo di più agenti o il passaggio di consegne.

Il miglior primo assistente IA personalizzato non è il più autonomo. È quello di cui si possono spiegare il lavoro, le prove, le autorizzazioni e il comportamento in caso di errore in poche frasi. Iniziate da lì, testatelo con casi limite reali ed espandetelo solo quando la versione attuale avrà acquisito la funzionalità successiva.