La sesión de un agente puede durar más que su entorno. Tu aplicación administra los recursos de cómputo y los archivos que usa un entorno self_hosted.
Iniciar un entorno
Tu aplicación puede iniciar los recursos de cómputo después de crear una sesión. Usa el SDK o la API de tu proveedor y luego conecta el ejecutor con el ID del entorno de la sesión y una clave de entorno.
Consulta los ejemplos de sandboxes administrados por la aplicación en el OpenAI Cookbook.
Usa un único componente para administrar el entorno de cada sesión. Almacena la correspondencia entre la sesión y los recursos de cómputo del proveedor. Las solicitudes repetidas o simultáneas no deben crear entornos duplicados.
Iniciar recursos de cómputo desde webhooks
También puedes esperar hasta que una entrada necesite una conexión con el entorno. La API emite agent.session.action_required con required_action.type: "environment_connection" antes de esperar al ejecutor. Tu manejador de webhooks inicia o reconecta el entorno.
Consulta los ejemplos de sandboxes administrados mediante webhooks en el OpenAI Cookbook.
Sigue las instrucciones de configuración de webhooks para registrar tu manejador para agent.session.action_required y agent.session.failed. Mantén su secreto de firma y su credencial de lectura de sesiones separados de la clave de entorno del ejecutor. Si varios manejadores de proveedores comparten un proyecto, dirige los eventos al manejador responsable de la sesión.
El manejador y el proceso de trabajo tienen funciones distintas:
- Verificar y poner en cola. Verifica la firma del webhook. Pon en cola las solicitudes de conexión solo cuando
data.required_action.typeseaenvironment_connection. Pon también en cola los fallos de las sesiones. Devuelve una respuesta HTTP de éxito solo después de que se hayan agregado correctamente a la cola. - Consultar el estado actual. El proceso de trabajo recupera la sesión. Ignora las sesiones eliminadas y las acciones resueltas. Si una sesión autoalojada aún necesita una conexión, inicia o reconecta su ejecutor usando
session.environment.idysession.environment.remote_url. Si una sesión sigue en estado de fallo, libera sus recursos de cómputo.
El flujo de eventos de la sesión informa la misma solicitud como agent.session.requires_action. Una acción requerida de tipo function_call necesita el resultado de una función, no el inicio del entorno. Los eventos de creación de turnos y agent.session.in_progress llegan demasiado tarde para iniciar un ejecutor desconectado.
Después de desplegar el manejador, crea una sesión autoalojada y envía una entrada. Asegúrate de que coincidan el directorio de trabajo y cualquier filtro de agentes configurado en tu manejador. El envío original continúa si el ejecutor se conecta antes del plazo límite.
Mantener el entorno disponible o detenerlo
Mantén los recursos de cómputo en ejecución entre turnos para reutilizarlos, o deja un período de gracia después de que termine un turno antes de detenerlos. Coordina el apagado con el trabajo entrante. Cancela cualquier apagado pendiente cuando se solicite una conexión o comience la ejecución. Vuelve a comprobar el estado antes de detener los recursos de cómputo.
Un evento de inactividad por sí solo no indica que sea seguro apagar el entorno. Puede llegar cuando se resuelve una solicitud de conexión, antes de que la entrada en espera inicie su turno. Si tu aplicación no puede coordinar el apagado con el trabajo entrante, mantén el entorno en ejecución.
Reconectar después de una desconexión
Los eventos de conexión informan sobre el estado. Usa agent.session.environment.connected y agent.session.environment.disconnected para observar las conexiones. Durante la configuración también se puede emitir agent.session.environment.pending o agent.session.environment.failed. Estos eventos no solicitan recursos de cómputo. Usa la acción requerida environment_connection para activar el inicio y comprueba por separado el estado del proveedor.
Una desconexión a mitad de un turno puede hacer que una herramienta falle, aunque el turno se complete. Revisa los resultados de las herramientas y la respuesta final del agente. La desconexión no solicita automáticamente una reconexión mediante un webhook ni reinicia un comando terminado de forma forzada. Una entrada posterior puede solicitar la reconexión.
La API espera hasta cinco minutos a que se establezca una conexión al recibir una entrada. Configura los tiempos de espera del cliente y del proxy para contemplar esta espera. Si se agota el tiempo, el envío falla. La entrada inicial puede fallar de forma asíncrona y dejar la sesión en estado failed.
La API no garantiza la recuperación de entradas pendientes tras un fallo del proceso. Comprueba el resultado de la solicitud o de la sesión antes de volver a intentarlo. No vuelvas a enviar la entrada mientras la solicitud original siga en espera. Una conexión tardía no vuelve a procesar una entrada cuyo tiempo de espera se haya agotado.
Reutilizar el ID del entorno no restaura los archivos en los recursos de cómputo de reemplazo. Usa el almacenamiento o las instantáneas del proveedor para conservarlos.
Liberar recursos
Deja de aceptar nuevas entradas. Coordina la liberación de recursos con cualquier operación de inicio que ya esté en curso para evitar dejar recursos de cómputo en ejecución.
Elimina la sesión y detén los recursos de cómputo del proveedor por separado. Eliminar una sesión no detiene su entorno ni emite un webhook de eliminación.