MicroVM de AWS Lambda

Usa las MicroVM de AWS Lambda para ejecutar las herramientas de tu agente en tu cuenta de AWS. OpenAI ejecuta el arnés de ejecución del agente. Cada MicroVM ejecuta codex exec-server y almacena los archivos del espacio de trabajo de la sesión.

De forma predeterminada, los ejemplos usan una MicroVM para un solo turno. Prepara una imagen reutilizable y luego inicia la MicroVM desde tu aplicación o mediante un webhook de OpenAI. Ambos métodos usan la misma imagen y las mismas credenciales. Elige un único responsable del aprovisionamiento por sesión.

Prueba los ejemplos de AWS en el Cookbook para trabajar con sandboxes administrados por la aplicación o mediante un webhook.

Cómo funciona

Si usas un webhook, tu aplicación crea una sesión autoalojada y envía datos de entrada. Cuando la sesión necesita un ejecutor, OpenAI envía agent.session.action_required con una acción environment_connection. API Gateway entrega el webhook a una función de Lambda que actúa como lanzador. Esta función verifica la firma, comprueba la sesión actual e inicia o reanuda una MicroVM.

El hook /run de la MicroVM obtiene una clave de entorno de Secrets Manager e inicia el ejecutor. El ejecutor establece una conexión saliente con OpenAI y se procesa la entrada pendiente. Tu aplicación sigue el flujo de eventos de la sesión, descarga los archivos de salida y termina la MicroVM después del último turno.

Antes de comenzar

Prepara los siguientes recursos:

• Acceso a AWS: una cuenta con acceso a las MicroVM de Lambda, una versión de la CLI de AWS que incluya lambda-microvms y permisos para crear imágenes y ejecutar MicroVM. Sigue la guía de inicio de AWS para crear el bucket de S3 para los artefactos y el rol de IAM para la creación de imágenes.
• Clave de aplicación: usa OPENAI_API_KEY para crear sesiones y enviar datos de entrada.
• Clave de entorno (OPENAI_EXECUTOR_API_KEY): crea una clave de entorno independiente que pertenezca a la misma organización, al mismo proyecto y al mismo usuario o cuenta de servicio que la clave de aplicación. Guarda su valor en Secrets Manager, por ejemplo, en un secreto llamado codex/agents-api/executor. El hook /run pasa la clave a Codex como CODEX_API_KEY.
• Rol de ejecución de la MicroVM: permite que este rol lea únicamente el secreto que contiene la clave de entorno. Agrega el permiso de descifrado si usas una clave de KMS administrada por el cliente. Para configurar el rol, consulta la documentación de AWS sobre seguridad y permisos.

Mantén la clave de aplicación y el secreto de firma del webhook fuera de la MicroVM. El lanzador del webhook necesita estas credenciales en su propio secreto de Secrets Manager. La máquina virtual solo recibe el ARN del secreto que contiene su clave de entorno.

Preparar una imagen reutilizable

Crea una imagen con la CLI de Codex, las dependencias de las herramientas, un directorio de trabajo como /workspace y un servidor HTTP para los hooks del ciclo de vida de AWS.

Los ejemplos implementan los siguientes hooks en /aws/lambda-microvms/runtime/v1:

Empaqueta el Dockerfile y el servidor de hooks en un artefacto de S3. Luego crea una imagen con control de versiones, por ejemplo, codex-executor. Habilita los seis hooks en la configuración de la imagen y configura el puerto de los hooks para que coincida con el del servidor. Excluye de la instantánea de la imagen los ID de sesión, las credenciales y las conexiones activas del ejecutor. Para obtener detalles sobre la creación de imágenes y la configuración de hooks, consulta la documentación de AWS sobre imágenes de MicroVM.

Al iniciar la MicroVM, tu aplicación o el lanzador serializa los siguientes valores en formato JSON en runHookPayload:

El hook /run analiza esta cadena del cuerpo de la solicitud de AWS, recupera la clave, establece CODEX_API_KEY en el entorno del proceso hijo e inicia el ejecutor. Haz que el hook devuelva la respuesta en cuanto se inicie el proceso. Si esperas a que termine el turno del agente, puede agotarse el tiempo de espera del hook.

Permite las conexiones salientes que necesita el ejecutor y el acceso a Secrets Manager. Configura un conector de salida de AWS si usas recursos privados o tienes restricciones de red. Para descargar archivos, agrega una ruta al servidor e invócala a través del punto de acceso HTTP de la MicroVM con un token de autenticación de AWS cuyo alcance se limite al puerto del servidor.

Iniciar la MicroVM

Elige si la aplicación o el webhook administrará el aprovisionamiento. En ambos casos, mantén abierto el flujo de eventos de la sesión desde la conexión hasta que termine el turno, incluido el procesamiento de la entrada.

Aprovisionamiento administrado por la aplicación

1. Crea una sesión autoalojada cuyo directorio de trabajo coincida con el de la imagen y luego abre su flujo de eventos.
2. Invoca la operación RunMicrovm de AWS con el ARN y la versión de la imagen, el rol de ejecución, los conectores de red y runHookPayload. Guarda el microvmId que devuelve la operación junto con el ID de sesión.
3. Espera a recibir agent.session.environment.connected. Luego envía los datos de entrada y sigue el turno hasta obtener el resultado.
4. Recupera los archivos de salida y detén la MicroVM.

Aprovisionamiento administrado mediante un webhook

Usa una API HTTP de API Gateway y una función Lambda de lanzamiento. Tu aplicación crea la sesión, abre su flujo de eventos y envía los datos de entrada. El webhook inicia o reanuda los recursos de cómputo cuando la sesión necesita una conexión.

1. Despliega una ruta POST /webhook que invoque al lanzador. Otorga al lanzador los permisos lambda:RunMicrovm, lambda:GetMicrovm, lambda:ResumeMicrovm y lambda:TerminateMicrovm para la imagen seleccionada. El lanzador también necesita leer sus credenciales, pasar el rol de ejecución de la MicroVM y usar los conectores de red configurados.
2. Registra el punto de acceso para agent.session.action_required y agent.session.failed. Guarda el secreto de firma del punto de acceso junto con la clave de aplicación del lanzador.
3. Verifica la firma del webhook con el cuerpo de la solicitud sin modificar antes de acceder a las sesiones o iniciar recursos de cómputo. Recupera la sesión actual y confirma que le corresponda al controlador, por ejemplo, comprobando que el agente de la sesión coincida con un agente guardado para ese fin.
4. Si environment_connection sigue pendiente, comprueba el estado de la máquina virtual registrada con GetMicrovm. Si está en estado SUSPENDED, reanúdala con ResumeMicrovm. Si está en estado PENDING o RUNNING, espera a que se conecte. Invoca RunMicrovm solo si no hay ninguna máquina virtual registrada. Guarda su ID en los metadatos de la sesión. Si no puedes guardarlo, termina la máquina virtual que acabas de iniciar.
5. Si la sesión sigue en estado failed, termina la MicroVM registrada para esa sesión. Ignora las sesiones eliminadas, las acciones resueltas y los eventos que le correspondan a otro controlador.

Si el ejecutor se conecta antes de que venza el tiempo de espera de la conexión, se procesa la entrada pendiente sin que tengas que volver a enviarla.

Un prototipo puede iniciar la MicroVM de forma síncrona y guardar su ID en los metadatos de la sesión. Antes de usarlo en producción, registra de forma persistente quién es responsable de cada lanzamiento, garantiza que los lanzamientos sean idempotentes y pon las tareas de aprovisionamiento en una cola. Los metadatos por sí solos no evitan los lanzamientos duplicados, y un lanzamiento lento puede superar el plazo de respuesta del webhook.

Detener la MicroVM

En el flujo de eventos de la sesión, espera a recibir agent.session.turn.completed, agent.session.turn.failed o agent.session.turn.cancelled para el agente principal (event.turn.subagent_id es null). Los subagentes comparten la MicroVM, por lo que sus eventos de fin de turno no deben activar la limpieza. Después del último turno, recupera los archivos necesarios, invoca TerminateMicrovm y verifica que la máquina virtual pase al estado TERMINATED. Ejecuta la limpieza también si se producen errores en la aplicación.

Los resultados de los turnos se comunican como eventos del flujo y no admiten suscripciones mediante webhooks. El webhook agent.session.failed se encarga de las fallas de la sesión, pero no cubre todos los turnos fallidos. No termines la MicroVM basándote únicamente en agent.session.idle, ya que este evento puede llegar antes de que se empiece a procesar la entrada pendiente.

Configura estos límites de AWS como respaldo en caso de que no se ejecute la limpieza:

Para conocer los controles de duración e inactividad, consulta la guía de AWS sobre la ejecución y el uso de MicroVM.

Elimina la sesión por separado. Eliminar la sesión no termina los recursos de cómputo de AWS ni genera un webhook de eliminación. Conserva la imagen y el secreto que contiene la clave de entorno para reutilizarlos. En los turnos posteriores, coordina la reutilización o el reemplazo de los recursos de cómputo y la persistencia de los archivos según la guía del ciclo de vida del sandbox.

Suspender y reanudar la MicroVM entre turnos

Usa las funciones de suspensión y reanudación de AWS para conservar el contenido de la memoria y del disco entre turnos. Asigna un valor distinto de cero a suspendedDurationSeconds. Mientras la máquina virtual esté suspendida, se aplican cargos por el almacenamiento de la instantánea. maximumDurationInSeconds limita a ocho horas el tiempo total de ejecución y suspensión.

Ejecuta cualquiera de los dos ejemplos con --suspend-resume para escribir en /workspace/hello.txt, suspender la máquina virtual y luego leer el archivo en un segundo turno. En el ejemplo administrado por la aplicación, esta reanuda la máquina virtual directamente. En el ejemplo administrado mediante un webhook, la aplicación envía otra entrada, lo que hace que el lanzador reanude la máquina virtual registrada. Ambos ejemplos verifican el contenido del archivo y ejecutan la limpieza después del último turno.

El hook /suspend detiene el ejecutor. El hook /resume vuelve a cargar su clave y lo reconecta. Suspende la máquina virtual solo después de que terminen las herramientas y los subagentes. Para que AWS reanude la máquina virtual automáticamente, esta debe recibir tráfico entrante. Enviar datos de entrada a la API de Agentes no basta para reanudarla.

Verificar y monitorear

Haz una prueba con un prompt que le pida al agente crear un archivo pequeño en /workspace. Confirma que el ejecutor se conecte, que el turno se complete, que el archivo descargado contenga el resultado esperado y que la MicroVM pase al estado TERMINATED después de la limpieza. Un lanzamiento exitoso por sí solo no verifica la integración.

Desde el directorio de los ejemplos de AWS, usa jq para leer el ARN de la imagen y la región del archivo donde se guardó el estado de la compilación. Ajusta la ruta si usaste un valor personalizado para --state y reemplaza el grupo de registros si cambiaste el nombre del lanzador:

123456789image_state=application_managed/.local/image.json
region=$(jq -r '.region' "$image_state")
image_arn=$(jq -r '.image_arn' "$image_state")

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

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

Registra juntos los ID de la sesión y de la MicroVM para rastrear una ejecución. Excluye de los registros las credenciales y los cuerpos sin procesar de las solicitudes del webhook.

Solución de problemas

Si falla la conexión, revisa agent.session.environment.failed y los registros del ejecutor. Consulta Sandboxes autoalojados para conocer el contrato común del ejecutor.

Referencias

• Ciclo de vida: la guía sobre la ejecución y el uso de MicroVM explica cómo iniciar, suspender, reanudar y terminar una MicroVM.
• Seguridad: la guía sobre seguridad y permisos describe los roles de IAM, los tokens de autenticación y los controles de acceso.