# Uso de las microVM de Lambda como entorno de pruebas para la API de agentes de OpenAI
Puede utilizar las microVM de AWS Lambda como entorno autohospedado para los agentes creados con la API de agentes de OpenAI, manteniendo los archivos del espacio de trabajo, la ejecución de las herramientas y el acceso a la red en la infraestructura que usted controle. OpenAI ejecuta el arnés del agente; la microVM de Lambda ejecuta sus tareas. En este ejemplo, se ejecuta `codex exec-server`, lo que a su vez ejecuta las llamadas a las herramientas del agente y guarda los archivos del espacio de trabajo de la sesión. Usted decide el contenido de la imagen, las rutas de red que puede utilizar el ejecutor y los recursos de AWS a los que está limitada su función de ejecución.
Cada una de las microVM se ejecuta como un entorno aislado de Firecracker que se inicia a partir de una instantánea de su imagen. La vida útil total de una microVM es de hasta 8 horas, incluido el tiempo de ejecución y el tiempo de suspensión. Finalícela después del último turno o suspéndala entre turnos. Cree una imagen reutilizable y, a continuación, inicie una microVM desde su aplicación o desde un iniciador de webhooks. Ambos enfoques utilizan la misma imagen y las mismas credenciales. Para obtener más información, consulte el [ejemplo de referencia](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) del entorno de pruebas autohospedado de la API de agentes de OpenAI en las microVM de Lambda.
## Funcionamiento
En la ruta administrada por webhook, una función de Lambda del iniciador da inicio a una microVM cuando la sesión necesita por primera vez un ejecutor. Reutiliza la microVM existente y, si esta está suspendida, la reanuda primero. La aplicación la finaliza tras el último turno. En la figura 1 se muestra el flujo:
1. La aplicación crea una sesión autohospedada y envía información a la API de agentes.
1. Cuando la sesión necesita un ejecutor, OpenAI envía un webhook de `agent.session.action_required` con una acción de `environment_connection` a un punto de conexión de Amazon API Gateway de su cuenta.
1. Una función de Lambda del iniciador verifica la firma del webhook, recupera la sesión actual y confirma que es propiedad del controlador.
1. El iniciador llama a la `RunMicrovm` con la imagen, la función de ejecución, los conectores de red y una `runHookPayload` que contiene los valores de conexión de la sesión.
1. El enlace de `/run` de la microVM utiliza su función de ejecución de IAM para recuperar la clave ejecutora de AWS Secrets Manager e iniciar Codex.
1. El ejecutor se registra con OpenAI en `https://api.openai.com`. A continuación, se abre una conexión WebSocket segura a `wss://codex-cloud-environments.chatgpt.com` para recibir los comandos de la herramienta y devolver los resultados.
1. Su aplicación puede cargar los archivos de entrada y descargar los archivos de salida mediante el punto de conexión HTTPS autenticado de la microVM. Sigue el flujo de eventos de la sesión y tiene capacidad para suspender la microVM entre turnos.
1. Una vez terminado el último turno, la aplicación finaliza la microVM.
Figura 1. Aprovisionamiento administrado por webhook para un entorno de pruebas de la API de agentes en microVM de Lambda AWS
Mantenga la clave de la aplicación y el secreto de la firma del webhook fuera de la microVM. El iniciador solo pasa el ARN del secreto de la clave del ejecutor; la máquina virtual recupera la clave mediante su rol de ejecución.
## Propiedades clave
| Propiedad | Benefit |
| --- | --- |
| Aislamiento de Firecracker | Límite virtualizado mediante hardware para la microVM de cada sesión |
| Inicio basado en instantáneas | Cada microVM se inicia a partir de una instantánea de su imagen preparada |
| IAM a través del rol de ejecución | El enlace de /run lee la clave del ejecutor con el rol de ejecución de la microVM; la clave no se almacena en la imagen |
| Duración con estado | Cada microVM puede funcionar hasta 8 horas, incluido el tiempo de suspensión |
| Suspensión y reanudación entre turnos | El estado de la memoria y del disco se conservan para que los siguientes turnos continúen en el mismo entorno |
| Procesamiento basado en el uso | Las máquinas virtuales en ejecución generan cargos por proceso. La suspensión detiene los cargos de proceso; el almacenamiento de instantáneas y las lecturas/escrituras se facturan por separado. |
## Requisitos previos
+ Una cuenta AWS con acceso a microVM de Lambda, una versión de AWS de la CLI que incluye `lambda-microvms` y permisos para crear imágenes y ejecutar microVM. Si desea crear el bucket de artefactos de Amazon Simple Storage Service (Amazon S3) y el rol de compilación de imágenes de AWS Identity and Access Management (IAM), consulte [Creación de la primera MicroVM de Lambda](microvms-getting-started.md).
+ Una clave de aplicación de OpenAI (`OPENAI_API_KEY`) para la creación de sesiones y el envío de entradas.
+ Una clave ejecutora de OpenAI independiente (`OPENAI_EXECUTOR_API_KEY`) con la misma organización, proyecto y cuenta de usuario o de servicio que la sesión. Guárdelo en Secrets Manager, por ejemplo, como `codex/agents-api/executor`. El enlace de `/run` lo pasa a Codex como `CODEX_API_KEY`.
+ Un rol de ejecución de microVM que solo puede leer el secreto de la clave ejecutora. Si el secreto utiliza una clave del Servicio de administración de claves de AWS (AWS AWS KMS) administrada por el cliente, añada un permiso de descifrado. Consulte [Seguridad y permisos](microvms-security.md).
## Preparación de la imagen de la microVM
Cree una imagen que incluya la CLI de Codex, las dependencias de sus herramientas, un directorio de trabajo, como por ejemplo, `/workspace`, y un servidor HTTP para los enlaces del ciclo de vida.
| Enlace | Comportamiento |
| --- | --- |
| /aws/lambda-microvms/runtime/v1/ready | Devuelve HTTP 200 cuando el servidor está preparado para que Lambda tome la instantánea. El ejecutor permanece desconectado. |
| /aws/lambda-microvms/runtime/v1/run | Lee los valores de conexión de la sesión y el ARN del secreto, obtiene la clave del ejecutor y lo inicia. |
| /aws/lambda-microvms/runtime/v1/validate | Optional. Comprueba que Codex se esté ejecutando y que se puede escribir en el espacio de trabajo. |
| /aws/lambda-microvms/runtime/v1/suspend | Necesario para suspender/reanudar. Detiene el ejecutor y vacía las escrituras antes de que AWS tome instantáneas de la máquina virtual. |
| /aws/lambda-microvms/runtime/v1/resume | Necesario para suspender/reanudar. Recupera la clave una vez más y reinicia el ejecutor en el mismo entorno. |
| /aws/lambda-microvms/runtime/v1/terminate | Optional. Detiene el ejecutor y vacía las escrituras antes de la finalización. |
Empaquete el servidor `Dockerfile` y el servidor de enlaces en un artefacto de Amazon S3 y, a continuación, cree la imagen de `codex-executor` con 8 GB de memoria base (4 vCPU de referencia). Habilite los enlaces seleccionados en la configuración de la imagen y ajuste el puerto de enlace para que coincida con su servidor. Mantenga los identificadores de sesión, las credenciales y las conexiones del ejecutor activo fuera de la instantánea de la imagen. Para obtener información sobre la configuración de compilación y enlace, consulte [Imágenes de MicroVM](microvms-images.md).
En el momento del inicio, la aplicación o el iniciador serializan los siguientes valores como JSON en `runHookPayload`:
| Valor | Finalidad |
| --- | --- |
| session.environment.id | Identifica el entorno al que se conecta el ejecutor |
| session.environment.remote\_url | Brinda la URL de conexión de OpenAI del ejecutor |
| ARN del secreto de la clave del ejecutor | Permite que el enlace recupere la clave a través del rol de ejecución de la microVM |
Regrese del enlace de `/run` una vez que se inicie el proceso del ejecutor, sin esperar a que finalice el turno, para evitar que se agote el tiempo de espera del enlace.
## Iniciación de microVM
Puede iniciar microVM desde su aplicación o desde un iniciador de webhooks. En ambos casos, mantenga abierta la transmisión de eventos de la sesión hasta que termine el turno.
### Aprovisionamiento administrado por la aplicación
1. Cree una sesión autohospedada cuyo directorio de trabajo coincida con la imagen y, a continuación, abra su correspondiente transmisión de eventos.
1. Llame a la `RunMicrovm` con el ARN y la versión de la imagen, el rol de ejecución, los conectores de red y la `runHookPayload`. Guarde el `microvmId` devuelto junto con el identificador de sesión.
1. Espere a `agent.session.environment.connected`, luego envíe la entrada y siga el resultado del turno.
1. Recupere los archivos de salida y termine el turno tal y como se describe en [Finalizar un turno](#microvms-integrations-openai-agents-api-ending-turn).
### Aprovisionamiento administrado por webhook
La aplicación crea la sesión, abre su transmisión y envía la entrada. El iniciador se encarga del resto cuando llega el webhook.
1. Implemente una ruta de `POST /webhook` en Amazon API Gateway que invoque el iniciador. Conceda al iniciador permiso para leer sus credenciales, inspeccionar, lanzar, reanudar y finalizar las microVM a partir de la imagen seleccionada, asigne la función de ejecución de la microVM y utilice los conectores de red configurados.
1. Registre el punto de conexión para `agent.session.action_required` y `agent.session.failed`. Guarde el secreto de firma del punto de conexión en Secrets Manager con la clave de aplicación del iniciador.
1. Verifique la firma del webhook con el cuerpo de la solicitud sin procesar antes de acceder a las sesiones o de iniciar el proceso. A continuación, recupere la sesión actual y confirme que el controlador es el propietario, por ejemplo, al hacer coincidir un agente guardado dedicado.
1. Si la `environment_connection` aún está pendiente, inspeccione la microVM grabada con `GetMicrovm`. Reanúdela con `ResumeMicrovm` si está suspendida. Llame a `RunMicrovm` solo si no hay ninguna máquina virtual grabada y, a continuación, guarde su identificador. Si no se puede guardar, finalice la máquina virtual que inició. Si el ejecutor se conecta antes de que se agote el tiempo de espera de la conexión, la entrada en espera continúa sin volver a enviarse.
1. En el caso de un evento de `agent.session.failed`, recupere la sesión actual y finalice la microVM grabada solo si su estado sigue siendo fallido. Ignore las sesiones eliminadas, las acciones resueltas y las sesiones que pertenecen a otro controlador.
El [ejemplo de referencia](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) guarda el ID de la microVM en los metadatos de la sesión. Las entregas simultáneas de webhooks pueden iniciar máquinas virtuales adicionales antes de guardar ese ID. Antes del uso en producción, se deben evitar los lanzamientos simultáneos para la misma sesión y deduplique los eventos de webhook.
## Finalizar un turno
En la figura 2 se muestra el ciclo de vida de la microVM para un solo turno y la ruta opcional de suspensión y reanudación para los turnos que siguen.
Figura 2. Ciclo de vida de las microVM para un turno de la API de agentes. `RunMicrovm` lanza la microVM, el enlace de `/run` inicia el ejecutor, el entorno se conecta, el turno se ejecuta y el turno finaliza. En la ruta de un solo turno, se recuperan los archivos y se llama a `TerminateMicrovm`. En la ruta de varios turnos, la microVM se suspende después del turno y se reanuda cuando ocurre la siguiente solicitud de conexión.
En la secuencia de la sesión, espere a `agent.session.turn.completed`, `agent.session.turn.failed` o `agent.session.turn.cancelled` para el agente principal, donde `event.turn.subagent_id` es `null`. Los subagentes comparten la microVM, por lo que sus eventos de terminal no activan la limpieza. Recupere los archivos que necesita. Tras el último turno, llame a `TerminateMicrovm` y confirme que la máquina virtual ha alcanzado el estado `TERMINATED`. Para los turnos siguientes, manténgala funcionando o suspéndala. Ejecute la limpieza si la aplicación se encuentra con un error.
Los resultados de los turnos llegan como eventos de transmisión, no como suscripciones a webhooks. El webhook de `agent.session.failed` cubre los errores de sesión, pero no todos los turnos fallidos. Por esta razón, no finalice solo en `agent.session.idle`, ya que puede llegar antes de que comience la entrada en espera.
Para limitar la vida útil de la microVM si no se ejecuta la limpieza, configure los siguientes ajustes al iniciarla:
| Opción | Directrices |
| --- | --- |
| maximumDurationInSeconds | Establezca un límite máximo para la carga de trabajo, como 900 para una prueba de 15 minutos. Este límite se aplica incluso mientras el trabajo está en progreso. |
| maxIdleDurationSeconds | Cubra la carga de trabajo prevista. Lambda mide el tráfico entrante, por lo que la conexión saliente del ejecutor no se encarga de restablecer este temporizador. |
| suspendedDurationSeconds / autoResumeEnabled | Utilice 0/false para el patrón de un solo turno, que no se ocupa de reanudar las microVM suspendidas. |
Consulte [Ejecución y uso de MicroVM](microvms-launching.md) para ver los controles de vida útil y de inactividad.
Elimine la sesión por separado. La eliminación de una sesión no detiene la microVM ni envía un webhook de eliminación. Mantenga la imagen y el secreto de la clave del ejecutor para volver a utilizarlas. Para gestionar los turnos de seguimiento, consulte [el ciclo de vida del entorno de pruebas](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws).
## Suspender y reanudar entre turnos
Para preservar el estado de la memoria y del disco entre turnos, suspenda la microVM cuando finalice el turno del agente principal y todas las herramientas y subagentes finalicen. Reanude la misma microVM la siguiente vez que la sesión necesite un ejecutor.
+ Establezca un valor diferente de cero `suspendedDurationSeconds`. Se aplican cargos por el almacenamiento de instantáneas cuando la microVM esté suspendida.
+ Active el enlace `/suspend` para vaciar las escrituras y cerrar las conexiones, y el enlace `/resume` para actualizar las credenciales y conectar de nuevo el ejecutor.
+ La ruta administrada por la aplicación reanuda la máquina virtual antes de enviar la entrada siguiente. En la ruta administrada por el webhook, el envío de la entrada desencadena la solicitud de conexión que reanuda la máquina virtual. El turno continúa después de que el ejecutor se vuelve a conectar.
**nota**
`maximumDurationInSeconds` limita el tiempo total de ejecución y suspensión a 8 horas. Para reanudar a petición, llame a `ResumeMicrovm`. La reanudación automática requiere tráfico entrante a la microVM; la entrada de la API de agentes por sí sola no la reanuda.
## Red
Permita las conexiones salientes exigidas por el ejecutor a OpenAI y el acceso a Secrets Manager. Para acceder a recursos privados o aplicar sus propias restricciones de red, conecte un conector de salida de VPC en el momento del inicio. Consulte [Uso de los conectores de red de salida](microvms-networking.md#microvms-networking-connectors).
El ejemplo es compatible con la carga y descarga de archivos a través del punto de conexión HTTPS de la microVM, mediante un token de autenticación vinculado al puerto del servidor.
## Supervisión
Ejecute cualquiera de los dos ejemplos y, a continuación, confirme que `hello.txt` realiza las descargas, la microVM alcanza el estado `TERMINATED` y la sesión eliminada devuelve HTTP 404.
**Registros del iniciador.** Revise los registros de la función de Lambda del iniciador en CloudWatch Logs:
```
aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m
```
**Ejecución de microVM.** Establezca `MICROVM_IMAGE_ARN` en el ARN de su imagen, utilice la región de AWS de su implementación y enumere las microVM de la imagen:
```
aws lambda-microvms list-microvms \
--image-identifier "$MICROVM_IMAGE_ARN" \
--query 'items[].{id:microvmId,state:state}' --output table
```
Registre los ID de sesión y de microVM juntos para poder rastrear una ejecución del principio a fin. Mantenga las credenciales y los cuerpos de los webhooks sin procesar fuera de los registros.
## Solución de problemas
| Síntoma | ¿Qué se debe comprobar? |
| --- | --- |
| Se rechaza la firma del webhook | Utilice el secreto de firma del punto de conexión y verifique el cuerpo de la solicitud sin modificar. |
| No se produce el lanzamiento de ninguna MicroVM | Compruebe la suscripción al webhook, el filtro de propiedad de la sesión, la acción environment\_connection pendiente y los permisos de IAM del iniciador. |
| Falla la compilación de la imagen | Compruebe el artefacto de Amazon S3, la función de creación de la imagen y la respuesta del enlace /ready. |
| /run falla o se agota el tiempo de espera | Compruebe el acceso al secreto y el inicio del ejecutor. Regrese una vez iniciado el proceso, no después del turno. |
| El ejecutor no puede conectarse | Compruebe el identificador del entorno, la URL remota, la propiedad de la clave y el acceso a la red saliente. |
| La microVM se detiene durante un turno | Compruebe la política de vida útil máxima así como de inactividad. El tráfico saliente del ejecutor no cuenta como actividad entrante. |
Para detectar errores de conexión, inspeccione los eventos de `agent.session.environment.failed` y los registros del ejecutor. Para ver el contrato de ejecutor compartido, consulte [entornos de pruebas autohospedados](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws).
## Recursos relacionados
+ [MicroVM de AWS Lambda](lambda-microvms-guide.md)
+ [Ejecución y uso de MicroVM](microvms-launching.md)
+ [Seguridad y permisos](microvms-security.md)
+ [Referencia de la API RunMicrovm](https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html)
+ [Entornos de pruebas autohospedados de la API de agentes de OpenAI](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)
+ [Guía sobre la API de agentes de OpenAI en AWS](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)