AWS Lambda MicroVMs를 사용하면 AWS 계정에서 에이전트의 도구를 실행할 수 있습니다. OpenAI는 에이전트 하네스를 실행하고, 각 MicroVM은 codex exec-server를 실행하며 세션의 워크스페이스 파일을 보관합니다.
예제는 기본적으로 한 턴에 MicroVM 하나를 사용합니다. 재사용할 이미지를 준비한 다음 애플리케이션에서 직접 또는 OpenAI 웹훅을 통해 MicroVM을 시작하세요. 두 방식 모두 같은 이미지와 자격 증명을 사용합니다. 세션마다 프로비저닝을 담당할 주체를 하나만 선택하세요.
AWS Cookbook 예제에서 애플리케이션 관리형 샌드박스와 웹훅 관리형 샌드박스를 실행해 보세요.
작동 방식
웹훅을 사용하는 경우 애플리케이션이 자체 호스팅 세션을 만들고 입력을 보냅니다. 세션에 실행기가 필요해지면 OpenAI가 agent.session.action_required 이벤트를 보내며, 이 이벤트에는 environment_connection 작업이 포함됩니다. API Gateway가 웹훅을 런처 역할을 하는 Lambda 함수로 전달합니다. 이 함수는 서명을 검증하고 현재 세션을 확인한 뒤 MicroVM을 시작하거나 재개합니다.
MicroVM의 /run 훅은 Secrets Manager에서 환경 키를 가져와 실행기를 시작합니다. 실행기가 OpenAI에 아웃바운드 연결을 설정하면 대기 중이던 입력 처리가 시작됩니다. 애플리케이션은 세션 스트림을 구독하고 출력 파일을 다운로드한 뒤 마지막 턴이 끝나면 MicroVM을 종료합니다.
시작하기 전에
다음 리소스를 준비하세요.
- AWS 액세스: Lambda MicroVMs를 사용할 수 있는 계정,
lambda-microvms명령어가 포함된 AWS CLI, 이미지를 빌드하고 MicroVM을 실행할 권한이 필요합니다. AWS 시작 가이드에 따라 아티팩트를 저장할 S3 버킷과 이미지 빌드에 사용할 IAM 역할을 만드세요. - 애플리케이션 키:
OPENAI_API_KEY를 사용해 세션을 만들고 입력을 제출하세요. - 환경 키(
OPENAI_EXECUTOR_API_KEY): 애플리케이션 키와 조직, 프로젝트, 소유자(사용자 또는 서비스 계정)가 일치하는 별도의 환경 키를 만드세요. 키 값을 Secrets Manager에 저장하세요. 예를 들어 보안 암호의 이름을codex/agents-api/executor로 지정할 수 있습니다./run훅은 이 키를CODEX_API_KEY로 Codex에 전달합니다. - MicroVM 실행 역할: 이 역할에는 환경 키가 저장된 보안 암호만 읽을 수 있도록 권한을 부여하세요. 고객 관리형 KMS 키를 사용한다면 복호화 권한도 추가하세요. 역할 설정 방법은 AWS 보안 및 권한 문서를 참고하세요.
애플리케이션 키와 웹훅 서명 비밀 키는 MicroVM 외부에 보관하세요. 웹훅 런처는 Secrets Manager에 별도의 보안 암호를 두고 이 자격 증명을 저장해야 합니다. VM에는 환경 키가 저장된 보안 암호의 ARN만 전달합니다.
재사용할 이미지 준비
Codex CLI, 도구 종속성, /workspace와 같은 작업 디렉터리, AWS 수명 주기 훅을 처리할 HTTP 서버를 포함하는 이미지를 빌드하세요.
예제에서는 /aws/lambda-microvms/runtime/v1 아래에 다음 훅을 구현합니다.
| 훅 | 동작 |
|---|---|
/ready |
AWS가 스냅샷을 생성할 수 있도록 서버 준비가 끝나면 HTTP 200을 반환합니다. 실행기는 연결하지 않은 상태로 둡니다. |
/validate |
Codex가 실행되고 워크스페이스에 쓸 수 있는지 확인합니다. |
/run |
세션 연결 정보와 보안 암호 ARN을 읽고 환경 키를 가져온 뒤 실행기를 시작합니다. |
/suspend |
AWS가 VM 스냅샷을 생성하기 전에 실행기를 중지합니다. |
/resume |
환경 키를 다시 불러오고 저장된 연결 정보로 실행기를 다시 시작합니다. |
/terminate |
VM이 종료되기 전에 실행기를 중지합니다. |
Dockerfile과 훅 서버를 S3 아티팩트 하나로 패키징한 뒤 codex-executor와 같이 버전이 지정된 이미지를 빌드하세요. 이미지 구성에서 훅 6개를 모두 활성화하고 훅 포트를 서버 포트와 일치시키세요. 이미지 스냅샷에는 세션 ID, 자격 증명, 활성 실행기 연결이 포함되지 않도록 하세요. 빌드 및 훅 구성 방법은 AWS MicroVM 이미지 문서를 참고하세요.
MicroVM을 시작할 때 애플리케이션이나 런처는 다음 값을 JSON으로 직렬화해 runHookPayload에 담습니다.
| 값 | 용도 |
|---|---|
session.environment.id |
실행기가 연결할 환경을 식별합니다. |
session.environment.remote_url |
실행기가 OpenAI에 연결할 때 사용할 URL을 제공합니다. |
| 환경 키가 저장된 보안 암호의 ARN | 훅이 MicroVM 실행 역할로 환경 키를 가져올 수 있게 합니다. |
/run 훅은 AWS 요청 본문에서 이 문자열을 파싱하고 키를 가져온 뒤 자식 프로세스 환경에 CODEX_API_KEY를 설정하고 실행기를 시작합니다. 프로세스가 시작되면 훅에서 반환하세요. 에이전트의 턴이 끝날 때까지 기다리면 훅이 시간 초과될 수 있습니다.
실행기에 필요한 아웃바운드 연결과 Secrets Manager 액세스를 허용하세요. 프라이빗 리소스에 접근해야 하거나 네트워크 제한이 있는 경우 AWS 이그레스 커넥터를 구성하세요. 파일을 다운로드하려면 서버에 라우트를 추가하세요. 그런 다음 해당 서버 포트에만 유효한 AWS 인증 토큰을 사용해 MicroVM의 HTTP 엔드포인트를 통해 라우트를 호출하세요.
MicroVM 시작
애플리케이션 관리형 프로비저닝과 웹훅 관리형 프로비저닝 중 하나를 선택하세요. 두 방식 모두 실행기가 연결되고 입력 처리를 거쳐 턴이 완료될 때까지 세션 이벤트 스트림을 열어 두세요.
애플리케이션 관리형 프로비저닝
- 작업 디렉터리가 이미지에 설정된 작업 디렉터리와 일치하도록 자체 호스팅 세션을 만든 뒤 세션의 이벤트 스트림을 여세요.
- AWS RunMicrovm을 호출할 때 이미지 ARN과 버전, 실행 역할, 네트워크 커넥터,
runHookPayload를 전달하세요. 반환된microvmId를 세션 ID와 함께 저장하세요. agent.session.environment.connected이벤트를 기다린 뒤 입력을 보내고 스트림에서 턴 결과를 확인하세요.- 출력 파일을 가져온 뒤 MicroVM을 종료하세요.
웹훅 관리형 프로비저닝
API Gateway HTTP API와 런처 Lambda를 사용하세요. 애플리케이션은 세션을 만들고 스트림을 연 뒤 입력을 제출합니다. 세션에 연결이 필요해지면 웹훅을 받은 런처가 컴퓨팅 리소스를 시작하거나 재개합니다.
- 런처를 호출하는
POST /webhook라우트를 배포하세요. 선택한 이미지에 대해 런처에lambda:RunMicrovm,lambda:GetMicrovm,lambda:ResumeMicrovm,lambda:TerminateMicrovm권한을 부여하세요. 런처에는 자체 자격 증명을 읽고 MicroVM 실행 역할을 전달하며 구성된 네트워크 커넥터를 사용할 권한도 필요합니다. - 엔드포인트를 등록하고
agent.session.action_required와agent.session.failed이벤트를 구독하세요. 엔드포인트의 서명 비밀 키를 런처의 애플리케이션 키와 함께 저장하세요. - 세션에 접근하거나 컴퓨팅 리소스를 시작하기 전에 원본 요청 본문으로 웹훅 서명을 검증하세요. 현재 세션을 조회하고 이 핸들러가 담당하는 세션인지 확인하세요. 예를 들어 세션의 에이전트가 이 핸들러 전용으로 저장해 둔 에이전트와 일치하는지 확인할 수 있습니다.
environment_connection작업이 아직 대기 중이라면GetMicrovm으로 기록된 VM의 상태를 확인하세요.SUSPENDED상태의 VM은ResumeMicrovm으로 재개하고,PENDING또는RUNNING상태의 VM은 연결될 때까지 기다리세요. 기록된 VM이 없을 때만RunMicrovm을 호출하세요. VM ID를 세션 메타데이터에 저장하고, 저장에 실패하면 방금 시작한 VM을 종료하세요.- 세션이 여전히
failed상태라면 해당 세션에 기록된 MicroVM을 종료하세요. 삭제된 세션, 이미 처리된 작업, 다른 핸들러가 담당하는 이벤트는 무시하세요.
연결 제한 시간 내에 실행기가 연결되면 입력을 다시 제출하지 않아도 대기 중인 입력 처리가 시작됩니다.
프로토타입에서는 MicroVM을 동기적으로 시작하고 ID를 세션 메타데이터에 저장해도 됩니다. 프로덕션에서 사용하기 전에는 어느 핸들러가 시작을 담당하는지 영구 저장하고 시작 작업의 멱등성을 보장하세요. 또한 프로비저닝 작업을 큐에 넣으세요. 메타데이터만으로는 중복 시작을 막을 수 없으며, 시작이 지연되면 웹훅 응답 기한을 넘길 수 있습니다.
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 이벤트만 보고 VM을 종료하지 마세요. 대기 중인 입력 처리가 시작되기 전에 이 이벤트가 도착할 수 있습니다.
정리 작업이 누락될 경우에 대비해 다음 AWS 제한을 설정하세요.
| 설정 | 지침 |
|---|---|
maximumDurationInSeconds |
워크로드의 최대 지속 시간을 설정하세요. 예를 들어 15분 테스트에는 900을 지정합니다. 제한에 도달하면 진행 중인 작업이 중단될 수 있습니다. |
maxIdleDurationSeconds |
예상 워크로드를 처리하기에 충분한 유휴 시간을 설정하세요. AWS는 인바운드 트래픽을 측정하므로 실행기의 아웃바운드 연결은 이 타이머를 초기화하지 않습니다. |
suspendedDurationSeconds / autoResumeEnabled |
예제의 기본값은 0 / false이며, 300 / false는 --suspend-resume 옵션을 사용할 때의 값입니다. |
수명 및 유휴 시간 설정은 AWS MicroVM 실행 및 사용 문서를 참고하세요.
세션 삭제는 별도로 수행하세요. 세션을 삭제해도 AWS 컴퓨팅 리소스가 종료되거나 삭제 웹훅이 전송되지는 않습니다. 이미지와 환경 키가 저장된 보안 암호는 재사용할 수 있도록 보관하세요. 후속 턴에서는 샌드박스 수명 주기를 참고해 컴퓨팅 리소스의 재사용 또는 교체와 파일 보존을 함께 관리하세요.
턴 사이에 일시 중단 및 재개
AWS의 일시 중단 및 재개 기능을 사용하면 턴 사이에도 메모리와 디스크 상태를 유지할 수 있습니다. suspendedDurationSeconds를 0이 아닌 값으로 설정하세요. 일시 중단 중에는 스냅샷 스토리지 요금이 부과됩니다. maximumDurationInSeconds에 따라 실행 시간과 일시 중단 시간을 합한 총시간은 최대 8시간으로 제한됩니다.
두 예제 중 하나를 --suspend-resume 옵션으로 실행하면 /workspace/hello.txt 파일을 쓰고 VM을 일시 중단한 뒤 두 번째 턴에서 파일을 읽습니다. 애플리케이션 관리형 예제는 VM을 직접 재개합니다. 웹훅 관리형 예제는 입력을 한 번 더 보내며, 이에 따라 런처가 기록된 VM을 재개합니다. 두 예제 모두 파일 내용을 확인하고 마지막 턴이 끝나면 리소스를 정리합니다.
/suspend 훅은 실행기를 중지하고, /resume 훅은 실행기의 키를 다시 불러와 연결을 복구합니다. 도구와 하위 에이전트의 작업이 모두 끝난 뒤에만 VM을 일시 중단하세요. AWS가 VM을 자동으로 재개하려면 VM에 인바운드 트래픽이 도달해야 합니다. Agents API에 입력을 보내는 것만으로는 VM이 재개되지 않습니다.
검증 및 모니터링
/workspace에 작은 파일을 만들도록 요청하는 프롬프트로 테스트하세요. 실행기가 연결되고 턴이 완료되는지, 다운로드한 파일에 예상한 결과가 있는지, 정리 후 MicroVM이 TERMINATED 상태에 도달하는지 확인하세요. MicroVM이 정상적으로 시작됐다는 사실만으로는 연동이 제대로 작동하는지 확인할 수 없습니다.
AWS 예제 디렉터리에서 jq를 사용해 저장된 빌드 상태에서 이미지 ARN과 리전을 읽으세요. --state로 다른 경로를 지정했다면 경로를 조정하고, 런처 이름을 변경했다면 로그 그룹도 변경하세요.
image_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실행 과정을 추적할 수 있도록 세션 ID와 MicroVM ID를 함께 기록하세요. 자격 증명과 웹훅 요청 본문 원문은 로그에 남기지 마세요.
문제 해결
| 증상 | 확인할 사항 |
|---|---|
| 웹훅 서명이 거부됨 | 엔드포인트의 서명 비밀 키를 사용하고 수정되지 않은 요청 본문으로 서명을 검증하세요. |
| MicroVM이 시작되지 않음 | 웹훅 구독, 세션 소유권 필터, 대기 중인 environment_connection 작업, 런처의 IAM 권한을 확인하세요. |
| 이미지 빌드 실패 | S3 아티팩트, 이미지 빌드 역할, /ready 훅의 응답을 확인하세요. |
/run 실패 또는 시간 초과 |
보안 암호에 접근할 수 있는지, 실행기가 시작되는지 확인하세요. 턴이 끝날 때까지 기다리지 말고 프로세스가 시작되면 훅에서 반환하세요. |
| 실행기 연결 실패 | 환경 ID, 원격 URL, 키 소유권, 아웃바운드 네트워크 액세스를 확인하세요. |
| 턴 도중 VM이 중지됨 | 최대 수명과 유휴 정책을 확인하세요. 실행기의 아웃바운드 트래픽은 인바운드 활동으로 집계되지 않습니다. |
연결에 실패하면 agent.session.environment.failed 이벤트와 실행기 로그를 확인하세요. 실행기가 공통으로 따라야 하는 규약은 자체 호스팅 샌드박스를 참고하세요.
참고 자료
- 수명 주기: MicroVM 실행 및 사용에서는 시작, 일시 중단, 재개, 종료를 설명합니다.
- 보안: 보안 및 권한에서는 IAM 역할, 인증 토큰, 액세스 제어를 설명합니다.