MicroVMs do AWS Lambda

Use as MicroVMs do AWS Lambda para executar as ferramentas do agente na sua conta da AWS. A OpenAI executa o harness do agente. Cada MicroVM executa codex exec-server e armazena os arquivos do espaço de trabalho da sessão.

Por padrão, os exemplos usam uma MicroVM para um único turno. Prepare uma imagem reutilizável e use-a para iniciar a MicroVM pelo seu aplicativo ou por um webhook da OpenAI. As duas opções usam a mesma imagem e as mesmas credenciais. Escolha um único responsável pelo provisionamento de cada sessão.

Experimente os exemplos do Cookbook para AWS para trabalhar com sandboxes gerenciados pelo aplicativo ou por webhook.

Como funciona

No fluxo com webhook, o aplicativo cria uma sessão auto-hospedada e envia a entrada. Quando a sessão precisa de um executor, a OpenAI envia agent.session.action_required com uma ação environment_connection. O API Gateway encaminha o webhook para uma função Lambda de inicialização. Essa função verifica a assinatura, consulta a sessão atual e inicia ou retoma uma MicroVM.

O hook /run da MicroVM busca uma chave de ambiente no Secrets Manager e inicia o executor. O executor abre uma conexão de saída com a OpenAI, e a sessão passa a processar a entrada pendente. O aplicativo acompanha o fluxo de eventos da sessão, baixa os arquivos de saída e encerra a MicroVM após o último turno.

Antes de começar

Prepare os seguintes recursos:

• Acesso à AWS: use uma conta com acesso às MicroVMs do Lambda, uma versão da AWS CLI que inclua lambda-microvms e permissões para criar imagens e executar MicroVMs. Siga o guia de introdução da AWS para criar o bucket do S3 para artefatos e o perfil do IAM para criação de imagens.
• Chave do aplicativo: use OPENAI_API_KEY para criar sessões e enviar entradas.
• Chave de ambiente (OPENAI_EXECUTOR_API_KEY): crie uma chave de ambiente separada, que pertença à mesma organização, ao mesmo projeto e ao mesmo titular (usuário ou conta de serviço) que a chave do aplicativo. Armazene o valor no Secrets Manager, por exemplo, em um segredo chamado codex/agents-api/executor. O hook /run passa a chave ao Codex como CODEX_API_KEY.
• Perfil de execução da MicroVM: permita que esse perfil leia apenas o segredo da chave de ambiente. Adicione a permissão de descriptografia se você usar uma chave do KMS gerenciada pelo cliente. Para configurar o perfil, consulte a documentação da AWS sobre segurança e permissões.

Mantenha a chave do aplicativo e o segredo de assinatura do webhook fora da MicroVM. A função de inicialização acionada pelo webhook precisa dessas credenciais em um segredo próprio no Secrets Manager. A VM recebe apenas o ARN do segredo que contém sua chave de ambiente.

Prepare uma imagem reutilizável

Crie uma imagem com a CLI do Codex, as dependências das ferramentas, um diretório de trabalho como /workspace e um servidor HTTP para os hooks de ciclo de vida da AWS.

Os exemplos implementam os seguintes hooks em /aws/lambda-microvms/runtime/v1:

Empacote o Dockerfile e o servidor de hooks em um artefato do S3. Em seguida, crie uma imagem com controle de versão, como codex-executor. Na configuração da imagem, habilite os seis hooks e configure-os para usar a mesma porta do servidor. Mantenha os IDs de sessão, as credenciais e as conexões ativas do executor fora do snapshot da imagem. Para saber como criar a imagem e configurar os hooks, consulte a documentação da AWS sobre imagens de MicroVM.

Ao iniciar a MicroVM, o aplicativo ou a função de inicialização serializa os seguintes valores como JSON em runHookPayload:

O hook /run extrai essa string do corpo da requisição da AWS e interpreta seu conteúdo. Em seguida, recupera a chave, define CODEX_API_KEY no ambiente do processo filho e inicia o executor. Faça o hook retornar assim que o processo iniciar. Aguardar o fim do turno do agente pode fazer com que o hook exceda o tempo limite.

Permita as conexões de saída necessárias ao executor e o acesso ao Secrets Manager. Configure um conector de saída da AWS se precisar acessar recursos privados ou aplicar restrições de rede. Para baixar arquivos, adicione uma rota ao servidor e chame-a pelo endpoint HTTP da MicroVM com um token de autenticação da AWS cujo escopo se limite à porta do servidor.

Inicie a MicroVM

Escolha se o provisionamento será gerenciado pelo aplicativo ou por webhook. Nos dois casos, mantenha o fluxo de eventos da sessão aberto desde a conexão até a conclusão do turno, inclusive durante o envio da entrada.

Provisionamento gerenciado pelo aplicativo

1. Crie uma sessão auto-hospedada cujo diretório de trabalho corresponda ao da imagem. Em seguida, abra o fluxo de eventos da sessão.
2. Chame a operação RunMicrovm da AWS 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 encerre a MicroVM.

Provisionamento gerenciado por webhook

Use uma API HTTP do API Gateway e uma função Lambda de inicialização. O aplicativo cria a sessão, abre o fluxo de eventos e envia a entrada. Quando a sessão precisa de uma conexão, o webhook aciona a inicialização ou a retomada da MicroVM.

1. Implante uma rota POST /webhook que invoque a função de inicialização. Conceda à função as permissões lambda:RunMicrovm, lambda:GetMicrovm, lambda:ResumeMicrovm e lambda:TerminateMicrovm para a imagem selecionada. A função também precisa de permissões para ler suas credenciais, passar o perfil de execução da MicroVM e usar os conectores de rede configurados.
2. Registre o endpoint para os eventos agent.session.action_required e agent.session.failed. Armazene o segredo de assinatura do endpoint junto com a chave do aplicativo usada pela função de inicialização.
3. Verifique a assinatura do webhook usando o corpo bruto da requisição antes de acessar sessões ou iniciar recursos de computação. Consulte a sessão atual e confirme que o manipulador é responsável por ela. Por exemplo, verifique se o agente da sessão corresponde a um agente salvo dedicado a esse manipulador.
4. Se environment_connection ainda estiver pendente, consulte a VM registrada com GetMicrovm. Se o estado da VM for SUSPENDED, retome-a com ResumeMicrovm. Se for PENDING ou RUNNING, aguarde a conexão. Chame RunMicrovm somente se não houver uma VM registrada. Salve o ID da VM nos metadados da sessão. Se não conseguir salvá-lo, encerre a VM que acabou de iniciar.
5. Se a sessão ainda estiver no estado failed, encerre a MicroVM registrada para ela. Ignore sessões excluídas, ações já resolvidas e eventos sob a responsabilidade de outro manipulador.

Se o executor se conectar antes de expirar o tempo limite de conexão, a sessão processará a entrada pendente sem que o aplicativo precise reenviá-la.

Em um protótipo, você pode iniciar a MicroVM de forma síncrona e armazenar o ID dela nos metadados da sessão. Antes de usar essa abordagem em produção, implemente um controle persistente de quem é responsável pela inicialização, garanta a idempotência e coloque as tarefas de provisionamento em uma fila. Os metadados, por si só, não impedem inicializações duplicadas. Se a inicialização demorar, o prazo de resposta do webhook pode expirar.

Encerre a MicroVM

No fluxo de eventos da sessão, aguarde agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled para o agente principal (event.turn.subagent_id é null). Os subagentes compartilham a MicroVM, e os eventos que indicam o fim de seus turnos não devem acionar a liberação dos recursos. Após o último turno, recupere os arquivos necessários, chame TerminateMicrovm e verifique se a VM chega ao estado TERMINATED. Libere os recursos também em caso de erro no aplicativo.

Os resultados dos turnos chegam pelo fluxo de eventos da sessão. Não é possível assinar esses eventos por webhook. O webhook agent.session.failed trata falhas da sessão, mas não abrange todos os casos de falha de um turno. Não encerre a VM com base apenas em agent.session.idle, pois esse evento pode chegar antes que a sessão comece a processar uma entrada pendente.

Configure os seguintes limites na AWS para o caso de os recursos não serem liberados:

Para saber como controlar a duração e o tempo de inatividade, consulte Execução e uso de MicroVMs na documentação da AWS.

Exclua a sessão separadamente. A exclusão da sessão não encerra os recursos de computação da AWS nem gera um webhook de exclusão. Guarde a imagem e o segredo da chave de ambiente para reutilizá-los. Para os turnos seguintes, consulte Ciclo de vida do sandbox para coordenar a reutilização ou substituição dos recursos de computação e a persistência dos arquivos.

Suspenda e retome a MicroVM entre turnos

Use os recursos de suspensão e retomada da AWS para preservar o conteúdo da memória e do disco entre turnos. Defina suspendedDurationSeconds como um valor diferente de zero. O armazenamento do snapshot é cobrado enquanto a VM está suspensa. maximumDurationInSeconds limita a oito horas a soma do tempo em execução e do tempo em suspensão.

Execute qualquer um dos exemplos com --suspend-resume para gravar /workspace/hello.txt, suspender a VM e ler o arquivo em um segundo turno. No exemplo gerenciado pelo aplicativo, o próprio aplicativo retoma a VM. No exemplo gerenciado por webhook, o aplicativo envia outra entrada, o que aciona a função de inicialização para retomar a VM registrada. Ambos verificam o conteúdo do arquivo e liberam os recursos após o último turno.

O hook /suspend interrompe o executor. O hook /resume recarrega a chave do executor e o reconecta. Suspenda a VM somente depois que as ferramentas e os subagentes concluírem suas tarefas. A retomada automática da AWS exige tráfego de entrada na VM. O envio de uma entrada à Agents API, por si só, não reativa a VM.

Verifique e monitore a integração

Teste com um prompt que peça a criação de um arquivo pequeno em /workspace. Confirme que o executor se conecta, que o turno é concluído, que o arquivo baixado contém o resultado esperado e que a MicroVM chega ao estado TERMINATED após a liberação dos recursos. Iniciar a MicroVM com sucesso, por si só, não comprova que a integração funciona.

No diretório do exemplo da AWS, use jq para ler o ARN da imagem e a região no arquivo de estado salvo durante a criação da imagem. Ajuste o caminho se tiver usado um valor personalizado para --state e substitua o grupo de logs se tiver renomeado a função de inicialização:

123456789image_state=application_managed/.local/image.json
region=$(jq -r '.region' "$image_state")
image_arn=$(jq -r '.image_arn' "$image_state")

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

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

Registre juntos os IDs da sessão e da MicroVM nos logs para rastrear uma execução. Não registre credenciais nem o corpo bruto das requisições de webhook nos logs.

Solução de problemas

Em caso de falha de conexão, examine agent.session.environment.failed e os logs do executor. Consulte Sandboxes auto-hospedados para conhecer o contrato comum de integração do executor.

Referências

• Ciclo de vida: Execução e uso de MicroVMs explica como iniciar, suspender, retomar e encerrar MicroVMs.
• Segurança: Segurança e permissões aborda perfis do IAM, tokens de autenticação e controles de acesso.