Una sesión de agente puede seguir existiendo después de que termine 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 solo componente para administrar el entorno de cada sesión. Guarda la correspondencia entre cada sesión y los recursos de cómputo del proveedor. Las solicitudes repetidas o simultáneas no deben crear entornos duplicados.
Iniciar los recursos de cómputo desde webhooks
También puedes esperar hasta que se necesite una conexión con el entorno para procesar los datos de entrada. La API emite agent.session.action_required con required_action.type: "environment_connection" antes de quedar a la espera del ejecutor. Tu controlador de webhooks inicia o reconecta el entorno.
Consulta los ejemplos de sandboxes administrados mediante webhooks en el OpenAI Cookbook.
Sigue las instrucciones para configurar un webhook y registrar tu controlador para agent.session.action_required y agent.session.failed. Mantén el secreto de firma y la credencial de lectura de sesiones del controlador separados de la clave de entorno del ejecutor. Si varios controladores de proveedores comparten un proyecto, dirige los eventos al controlador responsable de la sesión.
El controlador y el proceso de trabajo tienen funciones distintas:
- Verificar y agregar a la cola. Verifica la firma del webhook. Agrega las solicitudes de conexión a la cola solo cuando
data.required_action.typeseaenvironment_connection. Agrega también los eventos de falla de sesión. Devuelve una respuesta HTTP de éxito solo después de que el evento se haya agregado correctamente a la cola. - Comprobar el estado actual. El proceso de trabajo recupera la sesión. Ignora las sesiones eliminadas y las acciones ya resueltas. Si una sesión autoalojada aún necesita una conexión, inicia o reconecta su ejecutor con
session.environment.idysession.environment.remote_url. Si la sesión sigue en estado de falla, libera sus recursos de cómputo.
El flujo de eventos de la sesión informa de la misma solicitud mediante agent.session.requires_action. Una acción requerida de tipo function_call necesita el resultado de una función y no requiere iniciar el entorno. Tanto los eventos de creación de turnos como los eventos agent.session.in_progress llegan demasiado tarde para iniciar un ejecutor desconectado.
Después de desplegar el controlador, crea una sesión autoalojada y envía datos de entrada. Usa el mismo directorio de trabajo y respeta cualquier filtro de agentes que hayas configurado en el controlador. La solicitud original sigue su curso si el ejecutor se conecta antes de que venza el plazo.
Mantener el entorno disponible o detenerlo
Mantén activos los recursos de cómputo entre turnos para reutilizarlos, o deja pasar un período de gracia después de que termine un turno antes de detenerlos. Coordina el apagado con la llegada de nuevas tareas. 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.
Por sí solo, un evento de inactividad no indica que sea seguro apagar el entorno. Puede llegar cuando se resuelve una solicitud de conexión, antes de que comience el turno correspondiente a los datos de entrada en espera. Si tu aplicación no puede coordinar el apagado con la llegada de nuevas tareas, mantén el entorno en ejecución.
Volver a conectarse después de una desconexión
Los eventos de conexión informan sobre el estado de la conexión. Usa agent.session.environment.connected y agent.session.environment.disconnected para supervisar las conexiones. Durante la configuración también pueden emitirse 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 iniciar los recursos y comprueba por separado el estado del proveedor.
Una desconexión durante un turno puede hacer que falle una herramienta, incluso si el turno se completa. 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 cuya ejecución se haya interrumpido. El envío posterior de datos de entrada puede dar lugar a una solicitud de reconexión.
Cuando se envían datos de entrada, la API espera hasta cinco minutos para que se establezca la conexión. Configura los tiempos de espera del cliente y del proxy teniendo en cuenta ese plazo. Si vence el plazo, el envío falla. El envío inicial puede fallar de forma asíncrona y dejar la sesión en estado failed.
La API no garantiza que se recuperen los datos de entrada pendientes si un proceso termina de forma inesperada. Comprueba el resultado de la solicitud o de la sesión antes de volver a intentarlo. No vuelvas a enviar los datos mientras la solicitud original siga en espera. Si la conexión se establece después de que venza el plazo, los datos de entrada no se vuelven a procesar.
Reutilizar el ID del entorno no restaura los archivos en los recursos de cómputo de reemplazo. Usa el almacenamiento del proveedor o instantáneas para conservarlos.
Liberar los recursos
Deja de aceptar nuevos datos de entrada. Coordina la liberación de recursos con cualquier tarea de inicio que ya esté en curso para evitar que queden recursos de cómputo activos.
Elimina la sesión y detén por separado los recursos de cómputo del proveedor. Al eliminar una sesión, no se detiene su entorno ni se emite un webhook de eliminación.