Sto costruendo agenti AI multi-passaggio utili per il mio flusso di lavoro

Ciao a tutti, Nina qui da agntbox.com! Spero che stiate passando tutti una settimana produttiva. Oggi, voglio approfondire qualcosa che ha attirato molto la mia attenzione recentemente: gli agenti AI. In particolare, voglio parlare di come possiamo rendere questi agenti non solo intelligenti, ma realmente utili in un modo che vada oltre un singolo compito isolato. Esploreremo un framework per costruire agenti AI multi-passaggio e con stato.

Lo so, lo so. “Framework” può sembrare un po’ secco, ma state con me. Non si tratta di un sistema complesso a livello aziendale. Si tratta di un approccio pratico che ho perfezionato per far sì che i miei agenti facciano più che semplicemente rispondere a una richiesta o riassumere un documento. Voglio che ricordino di cosa abbiamo parlato, seguano i compiti e persino adattino il loro comportamento in base alle interazioni ongoing. Pensateci meno come a una struttura rigida e più come a un modello mentale per progettare migliori compagni AI.

Il problema che continuavo a riscontrare con configurazioni di agenti più semplici era la perdita di contesto. Chiedevo a un agente di fare X, e lui faceva X. Poi gli chiedevano di fare Y, che dipendeva da X, e spesso si comportava come se non avessimo mai discusso di X. Era come parlare con qualcuno con perdita di memoria a breve termine. Frustrante, giusto?

La Sfida: Oltre le Interazioni Singole

Le mie prime esperienze nella costruzione di agenti AI seguivano spesso uno schema semplice: input dell’utente -> chiamata LLM -> output dell’agente. Questo funziona benissimo per compiti semplici, come generare una bozza di email veloce o trovare un’informazione specifica. Ma cosa succede se il compito richiede diversi passaggi, in cui l’esito di ogni passaggio influenza il successivo? Cosa succede se l’agente deve ricordare preferenze, azioni passate o conversazioni ongoing?

Supponiamo che io voglia che un agente mi aiuti a gestire il calendario dei contenuti del mio blog. Un agente semplice potrebbe generare un’idea per un post. Ma voglio che:

• Suggerisca argomenti basati su tendenze recenti (che deve ricercare).
• Elabori una bozza per un argomento scelto.
• Critichi la mia bozza in base a linee guida specifiche (ad es., SEO, tono).
• Proponga miglioramenti e poi segua se li ho implementati.
• Mi ricordi le scadenze imminenti.

Questa non è un’interazione singola. Questa è una conversazione, una collaborazione. Ed è qui che l’idea per un approccio più strutturato ha iniziato a cristallizzarsi.

Introducendo il Framework “Task-State-Tool”

Dopo molti tentativi e errori, sono arrivata a un framework concettuale che chiamo “Task-State-Tool.” Non è una libreria o un software specifico (anche se puoi certamente costruirlo con strumenti esistenti). È un modo di pensare alla progettazione degli agenti che li rende più capaci e persistenti.

1. Compiti: Definire lo Scopo dell’Agente

Ogni agente ha bisogno di uno scopo chiaro. Invece di pensare solo a un prompt, lo considero come una “Definizione di Compito.” Questo definisce ciò che l’agente deve raggiungere durante un’interazione potenzialmente lunga. È la stella polare dell’agente.

Per il mio agente del calendario dei contenuti, un compito di alto livello potrebbe essere: “Assistere Nina nella gestione del processo di creazione dei contenuti del suo blog, dalla generazione delle idee alla pubblicazione, garantendo qualità e consegna tempestiva.”

Sotto questo compito principale, ci sono sub-compiti. Queste sono azioni più piccole e discrete che l’agente può intraprendere. Ad esempio:

• GenerateTopicIdeas
• OutlineBlogPost
• ReviewDraft
• TrackProgress
• SendReminder

Ogni sub-compito ha bisogno di un obiettivo chiaro e di un output previsto.

2. Stato: La Memoria e il Contesto dell’Agente

Qui avviene la magia per la persistenza. Lo “Stato” è essenzialmente la memoria di lavoro dell’agente. È un archivio dati strutturato che contiene tutte le informazioni che l’agente deve ricordare durante le interazioni. Non si tratta solo della cronologia delle chat; è un’informazione analizzata e organizzata che è rilevante per il compito ongoing.

Pensateci come a un dizionario o a un oggetto JSON che viene aggiornato dopo ogni azione significativa. Per il nostro agente dei contenuti, lo stato potrebbe includere:

• current_blog_post_id: L’ID del post su cui si sta attualmente lavorando.
• topic_suggestions: Un elenco di argomenti suggeriti in precedenza.
• selected_topic: L’argomento scelto da Nina.
• outline_generated: Booleano, vero se esiste una bozza.
• draft_status: “in attesa,” “revisionato,” “revisioni necessarie.”
• deadlines: Un dizionario di ID dei post alle loro date di scadenza.
• user_preferences: Il tono preferito di Nina, lunghezza, parole chiave SEO.

Aggiornare lo stato non significa semplicemente aggiungere nuovi messaggi. Spesso coinvolge l’LLM che analizza la conversazione ed estrae entità chiave, decisioni o cambiamenti di stato. Questo stato strutturato è ciò che consente all’agente di riprendere esattamente da dove si era fermato, anche se chiudo il mio browser e torno più tardi.

Ecco un esempio semplificato in Python di come potrebbe apparire e essere aggiornato un oggetto di stato:

class AgentState:
 def __init__(self):
 self.data = {
 "current_blog_post_id": None,
 "topic_suggestions": [],
 "selected_topic": None,
 "outline_generated": False,
 "draft_status": "not_started", # "not_started", "pending", "reviewed", "revisions_needed", "published"
 "deadlines": {}, # {post_id: date_str}
 "user_preferences": {
 "tone": "conversational",
 "length": "1000-1500 words",
 "keywords": ["AI tools", "tech blogging"]
 }
 }

 def update(self, key, value):
 if key in self.data:
 self.data[key] = value
 print(f"Stato aggiornato: {key} = {value}")
 else:
 print(f"Attenzione: Tentativo di aggiornare una chiave di stato non esistente: {key}")

 def get(self, key):
 return self.data.get(key)

# Esempio di utilizzo:
my_state = AgentState()
print(my_state.get("draft_status")) # Output: not_started

# Immagina che l'LLM analizzi "Voglio lavorare su un post sui framework LLM" e identifichi un nuovo post.
my_state.update("current_blog_post_id", "post_123")
my_state.update("selected_topic", "LLM Frameworks")
my_state.update("draft_status", "pending")

print(my_state.get("selected_topic")) # Output: LLM Frameworks

3. Strumenti: Le Capacità dell’Agente

Gli strumenti sono le mani e i piedi dell’agente. Queste sono funzioni discrete o API che l’agente può chiamare per svolgere azioni nel mondo reale (o nel suo mondo simulato). L’LLM funge da cervello, decidendo quale strumento utilizzare e quando, in base all’input dell’utente e allo stato interno dell’agente.

Per il nostro agente dei contenuti, gli strumenti potrebbero includere:

• SearchInternet(query): Per ricercare tendenze recenti o fatti specifici.
• GenerateOutline(topic, preferences): Prende un argomento e le preferenze dell’utente, restituisce un’outline.
• CritiqueText(text, guidelines): Prende una bozza e linee guida, restituisce feedback.
• SaveDocument(content, post_id): Salva il contenuto generato in un database o file.
• SetReminder(post_id, date): Si integra con un’API del calendario.
• FetchPostContent(post_id): Recupera contenuti precedenti.

La parte cruciale qui è che l’LLM deve essere esplicitamente informato su questi strumenti, inclusi i loro nomi, descrizioni e parametri attesi. Questo viene spesso fatto tramite meccanismi di chiamata delle funzioni disponibili nei moderni LLM (come la chiamata delle funzioni di OpenAI o la chiamata degli strumenti di Gemini di Google).

Ecco un esempio semplificato in Python di come definire uno strumento per un LLM:

def get_current_weather(location: str):
 """Ottiene il meteo attuale in una data località.
 
 Args:
 location: La città e stato, ad es. San Francisco, CA
 """
 # In uno scenario reale, questo chiamerebbe un'API meteo
 if "london" in location.lower():
 return {"temperature": "10 Celsius", "forecast": "nuvoloso"}
 elif "new york" in location.lower():
 return {"temperature": "50 Fahrenheit", "forecast": "soleggiato"}
 else:
 return {"temperature": "sconosciuto", "forecast": "non disponibile"}

tools = [
 {
 "type": "function",
 "function": {
 "name": "get_current_weather",
 "description": "Ottieni il meteo attuale in una data località",
 "parameters": {
 "type": "object",
 "properties": {
 "location": {
 "type": "string",
 "description": "La città e stato, ad es. San Francisco, CA",
 }
 },
 "required": ["location"],
 },
 },
 }
]

# Quando un LLM decide di chiamare questo strumento, restituirebbe qualcosa del tipo:
# {"name": "get_current_weather", "arguments": {"location": "Londra, Regno Unito"}}
# Il tuo codice poi esegue get_current_weather("Londra, Regno Unito")

Come Tutto Si Collega: Il Loop dell’Agente

Quindi, come funzionano insieme questi tre elementi? È un ciclo continuo:

1. Input Utente: Nina invia un messaggio all’agente.
2. Costruzione del Contesto: L’agente prende l’input dell’utente, l’attuale AgentState, e la Task Definition. Combinano questi elementi per creare un prompt esaustivo per l’LLM.
3. Decisione dell’LLM: L’LLM elabora il prompt. Sulla base del compito, dello stato e degli strumenti disponibili, decide:
   • Cosa rispondere a Nina.
   • Quali strumenti chiamare (se ce ne sono), e con quali argomenti.
   • Come aggiornare il AgentState.
4. Esecuzione dello Strumento (Opzionale): Se il LLM decide di chiamare uno strumento, l’agente lo esegue. Il risultato dell’esecuzione dello strumento viene quindi reinserito nel ciclo.
5. Aggiornamento dello Stato: Lo AgentState viene aggiornato in base alla decisione del LLM e/o all’output dello strumento.
6. Output dell’Agente: L’agente risponde a Nina, chiedendo eventualmente chiarimenti o confermando un’azione.
7. Ripeti: Il ciclo continua con il successivo input di Nina.

Questo ciclo consente all’agente di mantenere il contesto, eseguire operazioni multi-step e persino autocompensarsi se un’azione non procede come previsto. È un modo molto più efficace per costruire assistenti AI davvero utili.

Un Esempio Pratico: “Schizza il Mio Prossimo Post”

Facciamo un semplice scenario con il mio agente di contenuto per blog:

Nina: “Ehi, ho bisogno di un’outline per il mio prossimo post sul framework Task-State-Tool. Mantienilo intorno alle 1500 parole, tono colloquiale, e assicurati di includere esempi pratici.”

1. Input dell’Utente: “Outline per il post sul framework Task-State-Tool…”
2. Costruzione del Contesto: L’agente vede l’attuale AgentState (che potrebbe essere vuoto o contenere interazioni precedenti). Combina questo con la richiesta dell’utente e il suo compito principale di gestione del contenuto.
3. Decisione del LLM: Il LLM, vedendo la frase “outline per il mio prossimo post” e conoscendo lo strumento OutlineBlogPost, decide di chiamarlo. Estrae “framework Task-State-Tool” come argomento, “1500 parole” per la lunghezza, “colloquiale” per il tono, e annota “esempi pratici.” Identifica anche questo come un nuovo post e suggerisce un aggiornamento per current_blog_post_id e selected_topic nello stato.
4. Esecuzione dello Strumento: L’agente chiama GenerateOutline(topic="Task-State-Tool framework", length="1500 words", tone="conversational", keywords=["practical examples"]).
5. Aggiornamento dello Stato: L’agente aggiorna il proprio stato:
   • current_blog_post_id: “post_124” (un ID generato di recente)
   • selected_topic: “framework Task-State-Tool”
   • outline_generated: True
   • draft_status: “pending_outline_review”

   L’outline restituito dallo strumento viene anche memorizzato, forse in un archivio di contenuti separato collegato da post_124.

6. Output dell’Agente: “Va bene, Nina. Ho generato un’outline per il tuo post sul ‘framework Task-State-Tool,’ puntando a circa 1500 parole con un tono colloquiale e esempi pratici. L’ho salvata come ‘post_124’. Vuoi che la mostri qui, o forse suggerire alcune sotto-sezioni?”

Ora, se rispondo con “Mostrami l’outline,” l’agente non ha bisogno di ri-comprendersi l’argomento o le mie preferenze. Recupera semplicemente l’outline memorizzato associato a post_124 dal proprio stato e la mostra. Questa è la potenza degli agenti con stato.

Considerazioni Pratiche per i Tuoi Agenti

Se stai cercando di costruire agenti AI più capaci e persistenti, ecco cosa consiglio in base alle mie esperienze con il framework Task-State-Tool:

1. Inizia con una Chiara Definizione del Compito: Prima di scrivere codice, definisci chiaramente cosa vuoi che il tuo agente raggiunga durante l’intero ciclo di vita. Scomponilo in sotto-compiti.
2. Progetta il Tuo Schema di Stato Presto: Pensa a tutte le informazioni che il tuo agente dovrà ricordare. Quali sono le entità chiave, gli stati e le preferenze degli utenti? Strutturala come un dizionario o una semplice classe.
3. Identifica gli Strumenti Necessari: Quali azioni esterne deve compiere il tuo agente? Mappa queste a funzioni specifiche o chiamate API. Assicurati che il tuo LLM capisca come chiamarle (le descrizioni e i parametri sono fondamentali).
4. Accogli il Ciclo: Comprendi che l’interazione dell’agente non è una chiamata singola. È un processo continuo di input, decisione, azione e aggiornamento dello stato.
5. Itera e Raffina gli Aggiornamenti dello Stato: Questa è spesso la parte più delicata. Come estrae il tuo LLM informazioni in modo affidabile dall’input dell’utente per aggiornare lo stato? Potresti aver bisogno di una chiamata LLM separata e più piccola solo per il parsing dello stato, oppure di ingegneria dei prompt accurata.
6. Non Esagerare con l’Ingegnerizzazione: Inizia semplice. Non hai bisogno di un complesso database per il tuo stato inizialmente. Un file JSON o un dizionario in memoria possono funzionare per i prototipi. Scala man mano che la complessità del tuo agente aumenta.

Costruire agenti con questo tipo di memoria persistente e capacità ci porta oltre semplici chatbot verso assistenti veramente intelligenti. È un viaggio, e ci saranno ostacoli, ma i risultati sono incredibilmente gratificanti. Provalo e fammi sapere cosa costruisci!

Fino alla prossima volta, continua a sperimentare!

🕒 Published: April 4, 2026