Crea con CometAPITi serve una sola API per più modelli?Testa il flusso di lavoro in Playground, poi crea una chiave API quando modello e costo sono adatti al tuo caso d'uso.
L'OpenAI Agents API è una piattaforma gestita per creare agenti IA che ragionano, usano strumenti, eseguono codice e completano attività multi-step. È progettata per applicazioni che devono proseguire il lavoro su più turni, eseguire strumenti e riprendersi da interruzioni senza implementare autonomamente l’intero loop dell’agente. Questa guida aiuta gli sviluppatori a valutarne le capacità, le opzioni di integrazione e i costi.
A differenza di una convenzionale LLM API, l’OpenAI Agents API supporta sessioni persistenti, ambienti di esecuzione gestiti, coordinamento multi-agente, eventi in streaming e artifact. Gli sviluppatori possono usare gli endpoint nativi dell’OpenAI Agents API per l’esecuzione gestita oppure integrare i modelli OpenAI supportati tramite CometAPI per creare workflow di agenti personalizzati. Si tratta di percorsi di integrazione distinti.
Punti chiave
L’OpenAI Agents API gestisce sessioni persistenti ed esecuzioni multi-step, riducendo l’orchestrazione che gli sviluppatori devono gestire.
Revisionato per chiarezza, attribuzione delle fonti e terminologia API aggiornata.
Le sue capacità principali includono esecuzione di codice in sandbox, strumenti e connessioni MCP, subagent e artifact salvati.
I costi dell’OpenAI Agents API combinano token del modello, strumenti idonei e compute ospitato opzionale; valuta il costo per attività completata.
I guadagni riportati dai clienti forniscono evidenze specifiche per il carico di lavoro, più che un benchmark standardizzato per ogni applicazione.
L’esecuzione gestita nativa e gli agenti personalizzati tramite CometAPI sono scelte d’integrazione separate con differenti responsabilità infrastrutturali.
Che cos’è l’OpenAI Agents API?
L’OpenAI Agents API è un servizio di esecuzione gestito per applicazioni che svolgono attività multi-step usando modelli di ragionamento e strumenti esterni. Espone l’harness dell’agente Codex come servizio. Invece di gestire manualmente chiamate al modello, esecuzione degli strumenti, stato di sessione e recupero dei task, gli sviluppatori possono delegare gran parte di questo coordinamento al runtime.
Un chatbot convenzionale genera una risposta; un agente può pianificare passaggi, eseguire codice in un ambiente autorizzato, ispezionare errori, riprovare e consegnare file generati. Questo rende l’API adatta a workflow operativi più che alla sola chat.
Workflow dell’OpenAI Agents API
Un workflow di agente riunisce quattro parti: l’agente definisce il modello, le istruzioni e gli strumenti disponibili; l’ambiente fornisce compute e accesso ai file; la sessione preserva il contesto e il lavoro salvato; gli eventi e gli item espongono avanzamento e risultati. Insieme, questi componenti consentono alla tua applicazione di inviare un task, seguirne l’esecuzione e proseguire il lavoro in turni successivi. Vedi la panoramica dell’Agents API per i concetti sottostanti.
Workflow tipico: creare una sessione; inviare un obiettivo; lasciare che il modello ragioni e scelga gli strumenti consentiti; eseguire tali strumenti; ispezionare i risultati intermedi; e trasmettere in streaming l’avanzamento e gli artifact finali. La sessione può essere proseguita secondo necessità.
Il diagramma ufficiale mostra l’applicazione che scambia input ed eventi con l’harness e la sandbox gestiti. Diagramma architetturale tratto dalla documentazione sull’architettura dell’OpenAI Agents API; artwork originale di OpenAI.
Quali sono le principali funzionalità dell’OpenAI Agents API?
Le capacità dell’harness gestito coprono esecuzione di codice, gestione del contesto, connessioni agli strumenti, steering e delega. La disponibilità dipende anche dall’ambiente configurato e dagli strumenti.
Funzionalità
Specifica
Vantaggio pratico
Runtime gestito
harness basato su Codex
Riduce il codice di orchestrazione
Persistenza delle sessioni
Stato multi-turn
Supporta il lavoro di follow-up
Gestione del contesto
Compattazione gestita
Workflow estesi
Esecuzione ospitata
Linux sandbox; Python e Node.js
Esecuzione reale di codice
Ambiente autogestito
Compute gestito dallo sviluppatore
Controllo dell’infrastruttura
Esecuzione multi-agente
Subagent configurabili
Sottoattività parallele
Connessioni agli strumenti
Functions e MCP
Integra servizi
Uso del computer
Interazione UI controllata
Automazione dell’interfaccia
Streaming e webhooks
Eventi di avanzamento
Applicazioni reattive
Artefatti
File salvati
Report consegnabili
Sessioni persistenti e gestione del contesto
Le sessioni preservano configurazione, contesto della conversazione e lavoro salvato su più turni. Gli sviluppatori possono inviare una nuova istruzione a una sessione esistente; la gestione del contesto aiuta a sostenere task estesi riducendo la necessità di scrivere logiche personalizzate di compressione del transcript.
Esecuzione di codice in sandbox
Ambiente
Infrastruttura
Uso ideale
none
Nessuna esecuzione locale
Workflow con strumenti remoti
openai_hosted
Sandbox gestita da OpenAI
Codice, analisi e processamento file
self_hosted
Compute controllato dallo sviluppatore
Infrastruttura personalizzata
Gli ambienti ospitati possono eseguire Python, Node.js e programmi da riga di comando in uno spazio di lavoro isolato. Un ambiente self-hosted consente all’agente gestito di usare compute controllato dallo sviluppatore. Gli sviluppatori gestiscono e mettono in sicurezza tale ambiente, mentre l’Agents API continua a gestire l’harness dell’agente e lo stato della sessione.
Collaborazione multi-agente
Un agente coordinatore può delegare attività indipendenti a subagent specialistici. Agenti di ricerca potrebbero esaminare fonti separate mentre un agente primario riconcilia le evidenze. Il parallelismo può migliorare il throughput, ma ulteriori chiamate al modello e il coordinamento possono aumentare i costi. L’API supporta concorrenza configurabile e impostazioni dei subagent.
OpenAI Agents API vs Agents SDK vs Responses API vs AgentKit
Dimensione
Agents API
Agents SDK
Responses API
AgentKit
Scopo
Esecuzione gestita
Orchestrazione code-first
Inferenza e strumenti
Componenti per agenti
Loop dell’agente
Gestito
App/SDK
Gestito dallo sviluppatore
Dipende dal componente
Infrastruttura
Ospitata o esterna
Controllata dallo sviluppatore
App più strumenti ospitati
Variabile
Multi-agente
Coordinamento integrato
Handover
Personalizzato
Specifico per componente
Ideale per
Task autonomi durevoli
Agenti personalizzati
Controllo fine-grained
Strumentazione per agenti
L’Agents API fornisce esecuzione gestita; l’Agents SDK è adatto ad applicazioni che possiedono il proprio stack di orchestrazione; la Responses API è appropriata per inferenza e workflow di strumenti più leggeri; AgentKit fornisce componenti di sviluppo complementari, non un altro runtime di agenti ospitato equivalente.
Come iniziare con l’OpenAI Agents API
Passo 1: Configurare l’accesso API
Usa una chiave di progetto OpenAI Platform con i permessi di agente e inferenza richiesti dai prerequisiti del quickstart. Gli esempi curl sono destinati a una shell compatibile con Bash con curl installato; l’esempio PowerShell imposta solo la variabile d’ambiente. Tieni le chiavi fuori dal controllo di versione.
Esempio di codice Bash: Esegui i seguenti comandi in un terminale compatibile con Bash.
export OPENAI_API_KEY="your-openai-api-key"
Esempio di codice PowerShell: Imposta la chiave API nel processo PowerShell corrente.
$env:OPENAI_API_KEY="your-openai-api-key"
Passo 2: Creare il primo agente
Esempio di codice Bash: Esegui i seguenti comandi in un terminale compatibile con Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write reliable Python code, execute it, and report observed results."
},
"environment": {"type": "openai_hosted", "container_size": "small"},
"input": "Calculate the mean and standard deviation of [12,15,19,20,24] in Python.",
"stream": true
}'
La sessione avvia il primo turno e trasmette in streaming eventi di stato mentre l’agente esegue strumenti e prepara una risposta.
Passo 3: Abilitare l’esecuzione multi-agente
Esempio di codice Bash: Esegui i seguenti comandi in un terminale compatibile con Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Delegate independent analyses and reconcile the results.",
"multi_agent": {"enabled": true, "max_concurrent_subagents": 2}
},
"environment": {"type": "none"},
"input": "Compare two release changes: date filtering in search and export URL behavior.",
"stream": true
}'
Passo 4: Continuare una sessione esistente
Esempio di codice Bash: Esegui i seguenti comandi in un terminale compatibile con Bash.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Summarize the findings in an executive report."}]}]}]}'
Archivia gli identificatori di sessione, applica meccanismi di retry e distingui le nuove istruzioni dai messaggi usati per indirizzare il lavoro attivo.
Passo 5: Ispezionare i risultati e fare clean-up
Esempio di codice Bash: Esegui i seguenti comandi in un terminale compatibile con Bash.
Lo sforzo di ragionamento influisce su latenza, consumo di token e profondità della pianificazione. Seleziona lo sforzo supportato dal modello e dall’interfaccia scelti seguendo le indicazioni ufficiali su GPT-6; le impostazioni a livello di modello non devono essere date per scontate come identiche per ogni endpoint.
Come creare un agente IA con CometAPI?
CometAPI può fornire l’inferenza del modello per un’applicazione di agente personalizzata. La tua applicazione rimane responsabile del loop dell’agente, dell’esecuzione degli strumenti, dello stato di sessione, del recupero e di qualsiasi instradamento tra i modelli supportati. Questo ti offre controllo sull’orchestrazione, rendendo però tale infrastruttura a tuo carico.
Scegli l’integrazione nativa con l’Agents API quando vuoi che OpenAI gestisca l’esecuzione dell’agente e lo stato della sessione. Scegli un’applicazione basata su CometAPI quando vuoi creare e gestire la tua orchestrazione attorno alle API dei modelli supportati. L’accesso a un modello tramite CometAPI non stabilisce di per sé il supporto per gli endpoint di sessione nativi dell’Agents API; verifica l’interfaccia che intendi usare. Anche i costi seguono percorsi diversi: l’uso nativo è fatturato da OpenAI, mentre un’applicazione personalizzata combina gli addebiti di CometAPI con i costi della tua infrastruttura.
Passo 1: Connettersi a CometAPI
Esempio di codice Bash: Esegui i seguenti comandi in un terminale compatibile con Bash.
Esempio di codice Python: Invia una richiesta di inferenza del modello e stampa la risposta.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.responses.create(
model="gpt-6-astra",
input=(
"Analyze an API latency spike after a database migration. "
"Identify possible causes and prioritize diagnostic steps."
),
)
print(response.output_text)
Gli sviluppatori possono accedere alla API GPT-6 Astra in CometAPI. L’esempio sopra esegue un’inferenza del modello; implementare il loop degli strumenti descritto di seguito è una responsabilità separata dell’applicazione.
Passo 2: Aggiungere un livello di esecuzione degli strumenti
Un controller personalizzato può istruire il modello, ispezionare le richieste di chiamata agli strumenti, autorizzare ed eseguire azioni, restituire i risultati e ripetere fino al completamento o a un limite predefinito. Imposta limiti su turni, chiamate agli strumenti, tempo di esecuzione e spesa; richiedi conferme indipendenti per operazioni distruttive.
Quali sono le migliori applicazioni per l’OpenAI Agents API?
Software engineering: Analizzare problemi, generare modifiche al codice, eseguire test e preparare revisioni, con approvazione prima del merge o del deploy.
Data analysis and reporting: Elaborare dataset caricati, eseguire calcoli in Python, creare grafici e trasformare i risultati in report a supporto delle decisioni.
IT incident response: Ispezionare alert, correlare log, consultare runbook e raccomandare remediation, con autorizzazione umana per azioni rischiose.
Customer support automation: Recuperare record pertinenti, riassumere ticket, redigere risposte e instradare i casi irrisolti tramite accesso CRM autorizzato.
Research and document processing: Confrontare documenti, verificare affermazioni, estrarre fatti e preparare risultati con citazioni di supporto.
Valuta il tuo flusso di lavoro
Inizia con un’attività rappresentativa del tuo carico e definisci cosa significa completamento riuscito. Confronta l’agente con il tuo processo attuale usando gli stessi input e criteri di accettazione. Includi richieste di follow-up e failure degli strumenti affinché la valutazione testi anche il recupero oltre al percorso ideale.
Metrica
Misura
Motivo
Completamento delle attività
Obiettivi riusciti
Utilità end-to-end
Successo degli strumenti
Integrazioni corrette
Rilevazione dei failure
Tasso di recupero
Completamento dopo un failure
Durabilità
Tempo al completamento
Tempo trascorso
Latenza
Costo per attività completata
Spesa / attività riuscita
Efficienza
Intervento umano
Azioni manuali
Autonomia
Conformità alla sicurezza
Aderenza alle policy
Controllo del rischio
Leggi queste misure congiuntamente. Un workflow che completa più task potrebbe comunque non essere adatto se richiede frequenti correzioni manuali o supera i tuoi limiti di tempo e costo. Usa i risultati per decidere dove automatizzare, dove mantenere il controllo umano e quali failure affrontare prima di espandere l’uso.
Quanto costa l’OpenAI Agents API?
Non è prevista una tariffa separata per la piattaforma dell’harness gestito. Token del modello, chiamate agli strumenti idonei e compute ospitato opzionale determinano il costo totale d’uso. Le tariffe del modello qui sotto sono in USD per milione di token per l’elaborazione Standard con prompt a contesto breve (fino a 272K token in input), verificate il 21 ottobre 2026. Prompt più lunghi, altri livelli di elaborazione, scritture in cache e elaborazioni regionali possono cambiare la tariffa applicabile.
OpenAI model pricing
Input / 1M
Cached input / 1M
Output / 1M
GPT-6 Astra
$10.00
$1.00
$50.00
GPT-6.1 Sol
$2.00
$0.10
$10.00
GPT-6 Luna
$0.10
$0.01
$0.50
Per l’accesso ai modelli tramite CometAPI, gli sviluppatori possono usare GPT-6.1 Sol e GPT-6 Luna. La tabella sopra mostra le tariffe OpenAI; la fatturazione di CometAPI segue le proprie tariffe applicabili.
Risorsa o strumento
Configurazione / base di fatturazione
Tariffa
Hosted container — Small
1 GB di memoria; periodo di 20 minuti
$0.03 per periodo
Hosted container — Medium
4 GB di memoria; periodo di 20 minuti
$0.12 per periodo
Hosted container — Large
16 GB di memoria; periodo di 20 minuti
$0.48 per periodo
Web search
Per 1.000 chiamate; token di contenuto fatturati separatamente
$10 per 1.000 chiamate, più token di contenuto
File search storage
Per GB al giorno, oltre la franchigia gratuita
$0.10 per GB/giorno
Esempio: stima del costo di un’attività
Componente
Calcolo illustrativo
Costo
Token di input
50.000 × $10 / 1M
$0.50
Token di output
10.000 × $50 / 1M
$0.50
Ricerche web
2 × $0.01
$0.02
Small container
Un periodo di 20 minuti
$0.03
Totale
Escluse voci incidentali
$1.05
Questo totale illustrativo di $1,05 presuppone i volumi di token indicati, due ricerche, un periodo da 20 minuti di small container e nessun token di contenuto di ricerca fatturabile extra o scrittura in cache. Il costo effettivo dipende anche da retry, uso dei subagent, comportamento della cache e regole di fatturazione della sandbox applicabili alla sessione. Tieni traccia del costo per attività completata con successo su un carico di lavoro rappresentativo.
Quali sono le limitazioni dell’OpenAI Agents API?
Limiti sui dati. L’Agents API attualmente supporta la residenza dei dati solo negli Stati Uniti e non supporta la Zero Data Retention (ZDR). Un sandbox self-hosted non cambia l’idoneità ZDR. Prima di inviare materiale sensibile, verifica che i termini di retention e residenza del servizio soddisfino i tuoi requisiti.
Compatibilità di API e modelli. Le interfacce in public beta possono cambiare e le funzionalità supportate possono variare in base al modello. Testa l’esatto modello, endpoint, impostazioni di ragionamento e strumenti che la tua applicazione usa. Ripeti i controlli di integrazione quando cambi modello o adotti un aggiornamento dell’API.
Controllo dell’esecuzione. I task multi-step possono accumulare token, richiedere tempi variabili e incontrare failure degli strumenti. Imposta budget e limiti su turni e runtime, concedi solo i permessi necessari al task e monitora in modo asincrono il lavoro di lunga durata. Pianifica come recuperare chiamate agli strumenti interrotte e richiedi approvazione umana per azioni con conseguenze significative.
FAQ
Come dovrebbero ritentare i client dell’OpenAI Agents API i messaggi di follow-up?
Riusa la stessa submission key quando ritenti lo stesso messaggio logico, seguendo il pattern di input della sessione e retry. Mantieni insieme l’ID di sessione e la submission key nello stato dell’applicazione. Un’istruzione utente separata deve usare la propria chiave; una risposta HTTP persa non dovrebbe essere automaticamente trattata come una nuova istruzione.
Una sessione dell’OpenAI Agents API può cambiare modello?
L’endpoint delle impostazioni di sessione supporta l’aggiornamento di modello, sforzo di ragionamento e service tier. Gli aggiornamenti influiscono sui turni successivi; un turno attivo mantiene le impostazioni esistenti. Conferma che la configurazione risultante sia supportata dal modello selezionato e crea una nuova sessione quando devi cambiare impostazioni che questo endpoint non accetta.
Come limita l’OpenAI Agents API l’accesso di rete del sandbox?
Gli ambienti ospitati da OpenAI supportano accesso in uscita abilitato, disabilitato o ristretto. La modalità ristretta usa allowlist esplicite di host e redirect o sottodomini possono richiedere voci proprie. Configura la network policy del sandbox per i servizi necessari a un task; l’accesso di rete e le credenziali dell’applicazione sono controlli separati.
Conclusione
Valuta l’Agents API su un’attività rappresentativa che richieda diverse chiamate agli strumenti e almeno un turno di follow-up. Misura tasso di completamento, comportamento di recupero, latenza e costo per task completato con successo. Questi risultati mostreranno se l’esecuzione gestita soddisfa i requisiti della tua applicazione.
