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 berjalan`codex 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 ](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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.
1. Saat sesi membutuhkan eksekutor, OpenAI mengirimkan `agent.session.action_required` webhook dengan `environment_connection` tindakan ke titik akhir Amazon API Gateway di akun Anda.
1. Fungsi peluncur Lambda memverifikasi tanda tangan webhook, mengambil sesi saat ini, dan mengonfirmasi bahwa handler memilikinya.
1. Peluncur memanggil `RunMicrovm` dengan gambar, peran eksekusi, konektor jaringan, dan `runHookPayload` yang membawa nilai koneksi sesi.
1. Pengait MicroVM menggunakan peran eksekusi IAM untuk mengambil kunci eksekutor dari AWS Secrets Manager dan memulai Codex. `/run`
1. 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.
1. 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.
1. Setelah giliran terakhir, aplikasi Anda mengakhiri microVM.
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 menyertakan`lambda-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](microvms-getting-started.md)
+ 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 sebagai`codex/agents-api/executor`. Peng `/run` ait meneruskannya ke Codex sebagai`CODEX_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](microvms-security.md).
## 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, lihat[Gambar MicroVM](microvms-images.md).
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.
1. Panggil `RunMicrovm` dengan gambar ARN dan versi, peran eksekusi, konektor jaringan, dan`runHookPayload`. Simpan yang dikembalikan di `microvmId` samping ID sesi.
1. Tunggu`agent.session.environment.connected`, lalu kirim input dan ikuti hasil giliran.
1. Ambil file output dan akhiri giliran seperti yang dijelaskan dalam[Mengakhiri giliran](#microvms-integrations-openai-agents-api-ending-turn).
### 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.
1. Daftarkan titik akhir untuk `agent.session.action_required` dan`agent.session.failed`. Simpan rahasia penandatanganan titik akhir di Secrets Manager dengan kunci aplikasi peluncur.
1. 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.
1. Jika `environment_connection` masih tertunda, periksa microVM yang direkam dengan`GetMicrovm`. 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.
1. 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 ](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) 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.
Gambar 2. Siklus hidup MicroVM untuk satu giliran API Agen. `RunMicrovm`meluncurkan 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, tunggu`agent.session.turn.completed`,`agent.session.turn.failed`, atau `agent.session.turn.cancelled` untuk agen utama, di `event.turn.subagent_id` mana`null`. Subagen berbagi microVM, sehingga peristiwa terminal mereka tidak memicu pembersihan. Ambil file yang Anda butuhkan. Setelah putaran terakhir, hubungi `TerminateMicrovm` dan konfirmasikan pencapaian VM`TERMINATED`. 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.failed`Webhook 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, lihat[Menjalankan dan menggunakan MicroVMS](microvms-launching.md).
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](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws).
## 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 nol`suspendedDurationSeconds`. 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**
`maximumDurationInSeconds`membatasi total waktu berjalan dan ditangguhkan hingga 8 jam. Untuk melanjutkan sesuai permintaan, hubungi`ResumeMicrovm`. 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](microvms-networking.md#microvms-networking-connectors).
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 mencapai`TERMINATED`, 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](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws).
## Sumber daya terkait
+ [AWS Lambda MicroVM](lambda-microvms-guide.md)
+ [Menjalankan dan menggunakan MicroVMS](microvms-launching.md)
+ [Keamanan dan izin](microvms-security.md)
+ [Referensi API RunMicrovm](https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html)
+ [Kotak pasir yang di-host sendiri OpenAI Agents API ](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)
+ [OpenAI Agents API pada panduan AWS](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)