Die Codex-Agentenschleife aufdröseln

• Codex CLI ist als Agent konzipiert, der in lokalen Umgebungen sicher und effizient hochwertige Softwareänderungen ausführt
• Die zentrale Struktur, die Agentenschleife (agent loop), verknüpft Benutzereingaben, Modellinferenz und Tool-Aufrufe zyklisch, um sinnvolle Aufgaben auszuführen
• Während der Schleife entstehende Prompt-Zusammenstellung, Verwaltung des Kontextfensters und Prompt-Caching sind zentrale Faktoren für Leistung und Stabilität
• Codex kommuniziert über die Responses API mit dem Modell; jede Anfrage besteht aus einer vollständigen JSON-Payload und bleibt dadurch zustandslos (stateless)
• Diese Struktur ermöglicht fortgeschrittene Funktionen wie Zero Data Retention (ZDR), Prompt-Caching und automatische Verdichtung (compaction) und bildet die Grundlage für das Design großer Agentensysteme

---

Überblick über die Codex-Agentenschleife

• Codex CLI arbeitet im Kern mit einer Schleifenstruktur, die die Interaktion zwischen Benutzer, Modell und Tools koordiniert
  • Es übernimmt die Benutzereingabe und erstellt den Prompt, der an das Modell gesendet wird
  • Wenn das Modell eine Antwort erzeugt oder einen Tool-Aufruf (tool call) anfordert, führt der Agent diesen aus und fügt das Ergebnis wieder dem Prompt hinzu
  • Sobald das Modell keine weiteren Tool-Aufrufe mehr macht und eine assistant-Nachricht erzeugt, endet ein Turn
• Jeder Turn ist Teil einer Konversation; frühere Nachrichten und Tool-Aufrufe werden vollständig in den Prompt der nächsten Anfrage aufgenommen
• Da die Prompt-Länge durch das Kontextfenster (context window) des Modells begrenzt ist, muss Codex dieses aktiv verwalten

Responses API und die Kommunikationsstruktur von Codex

• Codex CLI sendet für die Modellinferenz HTTP-Anfragen an die Responses API
  • Der API-Endpunkt variiert je nach Konfiguration und kann in OpenAI-, ChatGPT-, Azure- oder lokalen Umgebungen wie LM Studio und Ollama genutzt werden
• API-Anfragen bestehen aus einer JSON-Payload mit folgenden Hauptfeldern
  • System-/Developer-Nachrichten: legen den grundlegenden Kontext des Modells fest
  • instructions: Liste der Tools, die das Modell aufrufen kann
  • tools: Tool-Definitionen, die von Codex CLI, der Responses API oder dem Benutzer bereitgestellt werden, etwa über einen MCP-Server
  • input: Nachrichtenliste mit Konversationsverlauf und Umgebungsinformationen
• Codex liest Konfigurationen aus ~/.codex/config.toml sowie AGENTS.md und skills-Dateien im Projekt und fügt Benutzeranweisungen und Umgebungsinformationen automatisch ein

Prompt-Zusammenstellung und Ereignisverarbeitung

• Codex sendet jede Nachricht als JSON-Objekt (type, role, content) an die Responses API
• Der Server erzeugt daraus den Modell-Prompt und gibt die Antwort als SSE-Stream (Server-Sent Events) zurück
  • Das Ereignis response.output_text.delta wird für Streaming-Ausgaben verwendet
  • Das Ereignis response.output_item.added wird dem input der nächsten Anfrage hinzugefügt und setzt so die Schleife fort
• Das System ist so ausgelegt, dass ein früherer Prompt ein exakter Präfix des neuen Prompts bleibt, sodass Prompt-Caching genutzt werden kann

Leistungsoptimierung: Caching und zustandsloses Design

• Codex verwendet previous_response_id nicht und behält dadurch eine vollständig zustandslose (stateless) Anfragestruktur bei
  • Das ermöglicht Unterstützung für Zero Data Retention (ZDR)-Kunden und minimiert die Datenspeicherung
• Prompt-Caching nutzt identische Präfixe erneut und linearisiert die Sampling-Kosten
  • Ein Cache-Treffer tritt nur bei exakter Präfix-Übereinstimmung auf
  • Änderungen an Tool-Listen, Modell, Sandbox-Einstellungen oder Arbeitsverzeichnis führen zu Cache-Misses
• Dynamische Änderungen an MCP-Tools können Cache-Verluste verursachen; daher spiegelt Codex solche Änderungen durch das Einfügen neuer Nachrichten wider

Verwaltung des Kontextfensters und automatische Verdichtung (compaction)

• Wenn eine Konversation länger wird, führt Codex zur Vermeidung einer Überschreitung des Kontextfensters eine Konversationsverdichtung (compaction) durch
  • Anfangs geschah dies manuell über den Befehl /compact, inzwischen nutzt Codex automatisch den /responses/compact-Endpunkt der Responses API
  • Dieser Endpunkt gibt ein Element vom Typ type=compaction sowie verschlüsselten encrypted_content zurück, um das Modellverständnis zu erhalten
• Überschreitet Codex den auto_compact_limit, wird automatisch eine Verdichtung ausgeführt, um die Kontinuität der Konversation zu sichern

Fazit und Ausblick

• Die Agentenschleife von Codex ist eine Kernstruktur, die Modellinferenz, Tool-Aufrufe, Caching und Kontextverwaltung integriert
• Diese Struktur ermöglicht ein leistungsstarkes, zustandsloses und sicherheitsorientiertes Agentendesign
• In späteren Beiträgen sollen weitere interne Strukturen von Codex behandelt werden, darunter CLI-Architektur, Implementierung der Tool-Nutzung und Sandbox-Modelle