View a markdown version of this page

Lambda MicroVM을 OpenAI Agents API의 샌드박스로 사용 - AWS Lambda
작동 방식키 속성사전 조건MicroVM 이미지 준비MicroVM 시작턴 종료턴 사이에 일시 중지 및 재개네트워킹모니터링문제 해결관련 리소스

Lambda MicroVM을 OpenAI Agents API의 샌드박스로 사용

AWS Lambda MicroVM을 OpenAI Agents API로 구축된 에이전트를 위한 자체 호스팅 환경으로 사용하여 제어하는 인프라에서 워크스페이스 파일, 도구 실행 및 네트워크 액세스를 유지할 수 있습니다. OpenAI는 에이전트 하네스를 실행하고 Lambda MicroVM은 작업을 실행합니다. 이 예제에서는 에이전트의 도구 호출을 실행하고 세션의 워크스페이스 파일을 보관하는 codex exec-server를 실행합니다. 이미지 콘텐츠, 실행기가 취할 수 있는 네트워크 경로, 실행 역할의 범위가 지정된 AWS 리소스를 결정합니다.

각 MicroVM은 이미지의 스냅샷에서 부팅되는 Firecracker 격리 환경으로 실행됩니다. MicroVM의 총 수명은 실행 및 일시 중지 시간을 포함하여 최대 8시간입니다. 마지막 턴 후 종료하거나 턴 사이에 일시 중지합니다. 재사용 가능한 이미지 하나를 빌드한 다음 애플리케이션 또는 웹후크 시작 관리자에서 MicroVM을 시작합니다. 두 접근 방식 모두 동일한 이미지와 자격 증명을 사용합니다. 자세한 내용은 Lambda MicroVM의 OpenAI Agents API 자체 호스팅 샌드박스에 대한 참조 예제를 검토하세요.

작동 방식

Webhook 관리형 경로에서 시작 관리자 Lambda 함수는 세션에 실행기가 처음 필요할 때 MicroVM을 시작합니다. 기존 MicroVM을 재사용하여 일시 중지된 경우 먼저 재개합니다. 애플리케이션은 마지막 턴 후 이를 종료합니다. 그림 1은 흐름을 보여줍니다.

  1. 애플리케이션에서 자체 호스팅 세션을 생성하고 Agents API로 입력을 전송합니다.

  2. 세션에 실행기가 필요한 경우 OpenAI는 environment_connection 작업과 함께 agent.session.action_required 웹후크를 계정의 Amazon API Gateway 엔드포인트로 전송합니다.

  3. 시작 관리자 Lambda 함수는 웹후크 서명을 확인하고, 현재 세션을 검색하고, 핸들러가 해당 세션을 소유하고 있는지 확인합니다.

  4. 시작 관리자는 이미지, 실행 역할, 네트워크 커넥터 및 세션의 연결 값을 포함하는 runHookPayload를 사용하여 RunMicrovm을 호출합니다.

  5. MicroVM의 /run 후크는 IAM 실행 역할을 사용하여 AWS Secrets Manager에서 실행기 키를 검색하고 Codex를 시작합니다.

  6. 실행기는 https://api.openai.com에서 OpenAI에 등록합니다. 그런 다음 wss://codex-cloud-environments.chatgpt.com에 대한 보안 WebSocket 연결을 열어 도구 명령을 수신하고 결과를 반환합니다.

  7. 애플리케이션은 MicroVM의 인증된 HTTPS 엔드포인트를 통해 입력 파일을 업로드하고 출력 파일을 다운로드할 수 있습니다. 세션 이벤트 스트림을 따르며 턴 사이에 MicroVM을 일시 중지할 수 있습니다.

  8. 애플리케이션은 마지막 턴 후 MicroVM을 종료합니다.

AWS Lambda MicroVM의 에이전트 API 샌드박스에 대한 Webhook 관리형 프로비저닝

그림 1. AWS Lambda MicroVM의 에이전트 API 샌드박스에 대한 Webhook 관리형 프로비저닝

애플리케이션 키와 웹후크 서명 보안 암호를 MicroVM 외부에 보관합니다. 시작 관리자는 실행기 키 보안 암호 ARN만 전달합니다. VM은 실행 역할을 사용하여 키를 검색합니다.

키 속성

속성 혜택
Firecracker 격리 각 세션의 MicroVM에 대한 하드웨어 가상화 경계
스냅샷 기반 시작 각 MicroVM은 준비된 이미지의 스냅샷에서 시작됩니다.
실행 역할을 통한 IAM /run 후크는 MicroVM의 실행 역할로 실행기 키를 읽습니다. 키는 이미지에 저장되지 않습니다.
상태 저장 지속 시간 각 MicroVM은 일시 중지 시간을 포함하여 최대 8시간 동안 실행될 수 있습니다.
턴 사이에 일시 중지 및 재개 메모리 및 디스크 상태가 보존되므로 후속 턴이 동일한 환경에서 계속됩니다.
사용량 기반 컴퓨팅 VM을 실행하면 컴퓨팅 요금이 발생합니다. 일시 중지하면 컴퓨팅 요금이 중지됩니다. 스냅샷 보관과 읽기/쓰기는 별도로 청구됩니다.

사전 조건

  • Lambda MicroVM 액세스 권한이 있는 AWS 계정, lambda-microvms가 포함된 AWS CLI 버전, 이미지를 빌드하고 MicroVM을 실행할 수 있는 권한. Amazon Simple Storage Service(Amazon S3) 아티팩트 버킷 및 AWS Identity and Access Management(IAM) 이미지 빌드 역할을 생성하려면 첫 번째 Lambda MicroVM 생성를 참조하세요.

  • 세션을 생성하고 입력을 제출하기 위한 OpenAI 애플리케이션 키(OPENAI_API_KEY)입니다.

  • 세션과 동일한 조직, 프로젝트, 사용자 또는 서비스 계정이 있는 별도의 OpenAI 실행기 키(OPENAI_EXECUTOR_API_KEY)입니다. codex/agents-api/executor와 같은 Secrets Manager에 저장합니다. /run 후크는 이를 CODEX_API_KEY로 Codex에 전달합니다.

  • 실행기 키 보안 암호만 읽을 수 있는 MicroVM 실행 역할입니다. 보안 암호가 고객 관리형 AWS Key Management Service(AWS AWS KMS) 키를 사용하는 경우 복호화 권한을 추가합니다. 보안 및 권한 섹션을 참조하세요.

MicroVM 이미지 준비

Codex CLI, 도구 종속성, /workspace와 같은 작업 디렉터리, 수명 주기 후크용 HTTP 서버가 포함된 이미지를 빌드합니다.

후크 동작
/aws/lambda-microvms/runtime/v1/ready 서버가 Lambda의 스냅샷 생성 준비가 완료되면 HTTP 200을 반환합니다. 실행기는 연결 해제된 상태로 유지됩니다.
/aws/lambda-microvms/runtime/v1/run 세션 연결 값과 보안 암호 ARN을 읽고 실행기 키를 가져온 다음 실행기를 시작합니다.
/aws/lambda-microvms/runtime/v1/validate 선택 사항: Codex가 실행되고 워크스페이스가 쓰기 가능한지 확인합니다.
/aws/lambda-microvms/runtime/v1/suspend 일시 중지/재개에 필요합니다. 실행기를 중지하고 AWS가 VM의 스냅샷을 생성하기 전에 쓰기를 플러시합니다.
/aws/lambda-microvms/runtime/v1/resume 일시 중지/재개에 필요합니다. 키를 다시 가져오고 동일한 환경에 대해 실행기를 다시 시작합니다.
/aws/lambda-microvms/runtime/v1/terminate 선택 사항: 실행기를 중지하고 종료 전에 쓰기를 플러시합니다.

Amazon S3 아티팩트에 Dockerfile 및 후크 서버를 패키징한 다음 8GB의 기준 메모리(4 vCPU 기준)로 codex-executor 이미지를 빌드합니다. 이미지 구성에서 선택한 후크를 활성화하고 후크 포트를 서버와 일치하도록 설정합니다. 세션 ID, 자격 증명 및 라이브 실행기 연결을 이미지 스냅샷에서 제외합니다. 빌드 및 후크 구성은 MicroVM 이미지를 참조하세요.

시작 시 애플리케이션 또는 런처가 runHookPayload에서 다음 값을 JSON으로 직렬화합니다.

값 용도
session.environment.id 실행기가 연결되는 환경을 식별합니다.
session.environment.remote_url 실행기의 OpenAI 연결 URL을 제공합니다.
실행기 키 보안 암호 ARN 후크가 MicroVM의 실행 역할을 사용하여 키를 검색할 수 있도록 합니다.

후크 제한 시간을 방지하려면 실행기 프로세스가 시작되면 턴이 완료될 때까지 기다리지 않고 /run 후크에서 반환합니다.

MicroVM 시작

애플리케이션 또는 웹후크 런처에서 MicroVM을 시작할 수 있습니다. 두 경우 모두 턴이 완료될 때까지 세션 이벤트 스트림을 열어 둡니다.

애플리케이션 관리형 프로비저닝

  1. 작업 디렉터리가 이미지와 일치하는 자체 호스팅 세션을 생성한 다음 이벤트 스트림을 엽니다.

  2. 이미지 ARN 및 버전, 실행 역할, 네트워크 커넥터 및 runHookPayload를 사용하여 RunMicrovm을 호출합니다. 반환된 microvmId를 세션 ID와 함께 저장합니다.

  3. agent.session.environment.connected를 기다린 후 입력을 보내고 턴의 결과를 따릅니다.

  4. 턴 종료에 설명된 대로 출력 파일을 검색하고 턴을 종료합니다.

웹후크 관리형 프로비저닝

애플리케이션이 세션을 생성하고 스트림을 열고 입력을 제출합니다. 웹후크가 도착하면 런처가 나머지를 처리합니다.

  1. 런처를 호출하는 POST /webhook 경로를 Amazon API Gateway에 배포합니다. 런처에게 자격 증명을 읽고, 선택한 이미지에서 MicroVM을 검사, 시작, 재개 및 종료하고, MicroVM 실행 역할을 전달하고, 구성된 네트워크 커넥터를 사용할 수 있는 권한을 부여합니다.

  2. agent.session.action_required 및 agent.session.failed에 대한 엔드포인트를 등록합니다. 런처의 애플리케이션 키를 사용하여 엔드포인트의 서명 보안 암호를 Secrets Manager에 저장합니다.

  3. 세션에 액세스하거나 컴퓨팅을 시작하기 전에 원시 요청 본문과 비교하여 웹후크 서명을 확인합니다. 그런 다음 현재 세션을 검색하고, 예를 들어 저장된 전용 에이전트를 일치시켜 핸들러가 해당 세션을 소유하고 있는지 확인합니다.

  4. environment_connection이 여전히 보류 중인 경우 GetMicrovm을 사용하여 기록된 MicroVM을 검사합니다. 일시 중지된 경우 ResumeMicrovm으로 재개합니다. VM이 기록되지 않은 경우에만 RunMicrovm을 호출한 후 ID를 저장합니다. 저장에 실패하면 시작한 VM을 종료합니다. 연결 제한 시간 전에 실행기가 연결되면 대기 중인 입력은 다시 제출하지 않고 진행됩니다.

  5. agent.session.failed 이벤트의 경우 현재 세션을 검색하고 상태가 여전히 실패한 경우에만 기록된 MicroVM을 종료합니다. 삭제된 세션, 해결된 작업 및 다른 핸들러가 소유한 세션은 무시합니다.

참조 예제는 세션 메타데이터에 MicroVM ID를 저장합니다. 동시 웹후크 전송은 해당 ID가 저장되기 전에 추가 VM을 시작할 수 있습니다. 프로덕션에 사용하기 전에 동일한 세션에 대한 동시 시작을 방지하고 웹후크 이벤트를 중복 제거하세요.

턴 종료

그림 2는 한 번의 턴에 대한 MicroVM 수명 주기와 후속 턴에 대한 선택적 일시 중지 및 재개 경로를 보여줍니다.

에이전트 API 턴 하나에 대한 MicroVM 수명 주기

그림 2. 에이전트 API 턴 하나에 대한 MicroVM 수명 주기입니다. RunMicrovm은 MicroVM을 시작하고, /run 후크는 실행기를 시작하고, 환경을 연결하고, 턴을 실행하고, 턴을 종료합니다. 단일 턴 경로에서 파일을 검색하고 TerminateMicrovm을 호출합니다. 다중 턴 경로에서 MicroVM은 턴 후 일시 중지되고 다음 연결 요청 시 재개됩니다.

세션 스트림에서 기본 에이전트에 대해 agent.session.turn.completed, agent.session.turn.failed, 또는 agent.session.turn.cancelled를 기다립니다. 여기서 event.turn.subagent_id는 null입니다. 하위 에이전트는 MicroVM을 공유하므로 터미널 이벤트가 정리를 트리거하지 않습니다. 필요한 파일을 검색합니다. 마지막 턴 후 TerminateMicrovm을 호출하고 VM이 TERMINATED에 도달하는지 확인합니다. 후속 턴의 경우 계속 실행하거나 일시 중지합니다. 애플리케이션에 오류가 발생하면 정리를 실행합니다.

턴 결과는 웹후크 구독이 아닌 스트림 이벤트로 도착합니다. agent.session.failed 웹후크는 세션 실패를 다루지만 모든 실패 턴을 다루지는 않습니다. 따라서 대기 입력이 시작되기 전에 도착할 수 있으므로 agent.session.idle에서만 종료하지 마십시오.

정리가 실행되지 않는 경우 MicroVM의 수명을 제한하려면 시작 시 다음 설정을 구성합니다.

설정 지침
maximumDurationInSeconds 15분 테스트의 경우 900과 같이 워크로드의 상한을 설정합니다. 이 제한은 작업이 진행 중인 동안에도 적용됩니다.
maxIdleDurationSeconds 예상 워크로드를 포함합니다. Lambda는 인바운드 트래픽을 측정하므로 실행기의 아웃바운드 연결이 이 타이머를 재설정하지 않습니다.
suspendedDurationSeconds / autoResumeEnabled 일시 중지된 MicroVM을 재개하지 않는 단일 턴 패턴에는 0 / false를 사용합니다.

수명 및 유휴 제어는 MicroVM 실행 및 사용을 참조하세요.

세션을 별도로 삭제합니다. 세션을 삭제해도 MicroVM이 중지되거나 삭제 웹후크가 전송되지 않습니다. 재사용을 위해 이미지와 실행기 키를 비밀로 유지합니다. 후속 턴을 처리하려면 샌드박스 수명 주기를 참조하세요.

턴 사이에 일시 중지 및 재개

턴 사이에 메모리 및 디스크 상태를 유지하려면 기본 에이전트의 턴이 완료되고 모든 도구와 하위 에이전트가 완료된 후 MicroVM을 일시 중지합니다. 세션에서 다음에 실행기가 필요할 때 동일한 MicroVM을 재개합니다.

  • 0이 아닌 suspendedDurationSeconds를 설정합니다. MicroVM이 일시 중지된 동안 스냅샷 스토리지 요금이 적용됩니다.

  • /suspend 후크를 활성화하여 쓰기를 플러시하고 연결을 닫으며, /resume 후크를 활성화하여 자격 증명을 새로 고치고 실행기를 다시 연결합니다.

  • 애플리케이션 관리형 경로는 다음 입력을 보내기 전에 VM을 재개합니다. 웹후크 관리형 경로에서 입력을 제출하면 VM을 재개하는 연결 요청이 트리거됩니다. 실행기가 다시 연결되면 턴이 진행됩니다.

참고

maximumDurationInSeconds는 총 실행 및 일시 중지 시간을 8시간으로 제한합니다. 온디맨드로 재개하려면 ResumeMicrovm을 호출합니다. 자동 재개에는 MicroVM으로의 인바운드 트래픽이 필요합니다. 에이전트 API 입력만으로는 재개되지 않습니다.

네트워킹

OpenAI에 대한 실행기의 필수 아웃바운드 연결 및 Secrets Manager에 대한 액세스를 허용합니다. 프라이빗 리소스에 도달하거나 자체 네트워크 제한을 적용하려면 시작 시 VPC 송신 커넥터를 연결합니다. 송신 네트워크 커넥터 작업 섹션을 참조하세요.

이 예제에서는 서버의 포트로 범위가 지정된 인증 토큰을 사용하여 MicroVM의 HTTPS 엔드포인트를 통한 파일 업로드 및 다운로드를 지원합니다.

모니터링

두 예제 중 하나를 실행한 후 hello.txt가 다운로드되고 MicroVM이 TERMINATED에 도달하며 삭제된 세션이 HTTP 404를 반환하는지 확인합니다.

런처 로그. CloudWatch Logs에서 런처 Lambda 함수의 로그를 검토합니다.

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

MicroVM 실행 MICROVM_IMAGE_ARN을 이미지 ARN으로 설정하고, 배포의 AWS 리전을 사용하고, 이미지의 MicroVM을 나열합니다.

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

실행을 처음부터 끝까지 추적할 수 있도록 세션과 MicroVM ID를 함께 로깅합니다. 자격 증명과 원시 웹후크 본문을 로그에서 계속 제외합니다.

문제 해결

증상 확인할 사항
웹후크 서명이 거부됨 엔드포인트의 서명 보안 암호를 사용하고 수정되지 않은 요청 본문을 확인합니다.
MicroVM 시작 안 됨 웹후크 구독, 세션 소유권 필터, 보류 중인 environment_connection 작업 및 런처의 IAM 권한을 확인합니다.
이미지 빌드 실패 Amazon S3 아티팩트, 이미지 빌드 역할 및 /ready 후크 응답을 확인합니다.
/run 실패 또는 시간 초과 보안 암호 액세스 및 실행기 시작을 확인합니다. 턴이 아닌 프로세스를 시작한 후 반환합니다.
실행기가 연결할 수 없음 환경 ID, 원격 URL, 키 소유권 및 아웃바운드 네트워크 액세스를 확인합니다.
턴 중 MicroVM 중지 최대 수명 및 유휴 정책을 확인합니다. 아웃바운드 실행기 트래픽은 인바운드 활동으로 계산되지 않습니다.

연결 실패의 경우 agent.session.environment.failed 이벤트와 실행기 로그를 검사합니다. 공유 실행기 계약의 경우 자체 호스팅 샌드박스를 참조하세요.