Crea un agente IA funzionante: un glossario pratico

Un agente IA è un programma che riceve un obiettivo, decide una sequenza di azioni, e esegue quelle azioni usando strumenti finché l'obiettivo non è raggiunto o rinuncia. È diverso da un chatbot, che semplicemente risponde ai messaggi. Un agente pianifica, chiama funzioni, controlla i risultati e si adatta. Se hai usato solo ChatGPT tramite browser, costruire il tuo primo agente è il punto in cui il modello smette di essere un generatore di testo e diventa un componente in un sistema più grande.

Il ciclo principale

Ogni agente, indipendentemente da come viene commercializzato, esegue una variante dello stesso ciclo: osserva, pensa, agisci, ripeti. Concretamente:

1. L'agente riceve un compito ("trova il volo più economico per Lisbona il prossimo mese e scrivi un riepilogo in email").
2. Chiama il LLM con il compito più una descrizione degli strumenti disponibili.
3. Il modello ritorna sia una risposta finale che una chiamata a uno strumento, come search_flights(destination="Lisbon", month="2025-06").
4. Il tuo codice esegue quella funzione, ottiene un risultato reale, e lo reinserisce nel contesto del modello.
5. Il modello decide cosa fare dopo: chiamare un altro strumento, chiedere chiarimenti, o finire.

Questo pattern è spesso chiamato loop ReAct (reason plus act), ed è il fondamento di framework come gli agent executor di LangChain, gli agenti di LlamaIndex, e l'API function-calling di OpenAI. Puoi implementare il tutto da solo in meno di 100 righe di Python con solo un'API LLM e un while loop — i framework aggiungono comodità, non magia.

Gli strumenti sono quello che lo rendono un agente

Un modello senza strumenti può solo parlare. Dagli funzioni e può agire. Gli strumenti sono tipicamente funzioni Python semplici avvolte con uno schema che descrive il loro nome, parametri e scopo, così il modello sa quando e come chiamarli. Esempio:

def get_weather(city: str) -> str:
    """Return current weather for a given city."""
    resp = requests.get(f"https://api.weather.example/v1/{city}")
    return resp.json()["summary"]

Con il function-calling di OpenAI, passi uno schema JSON insieme a questa funzione, e il modello restituisce una chiamata strutturata come {"name": "get_weather", "arguments": {"city": "Lisbon"}} al posto di testo libero. Il tuo codice la analizza, esegue la funzione reale, e ritorna il risultato come un nuovo messaggio nella conversazione. Ripeti finché il modello ha abbastanza informazioni per rispondere.

Memoria e stato

Una singola chiamata API non ha memoria oltre la sua finestra di contesto. Gli agenti hanno bisogno di uno stato esplicito: una lista in esecuzione di messaggi (la cronologia conversazione), e spesso un archivio separato per fatti a lungo termine. Per compiti brevi, una lista Python di dict che rappresentano la conversazione è sufficiente. Per agenti che hanno bisogno di ricordare cose attraverso sessioni, ricorrerai a un database vettoriale (Chroma, Pinecone, Qdrant) per archiviare e recuperare informazioni passate rilevanti tramite embedding.

Non over-engineering questo all'inizio. Un numero sorprendente di progetti "agente" fallisce non perché il LLM è debole ma perché la gestione dello stato è sciatta: messaggi duplicati, crescita illimitata del contesto, o perdita della traccia di quale tool call appartiene a quale risultato.

Un esempio minimo funzionante

Ecco la forma di un agente minimal usando l'API di OpenAI, senza framework:

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]

while True:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=[weather_tool_schema],
    )
    msg = response.choices[0].message
    if msg.tool_calls:
        for call in msg.tool_calls:
            result = get_weather(**json.loads(call.function.arguments))
            messages.append(msg)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })
    else:
        print(msg.content)
        break

Questo è un vero agente funzionante. Tutto il resto — strategie di pianificazione, coordinamento multi-agente, pipeline di retrieval — si costruisce su questo ciclo.

Dove fallisce

Gli agenti falliscono in modi prevedibili: loop infiniti di chiamate a strumenti quando il modello non riesce a dire che ha avuto successo, argomenti di funzione allucinati, e costi in fuga dalle richiamate di strumenti costosi. Proteggiti dai loop con un cap di iterazioni massimo (ad esempio, 10 step) e registra ogni tool call durante lo sviluppo. Valida gli argomenti prima di eseguire qualsiasi cosa che tocca un sistema reale — un agente che può inviare email o eseguire comandi shell ha bisogno della stessa sanificazione degli input che applicheresti al codice user-facing, perché il LLM è, in effetti, un utente non affidabile che genera quell'input.

Dove andare dopo

Una volta che il ciclo funziona, i problemi interessanti iniziano: scegliere tra design single-agent e multi-agent, decidere quanta autonomia concedere, e testare gli agenti in modo affidabile quando il loro output non è deterministico. I track IA e Python di Korra Studio coprono retrieval-augmented generation, prompt design, e tool-calling patterns in maggior profondità se vuoi continuare a costruire da qui.