# 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](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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.
1. 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.
1. 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.
1. 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.
1. 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.
1. 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.
1. 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.
1. Após o turno final, sua aplicação encerra a MicroVM.
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](microvms-getting-started.md).
+ 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](microvms-security.md).
## 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](microvms-images.md).
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.
1. 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.
1. Aguarde `agent.session.environment.connected`, envie a entrada e acompanhe o resultado do turno.
1. Recupere os arquivos de saída e finalize o turno conforme descrito em [Encerrar um turno](#microvms-integrations-openai-agents-api-ending-turn).
### 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.
1. 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.
1. 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.
1. 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.
1. 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](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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.
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](microvms-launching.md).
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](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws).
## 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](microvms-networking.md#microvms-networking-connectors).
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](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws).
## Recursos relacionados
+ [AWS Lambda MicroVMs](lambda-microvms-guide.md)
+ [Execução e uso de microVMs](microvms-launching.md)
+ [Segurança e permissões](microvms-security.md)
+ [Referência da API RunMicroVM](https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html)
+ [Sandboxes auto-hospedadas da API Agents da OpenAI](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)
+ [API Agents da OpenAI no guia AWS](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)