Ciao a tutti, Emma qui da agent101.net!
Quindi, siamo nel 2026, e se sei come me, la tua casella di posta probabilmente è stracolma di “AI questo” e “AI quello.” Ogni due settimane, esce un nuovo framework, un nuovo modello, una nuova promessa di un AI che farà le tue tasse, porterà a spasso il tuo cane e forse scriverà anche il tuo prossimo romanzo. È emozionante, non fraintendermi, ma può anche sembrare un po’… opprimente. Soprattutto quando stai appena iniziando e cerchi di capire cos’è un “AI agent” al di là del marketing.
Qualche mese fa, ho avuto un vero “aha!” momento. Stavo cercando di automatizzare un compito super noioso per le mie finanze personali – fondamentalmente, tenere traccia di specifici tipi di spese su più conti bancari e poi catalogarli in un foglio di calcolo. Avevo provato tutte le soluzioni pronte all’uso, ma nulla si adattava alle mie categorie singolari. È allora che ho pensato: “Sicuramente un AI agent potrebbe aiutare in questo, giusto?”
Il problema era che ogni tutorial che trovavo sembrava scritto per qualcuno con un dottorato in informatica. Saltavano direttamente in sistemi multi-agente, orchestrazione complessa e termini come “ontologie” che mi facevano torcere gli occhi. Volevo solo costruire un agente semplice che facesse una cosa specifica! Volevo capire le basi assolute, il “hello world” degli agenti AI. E questo, miei cari amici, è esattamente ciò che affronteremo oggi.
Stiamo per costruire un agente super semplice, monouso, che può interagire con un modello linguistico di grandi dimensioni (LLM) per svolgere un compito specifico e mirato. Pensalo come il tuo primo passo per creare il tuo assistente digitale, adattato esattamente alle tue esigenze. Niente framework complessi, niente complicazioni multi-agente. Solo una guida pratica e diretta per mettere in funzione il tuo primo agente.
Il “Perché”: Oltre i Chatbot
Prima di addentrarci nel come, parliamo rapidamente del “perché.” Potresti pensare: “Emma, posso già parlare con ChatGPT. Non è un agente?” E hai ragione fino a un certo punto! ChatGPT è incredibilmente potente. Ma un chatbot autonomo è reattivo: gli chiedi qualcosa, risponde. Un AI agent, nella sua forma più semplice, è progettato per essere proattivo e orientato agli obiettivi. Ha un obiettivo specifico, può prendere decisioni e può spesso interagire con il suo ambiente (anche se quell’ambiente è solo un’API o un file system) per raggiungere tale obiettivo.
Il mio problema di tracciamento delle finanze è un esempio perfetto. Non volevo digitare manualmente le descrizioni delle transazioni e chiedere a ChatGPT di catalogarle una per una. Volevo qualcosa che potesse *prendere* le transazioni, *capire* cosa fossero e poi *metterle* nelle giuste categorie, tutto con un intervento minimo da parte mia. Questa è la differenza centrale: l’agenzia. Si tratta di dare potere all’AI per agire per suo conto, entro confini definiti, per raggiungere un obiettivo.
Il Nostro Primo Agente: Il Bot “Riepiloga & Tagga”
Per il nostro esempio pratico, costruiremo un agente super semplice che chiamo “bot Riepiloga & Tagga.” Immagina di ricevere spesso lunghe email, articoli o appunti di riunioni, e desideri due cose rapidamente: un riepilogo conciso e alcune etichette (parole chiave) pertinenti per una facile ricerca successiva. Questo è un problema perfetto e contenuto per il nostro primo agente.
Ecco cosa farà il nostro agente:
- Riceverà un pezzo di testo (ad esempio, un articolo, il corpo di un’email).
- Utilizzerà un LLM per generare un breve riepilogo del testo.
- Utilizzerà lo stesso LLM per generare da 3 a 5 etichette pertinenti per il testo.
- Presenterà sia il riepilogo che le etichette.
Lo terremo semplice, usando Python perché è molto adatto ai principianti e ampiamente usato per i compiti di AI. Utilizzeremo anche una delle API LLM più popolari – ti mostrerò come fare con OpenAI, ma i principi si applicano anche ad altri come Claude di Anthropic o Gemini di Google.
Cosa Ti Serve (Il Minimo Assoluto)
- Python installato sul tuo computer (versione 3.8 o superiore va bene).
- Una chiave API per un fornitore di LLM (ad esempio, OpenAI API key). Dovrai registrarti sul loro sito e aggiungere un po’ di credito. Non preoccuparti, per compiti semplici, il costo è di solito di pochi centesimi.
- Un editor di testo (VS Code, Sublime Text, o anche Notepad++ va bene).
Passo 1: Impostare il Tuo Ambiente
Prima, prepariamo il nostro ambiente Python. Apri il terminale o il prompt dei comandi.
# Crea una nuova directory per il tuo progetto
mkdir my_first_agent
cd my_first_agent
# Crea un ambiente virtuale (buona pratica!)
python3 -m venv venv
source venv/bin/activate # Su Windows: .\venv\Scripts\activate
# Installa la libreria OpenAI
pip install openai python-dotenv
La libreria `python-dotenv` è super utile per tenere la tua chiave API fuori dal tuo codice direttamente, che è una grande best practice di sicurezza. Non hardcodare mai le tue chiavi API!
Successivamente, crea un file chiamato `.env` nella tua directory `my_first_agent`. All’interno di questo file, inserisci la tua chiave API OpenAI in questo modo:
OPENAI_API_KEY="sk-your_actual_openai_api_key_here"
Sostituisci `”sk-your_actual_openai_api_key_here”` con la tua chiave reale. Salva e chiudi questo file.
Passo 2: Progettare il “Cervello” del Nostro Agente (Il Prompt)
Il cuore di qualsiasi agente alimentato da LLM è il suo prompt. Questo è il modo in cui istruiamo l’LLM su cosa vogliamo che faccia. Per il nostro bot Riepiloga & Tagga, abbiamo bisogno di un prompt chiaro e specifico.
Pensalo come dare istruzioni a uno stagista molto intelligente ma letterale. Devi essere esplicito.
# Nel tuo file Python principale (ad esempio, agent.py)
SYSTEM_PROMPT = """
Sei un utile assistente per l'analisi del testo. Il tuo obiettivo è fornire un riepilogo conciso e etichette pertinenti per qualsiasi testo fornito.
Quando ti fornirò un testo, tu:
1. Genererai un riepilogo che non superi le 3 frasi.
2. Genererai 3-5 etichette di una sola parola che rappresentano i principali argomenti o parole chiave del testo.
Formatta la tua uscita esattamente come segue:
Riepilogo: [Il tuo riepilogo di 3 frasi qui]
Etichette: [tag1, tag2, tag3, tag4, tag5] (o meno se appropriato, separate da virgole)
Assicurati che il tuo riepilogo sia obiettivo e che le tue etichette siano altamente pertinenti.
"""
Questo `SYSTEM_PROMPT` è cruciale. Definisce il ruolo dell’AI e delinea il formato di output atteso. Questo aiuta l’LLM a rimanere in carreggiata e ci fornisce risultati coerenti, il che è super importante per un agente che deve svolgere un compito ripetitivo.
Passo 3: Costruire il “Corpo” dell’Agente (Il Codice Python)
Ora mettiamo tutto insieme in uno script Python. Crea un file chiamato `agent.py` nella tua directory `my_first_agent`.
import os
from openai import OpenAI
from dotenv import load_dotenv
# Carica le variabili d'ambiente dal file .env
load_dotenv()
# Inizializza il client OpenAI
# Prenderà automaticamente la OPENAI_API_KEY da os.environ
client = OpenAI()
SYSTEM_PROMPT = """
Sei un assistente di analisi testuale utile. Il tuo obiettivo è fornire un riepilogo conciso e tag pertinenti per un dato testo.
Quando ti fornisco un testo, tu:
1. Genera un riepilogo lungo al massimo 3 frasi.
2. Genera da 3 a 5 tag di una sola parola che rappresentano gli argomenti principali o le parole chiave del testo.
Formatta il tuo output rigorosamente nel seguente modo:
Riepilogo: [Il tuo riepilogo di 3 frasi qui]
Tag: [tag1, tag2, tag3, tag4, tag5] (o meno se appropriato, separati da virgole)
Assicurati che il tuo riepilogo sia oggettivo e che i tuoi tag siano altamente pertinenti.
"""
def summarize_and_tag_agent(text_to_process: str):
"""
Il nostro semplice agente AI e tag per il testo utilizzando un LLM.
"""
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo", # Oppure "gpt-4" se hai accesso e desideri una qualità migliore
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": text_to_process}
],
temperature=0.7, # Controlla la casualità: 0.0 è deterministico, 1.0 è molto creativo
max_tokens=250 # Limita la lunghezza dell'output per evitare risposte troppo lunghe
)
agent_output = response.choices[0].message.content
return agent_output
except Exception as e:
print(f"Si è verificato un errore: {e}")
return None
if __name__ == "__main__":
# Esempio di utilizzo del nostro agente
article_text = """
In uno studio innovativo pubblicato la settimana scorsa, i ricercatori dell'Istituto di Robotica Avanzata hanno svelato un nuovo metodo per insegnare ai droni autonomi a navigare in ambienti urbani complessi con una precisione senza precedenti. La tecnica, chiamata "Neuro-Spatial Mapping," implica una combinazione originale di apprendimento per rinforzo profondo e elaborazione dei dati lidar in tempo reale. Questo consente ai droni di creare mappe 3D altamente dettagliate dei loro dintorni, prevedere i movimenti dei pedoni e identificare potenziali pericoli con un tasso di errore molto inferiore rispetto ai sistemi precedenti. Gli esperti credono che questo sviluppo potrebbe avere un impatto significativo sulla consegna dei pacchi, sulle operazioni di ricerca e soccorso e sull'ispezione delle infrastrutture, aprendo la strada a una più ampia adozione della tecnologia dei droni in aree densamente popolate. Tuttavia, rimangono preoccupazioni riguardo alla privacy e all'integrazione del controllo del traffico aereo, evidenziando la necessità di quadri normativi solidi che accompagnino questi progressi tecnologici.
"""
print("--- Esecuzione dell'agente di Riepilogo e Tag ---")
result = summarize_and_tag_agent(article_text)
if result:
print("\nOutput dell'agente:")
print(result)
# Parsing di base (può essere migliorato per solidità)
summary_line = [line for line in result.split('\n') if line.startswith("Riepilogo:")][0]
tags_line = [line for line in result.split('\n') if line.startswith("Tag:")][0]
summary = summary_line.replace("Riepilogo: ", "").strip()
tags_str = tags_line.replace("Tag: ", "").strip()
tags = [tag.strip() for tag in tags_str.split(',')]
print("\n--- Output Parsing ---")
print(f"Riepilogo: {summary}")
print(f"Tag: {tags}")
else:
print("L'agente non è riuscito a produrre un risultato.")
print("\n--- Un altro esempio ---")
email_text = """
Oggetto: Riunione di Revisione del Progetto Q1 Riprogrammata
Ciao Team,
Solo una nota veloce per far sapere a tutti che la riunione di revisione del progetto Q1, originariamente programmata per martedì prossimo, 2 aprile, è stata spostata. Si è presentato un conflitto con la disponibilità del VP di Ingegneria, che deve essere presente. La nuova data è ora giovedì 11 aprile, alle 10:00 nel Conference Room 3. Vi preghiamo di aggiornare i vostri calendari di conseguenza. Un invito aggiornato sarà inviato a breve. Ci scusiamo per qualsiasi inconveniente ciò possa causare.
Cordiali saluti,
Sarah
Coordinatore del Progetto
"""
result_email = summarize_and_tag_agent(email_text)
if result_email:
print("\nOutput dell'agente (Email):")
print(result_email)
else:
print("L'agente non è riuscito per l'esempio dell'email.")
Analizziamo cosa sta succedendo in `agent.py`:
- `import os`, `openai`, `dotenv`: Importiamo le librerie necessarie.
- `load_dotenv()`: Questa riga carica la tua `OPENAI_API_KEY` dal file `.env` nelle variabili d’ambiente del tuo script.
- `client = OpenAI()`: Questo inizializza il client OpenAI. Cerca automaticamente `OPENAI_API_KEY` nelle tue variabili d’ambiente.
- `SYSTEM_PROMPT`: Le nostre istruzioni attentamente formulate per il LLM.
- `summarize_and_tag_agent(text_to_process: str)`: Questo è il cuore del nostro agente.
- Effettua una chiamata a `client.chat.completions.create`. Questo è il modo in cui interagisci con i modelli di chat di OpenAI.
- `model=”gpt-3.5-turbo”`: Stiamo utilizzando un modello buono e conveniente. Potresti passare a `gpt-4` per una qualità superiore se necessario.
- `messages`: Questa è una lista di dizionari che rappresentano la conversazione. Il ruolo `system` stabilisce la persona e le istruzioni dell’agente, e il ruolo `user` fornisce il testo da elaborare.
- `temperature=0.7`: Questo parametro controlla quanto è “creativa” o “casuale” la risposta del LLM. Valori più bassi (ad es. 0.2) la rendono più concentrata e deterministica, valori più alti (ad es. 0.9) la rendono più variegata. Per il riepilogo, vogliamo che sia abbastanza consistente, quindi 0.7 è un buon compromesso.
- `max_tokens=250`: Questo imposta un limite superiore sulla lunghezza della risposta del LLM. Utile per controllare i costi e garantire la concisione.
- `if __name__ == “__main__”:`: Questo blocco viene eseguito quando esegui lo script direttamente. Fornisce un testo di esempio e stampa i risultati. Ho anche incluso un esempio di parsing di base per mostrare come potresti estrarre riepilogo e tag in modo programmatico.
Passo 4: Esecuzione del tuo primo agente!
Ora arriva la parte entusiasmante! Salva il tuo file `agent.py` e torna al tuo terminale (assicurati che il tuo ambiente virtuale sia ancora attivato: `source venv/bin/activate`).
python agent.py
Dovresti vedere un output simile a questo (la formulazione esatta potrebbe variare leggermente a causa della natura del LLM, ma il formato dovrebbe essere coerente):
--- Esecuzione dell'agente di Riepilogo e Tag ---
Output dell'agente:
Riepilogo: I ricercatori dell'Istituto di Robotica Avanzata hanno sviluppato "Neuro-Spatial Mapping," un nuovo metodo per i droni autonomi di navigare in ambienti urbani complessi. Questa tecnica combina l'apprendimento per rinforzo profondo e i dati lidar in tempo reale, consentendo ai droni di creare mappe 3D dettagliate e prevedere i movimenti con alta precisione. Questo progresso potrebbe rivoluzionare la consegna dei pacchi e il soccorso, sebbene persistano preoccupazioni sulla privacy e normativi.
Tag: Droni, Robotica, Navigazione, AI, Urbano
--- Output Parsing ---
Riepilogo: I ricercatori dell'Istituto di Robotica Avanzata hanno sviluppato "Neuro-Spatial Mapping," un nuovo metodo per i droni autonomi di navigare in ambienti urbani complessi. Questa tecnica combina l'apprendimento per rinforzo profondo e i dati lidar in tempo reale, consentendo ai droni di creare mappe 3D dettagliate e prevedere i movimenti con alta precisione. Questo progresso potrebbe rivoluzionare la consegna dei pacchi e il soccorso, sebbene persistano preoccupazioni sulla privacy e normativi.
Tag: ['Droni', 'Robotica', 'Navigazione', 'AI', 'Urbano']
--- Un altro esempio ---
Output dell'agente (Email):
Riepilogo: La riunione di revisione del progetto Q1, originariamente fissata per il 2 aprile, è stata riprogrammata per giovedì 11 aprile, alle 10:00 nel Conference Room 3. Questo cambiamento è dovuto a un conflitto con la disponibilità del VP di Ingegneria. Un invito aggiornato sarà inviato a breve.
Tag: Riunione, Riprogrammazione, Progetto, Q1, Revisione
Congratulazioni! Hai appena costruito ed eseguito il tuo primo agente AI! Potrebbe essere semplice, ma dimostra il concetto fondamentale: un’AI orientata agli obiettivi che interagisce con un LLM per svolgere un compito specifico basato sulle tue istruzioni.
Cosa c’è dopo? Renderlo tuo
Questo è solo il punto di partenza, ovviamente. Ecco alcune idee su come puoi estendere e sperimentare con il tuo nuovo agente:
- Modelli Differenti: Prova a cambiare `gpt-3.5-turbo` in `gpt-4` (se hai accesso) e osserva la differenza di qualità. Oppure prova un modello di un fornitore completamente diverso.
- Input Più Complessi: Sperimenta con il `SYSTEM_PROMPT`. Puoi fargli estrarre entità specifiche (nomi, date, luoghi)? Può tradurre il riepilogo in un’altra lingua?
- Metodi di Input: Invece di codificare a mano `article_text`, potresti far leggere all’agente un file? O prendere input direttamente dalla riga di comando?
- Metodi di Output: Invece di stampare semplicemente, potrebbe l’agente scrivere il riepilogo e i tag in un nuovo file? O addirittura caricarli in un database?
- Gestione degli Errori: Il blocco `try-except` è un inizio, ma potresti aggiungere controlli degli errori più sofisticati, specialmente per il parsing dell’output se il LLM non segue il formato perfettamente ogni volta.
- Uso di Strumenti (Uno Sguardo al Futuro): Questo agente è puramente linguistico. Il passo successivo nello sviluppo dell’agente spesso implica “uso degli strumenti,” in cui l’agente può chiamare funzioni esterne (come cercare sul web, inviare un’email o eseguire calcoli) in base alla sua comprensione del compito. Questo è un argomento per un altro giorno, ma si basa direttamente su questa fondazione!
Conclusioni Azionabili
- Inizia Semplice: Non cercare di costruire un super-agente fin dal primo giorno. Scegli un compito specifico e realizzabile.
- La Progettazione dei Prompt è Fondamentale: Il tuo agente è valido quanto le sue istruzioni. Sii chiaro, preciso e specifica il formato di output desiderato.
- Usa Variabili di Ambiente: Proteggi le tue API keys!
- Itera e Sperimenta: Modifica i tuoi prompt, prova modelli diversi e osserva come si comporta l’agente. È così che impari cosa funziona.
- Comprendi il “Perché”: Un agente non è solo un chatbot; è un sistema orientato agli obiettivi progettato per agire e raggiungere risultati.
Costruire il tuo primo agente AI può sembrare come decifrare un codice segreto, ma spero che questo tutorial l’abbia un po’ chiarito. È un concetto potente e una volta che comprendi queste basi, si apre un intero nuovo mondo di automazione e sistemi intelligenti. Vai avanti e costruisci!
Buon coding, e ci vediamo nel prossimo!
Emma
agent101.net
🕒 Published: