Analisi dell’Agents SDK di OpenAI: una guida

OpenAI sta introducendo diverse nuove offerte: Responses API, strumenti integrati per la ricerca sul web e nei file, uno strumento per l’uso del computer e l’Agents SDK open source. Mentre la Responses API consente agli sviluppatori di creare agenti sopra la sua tecnologia, l’Agents SDK può aiutarli a collegare gli agenti ad altri strumenti e processi web, eseguendo “workflow” che realizzano in autonomia ciò che l’utente o l’azienda desidera.

Il 2025 è spesso celebrato come “l’Anno degli agenti” e la mossa di OpenAI è considerata un passo chiave per il settore. L’Agents SDK consente agli sviluppatori di sfruttare facilmente i più recenti progressi di OpenAI (come ragionamento migliorato, interazioni multimodali e nuove tecniche di sicurezza) in scenari reali e multi-step. Per gli sviluppatori di LLM e i costruttori di agenti AI, l’Agents SDK fornisce una serie di “blocchi costruttivi” per creare e gestire i propri sistemi di IA autonoma.

Il valore dell’Agents SDK risiede nella capacità di affrontare le sfide del deployment di agenti AI in ambienti di produzione. Tradizionalmente, tradurre le potenti capacità dei LLM in workflow a più fasi è stato laborioso, richiedendo molta scrittura di regole personalizzate, progettazione sequenziale dei prompt e tentativi ed errori senza strumenti adeguati di osservabilità. Con l’Agents SDK e i nuovi strumenti API correlati come la Responses API, OpenAI punta a semplificare significativamente questo processo, consentendo agli sviluppatori di creare agenti più complessi e affidabili con meno sforzo.

Che cos’è l’Agents SDK

OpenAI torna all’open source in grande stile con il rilascio dell’Agents SDK, un toolkit progettato per aiutare gli sviluppatori a gestire, coordinare e ottimizzare i workflow degli agenti — persino costruendo agenti alimentati da altri modelli non OpenAI, come i concorrenti Anthropic e Google, o modelli open source della famiglia DeepSeek, Qwen, Mistral e Llama di Meta.

Perché usare l’Agents SDK

L’SDK si fonda su due principi guida di progettazione:

1. Funzionalità sufficienti per valerne la pena, ma pochi primitivi per impararlo rapidamente.
2. Funziona bene pronto all’uso, ma puoi personalizzare esattamente ciò che accade.

Ecco le principali funzionalità dell’SDK:

• Ciclo dell’agente: ciclo integrato che gestisce la chiamata agli strumenti, l’invio dei risultati all’LLM e il loop fino a quando l’LLM ha terminato.
• Orientato a Python: usa le funzionalità native del linguaggio per orchestrare e concatenare agenti, invece di dover imparare nuove astrazioni.
• Handoff: una potente funzione per coordinare e delegare tra più agenti.
• Guardrail: esegui convalide e controlli degli input in parallelo agli agenti, interrompendo in anticipo se i controlli falliscono.
• Strumenti funzione: trasforma qualsiasi funzione Python in uno strumento, con generazione automatica dello schema e validazione basata su Pydantic.
• Tracciamento: tracciamento integrato che consente di visualizzare, effettuare il debug e monitorare i workflow, oltre a utilizzare la suite OpenAI di strumenti di valutazione, fine-tuning e distillazione.

Come usare OpenAI Agents SDK

1. Configura il tuo ambiente Python

python -m venv env
source env/bin/activate

2. Installa l’Agents SDK

pip install openai-agents

3. imposta la variabile d’ambiente OPENAI_API_KEY

Imposta liberamente l’API OPENAI_API_KEY da CometAPI

• Accedi a cometapi.com. Se non sei ancora nostro utente, registrati prima
• Ottieni la chiave API delle credenziali di accesso dell’interfaccia. Fai clic su “Add Token” nella sezione API token del centro personale, ottieni la chiave del token: sk-xxxxx e invia.
• Ottieni l’URL di questo sito: https://api.cometapi.com/
• Seleziona l’endpoint OPENAI_API_KEY per inviare la richiesta API e imposta il corpo della richiesta. Il metodo e il body della richiesta sono ottenuti dalla documentazione API del nostro sito. Il nostro sito fornisce anche test Apifox per tua comodità.

4. Configura il tuo agente

Definisci quali strumenti può usare la tua IA. Supponiamo di voler abilitare la ricerca web e il recupero di file:

from agent_sdk import Agent, WebSearchTool, FileRetrievalTool

search_tool = WebSearchTool(api_key="your_api_key")
file_tool = FileRetrievalTool()

agent = Agent(tools=)

Ora il tuo agente sa come cercare sul web e recuperare documenti.

5. esegui

A differenza dei chatbot tradizionali, questa IA decide quale strumento usare in base all’input dell’utente:

def agent_task(query):
    result = agent.use_tool("web_search", query)
    return result

response = agent_task("Latest AI research papers")
print(response)

Nessun intervento manuale — solo esecuzione autonoma.

Il ciclo dell’agente

Quando chiami Runner.run(), l’SDK esegue un loop fino a ottenere un output finale:

1. L’LLM viene chiamato usando il modello e le impostazioni sull’agente, insieme alla cronologia dei messaggi.
2. L’LLM restituisce una risposta, che può includere chiamate agli strumenti.
3. Se la risposta ha un output finale, il loop termina e lo restituisce.
4. Se la risposta ha un handoff, l’agente viene impostato sul nuovo agente e il loop continua dal punto 1.
5. Le chiamate agli strumenti vengono elaborate (se presenti) e i messaggi di risposta degli strumenti vengono aggiunti. Quindi il loop continua dal punto 1.

Puoi usare il parametro max_turns per limitare il numero di esecuzioni del loop.

​Output finale

L’output finale è l’ultima cosa che l’agente produce nel loop:

• Se imposti un output_type sull’agente, l’output finale coincide con il momento in cui l’LLM restituisce qualcosa di quel tipo usando gli output strutturati.
• Se non c’è output_type (cioè risposte in testo semplice), allora la prima risposta dell’LLM senza alcuna chiamata a strumenti o handoff è considerata l’output finale.

Esempio Hello world

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

# Code within the code,

# Functions calling themselves,
# Infinite loop's dance.

Struttura tecnica

“L’OpenAI Agents SDK mira a essere un quadro concettuale che dimostra come agenti diversi, come un ‘Triage Agent’ o un ‘CRM Agent’, possano collaborare per completare attività tramite interazioni con strumenti e meccanismi di delega.”

Componenti chiave e architettura dell’Agents SDK

L’OpenAI Agents SDK è costruito su un set di principi conciso ma robusto. Al suo centro c’è il concetto di Agent, che rappresenta un’istanza di modello linguistico configurata con istruzioni specifiche e dotata della capacità di usare vari strumenti. Gli agenti iniziano ricevendo richieste degli utenti — come domande o definizioni di attività — quindi scompongono queste attività in sottoattività che possono implicare l’uso di strumenti predefiniti, per poi fornire una risposta completa. Questi Tools sono descritte funzionalmente come funzioni richiamabili; grazie all’Agents SDK, qualsiasi funzione Python può diventare facilmente uno strumento, con convalida automatica dello schema per input e output fornita tramite Pydantic. Ad esempio, funzioni Python che rappresentano uno strumento di interrogazione del database o uno strumento di ricerca web possono essere integrate direttamente nel toolkit di un agente.

Un altro elemento centrale dell’Agents SDK è l’Agent Loop, che definisce il processo iterativo di risoluzione dei compiti. Partendo da un primo tentativo di rispondere a una richiesta, un agente valuta se dispone di informazioni sufficienti o se deve eseguire azioni esterne. Quando necessario, l’agente invoca uno strumento pertinente, elabora l’output e rivaluta il compito. Questo ciclo si ripete finché l’agente non segnala il completamento dell’attività con una risposta “Ho finito”. L’Agents SDK gestisce questo processo in autonomia, semplificando lo sviluppo automatizzando attività ricorrenti come invocazione degli strumenti, gestione dei risultati e tentativi iterativi. Ciò consente agli sviluppatori di concentrarsi di più sulla definizione dei workflow e delle capacità degli agenti senza preoccuparsi della meccanica sottostante. OpenAI descrive questo approccio come orientato a Python, enfatizzando l’uso di costrutti Python familiari — come cicli, condizionali e chiamate di funzione — anziché linguaggi specifici di dominio (DSL). Con questa flessibilità, gli sviluppatori possono orchestrare agenti interconnessi facendo affidamento sulla sintassi nativa di Python.

Handoff e architettura multi-agente

Le capacità dell’SDK vanno oltre i singoli agenti. Attraverso una funzionalità nota come Handoff, i compiti possono essere trasferiti tra più agenti, consentendo loro di collaborare senza soluzione di continuità. Ad esempio, un “Triage Agent” potrebbe determinare la natura di una richiesta in arrivo e delegarla a un altro agente specializzato, oppure l’output di un agente potrebbe fungere da input per un altro. Questo sistema supporta workflow in cui agenti specializzati eseguono parti distinte di un compito più ampio, abilitando architetture multi-agente complesse. Inoltre, i guardrail migliorano l’affidabilità imponendo regole di validazione sugli input o sugli output degli agenti. Ad esempio, i guardrail possono imporre la conformità al formato dei parametri o terminare il loop in anticipo quando vengono rilevate anomalie, riducendo rischi come esecuzioni inefficienti o comportamenti indesiderati nelle operazioni reali.

Orchestrazione e monitoraggio

Oltre all’esecuzione dei compiti, l’Agents SDK include robuste funzionalità di orchestrazione, occupandosi dell’esecuzione degli strumenti, dei flussi di dati e della gestione del loop. Nonostante l’alto livello di automazione, OpenAI dà priorità alla trasparenza, equipaggiando gli sviluppatori con strumenti per monitorare l’attività degli agenti in tempo reale. Tramite la funzione di tracciamento integrata, accessibile nella dashboard di OpenAI, gli sviluppatori possono visualizzare i workflow passo dopo passo, osservando quando vengono chiamati gli strumenti, quali input utilizzano e quali output restituiscono. La piattaforma utilizza l’infrastruttura di monitoraggio di OpenAI per scomporre l’esecuzione della logica degli agenti in trace e span, offrendo approfondimenti granulari sul comportamento degli agenti. Questo consente agli sviluppatori di diagnosticare colli di bottiglia, risolvere problemi, ottimizzare i workflow e monitorare le prestazioni. Inoltre, l’architettura di tracciamento supporta valutazioni sofisticate, consentendo il fine-tuning e il miglioramento delle prestazioni degli agenti nel tempo.

Vantaggi

L’OpenAI Agents SDK non è solo per sviluppatori individuali, ma offre vantaggi significativi anche alle aziende che costruiscono prodotti basati su agenti AI. Iniziamo dai vantaggi:

Prototipazione rapida e produzione: l’Agents SDK implementa comportamenti complessi degli agenti con codice e configurazione minimi, accorciando il ciclo dall’idea al prodotto. Ad esempio, la piattaforma crypto mainstream Coinbase utilizza l’SDK per prototipare e distribuire rapidamente sistemi di supporto multi-agente. Allo stesso modo, in aree come gli assistenti di ricerca aziendale, le aziende possono integrare gli strumenti di ricerca web e di recupero file dell’SDK per fornire rapidamente valore. Delegando i dettagli dell’orchestrazione, gli sviluppatori possono concentrarsi sulle funzionalità specifiche del prodotto.

Riduzione dei costi di sviluppo: costruire un sistema di agenti da zero richiede un notevole investimento ingegneristico. L’Agents SDK riduce i costi fornendo soluzioni pronte all’uso per esigenze comuni — gestione del loop, sincronizzazione delle chiamate API, gestione degli errori e output formattati per l’LLM. Essendo open source, consente anche la personalizzazione per soddisfare le esigenze dell’azienda. Questo è un vantaggio per le startup, che possono creare potenti prodotti guidati da agenti con risorse limitate.

Tracciabilità e debug: la dashboard di tracciamento integrata dell’SDK trasforma le applicazioni business. Le preoccupazioni del settore per l’IA vista come una “scatola nera” ora lasciano spazio alla possibilità di registrare e verificare ogni passo dell’agente. Se un agente di assistenza clienti fornisce una risposta errata, il trace mostra quale chiamata a uno strumento o quale passo è fallito. La schermata di log/trace della piattaforma OpenAI migliora l’auditabilità degli agenti — fondamentale nei settori soggetti a regolamentazione o audit interni. Ciò consente alle aziende di integrare l’IA con maggiore fiducia, sapendo di poter spiegare i risultati quando necessario.

Accesso ai modelli e agli strumenti più recenti di OpenAI: utilizzare l’Agents SDK significa sfruttare i modelli di punta di OpenAI (ad es. GPT-4) e gli strumenti attuali (ricerca web, esecuzione di codice). Questo offre un vantaggio di qualità rispetto alla costruzione di alternative che potrebbero basarsi su modelli più deboli. Per applicazioni che richiedono alta accuratezza o informazioni aggiornate (ad es. assistenti di ricerca, agenti per l’analisi finanziaria), le prestazioni dei modelli di OpenAI sono un grande vantaggio. Man mano che OpenAI aggiunge strumenti (con l’indicazione di ulteriori integrazioni in arrivo), gli utenti dell’SDK possono adottarli facilmente.

CometAPI è pienamente compatibile con il protocollo di interfaccia OpenAI per garantire un’integrazione senza soluzione di continuità. Puoi evitare dipendenze da modelli e servizi (rischio di lock-in), ridurre le preoccupazioni relative a privacy e sicurezza dei dati e ridurre i costi. Sfruttare i potenti modelli e strumenti di OpenAI può essere costoso e talvolta limitare le prestazioni. CometAPI offre prezzi più economici.

Conclusione

OpenAI è impegnata a far progredire le capacità dell’IA con offerte innovative come la Responses API. Introducendo questi strumenti, aziende e sviluppatori hanno l’opportunità di creare soluzioni di IA più intelligenti, adattabili e altamente affidabili. Questi sviluppi indicano un futuro in cui l’intelligenza artificiale continuerà a guidare cambiamenti di impatto e a sbloccare nuove possibilità in tutti i settori.