- Agents API, Agents SDK und Responses API
- Was ist eine Agenten-Harness?
- Warum ein Agent dennoch eine Sandbox benötigt
- Novita Sandbox in dieser Architektur
- Lebenszyklus, Persistenz und langlebige Arbeit
- Verbinden von Novita mit dem selbst gehosteten Pfad
- Sicherheit und Anmeldeinformationen
- Kosten und Grenzen
- Wo diese Architektur passt
- FAQ
- Empfohlene Artikel
Die OpenAI Agents API ermöglicht es Ihnen, mit einem einzigen Sitzungserstellungsaufruf einen dauerhaften Cloud-Agenten zu starten, während OpenAI die Agenten-Harness in der Cloud ausführt. Novita Sandbox ersetzt weder die Agents API noch die von OpenAI verwaltete Harness. Es bietet Ihnen eine isolierte, zustandsbehaftete Laufzeitumgebung für den von OpenAI dokumentierten selbst gehosteten Ausführungspfad: Ihre Anwendung verbindet die Sandbox mit der Sitzung, der Agent führt Befehle aus und bearbeitet Dateien in dieser Laufzeitumgebung, und Ihre Anwendung besitzt den Lebenszyklus der Sandbox. Diese Aufteilung ist wichtig, wenn Sie einen von OpenAI gehosteten Agenten-Workflow möchten, aber eine separate, wiederverwendbare Umgebung für Code, Dateien, Browser, Computernutzung und langlebige Aufgaben benötigen.
Dieser Leitfaden erklärt die Hauptkonzepte der API, wie sich Harness und Umgebung die Verantwortung teilen, wie Sie eine Novita Sandbox mit dem selbst gehosteten Pfad verbinden und was Sie prüfen sollten, bevor Sie von einem Prototyp in die Produktion wechseln. Wenn Sie nur die Produktseite benötigen, ist Novita Sandbox der beste Ausgangspunkt.
Agents API, Agents SDK und Responses API
Der Agenten-Laufzeitvergleich von OpenAI unterscheidet drei Integrationsmodelle:
| Sie möchten | Verwenden Sie | Wer verwaltet den Zustand |
|---|---|---|
| Eine langlebige Aufgabe über eine von OpenAI verwaltete Codex-Harness ausführen | Agents API | Gespeicherte Sitzungskonfiguration, Züge und Elemente |
| Die Agentenschleife in Ihrer Anwendung behalten | Agents SDK | Anwendungszustand, SDK-Sitzungen oder Responses-Unterhaltungen |
| Modelle direkt aufrufen und alles selbst orchestrieren | Responses API | Anwendungsverlauf oder Responses-Unterhaltungen |
Die Agents API ist die Option mit der höchsten Abstraktionsebene. OpenAI beschreibt sie als Zugriff auf die Codex-Harness über eine von OpenAI verwaltete API. Sie übernimmt Sitzungen, Orchestrierung, Kontextkomprimierung und Wiederherstellung. Das Agents SDK läuft innerhalb Ihrer Anwendung und gibt Ihnen mehr Kontrolle über Bereitstellung, Speicherung, Genehmigungen und Laufzeitintegration. Die Responses API ist der Modellebene am nächsten. Diese Unterteilung ist nützlich, da „Agent“ entweder eine wiederverwendbare Modell-/Tool-Konfiguration oder einen dauerhaften laufenden Agenten bedeuten kann; die API-Dokumentation verwendet diese Begriffe in den einzelnen Laufzeiten unterschiedlich.
Was ist eine Agenten-Harness?
Eine Agenten-Harness ist der Cloud-Dienst, der einen Agenten-Durchlauf umgibt. Sie sendet Anweisungen und Kontext an das Modell, ruft Tools auf, verfolgt den Fortschritt, behandelt Unterbrechungen und Wiederaufnahmen und organisiert die Arbeit in einem überprüfbaren Strom. In der Agents API ist diese Harness die verwaltete Codex-Harness.
Die verwaltete Harness unterstützt:
- Ausführen von Befehlen und Code, wenn eine Umgebung angehängt ist.
- Anwenden relevanter Fähigkeiten und Anweisungen.
- Verbinden mit externen Daten über Tools oder MCP.
- Steuern des Agenten während der Arbeit.
- Zusammenfassen vorheriger Arbeit zur Verwaltung des Kontextfensters.
- Aufteilen von Arbeit in Teilaufgaben und Delegieren an Unteragenten.
- Fortsetzen einer Sitzung an der Stelle, an der sie unterbrochen wurde.
Das bedeutet nicht, dass Ihre Anwendung verschwindet. Ihre Anwendung erstellt weiterhin die Sitzung, sendet Eingaben, empfängt Ereignisse, behandelt Genehmigungen oder Funktionsaufrufe und entscheidet, wie IDs und Artefakte gespeichert werden. Die Harness reduziert den Orchestrierungsaufwand; sie entfernt keine Produktrichtlinien.
Warum ein Agent dennoch eine Sandbox benötigt
Einige Agenten beantworten Fragen oder rufen entfernte APIs auf, ohne ein Dateisystem zu berühren. Andere müssen Dateien erstellen, Abhängigkeiten installieren, Skripte ausführen, einen Browser inspizieren, einen Desktop steuern oder eine mehrstufige Aufgabe am Leben erhalten, während der Benutzer abwesend ist. Eine Sandbox gibt diesen Aktionen eine austauschbare Ausführungsumgebung, anstatt sie Ihren Produktserver oder lokalen Rechner berühren zu lassen.
Die Agents API behandelt die Umgebung als optional. Die Architekturdokumentation von OpenAI unterstützt drei Ausführungsoptionen:
none— die Harness hat keine Shell oder kein Dateisystem. Funktionstools geben Ergebnisse an die Harness zurück.openai_hosted— OpenAI stellt die Sandbox bereit und verwaltet sie.self_hosted— Ihre Anwendung startet und verbindet die Umgebung, sodass Sie Ihre eigene Rechenleistung, Ihr privates Netzwerk oder Ihre eigene Software verwenden können.
Hier ist die Grenze zwischen den beiden Systemen am klarsten. Die Agents API und OpenAI können die Harness hosten, aber eine selbst gehostete Umgebung ermöglicht es Ihrem Team, die Ausführungsplattform auszuwählen. Diese Wahl wirkt sich auf Isolierung, Dateisystemform, Netzwerk, SDKs, Pause-/Fortsetzungsverhalten, Abrechnung und den Umfang der von Ihnen zu wartenden Infrastruktur aus.
Novita Sandbox in dieser Architektur
Novita Sandbox ist eine verwaltete Ausführungsumgebung für KI-Agenten. Die offizielle Übersicht beschreibt isolierte, zustandsbehaftete Laufzeitumgebungen zum Ausführen von Code, Installieren von Abhängigkeiten, Zugreifen auf Dateien, Verwenden von Browsern und Beibehalten des Zustands über Sitzungen hinweg ohne Infrastrukturverwaltung. In einem reinen Novita-Agenten-Stapel erstellt Ihre Anwendung die Sandbox, das Modell oder Agenten-Framework wählt Tool-Aufrufe aus, die Sandbox führt sie aus, und Ihre Anwendung behält Richtlinien, Genehmigungen und Speicher außerhalb der Laufzeitumgebung.
Bei der Agents API ist der empfohlene genaue Rahmen komplementär und nicht nativ: Die aktuellen Leitfäden von OpenAI für selbst gehostete Sandboxen listen Cloudflare, Daytona, DigitalOcean, E2B, Blaxel, Modal, Runloop, OCI und Vercel als dokumentierte Anbieter auf. Novita Sandbox befindet sich derzeit nicht in dieser Anbieterliste. Der praktische Weg besteht daher darin, Novita als Ihre anwendungsverwaltete Ausführungsumgebung zu verwenden und sie über den selbst gehosteten Umgebungsvertrag von OpenAI mit einer Agents-API-Sitzung zu verbinden. Das bewahrt die nützliche Trennung – OpenAI führt die dauerhafte Harness aus, Novita Sandbox stellt die Laufzeitumgebung bereit – ohne eine offizielle Anbieterintegration zu behaupten, die die aktuellen Dokumente nicht unterstützen.
Novita Sandbox basiert auf fünf Konzepten:
| Konzept | Was es dem Agenten bietet |
|---|---|
| Sandbox | Eine isolierte Laufzeitumgebung mit eigenem Dateisystem und Prozessraum |
| Vorlage | Ein reproduzierbares Startimage, Abhängigkeiten, Konfiguration und Einrichtung |
| Snapshot | Ein gespeicherter Sandbox-Zustand, der wiederverwendet werden kann, um wiederholte Einrichtung zu vermeiden |
| Secret | Teambezogene, verschlüsselte Werte, die das Hartcodieren von Anmeldeinformationen vermeiden |
| Region | Der Standort der aktuellen US-v1/v2-Endpunkte |
Die Laufzeitumgebung unterstützt Codierungsagenten, Browseragenten, Datenanalyse-, Forschungs- und RL-ähnliche Workloads. Die Novita Sandbox-Übersicht ist die Quelle für aktuelle Regionen und das Lebenszyklusverhalten.
Lebenszyklus, Persistenz und langlebige Arbeit
Novita Sandbox hat drei Lebenszykluszustände: running (läuft), paused (pausiert) und killed (beendet). Eine laufende Sandbox kann Befehle ausführen und Verbindungen bedienen. Eine pausierte Sandbox bewahrt den Dateisystem- und Arbeitsspeicherzustand, einschließlich laufender Prozesse und Variablen, während die Abrechnung für CPU und RAM gestoppt wird. Netzwerkverbindungen werden bis zur Wiederaufnahme unterbrochen. Eine beendete Sandbox wird terminiert und kann nicht wiederhergestellt werden.
Zwei Zeitüberschreitungssteuerungen treiben die Übergänge an: Ein Sandbox-Timeout zählt ab der Erstellung herunter, und ein Leerlauf-Timeout wird ausgelöst, wenn für die konfigurierte Dauer kein Client verbunden war. Bei jedem dieser Ereignisse können Sie wählen, ob Sie pausieren statt beenden möchten, und optional die automatische Wiederaufnahme aktivieren. Dies ist nützlich für eine Codebearbeitungsaufgabe, die auf eine Überprüfung wartet, eine Browsersitzung, die zwischen Schritten pausiert, oder ein Datenanalyse-Notebook, das später mit intakten Abhängigkeiten und Variablen fortgesetzt wird.
Snapshots unterscheiden sich vom Pausieren. Das Pausieren behält den aktuellen Sandbox-Zustand für diese Instanz bei. Ein Snapshot erfasst den Zustand als wiederverwendbare Umgebung, sodass eine neue Sandbox mit bereits vorhandenen installierten Abhängigkeiten, Konfiguration und Dateien starten kann. Verwenden Sie in der Produktion Vorlagen für wiederholbare Basisimages, Snapshots für wiederverwendbare Arbeitszustände und Secrets für Anmeldeinformationen, anstatt sie in eine Vorlage oder einen Snapshot einzubacken.
Verbinden von Novita mit dem selbst gehosteten Pfad
Der Leitfaden von OpenAI für selbst gehostete Sandboxen definiert die Verbindungsform. Ihre Anwendung erstellt eine Sitzung mit environment.type: "self_hosted", erhält die Umgebungs-ID und die Remote-URL, startet einen Executor in Ihrer Laufzeitumgebung und meldet dann die Sitzung als verbunden. Der offizielle Executor-Befehl lautet:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
Der Sitzungsereignisstrom meldet agent.session.environment.pending, connected oder failed. Sie müssen den Executor laufen lassen, während der Agent arbeitet, und das Herunterfahren koordinieren, bevor Sie die Rechenleistung stoppen.
Das folgende Grundgerüst zeigt die Novita-Seite dieses Ablaufs unter Verwendung des offiziellen Novita SDK. Es erstellt eine Sandbox, bereitet die Authentifizierung vor, ohne ein Geheimnis in den Quellcode zu setzen, und gibt Ihnen den Ort, um den OpenAI-Executor zu starten. Die genaue Art und Weise, wie Sie den Executor-Schlüssel injizieren und auf den Ereignisstrom warten, hängt von Ihrer Anwendung und der OpenAI SDK-Version ab.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Erstellen Sie die Agents-API-Sitzung mit environment.type=self_hosted, "
"starten Sie dann hier codex exec-server."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
Überprüfen Sie vor der Verwendung dieses Pfades in der Produktion die aktuellen OpenAI SDK-Objekte, den Umgebungsschlüsselnamen, das Remote-URL-Verhalten und die Lebenszyklusanforderungen anhand des Leitfadens für selbst gehostete Sandboxen von OpenAI. Gehen Sie nicht davon aus, dass die Sitzungs-API die Sandbox für Sie verwaltet; bei self_hosted liegt diese Verantwortung explizit bei Ihnen.
Für den einfacheren Workflow ohne Agents API zeigt die Anleitung für Codex-Agenten von Novita, wie Sie die Codex CLI direkt auf der codex-Vorlage ausführen, ihre Ausgabe streamen und die Sandbox nach Abschluss beenden.
Sicherheit und Anmeldeinformationen
Behandeln Sie Harness, Sandbox und Anwendungsserver als separate Vertrauensbereiche.
- Bewahren Sie OpenAI-API-Schlüssel, Novita-API-Schlüssel, Git-Tokens und Datenbank-Anmeldeinformationen außerhalb von Prompts und Quelldateien auf.
- Verwenden Sie Novita Sandbox Secrets für teambezogene sensible Werte, die innerhalb der Sandbox verwendet werden.
- Verwenden Sie OpenAI-Tresore für Anmeldeinformationen, die laut OpenAI-Richtlinien außerhalb der Sandbox bleiben sollten.
- Bevorzugen Sie sicheren Sandbox-Zugriff. Die Novita-Dokumentation besagt, dass der sichere Zugriff für Sandboxen, die mit SDK Version 2.0.0 oder höher erstellt wurden, automatisch aktiviert ist; ältere benutzerdefinierte Vorlagen müssen möglicherweise neu erstellt werden.
- Legen Sie eine explizite Netzwerkrichtlinie fest und erweitern Sie diese nur, wenn eine Aufgabe dies erfordert.
- Überprüfen Sie generierten Code und Artefakte, bevor sie breitere Berechtigungen erhalten oder Produktionssysteme erreichen.
Diese Kontrollen arbeiten zusammen. Eine Sandbox reduziert die Schadensreichweite von generiertem Code, autorisiert jedoch nicht den Agenten, validiert nicht die Absicht und entscheidet nicht, welche Artefakte die Laufzeitumgebung verlassen dürfen.
Kosten und Grenzen
OpenAI berechnet die Modellnutzung der Agents API zu den API-Sätzen des ausgewählten Modells und OpenAI-Tools zu ihren Standardsätzen. Für eine von OpenAI gehostete Umgebung gilt der Containersatz. Für einen selbst gehosteten Pfad fallen die Ausführungsressourcen zu den Kosten Ihres Anbieters an.
Die Abrechnung von Novita Sandbox erfolgt pro Sekunde für CPU und RAM, während eine Sandbox läuft. Das Pausieren stoppt die CPU- und RAM-Kosten. Pausierte Daten werden als persistenter Speicher aufbewahrt; jedes Konto umfasst 60 GB kostenlosen persistenten Speicher, zusätzlicher Speicher wird stündlich abgerechnet. Jede laufende Sandbox umfasst 20 GB flüchtigen Speicher. Die offiziellen Sandbox-Guthaben und -Preise ändern sich, daher bestätigen Sie die aktuellen Werte auf der Preisseite für Novita Sandbox.
Die Kontingentlimits von Novita sind auch für parallele Workloads wichtig. Zum Zeitpunkt der Erstellung dieses Artikels haben kostenlose Konten standardmäßig 5 gleichzeitige Sandboxes und kostenpflichtige Konten 100; die maximale vCPU und der maximale Arbeitsspeicher einer einzelnen Sandbox unterscheiden sich je nach Tarif. Unternehmenslimits können angepasst werden. Überprüfen Sie die Anleitung zu Kontingentlimits und Sandbox.get_quota(), anstatt sich auf Beispiele auf Marketingseiten zu verlassen.
Wo diese Architektur passt
Eine selbst gehostete Novita-Laufzeitumgebung ist eine gute Wahl, wenn:
- Der Agent Code ausführen, Dateien ändern, Abhängigkeiten installieren, Tests ausführen, im Internet surfen oder mit einem Desktop interagieren muss.
- Die Anwendung zustandsbehaftete Sitzungen über menschliche Verzögerungen, Wiederholungen oder mehrstufige Überprüfungen hinweg benötigt.
- Sie eine isolierte Ausführung getrennt von Ihrem Produktserver wünschen.
- Ihr Workload von Vorlagen, Snapshots, Pause/Fortsetzung oder reproduzierbaren Umgebungen profitiert.
Es ist nicht die richtige Wahl, wenn:
- Die Aufgabe nur entfernte Funktionsaufrufe und kein Dateisystem oder keine Shell benötigt.
- Sie eine von OpenAI verwaltete Umgebung benötigen und den Lebenszyklus der Umgebung nicht selbst verwalten möchten.
- Sie einen Anbieter benötigen, der in den aktuellen direkten Sandbox-Anbieterleitfäden von OpenAI aufgeführt ist.
- Ihr Compliance-Modell von Anbietern verwaltete Isolationskontrollen erfordert, die Novita für Ihre Bereitstellung nicht dokumentiert hat.
Die sicherste Bewertung ist ein kleiner Proof of Concept mit Ihrem tatsächlichen Repository, Ihren Befehlen, Ihrer Netzwerkrichtlinie, Ihrer Geheimnisbehandlung und Ihren Fehlerpfaden. Messen Sie dann Start, Pause/Fortsetzung, Aufgabenabschluss und die Gesamtkosten eines repräsentativen Durchlaufs.
FAQ
Integriert Novita Sandbox nativ mit der OpenAI Agents API?
Laut den aktuellen Umgebungsanbieter-Leitfäden von OpenAI nicht. Die genaue Architektur besteht darin, den selbst gehosteten Umgebungspfad der Agents API zu verwenden, Novita Sandbox als Ihre anwendungsverwaltete Laufzeitumgebung zu starten und den dokumentierten Executor darin auszuführen. Überprüfen Sie die aktuellen Leitfäden vor der Veröffentlichung, da sich Anbieterintegrationen ändern können.
Benötige ich Novita trotzdem, wenn OpenAI eine gehostete Sandbox anbietet?
Es hängt von Ihren Anforderungen ab. Die gehostete Sandbox von OpenAI ist der pflegeleichte Weg. Novita Sandbox ist nützlich, wenn Sie eine separate Laufzeitumgebung für benutzerdefinierte Images, Vorlagen, Snapshots, Browser- oder Computer-Use-Workflows, zustandsbehaftetes Pause/Fortsetzen oder anbieterseitige Kontrolle über Ressourcen wünschen.
Kann der Agent Prozesse und Dateien über eine Pause hinweg behalten?
Ja. Die Pause/Fortsetzen-Dokumentation von Novita besagt, dass der Dateisystem- und Arbeitsspeicherzustand, einschließlich laufender Prozesse und Variablen, erhalten bleibt. Netzwerkverbindungen werden bis zur Wiederaufnahme der Sandbox unterbrochen.
Ist dies dasselbe wie das OpenAI Agents SDK?
Nein. Das Agents SDK läuft in Ihrer Anwendung und gibt Ihnen mehr Kontrolle über die Agentenschleife. Die Agents API verwendet die verwaltete Codex-Harness von OpenAI. Novita Sandbox kann die Ausführung für beide Muster hosten, aber das Sitzungs- und Orchestrierungsverhalten unterscheidet sich.
Wo soll ich anfangen?
Probieren Sie den Quickstart der OpenAI Agents API aus, um Harness-Sitzungen und Ereignisse zu verstehen. Erstellen Sie dann eine Novita Sandbox und entscheiden Sie, ob deren Laufzeit, Lebenszyklus, Sicherheit und Kostenmodell Ihren Produktionsanforderungen entsprechen.
