Costruire agenti con OpenAI Agents SDK

Il braccio operativo della nostra applicazione sarà costituito da agenti. Questi sono formati dalla combinazione di un LLM più una serie di strumenti, detti tool. Il concetto di tool è stato già incontrato con il protocollo MCP ed, in sostanza, non si discosta molto da questo. Parliamo di funzionalità messe a disposizione che estenderanno le facoltà dell'LLM rendendolo in grado di interagire con sistemi diversi, recuperare dati, svolgere elaborazioni e, cosa che ci interessa molto qui, interagire con server MCP.

Costruire un agente da zero può essere difficoltoso e per questo sfrutteremo un bel framework che ci viene messo a disposizione da OpenAI: l'Agents SDK.

Agents SDK: agenti subito pronti

L'Agents SDK offre tutta una serie di vantaggi che possiamo mettere in pratica con poche righe di codice in Python (o, volendo, in TypeScript):

• astrazione del ciclo di messaggi dell'agente: il passaggio di messaggi sarà del tutto trasparente e non dovremo mai occuparcene. Grande vantaggio a meno che non avremo necessità di gestire noi il tutto dal di dentro e quindi preferiremo costruire l'agente "a mano";
• integrazione dei tool: del tutto naturale aumentare funzionalità a disposizione ed utilizzarne altre già esistenti messe a disposizione anche da OpenAI stessa;
• supporto nativo a MCP: fondamentale in questa guida. Tutto il ciclo di inizializzazione, richiesta del MCP-Session-id, tool/list per la ricerca di tool e tool/call per la loro invocazione che abbiamo visto nelle lezioni su MCP di questa guida sarà tutto gestito dal framework stesso;
• API asincrone: indispensabili per la gestione di operazioni dalle tempistiche variabili e l'interazione snella con modelli remoti;
• orchestrazione multiagente: un agente da solo tipicamente non basta. E' necessario svilupparne diversi, specializzati e coordinarli alla perfezione;
• funzioni di tracciamento e debug: le capacità degli agenti devono essere ben vigilate pertanto il debug ed il tracciamento del loro lavoro è vitale.

Il primo agente

Proviamo questo framework creando un agente in cui incroceremo un LLM e un tool. L'aspetto principale da verificare è che l'agente faccia tutto con l'LLM ma riconosca il momento giusto per invocare il tool messo a disposizione.

Il nostro agente contiene un tool che genera un oroscopo (casuale, ovviamente) per il segno che gli suggeriamo noi. La cosa interessante è che il tool genera dei voti numerici ma l'LLM crea dei messaggi di testo basandosi su quelli.

E' un esperimento tecnico ma che mostra anche molto della logica degli agenti, il tutto semplificato grazie al nostro framework.

Come ci muoviamo?

• usiamo un modello OpenAI (nel nostro caso, gpt-5-mini, abbastanza economico);
• definiamo il nostro tool oroscopo con il decorator @function_tool;
• creiamo l'agente con la classe Agent del package agents in cui specifichiamo modello, istruzioni e lista di tool;
• usiamo API asincrone, per migliorare l'efficienza, così iniziamo ad abituarci da subito;
• definiamo un ciclo per l'input ripetuto da parte dell'utente, in questo modo potremo fare più domande, alcune riguardanti l'oroscopo, altre riguardo tematiche generali di competenza dell'LLM.

Ecco il codice:

import asyncio
import random
from agents import Agent, Runner, function_tool
# definiamo il tool
@function_tool
def oroscopo(segno: str) -> dict:
    """
    Return a fake horoscope for the given zodiac sign.
    The tool generates random scores between 1 and 5 for:
    - love
    - work
    - money
    """
    # scegliamo volutamente una descrizione in inglese
    return {
        "segno": segno.capitalize(),
        "amore": random.randint(1, 5),
        "lavoro": random.randint(1, 5),
        "soldi": random.randint(1, 5),
    }
#costruiamo l'agente con tool e istruzioni (anche queste in inglese)
agente = Agent(
    name="Zodiaco",
    model="gpt-5-mini",
    instructions="""
You are a friendly assistant.
If the user asks for a horoscope for a zodiac sign,
use the oroscopo tool.
The tool returns scores from 1 to 5 for love, work and money.
Present the result in a pleasant way inventing a textual message corresponding to the score.
For every other request, answer normally using your own knowledge.
""",
    tools=[oroscopo],
)
async def main():
    # un ciclo che continua a chiedere input all'utente
    while True:
        domanda= input("\nTu: ")
        if domanda.lower().startswith("basta"):
            break
        result = await Runner.run(agente, domanda)
        print("\nA.I.:")
        print(result.final_output)
if __name__ == "__main__":
    asyncio.run(main())

L'output prodotto dopo le nostre domande (leggermente abbreviato sulla prima) è il seguente:

>python primo_agente.py
Tu: Chi era Nerone?
A.I.:
Nerone (Nero Claudio Cesare Augusto Germanico) nacque a Antium il 15 dicembre 37 d.C.
...
Tu: Dimmi l'oroscopo per il segno dell'ariete
A.I.:
Ecco l’oroscopo per l’Ariete:
- Amore — 5/5: Giorno molto favorevole nei sentimenti: passione, complicità e attenzioni in più. Se sei single, possibile incontro interessante; se sei in coppia, rinforzo della sintonia.
- Lavoro — 4/5: Buone opportunità e riconoscimenti; energia e determinazione ti aiutano a portare avanti progetti. Sfrutta l’impulso per avanzare ma mantieni la calma nei dettagli.
- Soldi — 2/5: Evita spese impulsive e valuta con attenzione investimenti o acquisti importanti. Meglio prudenza e pianificazione per non correre rischi inutili.
Buona giornata!

Notiamo che l'esperimento è un successo perché otteniamo le due cose più importanti. Primo, l'agente sa quando chiamare il tool. Secondo, i voti generati sono 5, 4 e 2 e l'LLM genera dei messaggi di testo coerenti con il punteggio ottenuto.

Questo è proprio quello che vogliamo da un agente: il tool genera dati e l'LLM li completa con la propria Intelligenza Artificiale. Ora siamo pronti per vedere due aspetti fondamentali per la nostra app: integrazione di MCP e collaborazione tra agenti.