A sessão de um agente pode continuar existindo depois que seu ambiente é encerrado. Seu aplicativo gerencia os recursos computacionais e os arquivos usados pelo ambiente self_hosted.
Iniciar um ambiente
Seu aplicativo pode iniciar os recursos computacionais depois de criar uma sessão. Use o SDK ou a API do provedor e, em seguida, conecte o executor usando o ID do ambiente da sessão e uma chave de ambiente.
Consulte os exemplos de sandboxes gerenciados pelo aplicativo no OpenAI Cookbook.
Use um único componente para gerenciar o ambiente de cada sessão. Registre quais recursos computacionais do provedor correspondem a cada sessão. Solicitações repetidas ou simultâneas não devem criar ambientes duplicados.
Iniciar recursos computacionais por meio de webhooks
Você também pode esperar até que seja necessário conectar o ambiente para processar uma entrada. A API emite agent.session.action_required com required_action.type: "environment_connection" antes de aguardar o executor. O manipulador de webhook inicia ou reconecta o ambiente.
Consulte os exemplos de sandboxes gerenciados por webhooks no OpenAI Cookbook.
Siga as instruções de configuração do webhook para registrar seu manipulador para os eventos agent.session.action_required e agent.session.failed. Mantenha o segredo de assinatura do manipulador e a credencial de leitura de sessões separados da chave de ambiente do executor. Se vários manipuladores de provedores compartilharem um projeto, encaminhe cada evento ao manipulador responsável pela sessão.
O manipulador e o processo de trabalho têm responsabilidades distintas.
- Verificar e colocar na fila. Verifique a assinatura do webhook. Coloque as solicitações de conexão na fila somente quando
data.required_action.typeforenvironment_connection. Coloque também os eventos de falha de sessão na fila. Retorne uma resposta HTTP de sucesso somente após confirmar que o evento entrou na fila. - Verificar o estado atual. O processo de trabalho consulta a sessão. Ignore sessões excluídas e ações já resolvidas. Se uma sessão auto-hospedada ainda precisar de conexão, inicie ou reconecte o executor usando
session.environment.idesession.environment.remote_url. Se a sessão ainda estiver em estado de falha, libere seus recursos computacionais.
O fluxo de eventos da sessão informa a mesma solicitação como agent.session.requires_action. Uma ação obrigatória do tipo function_call exige o resultado de uma função e não requer a inicialização do ambiente. A criação do turno e os eventos agent.session.in_progress ocorrem tarde demais para iniciar um executor que está offline.
Depois de implantar o manipulador, crie uma sessão auto-hospedada e envie os dados de entrada. Use o diretório de trabalho configurado no manipulador e respeite os filtros de agente que ele usar. Se o executor se conectar antes do fim do prazo, o processamento da solicitação original continuará.
Manter o ambiente disponível ou encerrá-lo
Mantenha os recursos computacionais em execução entre os turnos para reutilizá-los ou aguarde algum tempo após o fim de um turno antes de desligá-los. Coordene o desligamento com a chegada de novas tarefas. Cancele qualquer desligamento pendente ao receber uma solicitação de conexão ou quando a execução começar. Verifique o estado novamente antes de desligar os recursos computacionais.
Um evento de inatividade, por si só, não indica que é seguro desligar o ambiente. Ele pode chegar assim que uma solicitação de conexão deixa de estar pendente, antes que comece o turno da entrada que aguardava a conexão. Se o aplicativo não conseguir coordenar o desligamento com a chegada de novas tarefas, mantenha o ambiente em execução.
Reconectar após uma desconexão
Os eventos de conexão informam o estado da conexão. Use agent.session.environment.connected e agent.session.environment.disconnected para acompanhar as conexões. Durante a configuração, a API também pode emitir agent.session.environment.pending ou agent.session.environment.failed. Esses eventos não solicitam recursos computacionais. Use a ação obrigatória environment_connection para iniciar os recursos e verifique separadamente o estado do provedor.
Uma desconexão durante um turno pode causar uma falha na execução de uma ferramenta, mesmo que o turno seja concluído. Examine os resultados das ferramentas e a resposta final do agente. A desconexão não solicita automaticamente a reconexão por webhook nem reinicia um comando encerrado à força. Uma entrada posterior pode solicitar a reconexão.
Ao receber uma entrada que precisa de conexão, a API aguarda até cinco minutos para que a conexão seja estabelecida. Configure os tempos limite do cliente e do proxy para permitir essa espera. Se o prazo expirar, a solicitação falhará. O processamento da entrada inicial pode falhar de forma assíncrona e deixar a sessão no estado failed.
A API não garante a recuperação de entradas pendentes após uma falha do processo. Verifique o resultado da solicitação ou da sessão antes de tentar novamente. Não reenvie a entrada enquanto a solicitação original estiver aguardando. Uma conexão estabelecida depois do prazo não faz com que a API processe novamente a entrada cujo prazo expirou.
Reutilizar o ID do ambiente não restaura os arquivos nos recursos computacionais que substituem os anteriores. Use o armazenamento do provedor ou snapshots para preservar os arquivos.
Liberar recursos
Pare de aceitar novas entradas. Coordene a liberação dos recursos com qualquer inicialização já em andamento para evitar que os recursos computacionais continuem em execução.
Exclua a sessão e, em uma operação separada, desligue os recursos computacionais do provedor. A exclusão de uma sessão não encerra seu ambiente nem dispara um webhook de exclusão.