Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo di Lambda MicroVMS come sandbox per l'API OpenAI Agents

Puoi utilizzare AWS Lambda MicroVMS come ambiente ospitato autonomamente per gli agenti creato con l'API OpenAI Agents, mantenendo i file dell'area di lavoro, l'esecuzione degli strumenti e l'accesso alla rete nell'infrastruttura che controlli. OpenAI esegue il cablaggio degli agenti; Lambda MicroVM esegue le tue attività. In questo esempio, viene eseguitocodex exec-server, che esegue le chiamate agli strumenti dell'agente e contiene i file dello spazio di lavoro della sessione. Sei tu a decidere il contenuto dell'immagine, i percorsi di rete che l'esecutore può intraprendere e AWS le risorse a cui è destinato il suo ruolo di esecuzione.

Ogni MicroVM viene eseguita come un Firecracker-isolated ambiente che si avvia da un'istantanea dell'immagine. La durata totale di una microVM è fino a 8 ore, inclusi i tempi di esecuzione e di sospensione. Terminalo dopo l'ultimo turno o sospendilo tra un turno e l'altro. Si crea un'immagine riutilizzabile, quindi si avvia una MicroVM dall'applicazione o da un webhook launcher. Entrambi gli approcci utilizzano la stessa immagine e le stesse credenziali. Per maggiori dettagli, consulta l'esempio di riferimento per la sandbox self-hosted dell'API OpenAI Agents su Lambda MicroVMS.

Come funziona

Nel percorso gestito dal webhook, una funzione Lambda di avvio avvia una microVM quando la sessione richiede per la prima volta un esecutore. Riutilizza la microVM esistente, riprendendola prima se sospesa. L'applicazione la termina dopo l'ultimo turno. La Figura 1 mostra il flusso:

Figura 1. Webhook-managed provisioning per una sandbox dell'API Agents su AWS Lambda MicroVMS.

Mantieni segrete la chiave dell'applicazione e la firma del webhook all'esterno della MicroVM. Il launcher passa solo l'ARN segreto della chiave esecutrice; la VM recupera la chiave utilizzando il suo ruolo di esecuzione.

Proprietà chiave

Prerequisiti

Preparazione dell'immagine MicroVM

Crea un'immagine che includa l'interfaccia a riga di comando del Codex, le dipendenze degli strumenti, una directory di lavoro ad esempio e un server HTTP per /workspace gli hook del ciclo di vita.

Confeziona il server Dockerfile e aggancia il server in un artefatto Amazon S3, quindi crea l'codex-executorimmagine con 8 GB di memoria di base (4 vCPU di base). Abilita gli hook selezionati nella configurazione dell'immagine e imposta la porta hook in modo che corrisponda al tuo server. Tieni gli ID di sessione, le credenziali e le connessioni live executor fuori dall'istantanea dell'immagine. Per la configurazione di build e hook, vedere. Immagini MicroVM

All'avvio, l'applicazione o il launcher serializza i seguenti valori come JSON in: runHookPayload

Ritorna dall'/runhook una volta avviato il processo di esecuzione, senza attendere la fine del turno, per evitare un timeout dell'hook.

Avvio di MicroVMS

Puoi avviare MicroVMS dalla tua applicazione o da un webhook launcher. In entrambi i casi, mantieni aperto il flusso degli eventi della sessione fino alla fine del turno.

Application-managed approvvigionamento

Webhook-managed approvvigionamento

L'applicazione crea la sessione, apre il relativo stream e invia l'input. Il launcher si occupa del resto quando arriva il webhook.

L'esempio di riferimento salva l'ID MicroVM nei metadati della sessione. Le consegne simultanee di webhook possono avviare VM aggiuntive prima che l'ID venga salvato. Prima dell'uso in produzione, impedite gli avvii simultanei per la stessa sessione e deduplicate gli eventi webhook.

Fine di un turno

La Figura 2 mostra il ciclo di vita della microVM per un singolo turno e il percorso opzionale di sospensione e ripresa per i turni successivi.

Figura 2. Ciclo di vita di MicroVM per un turno di API Agents. RunMicrovmavvia la microVM, l'/runhook avvia l'esecutore, l'ambiente si connette, il turno viene eseguito e il turno termina. Nel percorso a turno singolo, si recuperano i file e si chiama. TerminateMicrovm Nel percorso a più turni, la microVM si sospende dopo il turno e riprende alla successiva richiesta di connessione.

Nello stream della sessione, attendi agent.session.turn.completed che sia agent.session.turn.failed agent.session.turn.cancelled l'agente principale. event.turn.subagent_id null I subagent condividono la MicroVM, quindi gli eventi del terminale non attivano la pulizia. Recupera i file che ti servono. Dopo l'ultimo turno, chiama TerminateMicrovm e conferma che la VM arriva. TERMINATED Per i turni successivi, mantienila in funzione o sospendila. Esegui la pulizia se l'applicazione riscontra un errore.

I risultati a turni arrivano come eventi di streaming, non come abbonamenti ai webhook. Il agent.session.failed webhook copre gli errori di sessione ma non tutti i turni falliti. Per questo motivo, non terminate l'operazione agent.session.idle da sola, perché può arrivare prima dell'inizio dell'input in attesa.

Per limitare la durata della microVM se la pulizia non viene eseguita, configura le seguenti impostazioni all'avvio:

Per i controlli relativi alla durata e allo stato di inattività, consulta. Esecuzione e utilizzo di MicroVMS

Elimina la sessione separatamente. L'eliminazione di una sessione non arresta la MicroVM né invia un webhook di cancellazione. Mantieni segrete l'immagine e la chiave di esecuzione per poterle riutilizzare. Per la gestione dei turni di follow-up, consulta Sandbox lifecycle. https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws

Sospensione e ripresa tra un turno e l'altro

Per preservare la memoria e lo stato del disco tra un turno e l'altro, sospendi la MicroVM al termine del turno dell'agente principale e al termine di tutti gli strumenti e i subagent. Riprendi la stessa MicroVM quando la sessione successiva richiede un esecutore.

Rete

Consenti le connessioni in uscita richieste dall'esecutore a OpenAI e l'accesso a Secrets Manager. Per accedere a risorse private o applicare le tue restrizioni di rete, collega un connettore di uscita VPC al momento dell'avvio. Consulta Utilizzo dei connettori di rete in uscita.

L'esempio supporta l'upload e il download di file tramite l'endpoint HTTPS di MicroVM, utilizzando un token di autenticazione con ambito alla porta del server.

Monitoraggio

Esegui uno degli esempi, quindi conferma che i hello.txt download, la microVM raggiunga e che la sessione eliminata restituisca TERMINATED HTTP 404.

Log del launcher. Controlla i log della funzione Lambda di avvio in CloudWatch Logs:

aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m

Esecuzione di MicroVMS. Imposta MICROVM_IMAGE_ARN l'ARN dell'immagine, utilizza la AWS regione della distribuzione ed elenca i MicroVM per l'immagine:

aws lambda-microvms list-microvms \
  --image-identifier "$MICROVM_IMAGE_ARN" \
  --query 'items[].{id:microvmId,state:state}' --output table

Registra insieme gli ID di sessione e MicroVM in modo da poter tracciare un'esecuzione dall'inizio alla fine. Tieni le credenziali e i corpi grezzi dei webhook lontani dai log.

Risoluzione dei problemi

In caso di errori di connessione, ispeziona agent.session.environment.failed gli eventi e i registri degli esecutori. Per il contratto di esecuzione condiviso, vedi sandbox. Self-hosted

Risorse correlate