View a markdown version of this page

Uso de las microVM de Lambda como entorno de pruebas para la API de agentes de OpenAI - AWS Lambda
FuncionamientoPropiedades claveRequisitos previosPreparación de la imagen de la microVMIniciación de microVMFinalizar un turnoSuspender y reanudar entre turnosRedSupervisiónSolución de problemasRecursos relacionados

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 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.

  2. 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.

  3. Una función de Lambda del iniciador verifica la firma del webhook, recupera la sesión actual y confirma que es propiedad del controlador.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. Una vez terminado el último turno, la aplicación finaliza la microVM.

Aprovisionamiento administrado por webhook para un entorno de pruebas de la API de agentes en microVM de Lambda AWS

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.

  • 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.

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.

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.

  2. 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.

  3. Espere a agent.session.environment.connected, luego envíe la entrada y siga el resultado del turno.

  4. Recupere los archivos de salida y termine el turno tal y como se describe en Finalizar un turno.

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.

  2. 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.

  3. 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.

  4. 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.

  5. 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 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.

Ciclo de vida de la microVM para un turno de la API de agentes

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 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.

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.

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.