Mit AWS Lambda MicroVMs kannst du die Tools deines Agenten in deinem AWS-Konto ausführen. OpenAI betreibt den Agenten-Harness. Auf jeder MicroVM läuft codex exec-server. Dort liegen auch die Dateien aus dem Workspace der Sitzung.
Standardmäßig verwenden die Beispiele eine MicroVM für einen einzelnen Durchlauf. Bereite ein wiederverwendbares Image vor und starte daraus eine MicroVM, entweder über deine Anwendung oder über einen OpenAI-Webhook. Beide Varianten verwenden dasselbe Image und dieselben Zugangsdaten. Lege für jede Sitzung fest, welche der beiden Varianten die Bereitstellung übernimmt.
Probiere die AWS-Beispiele im Cookbook für Sandboxes aus, die von einer Anwendung oder einem Webhook verwaltet werden.
So funktioniert es
Bei der Webhook-Variante erstellt deine Anwendung eine selbst gehostete Sitzung und sendet eine Eingabe. Sobald die Sitzung einen Executor benötigt, sendet OpenAI agent.session.action_required mit einer Aktion vom Typ environment_connection. API Gateway leitet den Webhook an eine Lambda-Funktion weiter, die als Launcher dient. Der Launcher prüft die Signatur und die aktuelle Sitzung. Anschließend startet er eine MicroVM oder setzt eine angehaltene MicroVM fort.
Der /run-Hook der MicroVM ruft einen Umgebungsschlüssel aus Secrets Manager ab und startet den Executor. Der Executor baut eine ausgehende Verbindung zu OpenAI auf. Danach wird die ausstehende Eingabe verarbeitet. Deine Anwendung verfolgt den Ereignisstream der Sitzung, lädt Ausgabedateien herunter und beendet die MicroVM nach dem letzten Durchlauf.

Voraussetzungen
Bereite Folgendes vor:
- AWS-Zugriff: Du brauchst ein Konto mit Zugriff auf Lambda MicroVMs, eine Version der AWS CLI mit
lambda-microvmsund Berechtigungen zum Erstellen von Images und zum Ausführen von MicroVMs. Folge der Einstiegsanleitung von AWS, um den S3-Bucket für Artefakte und die IAM-Rolle zum Erstellen der Images anzulegen. - Anwendungsschlüssel: Verwende
OPENAI_API_KEY, um Sitzungen zu erstellen und Eingaben zu senden. - Umgebungsschlüssel (
OPENAI_EXECUTOR_API_KEY): Erstelle einen separaten Umgebungsschlüssel. Er muss derselben Organisation, demselben Projekt und demselben Benutzer- oder Dienstkonto zugeordnet sein wie der Anwendungsschlüssel. Speichere seinen Wert in Secrets Manager, zum Beispiel in einem Secret namenscodex/agents-api/executor. Der/run-Hook übergibt ihn alsCODEX_API_KEYan Codex. - Ausführungsrolle der MicroVM: Beschränke den Lesezugriff dieser Rolle auf das Secret mit dem Umgebungsschlüssel. Wenn du einen selbst verwalteten KMS-Schlüssel verwendest, erteile zusätzlich die Berechtigung zum Entschlüsseln. Wie du die Rolle einrichtest, erfährst du in der AWS-Dokumentation zu Sicherheit und Berechtigungen.
Bewahre den Anwendungsschlüssel und das Signatur-Secret des Webhooks außerhalb der MicroVM auf. Ein Webhook-Launcher benötigt diese Zugangsdaten in einem eigenen Secret in Secrets Manager. Die VM erhält nur den ARN des Secrets mit ihrem Umgebungsschlüssel.
Wiederverwendbares Image vorbereiten
Erstelle ein Image mit der Codex CLI, den Abhängigkeiten deiner Tools, einem Arbeitsverzeichnis wie /workspace und einem HTTP-Server für die Lebenszyklus-Hooks von AWS.
Die Beispiele implementieren unter /aws/lambda-microvms/runtime/v1 folgende Hooks:
| Hook | Verhalten |
|---|---|
/ready |
Gib HTTP 200 zurück, sobald AWS einen Snapshot des Servers erstellen kann. Der Executor darf zu diesem Zeitpunkt noch keine Verbindung herstellen. |
/validate |
Prüfe, ob Codex läuft und Schreibzugriff auf den Workspace besteht. |
/run |
Lies die Verbindungsdaten der Sitzung und den ARN des Secrets, rufe den Umgebungsschlüssel ab und starte den Executor. |
/suspend |
Stoppe den Executor, bevor AWS einen Snapshot der VM erstellt. |
/resume |
Lade den Umgebungsschlüssel erneut und starte den Executor mit den gespeicherten Verbindungsdaten neu. |
/terminate |
Stoppe den Executor, bevor die VM beendet wird. |
Packe das Dockerfile und den Hook-Server in ein S3-Artefakt. Erstelle daraus ein versioniertes Image, zum Beispiel codex-executor. Aktiviere alle sechs Hooks in der Image-Konfiguration und stelle als Hook-Port den Port deines Servers ein. Halte Sitzungs-IDs, Zugangsdaten und aktive Executor-Verbindungen aus dem Image-Snapshot heraus. Hinweise zum Erstellen des Images und zur Konfiguration der Hooks findest du in der AWS-Dokumentation zu MicroVM-Images.
Beim Start serialisiert deine Anwendung oder dein Launcher diese Werte als JSON in runHookPayload:
| Wert | Zweck |
|---|---|
session.environment.id |
Identifiziert die Umgebung, mit der sich der Executor verbindet. |
session.environment.remote_url |
Gibt die URL an, über die sich der Executor mit OpenAI verbindet. |
| ARN des Secrets mit dem Umgebungsschlüssel | Ermöglicht dem Hook, den Schlüssel über die Ausführungsrolle der MicroVM abzurufen. |
Der /run-Hook liest diesen String aus dem Anfragetext von AWS und parst ihn. Er ruft den Schlüssel ab, setzt CODEX_API_KEY in der Umgebung des Kindprozesses und startet den Executor. Lass den Hook zurückkehren, sobald der Prozess gestartet ist. Wartet der Hook auf das Ende des Agentendurchlaufs, kann sein Zeitlimit ablaufen.
Erlaube die ausgehenden Verbindungen, die der Executor benötigt, sowie den Zugriff auf Secrets Manager. Konfiguriere für private Ressourcen oder bei Netzwerkeinschränkungen einen AWS-Konnektor für ausgehenden Datenverkehr. Füge deinem Server für Dateidownloads eine Route hinzu. Rufe sie über den HTTP-Endpunkt der MicroVM mit einem AWS-Authentifizierungstoken auf, das auf den Port des Servers beschränkt ist.
MicroVM starten
Wähle die Bereitstellung über die Anwendung oder über den Webhook. Halte den Ereignisstream der Sitzung in beiden Fällen vom Verbindungsaufbau über die Verarbeitung der Eingabe bis zum Abschluss des Durchlaufs offen.
Bereitstellung über die Anwendung
- Erstelle eine selbst gehostete Sitzung mit demselben Arbeitsverzeichnis wie im Image. Öffne anschließend ihren Ereignisstream.
- Rufe die AWS-Operation RunMicrovm mit dem ARN und der Version des Images, der Ausführungsrolle, den Netzwerkkonnektoren und
runHookPayloadauf. Speichere die zurückgegebenemicrovmIdzusammen mit der Sitzungs-ID. - Warte auf
agent.session.environment.connected. Sende dann die Eingabe und verfolge den Durchlauf bis zum Ergebnis. - Rufe die Ausgabedateien ab und beende die MicroVM.
Bereitstellung über den Webhook
Verwende eine HTTP-API in API Gateway und eine Lambda-Funktion als Launcher. Deine Anwendung erstellt die Sitzung, öffnet ihren Ereignisstream und sendet eine Eingabe. Sobald die Sitzung eine Verbindung benötigt, löst der Webhook den Start oder die Fortsetzung der MicroVM aus.
- Stelle eine Route für
POST /webhookbereit, die den Launcher aufruft. Erteile dem Launcher für das ausgewählte Image die Berechtigungenlambda:RunMicrovm,lambda:GetMicrovm,lambda:ResumeMicrovmundlambda:TerminateMicrovm. Der Launcher muss außerdem seine Zugangsdaten lesen, die Ausführungsrolle der MicroVM übergeben und die konfigurierten Netzwerkkonnektoren verwenden können. - Registriere den Endpunkt für
agent.session.action_requiredundagent.session.failed. Speichere das Signatur-Secret des Endpunkts zusammen mit dem Anwendungsschlüssel des Launchers. - Prüfe die Webhook-Signatur anhand des unveränderten Anfragetexts, bevor du auf Sitzungen zugreifst oder eine VM startest. Rufe die aktuelle Sitzung ab und prüfe, ob der Handler für sie zuständig ist. Gleiche dazu beispielsweise den Agenten der Sitzung mit einem eigens dafür gespeicherten Agenten ab.
- Steht die Aktion
environment_connectionnoch aus, prüfe die bereits erfasste VM mitGetMicrovm. Setze eine VM im ZustandSUSPENDEDmitResumeMicrovmfort. Warte bei einer VM im ZustandPENDINGoderRUNNING, bis sie die Verbindung herstellt. RufeRunMicrovmnur auf, wenn noch keine VM erfasst ist. Speichere ihre ID in den Sitzungsmetadaten. Schlägt das Speichern fehl, beende die gerade gestartete VM. - Befindet sich die Sitzung weiterhin im Zustand
failed, beende die für sie erfasste MicroVM. Ignoriere gelöschte Sitzungen, bereits erledigte Aktionen und Ereignisse, für die ein anderer Handler zuständig ist.
Stellt der Executor die Verbindung vor Ablauf des Zeitlimits für den Verbindungsaufbau her, wird die ausstehende Eingabe verarbeitet, ohne dass du sie erneut senden musst.
Bei einem Prototyp kannst du die MicroVM synchron starten und ihre ID in den Sitzungsmetadaten speichern. Halte vor dem Produktiveinsatz dauerhaft fest, wer für den Start zuständig ist, gestalte den Startvorgang idempotent und verarbeite Bereitstellungsaufträge über eine Warteschlange. Metadaten allein verhindern keine Mehrfachstarts. Dauert der Start zu lange, kann die Frist für die Antwort auf den Webhook verstreichen.
MicroVM beenden
Warte im Ereignisstream der Sitzung auf agent.session.turn.completed, agent.session.turn.failed oder agent.session.turn.cancelled für den Hauptagenten (event.turn.subagent_id ist null). Subagenten nutzen dieselbe MicroVM. Ihre Abschlussereignisse dürfen daher keine Bereinigung auslösen. Lade nach dem letzten Durchlauf die benötigten Dateien herunter, rufe TerminateMicrovm auf und prüfe, ob die VM den Zustand TERMINATED erreicht. Führe die Bereinigung auch bei Anwendungsfehlern aus.
Das Ergebnis eines Durchlaufs wird als Ereignis im Stream gemeldet. Du kannst diese Ereignisse nicht per Webhook abonnieren. Der Webhook agent.session.failed meldet Fehler auf Sitzungsebene und erfasst daher nicht jeden fehlgeschlagenen Durchlauf. Beende die MicroVM nicht allein aufgrund von agent.session.idle. Dieses Ereignis kann eintreffen, bevor die Verarbeitung einer ausstehenden Eingabe beginnt.
Konfiguriere die folgenden AWS-Grenzwerte für den Fall, dass die Bereinigung ausbleibt:
| Einstellung | Hinweise |
|---|---|
maximumDurationInSeconds |
Lege eine maximale Laufzeit für die Aufgabe fest, etwa 900 für einen 15-minütigen Test. Bei Erreichen des Zeitlimits können laufende Aufgaben unterbrochen werden. |
maxIdleDurationSeconds |
Wähle das Zeitlimit passend zur erwarteten Aufgabe. AWS misst den eingehenden Datenverkehr. Die ausgehende Verbindung des Executors setzt diesen Timer nicht zurück. |
suspendedDurationSeconds / autoResumeEnabled |
Die Beispiele verwenden standardmäßig 0 / false. Die Werte 300 / false gelten bei Verwendung von --suspend-resume. |
Details zu den Einstellungen für Lebensdauer und Leerlauf findest du in der AWS-Anleitung MicroVMs ausführen und verwenden.
Lösche die Sitzung separat. Das Löschen einer Sitzung beendet keine Rechenressourcen in AWS und löst keinen Webhook für die Löschung aus. Bewahre das Image und das Secret mit dem Umgebungsschlüssel zur Wiederverwendung auf. Wie du für weitere Durchläufe Rechenressourcen wiederverwendest oder ersetzt und Dateien dauerhaft verfügbar hältst, erfährst du im Leitfaden zum Lebenszyklus einer Sandbox.
MicroVM zwischen Durchläufen anhalten und fortsetzen
Mit den AWS-Funktionen zum Anhalten und Fortsetzen bleiben die Inhalte des Arbeitsspeichers und des Datenträgers zwischen den Durchläufen erhalten. Setze suspendedDurationSeconds auf einen Wert größer als null. Solange die VM angehalten ist, fallen Speicherkosten für den Snapshot an. maximumDurationInSeconds begrenzt die Gesamtdauer aus Laufzeit und angehaltener Zeit auf acht Stunden.
Führe eines der beiden Beispiele mit --suspend-resume aus, um die Datei /workspace/hello.txt zu schreiben, die VM anzuhalten und die Datei in einem zweiten Durchlauf zu lesen. Im Beispiel mit Bereitstellung über die Anwendung setzt die Anwendung die VM direkt fort. Im Webhook-Beispiel sendet die Anwendung eine weitere Eingabe. Daraufhin setzt der Launcher die erfasste VM fort. Beide Beispiele prüfen den Dateiinhalt und führen nach dem letzten Durchlauf die Bereinigung aus.
Der /suspend-Hook stoppt den Executor. Der /resume-Hook lädt dessen Schlüssel erneut und stellt die Verbindung wieder her. Halte die VM erst an, wenn alle Tools und Subagenten ihre Arbeit abgeschlossen haben. Damit AWS die VM automatisch fortsetzt, muss Datenverkehr bei der VM eingehen. Eine Eingabe an die Agents API allein aktiviert sie nicht wieder.
Integration prüfen und überwachen
Teste die Integration mit einem Prompt, der den Agenten anweist, eine kleine Datei in /workspace zu erstellen. Prüfe, ob der Executor die Verbindung herstellt, der Durchlauf abgeschlossen wird, die heruntergeladene Datei das erwartete Ergebnis enthält und die MicroVM nach der Bereinigung den Zustand TERMINATED erreicht. Ein erfolgreicher Start allein reicht als Nachweis für die funktionierende Integration nicht aus.
Lies im Verzeichnis der AWS-Beispiele mit jq den ARN des Images und die Region aus den gespeicherten Build-Daten aus. Passe den Pfad an, wenn du mit --state einen eigenen Pfad angegeben hast. Ersetze den Namen der Protokollgruppe, wenn du den Launcher umbenannt hast:
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
Protokolliere die Sitzungs-ID und die MicroVM-ID zusammen, damit du einen Durchlauf nachvollziehen kannst. Zugangsdaten und unveränderte Webhook-Anfragetexte dürfen nicht in den Protokollen erscheinen.
Fehlerbehebung
| Symptom | Was du prüfen solltest |
|---|---|
| Die Webhook-Signatur wird abgelehnt | Verwende das Signatur-Secret des Endpunkts und prüfe die Signatur anhand des unveränderten Anfragetexts. |
| Es startet keine MicroVM | Prüfe das Webhook-Abonnement, den Filter für die Zuständigkeit des Handlers, die ausstehende Aktion environment_connection und die IAM-Berechtigungen des Launchers. |
| Das Erstellen des Images schlägt fehl | Prüfe das S3-Artefakt, die Rolle zum Erstellen des Images und die Antwort des /ready-Hooks. |
/run schlägt fehl oder überschreitet das Zeitlimit |
Prüfe den Zugriff auf das Secret und den Start des Executors. Der Hook muss zurückkehren, sobald der Prozess gestartet ist, ohne das Ende des Durchlaufs abzuwarten. |
| Der Executor kann keine Verbindung herstellen | Prüfe die Umgebungs-ID, die Remote-URL, die Zuordnung des Schlüssels und den Netzwerkzugriff für ausgehende Verbindungen. |
| Die VM stoppt während eines Durchlaufs | Prüfe die maximale Lebensdauer und die Einstellungen für den Leerlauf. Ausgehender Datenverkehr des Executors zählt nicht als eingehende Aktivität. |
Prüfe bei Verbindungsfehlern agent.session.environment.failed und die Protokolle des Executors. Die gemeinsamen Schnittstellenanforderungen für den Executor findest du im Leitfaden zu selbst gehosteten Sandboxes.
Weiterführende Dokumentation
- Lebenszyklus: Die AWS-Anleitung MicroVMs ausführen und verwenden beschreibt, wie du MicroVMs startest, anhältst, fortsetzt und beendest.
- Sicherheit: Die AWS-Dokumentation zu Sicherheit und Berechtigungen erläutert IAM-Rollen, Authentifizierungstoken und Zugriffskontrollen.