Agent Loop Mastery: OpenAI Codex System Design und Prompt-Caching-Strategien

Die Architektur moderner KI-Agenten stellt Systemdesigner vor Herausforderungen. OpenAI’s Codex-Harness zeigt Produktionsmuster für skalierbare Agenten-Systeme. Dieser Artikel analysiert die Konzepte des Agent Loops, Prompt-Caching-Strategien und das JSON-RPC-Protokoll, das mehrere Client-Oberflächen mit einer gemeinsamen Codebasis verbindet.

Überblick: Die Codex-Architektur

OpenAI’s Codex ist ein Agenten-System, das über CLI, Web, VS Code und macOS-App verfügbar ist. Die \“Codex Harness\“ ist eine gemeinsame Rust-Bibliothek, die den Agenten-Loop, Thread-Lifecycle, Tool-Execution und Auth-Logik für alle Oberflächen bereitstellt. Diese Architektur ermöglicht es, Features einmal zu entwickeln und überall bereitzustellen. Das System basiert auf einem App-Server-Protokoll, das JSON-RPC über stdio verwendet und so Sprach- und Plattformunabhängigkeit gewährleistet.

Prompt-Analyse: Der Agent Loop in Aktion

Der Prompt

{
  \"instructions\": \"gpt-5.2-codex_prompt.md\",
  \"tools\": [
    {
      \"name\": \"shell_tool\",
      \"description\": \"Execute shell commands in sandbox\",
      \"parameters\": {...}
    },
    {
      \"name\": \"update_plan\",
      \"description\": \"Update the current execution plan\",
      \"parameters\": {...}
    }
  ],
  \"input\": [
    {
      \"role\": \"developer\",
      \"content\": \"Sandbox permissions: read/write access to /home/user/project. Folders: /src, /docs\"
    },
    {
      \"role\": \"developer\", 
      \"content\": \"User config from ~/.codex/config.toml\"
    },
    {
      \"role\": \"user\",
      \"content\": \"AGENTS.md content from git root to cwd\"
    },
    {
      \"role\": \"user\",
      \"content\": \"Environment: cwd=/home/user/project, shell=bash\"
    },
    {
      \"role\": \"user\",
      \"content\": \"Actual user query: Create a new React component\"
    }
  ]
}

Bestandteile

Der Codex-Prompt folgt einer strukturierten Hierarchie mit vier Komponenten:

1. Instructions (System/Developer Message): Enthält modellspezifische Anweisungen und Entwicklerrichtlinien. Diese statischen Inhalte stehen am Anfang des Prompts, um Caching zu optimieren. Die Rolle \“developer\“ hat höhere Priorität als \“user\“ und beeinflusst, wie das Modell verschiedene Inhaltsbereiche gewichtet.

2. Tools Definition: Eine Liste verfügbarer Werkzeuge mit Beschreibungen und Parametern. Jedes Tool wird als JSON-Objekt definiert, das Name, Beschreibung, Parameter-Schema und Ausführungslogik enthält. Die Reihenfolge der Tools muss deterministisch sein, um Cache-Misses zu vermeiden.

3. Input Hierarchy: Die Eingaben folgen einer Reihenfolge: Zuerst Sandbox-Berechtigungen, dann Benutzerkonfiguration, gefolgt von AGENTS.md-Inhalten, Umgebungskontext und schließlich der Benutzeranfrage. Diese Schichtung nach Stabilität maximiert die Cache-Effizienz.

4. Role-Based Weighting: Das System verwendet eine Rollenhierarchie (system > developer > user > assistant), die bestimmt, wie das Modell verschiedene Nachrichten gewichtet. Developer-Nachrichten haben höheren Einfluss auf das Modellverhalten als reine User-Inputs.

Der Agent Loop: Inference und Tool Calls

Der Kern des Codex-Systems ist der Agent Loop – ein zyklischer Prozess, der Modell-Inferenz mit Tool-Execution verbindet. Der Loop beginnt mit der Prompt-Konstruktion, sendet diese an die Responses API und verarbeitet Server-Sent Events. Wenn das Modell einen Tool-Call anfordert (z.B. \“run ls\“), wird dieser ausgeführt und das Ergebnis an den Prompt angehängt. Das Modell wird dann mit dem aktualisierten Prompt erneut abgefragt. Dieser Zyklus wiederholt sich, bis das Modell eine finale Assistant-Nachricht ausgibt, die das Ende eines \“Turns\“ signalisiert.

Der Loop ist O(n²) in Bezug auf gesendete Bytes, da jede Iteration die gesamte Konversationshistorie erneut senden muss. Dies macht Caching-Strategien und Kompaktionsmechanismen wichtig für die Skalierbarkeit.

Prompt-Caching: Effizienz durch intelligente Strukturierung

Prompt-Caching ist wichtig für die Effizienz des Codex-Systems. Da LLM-Inferenz jeden Input-Token bei jedem Aufruf verarbeiten muss, ermöglicht Prefix-Caching die Wiederverwendung bereits berechneter Ergebnisse. Codex erreicht dies durch:

1. Statische Prefix-Organisation: Alle statischen Inhalte (Instructions, Tool-Definitionen) stehen am Prompt-Anfang. Da diese sich nicht ändern, können sie bei jedem neuen Turn aus dem Cache geladen werden.

2. Append-Only History: Konversationshistorie wird nur angehängt, nie eingefügt oder geändert. Dies erhält den gemeinsamen Prefix zwischen aufeinanderfolgenden Turns.

3. Deterministische Tool-Ordering: Tools müssen in konsistenter Reihenfolge definiert werden. Nicht-deterministische Ordering verursacht Cache-Misses, wie das Team bei MCP-Tools entdeckte.

4. Context-Aware Appending: Wenn sich Kontext ändert (z.B. Sandbox-Konfiguration), werden neue Nachrichten am Ende angehängt, nicht in der Mitte eingefügt, um den Cache-Prefix zu erhalten.

Context Window Management: Kompaktionsstrategien

Bei langen Agenten-Sessions kann die Konversationshistorie das Context-Limit des Modells überschreiten. Codex verwendet drei Strategien:

1. Automatische Kompaktion: Wenn der Token-Count auto_compact_limit überschreitet, ruft Codex /responses/compact auf, der eine komprimierte Darstellung der Konversation zurückgibt.

2. Latent State Preservation: Statt einfacher Text-Zusammenfassungen verwendet Codex encrypted_content-Blobs, die das latente Verständnis des Modells kodieren – reicher als jede Textzusammenfassung.

3. Privacy-Preserving Design: Für Zero Data Retention Kunden behält OpenAI nur den Decryption-Key, nicht die Daten selbst, was Privatsphäre mit State-Preservation kombiniert.

App Server Protocol: JSON-RPC für stabile Clients

Das App-Server-Protokoll definiert drei primitive Abstraktionen:

Item: Atomare Einheit von Input/Output mit explizitem Lifecycle (started → delta events → completed). Ermöglicht sofortiges UI-Rendering ohne auf vollständigen Content zu warten.

Turn: Eine Einheit von Agenten-Arbeit, die mit Client-Input beginnt und endet, wenn der Agent alle Outputs produziert hat. Enthält eine Sequenz von Items für Zwischenschritte.

Thread: Dauerhafter Container für Sessions, hält multiple Turns, persistiert Event-History und ermöglicht Resume nach Disconnect.

Häufig gestellte Fragen

Warum ist die Reihenfolge der Tool-Definitionen so wichtig für das Caching?

Prompt-Caching funktioniert nur bei exakten Prefix-Matches. Wenn Tool-Definitionen in nicht-deterministischer Reihenfolge generiert werden, ändert sich der Prompt-Prefix bei jedem Turn, was Cache-Misses verursacht. Codex löst dies durch deterministische Sortierung und Reihenfolge-Management.

Wie unterscheidet sich Codex-Kompaktion von traditioneller Text-Zusammenfassung?

Traditionelle Zusammenfassungen verlieren Kontext und Nuancen. Codex verwendet encrypted_content-Blobs, die das latente Verständnis des Modells kodieren – eine reichere Repräsentation, die mehr semantische Information bewahrt. Für Zero Data Retention wird nur der Encryption-Key gespeichert, nicht die Daten selbst.

Warum verwendet Codex JSON-RPC über stdio statt REST oder GraphQL?

JSON-RPC über stdio bietet bidirektionales Streaming, sprachunabhängige Kompatibilität und einfache Integration in verschiedene Client-Umgebungen. Das Protokoll ermöglicht Backward Compatibility, sodass ältere Clients mit neueren Server-Binaries kommunizieren können – wichtig für unabhängige Release-Zyklen.

Wie verhindert Codex O(n²) Kosten im Agent Loop?

Durch kombinierte Strategien: Prompt-Caching reduziert Rechenkosten für statische Prefixe, Append-Only History erhält Cache-Kohärenz, und Kompaktion managt Context-Window-Überschreitungen. Zusammen ermöglichen dies nahezu lineare Skalierung statt quadratischer Kosten.

Was sind die größten Herausforderungen bei der Prompt-Strukturierung für Agenten?

Die Hauptherausforderungen sind: Balance zwischen statischem Content (für Caching) und dynamischem Context, Management der Rollenhierarchie für korrekte Modellgewichtung, Handling von Context-Limits ohne Informationsverlust, und Sicherstellung deterministischer Prompt-Generierung für reliable Caching.

Quelle

Basiert auf diesem Artikel.