OpenAI Agents API: il pilot sicuro parte da sandbox, rete e log

Cosa cambia davvero con Agents API

OpenAI ha annunciato Agents API il 10 settembre 2026 in public beta. L’API offre alle applicazioni un harness Codex gestito da OpenAI: mantiene sessioni, orchestra il lavoro, compatta il contesto e gestisce il recupero, mentre chi sviluppa sceglie modello, strumenti e ambiente di esecuzione.

Una sessione può durare oltre un singolo turno, ricevere nuovi input e produrre eventi o artefatti. L’agente può lavorare senza sandbox, in una sandbox ospitata da OpenAI oppure in un ambiente self-hosted collegato tramite executor. Può inoltre usare function tool, server MCP e subagent.

La novità non rende superflua l’architettura di sicurezza. Il codice generato può leggere ciò che l’ambiente espone, usare la rete consentita e invocare gli strumenti configurati. Il compito del team resta definire quel confine, osservare cosa avviene e decidere quali azioni richiedono un passaggio umano.

Agents API, Agents SDK e Responses API non sono tre nomi per la stessa cosa

Agents API è pensata per task lunghi nei quali OpenAI esegue l’harness Codex e conserva lo stato della sessione. Agents SDK lascia invece all’applicazione il controllo del loop, dello storage, delle approvazioni e dell’integrazione con il runtime. Responses API è il livello più diretto: l’applicazione chiama i modelli e costruisce o ospita l’orchestrazione necessaria.

Scegli Agents API quando il valore sta nel far proseguire un agente attraverso più passaggi senza costruire da zero gestione della sessione, compattazione e coordinamento. Se il requisito principale è possedere ogni transizione del loop o integrare approvazioni molto specifiche nel backend, confrontala seriamente con Agents SDK. Se serve una singola chiamata o un flusso corto e deterministico, Responses API può essere sufficiente.

Non migrare soltanto perché l’API è nuova. Scrivi prima il problema operativo: durata, stato da conservare, strumenti necessari, luogo in cui devono vivere i dati e persona responsabile dell’esito.

Harness

Il ciclo operativo che coordina modello, strumenti, contesto, turni e recupero. In Agents API è gestito da OpenAI.

Ambiente

Il luogo opzionale in cui l’agente accede ai file ed esegue comandi: ospitato da OpenAI oppure collegato dalla tua infrastruttura.

Sessione

L’istanza durevole dell’agente, con turni, eventi, elementi salvati e riferimenti all’ambiente.

Il primo pilot deve essere noioso, sintetico e reversibile

Evita il repository di produzione, i ticket clienti e le credenziali reali. Prepara invece una piccola cartella con file sintetici e un compito verificabile, per esempio generare e testare uno script che ordina un elenco di release fittizie. Confronta file iniziali, comandi eseguiti, artefatto finale e token usati.

Nella sandbox OpenAI il valore predefinito documentato per la rete in uscita è enabled. Per il primo pilot impostalo esplicitamente su disabled. In questo modo la prova misura sessione, file e comandi senza trasformarsi anche in un test di navigazione, download, MCP e gestione dei segreti.

Anche multi-agent va lasciato spento all’inizio. Aggiungere subagent prima di aver stabilito un comportamento di riferimento moltiplica traiettorie, costi e punti da diagnosticare. Una sola sessione con un risultato atteso è una baseline più utile.

const events = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions: [
      "Lavora soltanto sui file sintetici presenti in /workspace.",
      "Esegui il test indicato e riporta comando, esito e limiti.",
      "Non cercare alternative di rete se manca un dato."
    ].join(" "),
    multi_agent: { enabled: false }
  },
  environment: {
    type: "openai_hosted",
    network: { access: "disabled" },
    files: [/* file sintetici autorizzati */]
  },
  input: "Crea lo script richiesto, esegui il test e salva il report.",
  stream: true
});

La sandbox isola il calcolo, ma la rete va ristretta esplicitamente

La sandbox ospitata offre un workspace Linux con Python, Node.js e strumenti da riga di comando. Puoi fornire file, pacchetti, variabili, skill e plugin. Ogni elemento amplia ciò che l’agente può leggere o eseguire: configura soltanto ciò che il task richiede e fissa le versioni dei pacchetti quando la riproducibilità conta.

La rete può essere enabled, disabled oppure restricted. La modalità restricted accetta da uno a cento hostname esatti: niente wildcard, protocolli, percorsi o porte; anche sottodomini e destinazioni dei redirect vanno dichiarati. La documentazione segnala inoltre che i server MCP stdio ospitati richiedono attualmente rete enabled, un compromesso da valutare prima di usarli.

Se scegli self-hosted, OpenAI mantiene l’harness ma un executor nella tua macchina, container o sandbox esegue comandi e accede ai file. Ambienti condivisi possono vedere le stesse risorse: separali per utente o workload e non trattare “self-hosted” come sinonimo di “isolato”.

• Fase 1: dati sintetici, rete disabled, nessun MCP, nessun subagent.
• Fase 2: rete restricted con un solo hostname necessario e redirect verificati.
• Fase 3: uno strumento read-only, schema e provenienza dell’output controllati.
• Fase 4: scritture limitate a un ambiente di prova, con approvazione esterna e rollback.
• Stop: rete enabled generale, credenziali di produzione o ambienti condivisi senza una motivazione revisionata.

Tieni la chiave dell’applicazione fuori dall’ambiente dell’agente

Il quickstart richiede a una chiave applicativa i permessi api.agents.read e api.agents.write per le sessioni, più api.responses.write per l’inferenza. La documentazione impone di mantenerla fuori dalla sandbox: il codice generato non deve poter leggere la credenziale che amministra l’intero flusso.

Per un ambiente self-hosted si usa invece una chiave executor separata in CODEX_API_KEY. Serve a collegare l’ambiente e non autorizza le altre operazioni API. Va comunque esclusa da sorgenti, immagini e log, e ruotata o revocata quando necessario.

Per MCP collegati dal servizio OpenAI, un vault può associare bearer token o grant OAuth al server senza consegnare all’agente i valori segreti. Questo protegge il valore della credenziale, ma non riduce automaticamente i permessi del tool: endpoint, scope e azioni esposte vanno ancora revisionati e limitati.

APPLICAZIONE
- chiave: fuori dalla sandbox
- permessi: agents read/write + responses write
- proprietario: servizio backend

AMBIENTE SELF-HOSTED
- chiave: CODEX_API_KEY separata
- capacità: collegare l'executor
- accesso: file, processi e rete del workload isolato

MCP
- origine connessione: servizio OpenAI oppure ambiente
- tool consentiti: elenco esplicito
- scritture: assenti nel pilot
- credenziale: vault o meccanismo separato documentato

Aggiungi subagent solo quando i task sono davvero indipendenti

Agents API può dare a ogni subagent un contesto separato e farli lavorare in parallelo, mentre l’agente principale coordina e combina i risultati. La documentazione raccomanda questo schema per domande indipendenti, come revisionare documenti diversi o indagare cause separate.

Passaggi brevi o dipendenti devono restare nell’agente principale. Se più agenti modificano gli stessi file, serve coordinamento esplicito; nella pratica è spesso più semplice assegnare proprietà non sovrapposte oppure eseguire in sequenza.

Per abilitare il multi-agent si imposta multi_agent.enabled e si limita max_concurrent_subagents. Quel numero è un tetto di concorrenza, non una misura di qualità. Prima di aumentarlo, confronta accuratezza, latenza, uso token e conflitti con la baseline a un agente.

• DottorLone: organizzare sessioni agentiche parallele senza modifiche concorrenti →

Definisci il successo prima di guardare un output convincente

La dashboard e la cronologia della sessione permettono di ispezionare turni, chiamate ai tool e subagent. Gli eventi mostrano l’attività in corso; l’uso registrato distingue i token dei turni dell’agente principale e dei subagent. La documentazione specifica però che recupero delle trace via API ed exporter esterni non fanno parte della public beta.

Un log non dimostra da solo correttezza. Per il pilot stabilisci prima condizioni osservabili: file ammessi, rete prevista, test da eseguire, formato dell’artefatto, tetto di spesa, comportamento quando manca un input e assenza di scritture esterne.

Ripeti lo stesso caso alcune volte perché il comportamento dei modelli non è perfettamente deterministico. Valuta separatamente risultato finale e condotta: un output corretto ottenuto usando una fonte non consentita o saltando il test resta un fallimento operativo.

Caso: <nome del task sintetico>
Sessione: <ID>
Input e file autorizzati: <elenco>
Rete attesa: disabled
Tool e MCP attesi: nessuno
Subagent attesi: zero

Risultato funzionale: superato / fallito
Test dichiarato: <comando>
Test osservato nei log: sì / no
File modificati: <elenco reale>
Accessi o azioni inattese: nessuna / <spiega>
Token e costo registrati: <valori dashboard>
Decisione: stop / ripeti / amplia una sola capacità

Checklist e fonti primarie prima del primo uso

La fotografia è aggiornata al 14 settembre 2026. Agents API è in public beta: header, namespace SDK, modelli consentiti, prezzi, limiti, funzioni di tracing e comportamento delle sandbox possono cambiare. Verifica sempre documentazione e dashboard del progetto prima di applicare configurazioni o stime.

Non ho eseguito il quickstart su una sessione reale e non attribuisco all’API risultati di affidabilità misurati da DottorLone. Le percentuali riportate da clienti nella pagina di lancio sono dichiarazioni dei rispettivi clienti, non benchmark indipendenti usati in questa guida.

• Il caso d’uso richiede davvero una sessione lunga e gestita.
• L’ambiente è dedicato e contiene soltanto file sintetici o autorizzati.
• network.access è impostato esplicitamente, non lasciato al default.
• La chiave applicativa resta fuori dall’ambiente dell’agente.
• Tool, MCP e credenziali hanno scope minimo e sono inventariati.
• Multi-agent è disabilitato finché la baseline a un agente non è stabile.
• Esito, test, file, tool call, token e limiti sono verificati nei log.
• Esiste un tetto di spesa e una condizione di arresto.
• Ogni ampliamento introduce una sola nuova capacità e un test dedicato.
• Una persona revisiona il risultato prima di qualunque effetto esterno.

• OpenAI: annuncio di Agents API del 10 settembre 2026 ↗
• OpenAI Docs: panoramica di Agents API ↗
• OpenAI Docs: quickstart, header beta e permessi della chiave ↗
• OpenAI Docs: sandbox ospitata e controllo della rete ↗
• OpenAI Docs: isolamento, rete e separazione delle credenziali ↗
• OpenAI Docs: orchestrazione multi-agent ↗
• OpenAI Docs: log, trace e uso token ↗
• DottorLone: distinguere skill, MCP e plugin →
• DottorLone: proteggere i confini di fiducia nei tool degli agenti →