View a markdown version of this page

Utilização de MicroVMs Lambda como ambiente de teste para a API Agents da OpenAI - AWS Lambda
Como funcionaPrincipais propriedadesPré-requisitosPreparação da imagem da MicroVMInicializanda MicroVMsEncerrar um turnoSuspensão e retomada entre os turnosRedesMonitoramentoSolução de problemasRecursos relacionados

Utilização de MicroVMs Lambda como ambiente de teste para a API Agents da OpenAI

Você pode usar o AWS Lambda MicroVMs como ambiente auto-hospedado para agentes criados com a API Agents da OpenAI, mantendo arquivos do espaço de trabalho, execução de ferramentas e acesso à rede na infraestrutura que você controla. A OpenAI executa o harness do agente; o Lambda MicroVM executa suas tarefas. Neste exemplo, ele executa codex exec-server, o que executa as chamadas de ferramenta do agente e mantém os arquivos do espaço de trabalho da sessão. Você decide o conteúdo da imagem, os caminhos de rede que o executor pode seguir e os recursos da AWS para os quais seu perfil de execução está definido.

Cada MicroVM é executada como um ambiente Firecracker isolado que é inicializado a partir de um snapshot da sua imagem. O tempo de vida total de uma MicroVM é de até 8 horas, incluindo runtime e suspensão. Encerre-a após o turno final ou suspenda-a entre turnos. Você cria uma imagem reutilizável e depois inicia uma MicroVM a partir da sua aplicação ou de um inicializador de webhook. Ambas as abordagens usam a mesma imagem e credenciais. Para obter mais detalhes, consulte o exemplo de referência da sandbox auto-hospedada da API Agents da OpenAI no Lambda MicroVMs.

Como funciona

Na rota gerenciada por webhook, uma função do Lambda inicializadora inicia uma MicroVM quando a sessão precisa de um executor pela primeira vez. Ele reutiliza a MicroVM existente, retomando-a primeiro caso esteja suspensa. Sua aplicação encerra a execução após o último turno. A Figura 1 mostra o fluxo:

  1. Sua aplicação cria uma sessão auto-hospedada e envia dados para a API dos Agentes.

  2. Quando a sessão precisa de um executor, a OpenAI envia um webhook agent.session.action_required com uma ação environment_connection para um endpoint do Amazon API Gateway na sua conta.

  3. Uma função do Lambda inicializadora verifica a assinatura do webhook, recupera a sessão atual e confirma se o manipulador é o proprietário dela.

  4. O inicializador chama RunMicrovm com a imagem, o perfil de execução, os conectores de rede e um runHookPayload que contém os valores de conexão da sessão.

  5. O hook /run da MicroVM usa seu perfil de execução do IAM para recuperar a chave do executor do AWS Secrets Manager e iniciar o Codex.

  6. O executor se registra na OpenAI em https://api.openai.com. Em seguida, abre uma conexão segura do WebSocket com wss://codex-cloud-environments.chatgpt.com para receber comandos da ferramenta e retornar resultados.

  7. Sua aplicação pode carregar arquivos de entrada e baixar arquivos de saída por meio do endpoint HTTPS autenticado da MicroVM. Ele segue o fluxo de eventos da sessão e pode suspender a MicroVM entre turnos.

  8. Após o turno final, sua aplicação encerra a MicroVM.

Provisionamento gerenciado por webhook para uma sandbox da API Agents no AWS Lambda MicroVMs

Figura 1. Provisionamento gerenciado por webhook para uma sandbox da API Agents no AWS Lambda MicroVMs.

Mantenha a chave da aplicação e o segredo de assinatura do webhook fora da MicroVM. O inicializador passa somente o ARN do segredo da chave do executor; a VM recupera a chave usando seu perfil de execução.

Principais propriedades

Propriedade Benefício
Isolamento do Firecracker Limite virtualizado por hardware para a MicroVM de cada sessão
Inicialização baseada em snapshot Cada MicroVM é iniciado a partir de um snapshot da sua imagem preparada
IAM por meio do perfil de execução O hook /run lê a chave do executor com o perfil de execução da MicroVM; a chave não é armazenada na imagem
Duração por estado Cada MicroVM pode ser executado por até 8 horas, incluindo o tempo de suspensão
Suspender e retomar entre turnos A memória e o estado do disco são preservados, de modo que os turnos seguintes continuam no mesmo ambiente
Computação baseada em uso Máquinas virtuais em execução geram cobranças por recursos de computação. A suspensão interrompe a cobrança pelos serviços de computação; o armazenamento de snapshots e as operações de leitura/gravação são cobradas separadamente.

Pré-requisitos

  • Uma conta da AWS com acesso ao Lambda MicroVMs, uma versão da AWS CLI que inclui lambda-microvms e permissões para criar imagens e executar microVMs. Para criar o bucket de artefatos do Amazon Simple Storage Service (Amazon S3) e o perfil de construção de imagem do AWS Identity and Access Management (IAM), consulte Criar seu primeiro Lambda MicroVM.

  • Uma chave de aplicação OpenAI (OPENAI_API_KEY) para criar sessões e enviar informações.

  • Uma chave de executor separada da OpenAI (OPENAI_EXECUTOR_API_KEY) com a mesma organização, projeto e conta de usuário ou serviço da sessão. Armazene-a no Secrets Manager, por exemplo, como codex/agents-api/executor. O hook /run o passa para o Codex como CODEX_API_KEY.

  • Um perfil de execução de microVM que pode ler apenas o segredo da chave do executor. Se o segredo usar uma chave do AWS Key Management Service (AWS AWS KMS) gerenciada pelo cliente, adicione a permissão de descriptografia. Consulte Segurança e permissões.

Preparação da imagem da MicroVM

Crie uma imagem que inclua a CLI do Codex, as dependências da sua ferramenta, um diretório de trabalho, como /workspace, e um servidor HTTP para os ganchos do ciclo de vida.

Hook Comportamento
/aws/lambda-microvms/runtime/v1/ready Retorna o código HTTP 200 quando o servidor está pronto para que o Lambda faça o snapshot. O executor permanece desconectado.
/aws/lambda-microvms/runtime/v1/run Lê os valores de conexão da sessão e o ARN do segredo, obtém a chave do executor e inicia o executor.
/aws/lambda-microvms/runtime/v1/validate Opcional. Verifica se o Codex está em execução e se a área de trabalho permite gravação.
/aws/lambda-microvms/runtime/v1/suspend Necessário para suspender/retomar. Interrompe o executor e libera as gravações antes de a AWS capturar o snapshot da VM.
/aws/lambda-microvms/runtime/v1/resume Necessário para suspender/retomar. Busca a chave novamente e reinicia o executor para o mesmo ambiente.
/aws/lambda-microvms/runtime/v1/terminate Opcional. Interrompe o executor e atualiza as gravações antes do encerramento.

Empacote o Dockerfile e o servidor de hooks em um artefato do Amazon S3 e, em seguida, crie a imagem codex-executor com 8 GB de memória básica (linha de base de 4 vCPUs). Habilite os hooks selecionados na configuração da imagem e defina a porta do hook de acordo com o seu servidor. Não inclua IDs de sessão, credenciais e conexões ativas do executor no snapshot da imagem. Para configuração de compilação e conexão, consulte Imagens da microVM.

Na inicialização, sua aplicação ou seu inicializador serializa os seguintes valores como JSON em runHookPayload:

Valor Finalidade
session.environment.id Identifica o ambiente ao qual o executor se conecta
session.environment.remote_url Fornece o URL de conexão da OpenAI do executor
ARN de segredo da chave do executor Permite que o hook recupere a chave usando a perfil de execução da MicroVM

Retorne do hook /run quando o processo executor for iniciado, sem esperar que o turno termine, para evitar o tempo limite do hook.

Inicializanda MicroVMs

Você pode iniciar MicroVMs a partir da sua aplicação ou de um inicializador de webhook. Em ambos os casos, mantenha o fluxo de eventos da sessão aberto até que o turno termine.

Provisionamento gerenciado pela aplicação

  1. Crie uma sessão auto-hospedada cujo diretório de trabalho corresponda à imagem e, em seguida, abra seu fluxo de eventos.

  2. Chame RunMicrovm com o ARN e a versão da imagem, o perfil de execução, os conectores de rede e runHookPayload. Salve o microvmId retornado junto com o ID da sessão.

  3. Aguarde agent.session.environment.connected, envie a entrada e acompanhe o resultado do turno.

  4. Recupere os arquivos de saída e finalize o turno conforme descrito em Encerrar um turno.

Provisionamento gerenciado por webhook

Sua aplicação cria a sessão, abre o fluxo e envia a entrada. O inicializador cuida do resto quando o webhook chega.

  1. Implante uma rota POST /webhook no Amazon API Gateway que invoque o inicializador. Conceda ao inicializador permissão para ler suas credenciais, inspecionar, iniciar, retomar e encerrar MicroVMs a partir da imagem selecionada, passar o perfil de execução da MicroVM e usar os conectores de rede configurados.

  2. Registre o endpoint para agent.session.action_required e agent.session.failed. Armazene o segredo de assinatura do endpoint no Secrets Manager com a chave da aplicação do inicializador.

  3. Verifique a assinatura do webhook em relação ao corpo bruto da solicitação antes de acessar sessões ou iniciar recursos de computação. Em seguida, recupere a sessão atual e confirme se o manipulador é o responsável por ela, por exemplo, verificando se corresponde a um agente específico que foi salvo.

  4. Se environment_connection ainda estiver pendente, inspecione a MicroVM gravada com GetMicrovm. Continue com ResumeMicrovm se estiver suspenso. Chame RunMicrovm apenas se nenhuma VM for gravada e salve sua ID. Se o salvamento falhar, encerre a VM que você iniciou. Se o executor se conectar antes do tempo limite de conexão, a entrada em espera seguirá adiante sem necessidade de reenvio.

  5. Para um evento agent.session.failed, recupere a sessão atual e encerre a MicroVM gravado apenas se o status ainda estiver com falha. Se o executor se conectar antes do tempo limite de conexão, a entrada em espera seguirá adiante sem necessidade de reenvio.

O exemplo de referência salva o ID da MicroVM nos metadados da sessão. Entregas simultâneas de webhook podem iniciar VMs extras antes que esse ID seja salvo. Antes de colocar em produção, evite inicializações simultâneas para a mesma sessão e elimine eventos duplicados de webhooks.

Encerrar um turno

A Figura 2 mostra o ciclo de vida da MicroVM para um único turno, bem como o caminho opcional de suspensão e retomada para os turnos seguintes.

Ciclo de vida da MicroVM para uma execução da API Agents

Figura 2. Ciclo de vida da MicroVM para um turno de API Agents. O RunMicrovm inicia a MicroVM, o hook /run inicia o executor, o ambiente se conecta, o turno é executado e o turno termina. No caminho de uma única etapa, você recupera os arquivos e chama TerminateMicrovm. No caminho com vários turnos, a MicroVM é suspenso após a volta e retomada na próxima solicitação de conexão.

No stream da sessão, aguarde agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled pelo agente principal, onde event.turn.subagent_id é null. Os subagentes compartilham a MicroVM; portanto, os eventos de seus terminais não são gatilhos para a limpeza. Recupere os arquivos de que você precisa. Após o último turno, chame TerminateMicrovm e confirme se a VM alcança TERMINATED. Para turnos subsequentes, mantenha a operação em andamento ou suspenda-a. Execute a limpeza se sua aplicação encontrar um erro.

Os resultados do turno são recebidos como eventos de fluxo, e não como assinaturas de webhooks. O webhook agent.session.failed aborda as falhas da sessão, mas não todos os turnos malsucedidos. Por esse motivo, não encerre em agent.session.idle sozinho, pois ele pode chegar antes do início da espera pela entrada.

Para limitar o tempo de vida da MicroVM caso a limpeza não seja executada, configure as seguintes opções no momento da inicialização:

Configuração Orientação
maximumDurationInSeconds Defina um limite máximo para a workload, como 900 para um teste de 15 minutos. Esse limite se aplica mesmo enquanto o trabalho estiver em andamento.
maxIdleDurationSeconds Atenda à workload prevista. O Lambda mede o tráfego de entrada; portanto, a conexão de saída do executor não reinicia esse temporizador.
suspendedDurationSeconds / autoResumeEnabled Use 0 / false para o padrão de volta única, que não retoma as MicroVMs suspensas.

Para obter informações sobre os controles de tempo de vida e inatividade, consulte Execução e uso de microVMs.

Exclua a sessão separadamente. A exclusão de uma sessão não interrompe a MicroVM nem envia um webhook de exclusão. Mantenha a imagem e a chave do executor em segredo para reutilização. Para lidar com turnos de acompanhamento, consulte Ciclo de vida da Sandbox.

Suspensão e retomada entre os turnos

Para preservar a memória e o estado do disco entre os turnos, suspenda a MicroVM após a conclusão do turno do agente principal e assim que todas as ferramentas e subagentes tiverem terminado. Retome a mesma MicroVM quando a sessão precisar de um executor novamente.

  • Defina um valor diferente de zero suspendedDurationSeconds. As taxas de armazenamento de snapshots são cobradas enquanto a MicroVM estiver suspensa.

  • Ative o hook /suspend para liberar gravações e fechar conexões, e o hook /resume para atualizar as credenciais e reconectar o executor.

  • O caminho gerenciado pela aplicação retoma a VM antes de enviar a próxima entrada. No caminho gerenciado pelo webhook, o envio da entrada aciona a solicitação de conexão que retoma a VM. O turno continua quando o executor se reconecta.

nota

maximumDurationInSeconds limita o tempo total de execução e suspensão a 8 horas. Para retomar sob demanda, chame ResumeMicrovm. A retomada automática requer tráfego de entrada para a MicroVM; a entrada da API de agentes por si só não a retoma.

Redes

Permita as conexões de saída necessárias do executor com a OpenAI e o acesso ao Secrets Manager. Para acessar recursos privados ou aplicar suas próprias restrições de rede, conecte um conector de saída da VPC no momento da inicialização. Consulte Trabalho com conectores de rede de saída.

O exemplo permite fazer upload e baixar arquivos por meio do endpoint HTTPS da MicroVM, utilizando um token de autenticação com escopo restrito à porta do servidor.

Monitoramento

Execute qualquer um dos exemplos e confirme se hello.txt é baixado, a MicroVM alcança TERMINATED e a sessão excluída retorna HTTP 404.

Logs do inicializador. Analise os logs da função Lambda inicializadora no CloudWatch Logs:

aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m

Execução de MicroVMs. Defina MICROVM_IMAGE_ARN como o ARN da sua imagem, use a Região AWS da sua implantação e liste as MicroVMs da imagem:

aws lambda-microvms list-microvms \
  --image-identifier "$MICROVM_IMAGE_ARN" \
  --query 'items[].{id:microvmId,state:state}' --output table

Registre os IDs de sessão e de MicroVM juntos para que você possa rastrear uma execução de ponta a ponta. Mantenha as credenciais e os corpos brutos do webhook fora dos logs.

Solução de problemas

Sintomas O que verificar
A assinatura do webhook foi rejeitada Use o segredo de assinatura do endpoint e verifique o corpo da solicitação não modificado.
Nenhuma microVM é iniciada Verifique a assinatura do webhook, o filtro de propriedade da sessão, a ação environment_connection pendente e as permissões do IAM do inicializador.
A criação da imagem falha Verifique o artefato do Amazon S3, o perfil de criação da imagem e a resposta do hook /ready.
/run falha ou atinge o tempo limite Verifique o acesso secreto e a inicialização do executor. Retorne depois de iniciar o processo, não depois do turno.
O executor não consegue se conectar Verifique o ID do ambiente, a URL remota, a propriedade da chave e o acesso à rede de saída.
A MicroVM para durante um turno Verifique a vida útil máxima e a política de inatividade. O tráfego de saída do executor não conta como atividade de entrada.

Para falhas de conexão, inspecione eventos agent.session.environment.failed e os logs do executor. Para o contrato de executor compartilhado, consulte Sandboxes auto-hospedadas.