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:

1. L'applicazione crea una sessione ospitata autonomamente e invia input all'API degli agenti.

2. Quando la sessione richiede un esecutore, OpenAI invia un agent.session.action_required webhook con un'environment_connectionazione a un endpoint Amazon API Gateway presente nel tuo account.

3. Una funzione Lambda di avvio verifica la firma del webhook, recupera la sessione corrente e conferma che il gestore ne è il proprietario.

4. Il launcher chiama RunMicrovm con l'immagine, il ruolo di esecuzione, i connettori di rete e un runHookPayload file contenente i valori di connessione della sessione.

5. L'/runhook della MicroVM utilizza il suo ruolo di esecuzione IAM per recuperare la chiave dell'esecutore da AWS Secrets Manager e avviare Codex.

6. L'esecutore si registra con OpenAI all'indirizzo. https://api.openai.com Quindi apre una WebSocket connessione sicura per ricevere i comandi degli strumenti e wss://codex-cloud-environments.chatgpt.com restituire i risultati.

7. L'applicazione può caricare file di input e scaricare file di output tramite l'endpoint HTTPS autenticato della MicroVM. Segue il flusso degli eventi della sessione e può sospendere la MicroVM tra un turno e l'altro.

8. Dopo l'ultimo turno, l'applicazione termina la microVM.

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

Proprietà	Vantaggio
Isolamento con petardi	Hardware-virtualized limite per la MicroVM di ogni sessione
Snapshot-based avvio	Ogni MicroVM viene avviata da un'istantanea dell'immagine preparata
IAM tramite il ruolo di esecuzione	L'/runhook legge la chiave dell'esecutore con il ruolo di esecuzione della microVM; la chiave non è memorizzata nell'immagine
Durata statica	Ogni MicroVM può funzionare fino a 8 ore, incluso il tempo di sospensione
Sospendi e riprendi tra un turno e l'altro	Lo stato della memoria e del disco viene preservato in modo che i turni successivi continuino nello stesso ambiente
Usage-based calcolo	L'esecuzione delle VM comporta costi di elaborazione. La sospensione interrompe i costi di elaborazione e archiviazione delle istantanee e viene fatturata separatamente. reads/writes

Prerequisiti

• Un AWS account con accesso a Lambda MicroVMS, una versione AWS CLI che include lambda-microvms e autorizzazioni per creare immagini ed eseguire MicroVMS. Per creare il bucket degli artifact e il ruolo di creazione delle immagini (IAM) di Amazon Simple Storage Service (Amazon S3), consulta. AWS Identity and Access Management Crea la tua prima microVM Lambda

• Una chiave applicativa OpenAI (OPENAI_API_KEY) per creare sessioni e inviare input.

• Una chiave esecutiva OpenAI separata (OPENAI_EXECUTOR_API_KEY) con la stessa organizzazione, progetto e account utente o servizio della sessione. Archiviala in Secrets Manager, ad esempio come. codex/agents-api/executor L'/runhook lo passa a Codex comeCODEX_API_KEY.

• Un ruolo di esecuzione di MicroVM in grado di leggere solo la chiave segreta dell'esecutore. Se il segreto utilizza una AWS chiave Key Management Service (AWS AWS KMS) gestita dal cliente, aggiungi l'autorizzazione di decrittografia. Consulta Sicurezza e autorizzazioni.

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.

Gancio	Comportamento
/aws/lambda-microvms/runtime/v1/ready	Restituisce HTTP 200 quando il server è pronto per l'acquisizione dell'istantanea da parte di Lambda. L'esecutore rimane disconnesso.
/aws/lambda-microvms/runtime/v1/run	Legge i valori di connessione della sessione e l'ARN segreto, recupera la chiave dell'esecutore e avvia l'esecutore.
/aws/lambda-microvms/runtime/v1/validate	Facoltativo. Verifica che Codex sia eseguito e che lo spazio di lavoro sia scrivibile.
/aws/lambda-microvms/runtime/v1/suspend	Obbligatorio per. suspend/resume Arresta l'esecutore e svuota le scritture prima di creare AWS istantanee della VM.
/aws/lambda-microvms/runtime/v1/resume	suspend/resumeObbligatorio per. Recupera nuovamente la chiave e riavvia l'esecutore per lo stesso ambiente.
/aws/lambda-microvms/runtime/v1/terminate	Facoltativo. Ferma l'esecutore e svuota le scritture prima della terminazione.

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

Valore	Scopo
session.environment.id	Identifica l'ambiente a cui l'esecutore si connette
session.environment.remote_url	Fornisce l'URL di connessione OpenAI dell'esecutore
Executor-key ARN segreto	Consente all'hook di recuperare la chiave utilizzando il ruolo di esecuzione della microVM

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

1. Crea una sessione ospitata autonomamente la cui directory di lavoro corrisponde all'immagine, quindi apri il relativo flusso di eventi.

2. Chiama RunMicrovm con l'ARN e la versione dell'immagine, il ruolo di esecuzione, i connettori di rete e. runHookPayload Salva il risultato microvmId insieme all'ID della sessione.

3. Attendiagent.session.environment.connected, quindi invia l'input e segui il risultato del turno.

4. Recupera i file di output e termina il turno come descritto inFine di un turno.

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.

1. Distribuisci una POST /webhook route in Amazon API Gateway che richiami il launcher. Concedi al launcher il permesso di leggere le sue credenziali, ispezionare, avviare, riprendere e terminare MicroVMS dall'immagine selezionata, passare il ruolo di esecuzione di MicroVM e utilizzare i connettori di rete configurati.

2. agent.session.action_requiredRegistra l'endpoint per e. agent.session.failed Memorizza il segreto di firma dell'endpoint in Secrets Manager con la chiave applicativa del launcher.

3. Verifica la firma del webhook rispetto al corpo della richiesta non elaborata prima di accedere alle sessioni o avviare il calcolo. Quindi recupera la sessione corrente e conferma che il gestore ne è il proprietario, ad esempio abbinando un agente salvato dedicato.

4. Se environment_connection è ancora in sospeso, ispeziona la microVM registrata con. GetMicrovm Riprendila con se è stata sospesa. ResumeMicrovm Chiama RunMicrovm solo se non è registrata alcuna VM, quindi salva il suo ID. Se il salvataggio non riesce, interrompi la VM che hai avviato. Se l'esecutore si connette prima del timeout della connessione, l'input in attesa procede senza reinvio.

5. Per un agent.session.failed evento, recupera la sessione corrente e termina la microVM registrata solo se il suo stato è ancora fallito. Ignora le sessioni eliminate, le azioni risolte e le sessioni di proprietà di un altro gestore.

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:

Impostazione	Linee guida
maximumDurationInSeconds	Imposta un limite massimo per il carico di lavoro, ad esempio 900 per un test di 15 minuti. Questo limite si applica anche mentre il lavoro è in corso.
maxIdleDurationSeconds	Copri il carico di lavoro previsto. Lambda misura il traffico in entrata, quindi la connessione in uscita dell'esecutore non azzera questo timer.
suspendedDurationSeconds / autoResumeEnabled	Usa 0/false per il pattern a turno singolo, che non riprende le MicroVM sospese.

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.

• Imposta un valore diverso da zero. suspendedDurationSeconds I costi di archiviazione delle istantanee si applicano mentre la MicroVM è sospesa.

• Abilita l'/suspendhook per svuotare le scritture e chiudere le connessioni e l'/resumehook per aggiornare le credenziali e ricollegare l'esecutore.

• Il percorso gestito dall'applicazione riprende la macchina virtuale prima di inviare l'input successivo. Nel percorso gestito dal webhook, l'invio dell'input attiva la richiesta di connessione che riprende la VM. Il turno procede una volta che l'esecutore si riconnette.

Nota

maximumDurationInSecondslimita il tempo totale di funzionamento e di sospensione a 8 ore. Per riprendere su richiesta, chiamaResumeMicrovm. Il ripristino automatico richiede il traffico in entrata verso la MicroVM; l'input dell'API degli agenti da solo non lo riprende.

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

Caratteristiche	Cosa controllare
La firma Webhook viene rifiutata	Utilizza il segreto di firma dell'endpoint e verifica il corpo della richiesta non modificato.
Nessun avvio di MicroVM	Controlla l'abbonamento al webhook, il filtro di proprietà della sessione, l'environment_connectionazione in sospeso e le autorizzazioni IAM del launcher.
La creazione dell'immagine non riesce	Controlla l'artefatto di Amazon S3, il ruolo di creazione dell'immagine e la risposta dell'/readyhook.
/runfallisce o scade	Controlla l'accesso segreto e l'avvio dell'esecutore. Ritorna dopo aver iniziato il processo, non dopo il turno.
L'esecutore non riesce a connettersi	Controlla l'ID dell'ambiente, l'URL remoto, la proprietà della chiave e l'accesso alla rete in uscita.
MicroVM si ferma durante un turno	Controlla la durata massima e la politica di inattività. Il traffico degli esecutori in uscita non viene conteggiato come attività in entrata.

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

• AWS Lambda MicroVM

• Esecuzione e utilizzo di MicroVMS

• Sicurezza e autorizzazioni

• Documentazione di riferimento dell’API RunMicrovm

• Sandbox ospitate autonomamente dall'API OpenAI Agents

• API OpenAI Agents sulla guida AWS