View a markdown version of this page

Menggunakan Lambda MicroVMS sebagai kotak pasir untuk OpenAI Agents API - AWS Lambda
Cara kerjanyaProperti utamaPrasyaratMempersiapkan gambar microVMMeluncurkan MicroVMSMengakhiri giliranMenangguhkan dan melanjutkan di antara belokanJaringanMemantauPemecahan masalahSumber daya terkait

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menggunakan Lambda MicroVMS sebagai kotak pasir untuk OpenAI Agents API

Anda dapat menggunakan AWS Lambda MicroVMS sebagai lingkungan yang di-host sendiri untuk agen yang dibangun dengan OpenAI Agents API, menyimpan file ruang kerja, eksekusi alat, dan akses jaringan di infrastruktur yang Anda kendalikan. OpenAI menjalankan harness agen; Lambda microVM mengeksekusi tugas Anda. Dalam contoh ini, ia berjalancodex exec-server, yang mengeksekusi panggilan alat agen dan menyimpan file ruang kerja sesi. Anda memutuskan konten gambar, jalur jaringan yang dapat diambil pelaksana, dan AWS sumber daya yang menjadi cakupan peran pelaksanaannya.

Setiap microVM berjalan sebagai Firecracker-isolated lingkungan yang melakukan boot dari snapshot gambar Anda. Total masa pakai microVM hingga 8 jam, termasuk waktu berjalan dan ditangguhkan. Hentikan setelah belokan terakhir, atau tunda di antara belokan. Anda membuat satu gambar yang dapat digunakan kembali, lalu meluncurkan microVM dari aplikasi Anda atau peluncur webhook. Kedua pendekatan menggunakan gambar dan kredenSIAL yang sama. Untuk detail selengkapnya, tinjau contoh referensi untuk kotak pasir yang di-host sendiri OpenAI Agents API di Lambda MicroVMS.

Cara kerjanya

Di jalur yang dikelola webhook, fungsi peluncur Lambda memulai microVM ketika sesi pertama kali membutuhkan eksekutor. Ini menggunakan kembali microVM yang ada, melanjutkannya terlebih dahulu jika ditangguhkan. Aplikasi Anda mengakhirinya setelah giliran terakhir. Gambar 1 menunjukkan aliran:

  1. Aplikasi Anda membuat sesi yang di-host sendiri dan mengirimkan masukan ke API Agen.

  2. Saat sesi membutuhkan eksekutor, OpenAI mengirimkan agent.session.action_required webhook dengan environment_connection tindakan ke titik akhir Amazon API Gateway di akun Anda.

  3. Fungsi peluncur Lambda memverifikasi tanda tangan webhook, mengambil sesi saat ini, dan mengonfirmasi bahwa handler memilikinya.

  4. Peluncur memanggil RunMicrovm dengan gambar, peran eksekusi, konektor jaringan, dan runHookPayload yang membawa nilai koneksi sesi.

  5. Pengait MicroVM menggunakan peran eksekusi IAM untuk mengambil kunci eksekutor dari AWS Secrets Manager dan memulai Codex. /run

  6. Pelaksana mendaftar dengan OpenAI di. https://api.openai.com Kemudian membuka WebSocket koneksi aman wss://codex-cloud-environments.chatgpt.com untuk menerima perintah alat dan mengembalikan hasil.

  7. Aplikasi Anda dapat mengunggah file input dan mengunduh file output melalui titik akhir HTTPS yang diautentikasi MicroVM. Ini mengikuti aliran acara sesi dan dapat menangguhkan microVM di antara belokan.

  8. Setelah giliran terakhir, aplikasi Anda mengakhiri microVM.

Webhook-managed penyediaan untuk kotak pasir API Agents di MicroVMS AWS Lambda

Gambar 1. Webhook-managed penyediaan untuk kotak pasir API Agents di MicroVMS AWS Lambda.

Jaga rahasia kunci aplikasi dan penandatanganan webhook di luar microVM. Peluncur hanya melewati ARN rahasia kunci eksekusi; VM mengambil kunci menggunakan peran eksekusi.

Properti utama

Properti Manfaat
Isolasi petasan Hardware-virtualized batas untuk microVM setiap sesi
Snapshot-based startup Setiap microVM diluncurkan dari snapshot gambar yang Anda siapkan
IAM melalui peran eksekusi Peng /run ait membaca kunci eksekutor dengan peran eksekusi microVM; kunci tidak disimpan dalam gambar
Durasi status Setiap microVM dapat berjalan hingga 8 jam, termasuk waktu yang ditangguhkan
Tangguhkan dan lanjutkan di antara belokan Memori dan status disk dipertahankan sehingga putaran tindak lanjut berlanjut di lingkungan yang sama
Usage-based menghitung Menjalankan VM dikenakan biaya komputasi. Penangguhan menghentikan biaya komputasi; penyimpanan snapshot dan reads/writes ditagih secara terpisah.

Prasyarat

  • AWS Akun dengan akses Lambda MicroVMS, versi AWS CLI yang menyertakanlambda-microvms, dan izin untuk membuat gambar dan menjalankan MicroVMS. Untuk membuat bucket artefak Amazon Simple Storage Service (Amazon S3) dan peran pembuatan gambar AWS Identity and Access Management (IAM), lihat. Buat Lambda MicroVM pertama Anda

  • Kunci aplikasi OpenAI (OPENAI_API_KEY) untuk membuat sesi dan mengirimkan masukan.

  • Kunci eksekutor OpenAI terpisah (OPENAI_EXECUTOR_API_KEY) dengan organisasi, proyek, dan akun pengguna atau layanan yang sama dengan sesi. Simpan di Secrets Manager, misalnya sebagaicodex/agents-api/executor. Peng /run ait meneruskannya ke Codex sebagaiCODEX_API_KEY.

  • Peran eksekusi MicroVM yang hanya dapat membaca rahasia kunci eksekutor. Jika rahasia menggunakan AWS kunci Key Management Service (AWS AWS KMS) yang dikelola pelanggan, tambahkan izin dekripsi. Lihat Keamanan dan izin.

Mempersiapkan gambar microVM

Buat gambar yang menyertakan Codex CLI, dependensi alat Anda, direktori kerja seperti/workspace, dan server HTTP untuk kait siklus hidup.

Kait Perilaku
/aws/lambda-microvms/runtime/v1/ready Mengembalikan HTTP 200 ketika server siap untuk Lambda mengambil snapshot. Pelaksana tetap terputus.
/aws/lambda-microvms/runtime/v1/run Membaca nilai koneksi sesi dan ARN rahasia, mengambil kunci eksekutor, dan memulai eksekutor.
/aws/lambda-microvms/runtime/v1/validate Opsional. Memeriksa apakah Codex berjalan dan ruang kerja dapat ditulis.
/aws/lambda-microvms/runtime/v1/suspend Diperlukan untuk suspend/resume. Menghentikan eksekutor dan membilas penulisan sebelum mengambil AWS snapshot VM.
/aws/lambda-microvms/runtime/v1/resume Diperlukan untuk suspend/resume. Mengambil kunci lagi dan memulai ulang eksekutor untuk lingkungan yang sama.
/aws/lambda-microvms/runtime/v1/terminate Opsional. Menghentikan eksekutor dan membilas tulisan sebelum penghentian.

Kemas Dockerfile dan kaitkan server dalam artefak Amazon S3, lalu buat codex-executor gambar dengan memori dasar 8 GB (4 dasar vCPU). Aktifkan kait yang dipilih dalam konfigurasi gambar dan atur port kait agar sesuai dengan server Anda. Jauhkan ID sesi, kredenSIAL, dan koneksi eksekutor langsung dari snapshot gambar. Untuk konfigurasi build dan hook, lihatGambar MicroVM.

Saat diluncurkan, aplikasi atau peluncur Anda membuat serial nilai-nilai berikut sebagai JSON di: runHookPayload

Nilai Tujuan
session.environment.id Mengidentifikasi lingkungan yang terhubung dengan pelaksana
session.environment.remote_url Menyediakan URL koneksi OpenAI pelaksana
Executor-key rahasia ARN Memungkinkan hook mengambil kunci menggunakan peran eksekusi microVM

Kembali dari /run hook setelah proses eksekutor dimulai, tanpa menunggu giliran selesai, untuk menghindari batas waktu hook.

Meluncurkan MicroVMS

Anda dapat meluncurkan MicroVMS dari aplikasi Anda atau dari peluncur webhook. Dalam kedua kasus tersebut, biarkan aliran acara sesi tetap terbuka sampai giliran selesai.

Application-managed penyediaan

  1. Buat sesi yang di-host sendiri yang direktori kerjanya cocok dengan gambar, lalu buka aliran acaranya.

  2. Panggil RunMicrovm dengan gambar ARN dan versi, peran eksekusi, konektor jaringan, danrunHookPayload. Simpan yang dikembalikan di microvmId samping ID sesi.

  3. Tungguagent.session.environment.connected, lalu kirim input dan ikuti hasil giliran.

  4. Ambil file output dan akhiri giliran seperti yang dijelaskan dalamMengakhiri giliran.

Webhook-managed penyediaan

Aplikasi Anda membuat sesi, membuka streamnya, dan mengirimkan masukan. Peluncur menangani sisanya saat webhook tiba.

  1. Terapkan POST /webhook rute di Amazon API Gateway yang memanggil peluncur. Berikan izin peluncur untuk membaca kredensialnya, memeriksa, meluncurkan, melanjutkan, dan menghentikan microVM dari gambar yang dipilih, meneruskan peran eksekusi microVM, dan menggunakan konektor jaringan yang dikonfigurasi.

  2. Daftarkan titik akhir untuk agent.session.action_required danagent.session.failed. Simpan rahasia penandatanganan titik akhir di Secrets Manager dengan kunci aplikasi peluncur.

  3. Verifikasi tanda tangan webhook terhadap badan permintaan mentah sebelum mengakses sesi atau meluncurkan komputasi. Kemudian ambil sesi saat ini dan konfirmasikan bahwa handler memilikinya, misalnya dengan mencocokkan agen tersimpan khusus.

  4. Jika environment_connection masih tertunda, periksa microVM yang direkam denganGetMicrovm. Lanjutkan dengan ResumeMicrovm jika ditangguhkan. Panggil RunMicrovm hanya jika tidak ada VM yang direkam, lalu simpan ID-nya. Jika penyimpanan gagal, hentikan VM yang Anda luncurkan. Jika pelaksana terhubung sebelum batas waktu koneksi, input menunggu berlangsung tanpa pengiriman ulang.

  5. Untuk suatu agent.session.failed peristiwa, ambil sesi saat ini dan hentikan microVM yang direkam hanya jika statusnya masih gagal. Abaikan sesi yang dihapus, tindakan yang diselesaikan, dan sesi yang dimiliki oleh handler lain.

Contoh referensi menyimpan ID microVM dalam metadata sesi. Pengiriman webhook bersamaan dapat meluncurkan VM tambahan sebelum ID itu disimpan. Sebelum penggunaan produksi, cegah peluncuran bersamaan untuk sesi yang sama dan deduplikat peristiwa webhook.

Mengakhiri giliran

Gambar 2 menunjukkan siklus hidup microVM untuk satu putaran, dan jalur penangguhan dan lanjutkan opsional untuk putaran lanjutan.

Siklus hidup MicroVM untuk satu giliran API Agen

Gambar 2. Siklus hidup MicroVM untuk satu giliran API Agen. RunMicrovmmeluncurkan microVM, kait /run memulai eksekutor, lingkungan terhubung, belokan berjalan, dan belokan berakhir. Di jalur satu putaran, Anda mengambil file dan menelep TerminateMicrovm on. Di jalur multi-putaran, microVM menangguhkan setelah belokan dan melanjutkan pada permintaan koneksi berikutnya.

Pada aliran sesi, tungguagent.session.turn.completed,agent.session.turn.failed, atau agent.session.turn.cancelled untuk agen utama, di event.turn.subagent_id mananull. Subagen berbagi microVM, sehingga peristiwa terminal mereka tidak memicu pembersihan. Ambil file yang Anda butuhkan. Setelah putaran terakhir, hubungi TerminateMicrovm dan konfirmasikan pencapaian VMTERMINATED. Untuk giliran lanjutan, biarkan berjalan atau tunda. Jalankan pembersihan jika aplikasi Anda mengalami kesalahan.

Hasil Turn tiba sebagai acara streaming, bukan langganan webhook. agent.session.failedWebhook mencakup kegagalan sesi tetapi tidak setiap giliran yang gagal. Untuk alasan ini, jangan berhenti agent.session.idle sendiri, karena dapat tiba sebelum input menunggu dimulai.

Untuk mengikat masa pakai microVM jika pembersihan tidak berjalan, konfigurasikan pengaturan berikut saat peluncuran:

Pengaturan Bimbingan
maximumDurationInSeconds Tetapkan plafon untuk beban kerja, seperti 900 untuk tes 15 menit. Batas ini berlaku bahkan saat pekerjaan sedang berlangsung.
maxIdleDurationSeconds Tutupi beban kerja yang diharapkan. Lambda mengukur lalu lintas masuk, sehingga koneksi keluar pelaksana tidak mengatur ulang timer ini.
suspendedDurationSeconds / autoResumeEnabled Gunakan 0/false untuk pola putaran tunggal, yang tidak melanjutkan microVM yang ditangguhkan.

Untuk kontrol seumur hidup dan idle, lihatMenjalankan dan menggunakan MicroVMS.

Hapus sesi secara terpisah. Menghapus sesi tidak menghentikan microVM atau mengirim webhook penghapusan. Jaga rahasia gambar dan kunci eksekutor untuk digunakan kembali. Untuk menangani putaran tindak lanjut, lihat Siklus hidup Sandbox.

Menangguhkan dan melanjutkan di antara belokan

Untuk mempertahankan memori dan status disk di antara putaran, tunda microVM setelah giliran agen utama selesai dan semua alat dan subagen selesai. Lanjutkan microVM yang sama ketika sesi berikutnya membutuhkan eksekutor.

  • Tetapkan bukan nolsuspendedDurationSeconds. Biaya penyimpanan snapshot berlaku saat microVM ditangguhkan.

  • Aktifkan /suspend hook untuk menghapus penulisan dan menutup koneksi, dan /resume hook untuk menyegarkan kredenSIAL dan menghubungkan kembali eksekutor.

  • Jalur yang dikelola aplikasi melanjutkan VM sebelum mengirim input berikutnya. Di jalur yang dikelola webhook, mengirimkan input memicu permintaan koneksi yang melanjutkan VM. Giliran berlanjut setelah pelaksana terhubung kembali.

catatan

maximumDurationInSecondsmembatasi total waktu berjalan dan ditangguhkan hingga 8 jam. Untuk melanjutkan sesuai permintaan, hubungiResumeMicrovm. Resume otomatis memerlukan lalu lintas masuk ke microVM; Input API agen saja tidak melanjutkannya.

Jaringan

Izinkan koneksi keluar yang diperlukan eksekutor ke OpenAI dan akses ke Secrets Manager. Untuk menjangkau sumber daya pribadi atau menerapkan batasan jaringan Anda sendiri, pasang konektor keluar VPC pada waktu peluncuran. Lihat Bekerja dengan konektor jaringan jalan keluar.

Contoh ini mendukung unggahan dan unduhan file melalui titik akhir HTTPS microVM, menggunakan token otentikasi yang dicakup ke port server.

Memantau

Jalankan salah satu contoh, lalu konfirmasikan bahwa hello.txt unduhan, microVM mencapaiTERMINATED, dan sesi yang dihapus mengembalikan HTTP 404.

Log peluncur. Tinjau log fungsi peluncur Lambda di CloudWatch Log:

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

Menjalankan MicroVMS. Set MICROVM_IMAGE_ARN el ke gambar ARN Anda, gunakan Wil AWS ayah penerapan Anda, dan daftarkan microVM untuk gambar:

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

Log sesi dan ID microVM bersama-sama sehingga Anda dapat melacak proses dari ujung ke ujung. Jauhkan kredenSIAL dan badan webhook mentah dari log.

Pemecahan masalah

Gejala Apa yang harus diperiksa
Tanda tangan Webhook ditolak Gunakan rahasia penandatanganan titik akhir dan verifikasi badan permintaan yang tidak dimodifikasi.
Tidak ada peluncuran MicroVM Periksa langganan webhook, filter kepemilikan sesi, environment_connection tindakan yang tertunda, dan izin IAM peluncur.
Pembuatan gambar gagal Periksa artefak Amazon S3, peran pembuatan gambar, dan respons /ready kait.
/rungagal atau habis waktu Periksa akses rahasia dan startup pelaksana. Kembali setelah memulai proses, bukan setelah belokan.
Pelaksana tidak dapat terhubung Periksa ID lingkungan, URL jarak jauh, kepemilikan kunci, dan akses jaringan keluar.
MicroVM berhenti selama belokan Periksa kebijakan masa pakai dan idle maksimum. Lalu lintas pelaksana keluar tidak dihitung sebagai aktivitas inbound.

Untuk kegagalan koneksi, periksa agent.session.environment.failed peristiwa dan log pelaksana. Untuk kontrak eksekutor bersama, lihat kotak Self-hosted pasir.