Analyse der internen Funktionsweise von OpenAI Codex CLI: Agent Loop und Strategien für Prompt Caching

Zusammenfassung:

• Struktur des Agent Loop: Es wird detailliert erklärt, wie Codex CLI einen zyklischen Prozess aus Benutzereingabe, Modell-Inferenz und Tool-Ausführung orchestriert, um reale Aufgaben zu erledigen.
• Prompt-Aufbau und Responses API: Analysiert werden der Prozess, in dem Systemanweisungen, Tool-Definitionen und lokaler Umgebungskontext in die JSON-Payload der Responses API umgewandelt werden, sowie der Datenfluss.
• Performance-Optimierung und Zustandsverwaltung: Behandelt werden Strategien zur Maximierung von Prompt Caching, Kompaktierungstechniken für Dialoge zur Überwindung von Grenzen des Kontextfensters sowie zustandslose Designprinzipien für ZDR (Zero Data Retention).

Detaillierte Zusammenfassung:
Das Engineering-Team von OpenAI hat einen technischen Artikel veröffentlicht, der die Funktionsweise des „Agent Loop“, der Kernlogik des lokalen Software-Agenten Codex CLI, eingehend analysiert. Der Beitrag beschreibt aus technischer Sicht den gesamten Lebenszyklus: wie Benutzerbefehle entgegengenommen werden, wie mit dem Modell interagiert wird, wie Tools ausgeführt werden und wie Ergebnisse zurückgegeben werden.

1. Der Agent Loop (The Agent Loop)

Der Agent Loop ist eine zyklische Struktur, die Benutzereingaben entgegennimmt und mit dem Modell interagiert, bis die Aufgabe abgeschlossen ist.

• Prozess: Benutzereingabe -> Prompt-Erstellung -> Modell-Inferenz -> (Anfrage für Tool-Aufruf -> Tool-Ausführung -> Ergebnis anhängen -> erneute Inferenz) Wiederholung -> finale Antwort.
• Turn: Der gesamte Ablauf von der Benutzereingabe bis zu dem Zeitpunkt, an dem das Modell der Benutzerin oder dem Benutzer schließlich eine Nachricht (Assistant Message) sendet, wird als ein „Turn“ bezeichnet. Dabei kann der Agent Hunderte von Tool-Aufrufen ausführen, etwa ls, Dateibearbeitung usw.

2. Modell-Inferenz und Responses API

Codex CLI kommuniziert mit dem Modell über die Responses API. Diese API kann z. B. auf https://chatgpt.com/backend-api/codex/responses, https://api.openai.com/v1/responses oder auf Localhost (wie Ollama) konfiguriert werden.

Aufbau des initialen Prompts (Building the Initial Prompt)

Ein Prompt ist kein einfacher Text, sondern strukturierte Daten, die aus instructions, tools, input usw. bestehen.

• Instructions: System- oder Entwicklernachrichten, die Verhaltensanweisungen für das Modell definieren. (z. B. Verweis auf die Konfigurationsdatei ~/.codex/config.toml)
• Tools: Eine Liste von Tool-Definitionen, die das Modell verwenden kann. Dazu gehören Shell-Ausführung, Plan-Updates (update_plan), Websuche sowie benutzerdefinierte MCP-Server-Tools (Model Context Protocol).
• Input: Die tatsächliche Liste der an das Modell übergebenen Daten. Dazu gehören Sandbox-Berechtigungseinstellungen, projektspezifische Anweisungen und Umgebungskontext (Environment Context) wie das aktuelle Arbeitsverzeichnis (cwd) und der Shell-Typ.

Beispiel einer JSON-Payload:

{  
  "type": "message",  
  "role": "user",  
  "content": [  
    {  
      "type": "input_text",  
      "text": "Füge README.md ein Architekturdiagramm hinzu"  
    }  
  ]  
  // ... zusammen mit zuvor definiertem Umgebungskontext, Berechtigungseinstellungen usw. gesendet  
}  
  

3. Tool-Ausführung und Datenfluss

Wenn das Modell einen Tool-Aufruf (Function Call) anfordert, führt der Agent ihn aus, fügt das Ergebnis dem Gesprächsverlauf hinzu und ruft das Modell erneut auf.

Beispiel für JSON einer erneuten Anfrage nach Tool-Ausführung:

[  
  /* ... frühere Eingabeeinträge ... */  
  {  
    "type": "reasoning", // Inferenzprozess des Modells (CoT)  
    "summary": [...],  
    "encrypted_content": "gAAAAABpaDW..." // verschlüsselter Inferenzinhalt  
  },  
  {  
    "type": "function_call",  
    "name": "shell",  
    "arguments": "{\"command\":\"cat README.md\",\"workdir\":\"/Users/mbolin/code/codex5\"}",  
    "call_id": "call_8675309..."  
  },  
  {  
    "type": "function_call_output", // Ergebnis der Tool-Ausführung  
    "call_id": "call_8675309...",  
    "output": "<p align=\"center\"><code>npm i -g @openai/codex</code>..."  
  }  
]  
  

Es ist wichtig, die Struktur so zu gestalten, dass der vorherige Prompt ein exaktes Präfix (Prefix) des neuen Prompts ist. Davon hängt die Effizienz des später beschriebenen Prompt Caching ab.

4. Performance-Aspekte: Caching und ZDR

Je länger ein Gespräch wird, desto linearer wächst die Größe des Prompts, was Kosten und Latenz erhöht.

• Prompt Caching: OpenAI-Modelle können bei übereinstimmendem Anfang des Prompts (Prefix Match) frühere Rechenergebnisse wiederverwenden und dadurch die Geschwindigkeit erhöhen.

• Vermeidung von Cache Misses: Wenn sich die Tool-Liste oder Sandbox-Einstellungen mitten im Gespräch ändern, kann der Cache ungültig werden. Um das zu verhindern, verarbeitet Codex Konfigurationsänderungen per Hinzufügen neuer Nachrichten (Append) statt durch Bearbeiten bestehender Nachrichten.

• Zustandslosigkeit (Stateless) und ZDR: Parameter wie previous_response_id werden nicht verwendet; stattdessen wird jedes Mal der vollständige Kontext gesendet. So wird die Richtlinie Zero Data Retention (ZDR) eingehalten, bei der keine Daten auf dem Server gespeichert werden. Indem der Client verschlüsselte Inferenzinhalte (encrypted_content) empfängt und wieder an den Server zurücksendet, kann der Server früheren Inferenzkontext rekonstruieren, ohne selbst Zustand zu speichern.

5. Verwaltung des Kontextfensters (Compaction)

Um Token-Limits nicht zu überschreiten, verwendet Codex den Endpunkt /responses/compact, um den Gesprächsverlauf zu komprimieren. Dabei wird nicht einfach nur zusammengefasst, sondern eine komprimierte Liste von Einträgen einschließlich encrypted_content zurückgegeben, die das latente Verständnis des Modells bewahrt und die bisherigen Eingaben ersetzt.