Creare un agente AI

Avendo conosciuto significato e ruolo dei tool procediamo a creare il nostro primo agente AI.

Per avviare tale attività utilizziamo, come di consueto in questa guida, la libreria Langchain ed, in particolare, la funzione create_agent che automatizza le attività di integrazione dei tool nel flusso di lavoro di un LLM dando, al contempo, la possibilità di aggiungere ulteriori funzionalità in grado di rendere più fluida l'interazione con l'agente AI creato.

Proseguiremo l'esempio riguardante la scelta di nomi di bambini sfruttando il medesimo tool già visto.

Per prima cosa, ragioniamo sugli elementi salienti che dovremo integrare nell'architettura di un agente.

Cosa compone un agente AI

Cosa compone un agente AI? I tool e un LLM, perfetto lo sappiamo. Ma niente altro? In effetti, per un'architettura completa possiamo integrare ulteriori elementi che lo rendano particolarmente efficiente ed adeguato agli incarichi.

Descriviamone le componenti principali in un elenco ordinato in cui i numeri identificativi dei singoli punti richiameranno quelli inseriti nei commenti al codice in modo da poter seguire la costruzione dell'esempio:

1. definizione dei tool. Utilizziamo lo stesso tool visto nella lezione precedente. Questo a dimostrazione di quanto il codice scritto in quella occasione sia propedeutico alla progettazione di qualsiasi agente;
2. istanziazione del modello. Qui scegliamo un modello OpenAI ma, come di consueto, con init_chat_model potremmo importare modelli di qualsiasi provider compatibile. Supporremo l'esistenza di una chiave definita in una variabile api_key predisposta in precedenza;
3. definizione di un checkpointer come meccanismo di memoria per l'agente AI. Grazie a questo l'agente sarà in grado di ricordare gli scambi di messaggi con l'utente creando una conversazione con una sua storia. In questo caso, scegliamo - tra i vari meccanismi disponibili - un InMemorySaver, molto veloce ma temporaneo perché non salva i dati su un database come altre versioni;
4. creazione dell'agente che mette insieme i pezzi detti finora con apposite costanti grazie alla funzione create_agent:

   agent = create_agent(
       model=model,
       system_prompt=PROMPT,
       tools=[suggerisci_nome_maschietto],
       context_schema=Context,
       response_format=ToolStrategy(ResponseFormat),
       checkpointer=checkpointer
   )

   Si noti che viene impostata una ToolStrategy che definisce un formato di risposta del Tool indicando come scheletro una DataClass di nostra creazione;

5. viene avviata una conversazione con l'agente in cui, all'interno di un ciclo, lo invochiamo con il metodo invoke facendo domande per le quali - a seconda dei casi - verrà utilizzato o meno l'agente.

Il codice dell'esempio

Vediamo ora il codice completo dell'esempio:

from dataclasses import dataclass
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.tools import tool, ToolRuntime
from langgraph.checkpoint.memory import InMemorySaver
from langchain.agents.structured_output import ToolStrategy
from random import choice
from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
# 1. definiamo i tool (uno solo in questo caso)
@tool
def suggerisci_nome_maschietto(nome_lungo: bool) -> str:
    """
    Suggerisce nomi solo per bambini di sesso maschile.
    Usa True se l'utente vuole un nome lungo, False per un nome corto.
    """
    if nome_lungo:
        return choice(['Alessandro', 'Francesco', 'Riccardo', 'Leonardo'])
    else:
        return choice(['Ivo', 'Luca', 'Leo', 'Enea'])
# 2. configurazione del modello
model = init_chat_model(
    "gpt-5.4-mini-2026-03-17",
    temperature=0,
    api_key=api_key
)
#3. definizione del checkpointer come meccanismo di memoria
my_serde = JsonPlusSerializer(
    allowed_msgpack_modules=[("__main__", "ResponseFormat")]
)
checkpointer = InMemorySaver(serde=my_serde)
PROMPT = """
Sei un esperto di nomi. Se hai un tool adatto usalo, altrimenti rispondi usando le tue conoscenze.
"""
@dataclass
class ResponseFormat:
    """Struttura per la risposta dell'agente"""
    risposta_finale: str
    nome_suggerito: str | None = None
@dataclass
class Context:
    """identificativo dell'utente"""
    user_id: str
# 4. creazione dell'agente
agent = create_agent(
    model=model,
    system_prompt=PROMPT,
    tools=[suggerisci_nome_maschietto],
    context_schema=Context,
    response_format=ToolStrategy(ResponseFormat),
    checkpointer=checkpointer
)
# identificatore dell'unica conversazione esistente
config = {"configurable": {"thread_id": "1"}}
#5. conversazione con l'agente
while(True):
  query=input('\nTU: ')
  if query.lower().startswith('basta'):
    break
  response=agent.invoke(
    {"messages": [{"role": "user", "content": query}]},
    config=config,
    context=Context(user_id="1")
  )
  print(f'A.I.: {response['structured_response'].risposta_finale}')
  print('='*30)

Potremmo modificare il codice aggiungendo ulteriori tool (e apportando la relativa modifica all'elenco dei tool nella creazione dell'agente al punto 4) ed eventualmente ritoccando un po' il prompt: tanto basterebbe per eseguire delle proficue sperimentazioni.

Prova dell'esempio

Avviamo la seguente conversazione con il nostro agente AI:

TU: mi suggerisci un nome corto da maschietto?
A.I.: Certo: ti suggerisco **Leo**. È corto, moderno e facile da ricordare.
==============================
TU: Ed uno lungo?
A.I.: Certo: ti suggerisco **Alessandro**. È un nome lungo, elegante e molto classico.
==============================
TU: Se fosse una femminuccia?
A.I.: Posso aiutarti, ma al momento ho a disposizione solo suggerimenti per nomi da maschietto.
      Se vuoi, posso comunque proporti un nome femminile tra quelli più dolci e classici, ad esempio **Ginevra**.
==============================
TU: Qual è la capitale della Francia?
A.I.: La capitale della Francia è **Parigi**.
==============================
TU: Chi ha scritto i Promessi Sposi?
A.I.: I **Promessi Sposi** sono stati scritti da **Alessandro Manzoni**.
==============================
TU: Quali nomi mi hai suggerito sinora in questa conversazione?
A.I.: Sinora ti ho suggerito questi nomi: **Leo**, **Alessandro** e **Ginevra**.
==============================

Per prima cosa lo interroghiamo sull'unico argomento per cui possiede un tool ferrato: nomi di maschietto. Già sui nomi per femminucce ammette di non avere un tool idoneo ma che farà il possibile per soddisfarci con ricerche libere.

Dopo chiediamo cose che non c'entrano niente con i nomi di bambini come la capitale della Francia e l'autore dei Promessi Sposi e lui risponde bene perché accede comunque ad un ricco modello di OpenAI.

Dopo che vediamo il modello rispondere correttamente a tutto, gli facciamo il test della memoria. Gli chiediamo quali nomi ci ha suggerito fino a questo momento e lui risponde correttamente con tutti e tre. L'ha potuto fare grazie al checkpointer che gli conserva queste informazioni.

Come vediamo, il nostro agente non solo è in grado invocare i tool quando necessario ma anche di implementare tutta una serie di operazioni accessorie. Per esercizio, si potrà ispezionare meglio l'interno della struttura di risposta e provare ad espanderne il funzionamento.