OpenAI ha appena rilasciato un set di strumenti rivoluzionari per costruire agenti AI in modo semplice ed efficace. Il nuovo Agents SDK permette di orchestrare workflow multi-agente, integrare strumenti come ricerca web, file search, e persino l’uso del computer, il tutto con una logica più pulita e una maggiore osservabilità.
Ma perché è così importante? Fino ad ora, creare un agente AI funzionante significava scrivere prompt su prompt, creare logiche di orchestrazione personalizzate e fare debug alla cieca. Con il nuovo SDK, OpenAI semplifica enormemente la costruzione di agenti produttivi e affidabili, permettendo agli sviluppatori di concentrarsi sulle funzionalità, invece che sulla gestione di mille API diverse.
In questo articolo, ti guiderò nella creazione di un agente AI che può cercare informazioni nei file, navigare nel web e fornire consulenze strategiche. Vedremo come trasformare la teoria in codice funzionante. Pronto? Prepara il caffè e iniziamo! ☕
A cosa serve?
Creare un agente AI personalizzato può essere utile in una miriade di situazioni:
- Automatizzare compiti ripetitivi ad esempio, ricerca documentale o supporto clienti
- Migliorare i processi aziendali con un assistente sempre disponibile
- Sviluppare chatbot intelligenti per siti web o applicazioni
- Fornire consulenza basata su AI analizzando dati e suggerendo strategie
Se ti sei mai chiesto come costruire un sistema AI che lavori per te, oggi è il tuo giorno fortunato. Ne creeremo uno che, oltre a dare risposte basate sulle conoscenze di un LLM, inizia ad agire nel mondo digitale cercando sul web e sui vostri file system. Mostrandovi anche cosa sono i Guardrail dal punto di vista pratico.
Ingredienti
Per questa ricetta tecnologica, servono pochi ingredienti ma di qualità:
- Python 3.11+ (per scrivere e far girare il codice)
- openai-agents (la nuova libreria di open AI)
- Chiave API di OpenAI (senza questa, l’AI non ti ascolterà nemmeno Per creare un’API Key vai sul https://platform.openai.com, registratevi e dentro a Dashboard create l’API key; dopo aver inserito il vostro numero di carta di credito…)
Installa la libreria con:
pip install openai-agents
Esporta la tua chiave OPENAI nel Terminale dopo aver installato gli agenti
export OPENAI_API_KEY="tuo_token_api"
E siamo pronti a partire!
Livello di difficoltà
Espresso: 4/5 ☕☕☕☕ Abbastanza caffeina per farci lavorare sodo, ma nulla di impossibile se segui la guida.
Tempo di preparazione
Circa 60 minuti, giusto il tempo di un buon brainstorming con il tuo nuovo amico AI. Poi qualche mese per familiarizzare con questo nuovo modo di lavorare…
Procedura
1. Configurazione dell’ambiente
Per evitare che il nostro agente faccia cose strane, impostiamo alcune variabili di ambiente. Sono dei default, ma preferisco mostrarveli perchè vi serviranno in futuro:
import os
os.environ.setdefault("OPENAI_AGENTS_DISABLE_TRACING", "0")
os.environ.setdefault("OPENAI_AGENTS_DONT_LOG_TOOL_DATA", "0")
os.environ.setdefault("OPENAI_AGENTS_DONT_LOG_MODEL_DATA", "0")
Questo aiuta a gestire il logging e la sicurezza dei dati. Nulla di rivoluzionario, ma meglio impostarlo subito.
2. Creazione di un Guardrail per il controllo degli input
Non vogliamo che l’agente risponda a domande fuori tema, quindi creiamo un “guardrail” che filtra gli input. Ci sarebbe molto da parlare qui ma partite semplici.
from agents import GuardrailFunctionOutput, input_guardrail
@input_guardrail
def topic_guardrail(ctx, agent, input_text: str) -> GuardrailFunctionOutput:
allowed_keywords = ["intelligenza artificiale", "machine learning", "deep learning"]
text_lower = input_text.lower()
if any(keyword in text_lower for keyword in allowed_keywords):
return GuardrailFunctionOutput(output_info="Argomento valido", tripwire_triggered=False)
else:
return GuardrailFunctionOutput(
output_info="Argomento non valido: la domanda deve riguardare AI o argomenti correlati.",
tripwire_triggered=True
)
Traduzione: se qualcuno chiede all’agente di consigliargli il miglior ristorante di sushi, il nostro sistema gli dirà gentilmente di cambiare domanda.
3. Creazione degli Strumenti per la ricerca
Ora dotiamo il nostro agente di strumenti utili: uno per cercare informazioni nei documenti e uno per esplorare il web.
Per creare un vector store vai sul https://platform.openai.com, è possibile creare uno storage semplicemente aggiungendo i file desiderati. Poi servirà l’ID visibile nel riquadro rosso.
from agents.tool import FileSearchTool, WebSearchTool
VECTOR_STORE_ID = "vs_generic123456"
file_search_tool = FileSearchTool(
vector_store_ids=[VECTOR_STORE_ID],
max_num_results=3,
include_search_results=True
)
web_search_tool = WebSearchTool(
user_location={"type": "approximate", "city": "Milan", "country": "IT"},
search_context_size="high"
)
Ora il nostro agente ha due potenti armi: può cercare nei database e anche navigare nel web per raccogliere informazioni fresche.
4. Creazione degli agenti specializzati
Abbiamo gli strumenti, ora creiamo i cervelli che li useranno:
from agents import Agent
file_agent = Agent(
name="FileSearchAgent",
instructions="Usa il tool file_search per trovare informazioni nei documenti indicizzati.",
tools=[file_search_tool],
model="gpt-4o-mini"
)
web_agent = Agent(
name="WebSearchAgent",
instructions="Usa il tool web_search_preview per trovare informazioni online.",
tools=[web_search_tool],
model="gpt-4o-mini"
)
consultant_agent = Agent(
name="BusinessConsultantAgent",
instructions="Ricevi in input un testo con i risultati di ricerca e fornisci una consulenza strategica.",
model="gpt-4o-mini"
)
Abbiamo appena definito tre agenti specializzati, ognuno con un ruolo ben preciso:
- FileSearchAgent – È l’esperto di ricerca documentale. Gli passiamo un input, e lui utilizza il tool
file_search_toolper scandagliare i documenti indicizzati e restituirci informazioni pertinenti. - WebSearchAgent – È il nostro investigatore online. Se le informazioni non si trovano nei documenti interni, questo agente usa
web_search_toolper cercarle sul web, dando priorità a fonti autorevoli. - BusinessConsultantAgent – È il consulente strategico del team. Riceve i dati raccolti dagli altri agenti e li rielabora per fornire risposte più strutturate e utili per l’utente.
Abbiamo separato i compiti per rendere il sistema più modulare e scalabile. Ogni agente è autonomo e può essere riutilizzato o migliorato indipendentemente dagli altri. Inoltre, questa divisione semplifica il debugging e l’ottimizzazione: se uno dei tre agenti non performa bene, possiamo modificarlo senza toccare gli altri.
CONSIGLIO IMPORTANTE: FATE AGENTI SEMPLICI!
Il prossimo passo? Creare un coordinatore che sappia quando e come sfruttare questi agenti nel modo più efficiente.
5. Creazione dell’Agente Coordinatore
Ora ci serve un direttore d’orchestra per gestire il tutto.
coordinatorPrompt = """Sei il coordinatore di un team di esperti in AI.
Il tuo compito è analizzare la domanda dell’utente e decidere quali strumenti usare.
1. Se serve, usa il tool ’file_search_agent’ per estrarre informazioni dai documenti.
2. Se necessario, usa il tool ’web_search_agent’ per cercare online.
3. Combina i risultati e passa tutto al BusinessConsultantAgent per una strategia.
Infine, fornisci una risposta chiara all’utente."""
team_coordinator_agent = Agent(
name="TeamCoordinatorAgent",
instructions=coordinatorPrompt,
tools=[file_agent, web_agent],
handoffs=[consultant_agent],
model="gpt-4o",
input_guardrails=[topic_guardrail]
)
Ora l’agente coordinatore decide cosa fare in base alla richiesta dell’utente.
Questo agente è il direttore d’orchestra: non esegue direttamente ricerche o consulenze, ma decide quale strumento usare per rispondere nel modo migliore. Il suo flusso di lavoro è il seguente:
- Analizza la richiesta dell’utente per capire cosa serve.
- Decide quali strumenti attivare:
- Se la domanda riguarda dati interni → usa il
FileSearchAgent. - Se serve un’informazione aggiornata dal web → chiama il
WebSearchAgent. - Se il risultato richiede una valutazione strategica → passa tutto al
BusinessConsultantAgent.
- Se la domanda riguarda dati interni → usa il
- Compone una risposta chiara e dettagliata aggregando le informazioni ottenute.
È importante dirgli come fare handoff con gli altri agenti, ma ancora di più scrivere un buon prompt che gli spieghi “come ragionare”
6. Perché è utile?
- Automazione intelligente: invece di scegliere manualmente quale agente interrogare, lasciamo che il coordinatore faccia il lavoro pesante.
- Flessibilità: possiamo facilmente aggiungere nuovi agenti con altre specializzazioni (ad esempio un analista finanziario o un traduttore).
- Scalabilità: se il sistema cresce, basta migliorare il coordinatore senza toccare i singoli agenti.
Abbiamo costruito il nostro team di agenti AI, definito il loro coordinatore e impostato tutto il necessario per farli funzionare. Ora è arrivato il momento di vedere se il nostro sistema è davvero pronto a svolgere il suo lavoro!
7. Facciamo il primo test
Il nostro agente coordinatore è progettato per analizzare le richieste e scegliere i tool migliori per rispondere. Mettiamolo alla prova con una domanda semplice:
query = "Quali sono i primi passi per implementare l’AI in azienda?"
Possiamo eseguire il nostro agente con la parte finale dello script:
from agents import Runner, RunConfig
run_config = RunConfig(trace_include_sensitive_data=False, tracing_disabled=False)
try:
result = Runner.run_sync(team_coordinator_agent, query, run_config=run_config)
print("Risposta:", result.final_output)
except Exception as e:
print("Errore:", e)
print("Domanda non valida. Riformula la richiesta.")
Se tutto è configurato correttamente, dovremmo ottenere una risposta strutturata, elaborata dagli agenti coinvolti.
Quindi…
Abbiamo costruito un agente AI modulare e scalabile, capace di utilizzare strumenti specifici per rispondere a diverse esigenze. Tuttavia, la vera sfida risiede nel coordinare efficacemente questi agenti specializzati e monitorarne le prestazioni per garantire risposte accurate e pertinenti.
Coordinamento degli agenti
Il nostro agente coordinatore funge da direttore d’orchestra, analizzando la richiesta dell’utente e decidendo quale agente specializzato attivare. Questo processo decisionale è fondamentale per assicurare che ogni domanda riceva la risposta più appropriata, sfruttando al meglio le competenze di ciascun agente.
Monitoraggio e tracciamento con i nuovi strumenti di OpenAI
Per gestire e ottimizzare il comportamento degli agenti, è essenziale implementare sistemi di logging e tracing. OpenAI ha recentemente introdotto strumenti avanzati per facilitare questo compito:
- Responses API: Combina la semplicità delle Chat Completions con la capacità di utilizzare strumenti integrati, come la ricerca web e la ricerca file, semplificando lo sviluppo di applicazioni agentiche.
- Agents SDK: Fornisce un framework leggero per orchestrare flussi di lavoro con uno o più agenti, includendo funzionalità di osservabilità integrate per tracciare e ottimizzare le prestazioni.
- Strumenti di osservabilità integrati: Consentono di tracciare e ispezionare l’esecuzione dei flussi di lavoro degli agenti, offrendo una visione dettagliata delle interazioni e facilitando l’identificazione e la risoluzione di eventuali problemi.
Conclusione
Creare un agente AI efficace non è solo una questione di codice ben scritto. Serve un mix di coordinamento intelligente, monitoraggio costante e la capacità di far dialogare agenti specializzati in un ecosistema fluido.
Nei miei workshop lo dico spesso: questo è Software 3.0. Non è solo codice, non è solo AI. È un ibrido tra software tradizionale, interazione con modelli linguistici e processi aziendali intelligenti. Un nuovo modo di costruire strumenti digitali.
E qui entrano in gioco i nuovi strumenti di OpenAI per il logging e il tracing. Perché se vogliamo che il nostro sistema sia davvero utile, dobbiamo poter vedere cosa fa, come prende decisioni e come possiamo migliorarlo.
Ma, attenzione: bisogna imparare a frequentare questo mondo. Non si parte subito con un’AI che governa un’azienda. Si inizia con piccole automazioni, si osserva, si affina.
Andate per gradi. Sperimentate. Questa è una delle rivoluzioni più potenti degli ultimi 30 anni.
Siete d’accordo?
Massimiliano
Fonti e link utili
- Presentazione dei nuovi tool di Open AI
- Documentazione OpenAI Agents (Un po’ di teoria)
- Documentazione SDK
- API OpenAI
