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 eseguito`codex 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 ](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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.
1. Quando la sessione richiede un esecutore, OpenAI invia un `agent.session.action_required` webhook con un'`environment_connection`azione a un endpoint Amazon API Gateway presente nel tuo account.
1. Una funzione Lambda di avvio verifica la firma del webhook, recupera la sessione corrente e conferma che il gestore ne è il proprietario.
1. 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.
1. L'`/run`hook della MicroVM utilizza il suo ruolo di esecuzione IAM per recuperare la chiave dell'esecutore da AWS Secrets Manager e avviare Codex.
1. 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.
1. 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.
1. 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](microvms-getting-started.md)
+ 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'`/run`hook lo passa a Codex come`CODEX_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](microvms-security.md).
## 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-executor`immagine 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](microvms-images.md)
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'`/run`hook 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.
1. 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.
1. Attendi`agent.session.environment.connected`, quindi invia l'input e segui il risultato del turno.
1. Recupera i file di output e termina il turno come descritto in[Fine di un turno](#microvms-integrations-openai-agents-api-ending-turn).
### 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.
1. `agent.session.action_required`Registra l'endpoint per e. `agent.session.failed` Memorizza il segreto di firma dell'endpoint in Secrets Manager con la chiave applicativa del launcher.
1. 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.
1. 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.
1. 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 ](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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. `RunMicrovm`avvia la microVM, l'`/run`hook 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](microvms-launching.md)
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](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'`/suspend`hook per svuotare le scritture e chiudere le connessioni e l'`/resume`hook 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**
`maximumDurationInSeconds`limita il tempo totale di funzionamento e di sospensione a 8 ore. Per riprendere su richiesta, chiama`ResumeMicrovm`. 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](microvms-networking.md#microvms-networking-connectors).
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 ](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)
## Risorse correlate
+ [AWS Lambda MicroVM](lambda-microvms-guide.md)
+ [Esecuzione e utilizzo di MicroVMS](microvms-launching.md)
+ [Sicurezza e autorizzazioni](microvms-security.md)
+ [Documentazione di riferimento dell’API RunMicrovm](https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html)
+ [Sandbox ospitate autonomamente dall'API OpenAI Agents ](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)
+ [API OpenAI Agents sulla guida AWS](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)