Panoramica

L'API Agents è disponibile in versione beta. Consente agli sviluppatori di creare applicazioni con un agente Codex gestito da OpenAI, in grado di lavorare in più passaggi e proseguire nella stessa sessione.

La tua applicazione fornisce l'attività da svolgere, gli strumenti e la configurazione. OpenAI gestisce la sessione dell'agente e il coordinamento tra il suo modello e i suoi strumenti.

Cosa può fare un agente?

A seconda degli strumenti e dell'ambiente di esecuzione a disposizione, un agente può eseguire codice, modificare file, usare connessioni MCP e generare file per la tua applicazione. Puoi inviare ulteriori istruzioni o proseguire con un'altra attività nella stessa sessione.

Consulta la panoramica dell'API Agents per scoprire le funzionalità supportate e vedere alcuni esempi.

Come posso iniziare?

1. Crea una chiave API per l'applicazione nel tuo progetto sulla piattaforma OpenAI. Concedi le autorizzazioni api.agents.read e api.agents.write per le sessioni, oltre a api.responses.write per le richieste al modello.

2. Segui la guida rapida per configurare un agente, creare una sessione e inviare un'attività.

3. Segui gli eventi della sessione per verificare l'avanzamento e i risultati. Salva l'ID della sessione se vuoi proseguire il lavoro.

Conserva la tua chiave API al di fuori della sandbox dell'agente. Le richieste richiedono l'intestazione OpenAI-Beta: agents=v1. Gli SDK di OpenAI aggiungono questa intestazione automaticamente.

Il mio agente ha bisogno di una sandbox?

Scegli l'ambiente più adatto all'attività:

• Nessun ambiente: l'agente risponde alle domande o usa strumenti esterni senza bisogno di comandi shell integrati o di file nell'area di lavoro.

• Sandbox ospitata da OpenAI: l'agente deve eseguire script o lavorare con i file e vuoi che OpenAI gestisca la sua sandbox.

• Sandbox ospitata sulla tua infrastruttura: hai bisogno di usare la tua infrastruttura, il tuo software o la tua rete privata. La tua applicazione gestisce il ciclo di vita dell'ambiente.

Consulta l'architettura dell'API Agents per i dettagli sulla configurazione.

Dove posso esaminare una sessione?

Apri i log nella dashboard della piattaforma, seleziona Agenti e cerca l'ID della sessione. Puoi esaminare i turni, le chiamate agli strumenti e l'attività dei sottoagenti.

La guida all'osservabilità spiega anche come esaminare il consumo di token registrato.

Cosa fare se il flusso di eventi si interrompe?

Recupera la sessione esistente e i relativi elementi salvati prima di riprovare. In questo modo puoi verificare cosa è successo prima di inviare altro lavoro.

Un turno completato non significa che tutti gli strumenti abbiano funzionato correttamente. Esamina il risultato riportato. Il solo fatto che una sessione sia inattiva non conferma che l'attività sia stata completata correttamente.

Come viene fatturato l'utilizzo?

Alle richieste al modello si applicano le tariffe API del modello selezionato. Agli strumenti OpenAI e alle sandbox ospitate da OpenAI si applicano le rispettive tariffe per strumenti e container.

Consulta i prezzi delle API per le tariffe aggiornate.

Come vengono gestiti i dati e i file delle sessioni?

L'API Agents conserva lo stato della sessione per consentire al lavoro di proseguire da un turno all'altro. Puoi eliminare le sessioni e gli artefatti pubblicati quando non sono più necessari. Salva tutti i file che ti servono prima di eliminare una sessione.

Al momento l'API Agents supporta la residenza dei dati solo negli Stati Uniti. Non supporta l'assenza di conservazione dei dati, nemmeno quando usi una sandbox ospitata sulla tua infrastruttura. Consulta la documentazione dell'API Agents per i dettagli sui controlli dei dati.