Uma sessão de agente pode durar mais que seu ambiente. Seu aplicativo gerencia os recursos computacionais e os arquivos usados por um ambiente self_hosted.
Inicie um ambiente
Seu aplicativo pode iniciar os recursos computacionais após criar uma sessão. Use o SDK ou a API do seu provedor e, em seguida, conecte o executor com o ID do ambiente da sessão e uma chave de ambiente.
Veja os exemplos de sandboxes gerenciados pelo aplicativo no OpenAI Cookbook.
Use um único componente para gerenciar o ambiente de cada sessão. Armazene o mapeamento entre a sessão e os recursos computacionais do provedor. Solicitações repetidas ou simultâneas não devem criar ambientes duplicados.
Inicie recursos computacionais a partir de webhooks
Você também pode esperar até que uma entrada precise de uma conexão com o ambiente. A API emite agent.session.action_required com required_action.type: "environment_connection" antes de aguardar o executor. Seu manipulador de webhooks inicia ou reconecta o ambiente.
Veja os exemplos de sandboxes gerenciados por webhooks no OpenAI Cookbook.
Siga as instruções de configuração de webhooks para registrar seu manipulador para agent.session.action_required e agent.session.failed. Mantenha o segredo de assinatura e a credencial de leitura de sessões do manipulador separados da chave de ambiente do executor. Se vários manipuladores de provedores compartilharem um projeto, encaminhe os eventos ao manipulador responsável pela sessão.
O manipulador e o processador têm funções distintas:
- Verifique e coloque na fila. Verifique a assinatura do webhook. Coloque solicitações de conexão na fila somente quando
data.required_action.typeforenvironment_connection. Coloque também as falhas de sessão na fila. Retorne uma resposta HTTP de sucesso somente após a inclusão na fila ser bem-sucedida. - Verifique o estado atual. O processador consulta a sessão. Ignore sessões excluídas e ações resolvidas. Para uma sessão auto-hospedada que ainda precisa de uma conexão, inicie ou reconecte seu executor usando
session.environment.idesession.environment.remote_url. Para uma sessão que ainda está 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 necessária do tipo function_call exige um resultado de função, não a inicialização do ambiente. A criação do turno e os eventos agent.session.in_progress ocorrem tarde demais para iniciar um executor desconectado.
Após implantar o manipulador, crie uma sessão auto-hospedada e envie uma entrada. Use o diretório de trabalho e os filtros de agente configurados no seu manipulador. O envio original prossegue se o executor se conectar antes do prazo limite.
Mantenha o ambiente disponível ou pare-o
Mantenha os recursos computacionais em execução entre os turnos para reutilizá-los ou aguarde um intervalo após o fim de um turno antes de pará-los. Coordene o desligamento com a chegada de novas tarefas. Cancele um desligamento pendente quando uma conexão for solicitada ou uma execução começar. Verifique o estado novamente antes de parar os recursos computacionais.
Um evento de ociosidade, por si só, não indica que é seguro desligar o ambiente. Ele pode chegar quando uma solicitação de conexão é resolvida, antes que a entrada em espera inicie seu turno. Se seu aplicativo não puder coordenar o desligamento com a chegada de novas tarefas, mantenha o ambiente em execução.
Reconecte após uma desconexão
Os eventos de conexão informam o estado. Use agent.session.environment.connected e agent.session.environment.disconnected para monitorar as conexões. A configuração também pode emitir agent.session.environment.pending ou agent.session.environment.failed. Esses eventos não solicitam recursos computacionais. Use a ação necessária do tipo environment_connection para acionar a inicialização e verifique a integridade do provedor separadamente.
Uma desconexão durante um turno pode causar a falha de uma ferramenta, mesmo que o turno seja concluído. Inspecione os resultados das ferramentas e a resposta final do agente. A desconexão não solicita automaticamente uma reconexão por webhook nem reinicia um comando encerrado à força. Uma entrada posterior pode solicitar a reconexão.
A API aguarda até cinco minutos por uma conexão solicitada no momento da entrada. Configure os tempos limite do cliente e do proxy para acomodar essa espera. Se o prazo expirar, o envio falhará. A 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 de processo. Verifique o resultado da solicitação ou da sessão antes de tentar novamente. Não reenvie enquanto a solicitação original estiver aguardando. Uma conexão tardia não reprocessa entradas cujo tempo limite 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 preservá-los.
Libere os recursos
Pare de aceitar novas entradas. Coordene a liberação dos recursos com qualquer inicialização já em andamento para evitar deixar recursos computacionais em execução.
Exclua a sessão e pare os recursos computacionais do provedor separadamente. Excluir uma sessão não para seu ambiente nem emite um webhook de exclusão.